CoAP-Based Register Access
EEVideo Management uses the Constrained Application Protocol (CoAP) packet formats and transaction model for control and status communication between hosts and devices.
Implementing an established standard provides several benefits over an ad-hoc protocol:
-
Mature, tested protocol
-
Detailed specification for improved implementation compatibility
-
Range of existing options that can be implemented with minimal additional specification:
-
Security features
-
Proxy features
-
Optional alternate interfaces
-
-
Simplified integration with other CoAP-compliant services
-
Source-code libraries already available for a wide range of languages and platforms
-
Existing standardized port numbers and service strings for maximum Ethernet/IP compatibility
All packet and transaction details are fully specified in RFC 7252 and are already optimized for resource-constrained devices such as embedded video cameras. Those details are not repeated here.
CoAP provides maximum flexibility for a wide range of applications. Some of that flexibility can be trimmed for EEVideo to further reduce complexity. The specific CoAP application options chosen for EEVideo are described in this section.
EEVideo uses CoAP for two distinct functions: register access and device discovery. Device discovery is described later.
EEVideo to CoAP Mapping
Terminology
The vocabularies of digital video and Ethernet networking are not well aligned. In video systems a “server” usually means a central stream manager, while in networking it means the system providing a service. Both uses are correct, but context switching can be confusing. Therefore this specification avoids the term “server” entirely.
This specification aligns with digital video terminology. The following cross-reference may be helpful:
| Digital Video Term | CoAP Networking Term |
|---|---|
Camera, Sensor, Device |
Server |
Host, Controller |
Client |
Response |
Acknowledge with piggybacked response |
Device or Host |
Endpoint |
Read |
GET |
Write |
PUT |
Network Capabilities
Video applications typically require high-bandwidth, low-error networks. The low-throughput, low-bandwidth assumptions and optimizations of CoAP are therefore not necessarily valid for EEVideo.
Port
By default, EEVideo device and host management packets use port 5683. This is the IANA-assigned port number for unsecured CoAP. .Management Port
Port |
5683 |
Piggybacked Responses
EEVideo responses should be piggybacked on acknowledgements whenever possible.
One Request at a Time
To support resource-limited devices, a host must limit simultaneous outstanding interactions to one per device.
NStart |
1 |
Packet Size and UDP Fragmentation
To guarantee delivery on all Ethernet links, the total size of any EEVideo CoAP packet (including Ethernet, IP, and UDP headers) should not exceed 1472 bytes (1500-byte Ethernet MTU minus 28 bytes of headers).
A single Register Read or Register Write request shall therefore not request more than 360 registers (approximately) when using the maximum 4-byte Binary Address Option. Devices may return fewer registers than requested if the response would otherwise exceed this limit.
EEVideo Extensions to CoAP
Register Access
The primary purpose of CoAP transactions in EEVideo is to provide access to the status and control registers of an EEVideo device. A host must be able to read and write these registers, and the device must return appropriate responses. This results in four basic CoAP packet types:
| Packet | Source | Receiver | Payload | Options |
|---|---|---|---|---|
Register Read |
Host |
Device |
None |
Register Access, Binary Address |
Register Write |
Host |
Device |
Write Data |
Register Access, Binary Address |
Read Response |
Device |
Host |
Read Data |
None |
Write Response |
Device |
Host |
None |
None |
All EEVideo device capabilities can be realized with these four packets. The goal is to keep each packet as simple and efficient as possible.
Binary Address Option
Register-based requests must include an address. The simplest method is a binary value; no hardware resources are needed to convert strings. The CoAP standard defines no suitable option for a binary register address, so EEVideo defines a new Binary Address Option.
Request Meaning |
Provides a binary address that directs the request to a specific register or memory location. |
Response Meaning |
Provides the binary address of the register used to create the response. |
Critical or Elective |
Critical - Endpoints that do not recognize the Binary Address Option should report an error. The requestor is expecting a response based on the address option. If the appropriate response can not be delivered, an error is helpful. |
Safe-to-Forward |
Safe - Proxies need not understand the Address Option to forward it to an endpoint that does. |
Part of Cache-Key |
Yes — Responses differ by address, so caches must treat them separately. |
Format of Value |
uint — Unsigned integer in network byte order. |
Length of Value |
1-4 bytes - EEVideo registers are limited to a 32-bit (4 byte) address space. Typically all the registers of a device will fit in a much smaller space allowing shorter addresses. Upper (most significant) bits not included in the value are assumed to be 0. |
Single or Repeatable |
Repeatable — A single packet may address multiple registers. |
Default Value |
0 - Reading and Writing register 0 is a good default option. EEVideo device register 0 is read only, so writes will have no effect. Register 0 is also specified to contain capability details of the device, so it is helpful to retrieve its value. |
Option Number |
0b???? ???? ???n nn01 — (nnn must not be 111; upper bits TBD pending expert review) |
Register Access Option
Registers are read with GET and written with PUT using the register address. Efficiency is improved by the Register Access Option, which supports multi-register operations and bit-level writes in a single packet. The actual values for each mode are defined in the Register Read and Register Write sections.
Request Meaning |
Indicates how the register request should be processed |
Response Meaning |
Indicates how the register request was processed |
Critical or Elective |
Critical - Endpoints that do not recognize the Register Access Option should report an error. The requestor is expecting processing and a response based on this option. Receiving an error will indicate the request was not processed as expected. |
Safe-to-Forward |
Safe - Proxies need not understand the Register Access Option to forward it to an endpoint that might. |
Part of Cache-Key |
Yes — Responses differ by access option, so caches must treat them separately |
Format of Value |
uint — Unsigned integer in network byte order |
Length of Value |
1 byte |
Single or Repeatable |
Single — All registers in one packet use the same access option |
Default Value |
0 - The simplest, most common, Register Access Option is 0 for register reads and writes. If the default value is 0, the Register Access Option will not be required by most requests. |
Option Number |
0b???? ???? ???n nn01 — (nnn must not be 111; upper bits TBD pending expert review) |
Register Access Option Value
The Register Access Option Value is a single byte divided into two fields: type (3 bits) and count (5 bits), represented as t.c.
Register Access Count
Multiple registers may be accessed in one request either by repeating the Binary Address Option or by using the Count field in the Access Option. A host shall use only one of these methods per request.
The Count field (values 1–31 = 1–31 registers; 0 = 32 registers) applies only to specific access types and is ignored for others.
CoAP Option Number Registration
The two custom options defined above require IANA-assigned option numbers.
Until official numbers are assigned, implementations shall use the following provisional numbers for interoperability testing:
-
Binary Address Option: 0x1C01 (decimal 7169)
-
Register Access Option: 0x1C03 (decimal 7171)
Final numbers will be registered with IANA and updated in a future revision of this specification.
EEVideo Management Packets
Register Read Request
| Field | Value | Description | |
|---|---|---|---|
Ver |
0b01 |
Standard CoAP |
|
T |
0b00 |
Confirmable |
|
TKL |
0b0000 |
No Token required |
|
Code |
0x01 |
0.01 - Request . GET |
|
Message ID |
0x???? |
Set by host, matched by device in response |
|
Token |
- |
Optional, no token required |
|
Option - Register Access |
Delta |
0xE |
16 bit Delta required to reach custom option |
Length |
0x1 |
1 byte Register Access Option Value |
|
D - 269 |
0x?? |
Pending final option number assignment |
|
Count |
0b(cnt) |
5 bit Register Access Count |
|
Type |
0b(type) |
3 bit Register Access Type |
|
Option - Binary Address |
Delta |
0x4(? |
(Expect Binary Address Option number to be near Register Access option) |
Length |
0x1-0x4 |
For 1-4 byte address (addr) |
|
D - 269 |
0x?? |
Opt Delta extended value pending option number assignment |
|
Addr |
0x(addr) |
Binary Address |
|
Payload |
- |
No Payload for GET |
|
Total Length |
9-11+ bytes |
(plus Ethernet/IP/UDP headers and padding) |
|
Register Write Request
| Field | Value | Description | |
|---|---|---|---|
Ver |
0b01 |
Standard CoAP |
|
T |
0b00 |
Confirmable |
|
TKL |
0b0000 |
No Token required |
|
Code |
0x03 |
0.03 - Request . PUT |
|
Message ID |
0x???? |
Set by host, matched by device in response |
|
Token |
- |
Optional, no token required |
|
Option - Register Access |
Delta |
0xE |
16 bit Delta required to reach custom option |
Length |
0x1 |
1 byte Register Access Option Value |
|
D - 269 |
0x?? |
Option Delta extended value pending option number assignment |
|
Count |
0b(cnt) |
5 bit Register Access Count |
|
Type |
0b(type) |
3 bit Register Access Type |
|
Option - Binary Address |
Delta |
0x4(?) |
(Expect Binary Address Option number to be near Register Access option) |
Length |
0x1-0x4 |
For 1-4 byte for address (addr) |
|
D - 269 |
0x?? |
Delta value pending option number assignment |
|
Addr |
0x(addr) |
Binary Address |
|
Payload Marker |
0xFF |
||
Payload |
0xVVVVVVVV |
Contiguous 32-bit write values for requested registers in order of request |
|
Total Length |
13+ bytes |
(plus Ethernet/IP/UDP headers and padding) |
|
Register Read Response (successful)
| Field | Value | Description | |
|---|---|---|---|
Ver |
0b01 |
Standard CoAP |
|
T |
0b00 |
Confirmable |
|
TKL |
- |
Matches request token length |
|
Code |
0x15 |
2.05 - Success.Content |
|
Message ID |
0x???? |
Matches request Message ID |
|
Token |
- |
Matches request token content |
|
Payload Marker |
0xFF |
||
Payload |
0xVVVVVVVV |
List of 32-bit register values for requested registers, in order of request |
|
Total Length |
9+ bytes |
(plus Ethernet/IP/UDP headers and padding) |
|
Register Write Response (successful)
| Field | Value | Description | |
|---|---|---|---|
Ver |
0b01 |
Standard CoAP |
|
T |
0b00 |
Confirmable |
|
TKL |
- |
Matches request token length |
|
Code |
0x15 |
2.04 - Success.Changed |
|
Message ID |
0x???? |
Matches request Message ID |
|
Token |
- |
Matches request token content |
|
Total Length |
4 bytes |
(plus Ethernet/IP/UDP headers and padding) |
|
Error Responses
All error responses shall follow standard CoAP response codes and shall be confirmable. The following codes are defined for EEVideo:
| Code | Name | EEVideo Meaning |
|---|---|---|
0x80 |
4.00 Bad Request |
Malformed packet, unknown option, or invalid Register Access Type/Count |
0x84 |
4.04 Not Found |
Register address is outside the supported range or device does not implement the requested feature |
0x85 |
4.05 Method Not Allowed |
Attempted write to a read-only register |
0x8F |
4.15 Unsupported Content-Format |
(reserved for future use) |
0xA0 |
5.00 Internal Server Error |
Device-side error (e.g. FIFO underflow during read) |
0xA1 |
5.01 Not Implemented |
Requested feature or access type not supported in this firmware version |
The response may include a human-readable diagnostic payload (UTF-8 string). The Binary Address Option shall be echoed back in the error response so the host knows which register caused the failure.
Examples
Reading a Single Register
Host → Device (GET):
-
Register Access Option = 0b000.00001 (type 0, count 1)
-
Binary Address Option = 0x00000010 (register 0x10)
Device → Host (2.05 Content):
-
Payload = 32-bit value of register 0x10