The Ciholas Data Protocol (CDP) provides a method of communication between devices and services. CDP data is transmitted over ethernet as User Datagram Protocol (UDP) packets. Ciholas Real-Time Location Systems (RTLS) emit position data using the CDP format as an accessible way for users to gain access to the data and integrate their software.
CDP packets are transmitted through CDP Streams. CDP Streams are identified by the Ethernet interface, IP address, and Port through which the packet is sent. Streams are allowed to be both multicast and unicast. Different CDP Streams may be defined to distinguish different categories or classes of data.
All CDP numerical fields of length 2, 4, and 8 bytes are transmitted using little-endian format. NOTE: CDP does not utilize network byte order. The CDP format utilizes little-endian format in order to reduce overhead and complexity when transmitting or receiving packets. The overall effect is decreased processor usage as well as increasing confidence for developers through eliminating the need to byte swap data before usage.
CDP fields containing ASCII strings are not byte-swapped.
When a scale value is supplied for a 2s compliment field, the scale value represents the maximum value in the given units for the maximum integer. Conversion can be done to get the unit based value with floating point math.
| Value Size | Max Int |
|---|---|
| 1 | 127 |
| 2 | 32767 |
| 4 | 2147483647 |
A CDP Packet is made up of a CDP Packet Header followed a list of CDP Data Items.
| Field Name | Byte Length | Description |
|---|---|---|
| MARK | 4 | The 4 byte magic word (0x3230434C in little endian). |
| SEQUENCE | 4 | The sequence number of the CDP packet. The sequence number is incremented on every transmission from a given CDP Stream. |
| STRING | 8 | An ASCII string of “CDP0002” with a null terminator. |
| SERIAL NUMBER | 4 | The unique ID of the reporting device. If the reporting device does not have a serial number or it is unknown, 0 is used. |
All CDP Data Items start with a 4 byte CDP Data Item Header followed by 0 to 65535 bytes of data.
| Field Name | Byte Length | Description |
|---|---|---|
| TYPE | 2 | The type of the CDP Data Item. |
| SIZE | 2 | The size of the Data Item not including the Data Item Header. |
Shared structures are combinations of data that are commonly found in a CDP data items. The following definitions are combinations of data that are commonly used within the CDP Data Items.
This shared structure contains the X, Y, and Z coordinates for location data.
| Field Name | Byte Length | Description |
|---|---|---|
| X | 4 | The distance in millimeters from the location along the X axis. This value is a signed two’s complement integer. |
| Y | 4 | The distance in millimeters from the location along the Y axis. This value is a signed two’s complement integer. |
| Z | 4 | The distance in millimeters from the location along the Z axis. This value is a signed two’s complement integer. |
This shared structure contains the receive signal strength information supplied by the Decawave chip on a UWB reception. This is used in the calculation of signal strength and signal quality.
| Field Name | Byte Length | Description |
|---|---|---|
| FP AMPL1 | 2 | The First Path Amplitude 1 of the reception. |
| FP AMPL2 | 2 | The First Path Amplitude 2 of the reception. |
| FP AMPL3 | 2 | The First Path Amplitude 3 of the reception. |
| RXPACC | 2 | The Received Preamble Accumulation of the reception. |
| CIR POWER | 2 | The Channel Impulse Response Power of the reception. |
| STD NOISE | 2 | The Standard Noise of the reception. |
CDP Streams may contain data items not documented here. These data items should be skipped over in case they are encountered, so that subsequent data items can be safely parsed.