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.
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. |
CDP Streams may contain data items not documented here. These data items should be skipped over in case there are known data items appearing later in the same CDP packet.
This data type is used to report the magnetometer data from an onboard MPU-9250.
| Field Name | Byte Length | Description |
|---|---|---|
| X | 2 | The raw X magnetometer value. Please consult the datasheet for the MPU-9250 for more information. |
| Y | 2 | The raw Y magnetometer value. Please consult the datasheet for the MPU-9250 for more information. |
| Z | 2 | The raw Z magnetometer value. Please consult the datasheet for the MPU-9250 for more information. |
| NETWORK TIME | 4 | The timestamp when the MPU-9250 recorded the data. This value is represented in Network Time, which is roughly 1.026 microseconds per tick. |
This data type is used to report the pressure measured by an onboard LPS25H.
| Field Name | Byte Length | Description |
|---|---|---|
| PRESSURE | 4 | The raw pressure value. To convert this value to mBar, use the equation x / 4096 where x is the reported pressure value. See LPS25H datasheet for further detail. |
| NETWORK TIME | 4 | The timestamp when the LPS25H recorded the data. This value is represented in Network Time, which is roughly 1.026 microseconds per tick. |
This data type is used to report the temperature measured by an onboard LPS25H.
| Field Name | Byte Length | Description |
|---|---|---|
| TEMPERATURE | 2 | The raw temperature value. To convert this value to Celsius, use the equation 42.5 + x / 480 where x is the reported temperature value. See LPS25H datasheet for further detail. |
| NETWORK TIME | 4 | The timestamp when the LPS25H recorded the data. This value is represented in Network Time, which is roughly 1.026 microseconds per tick. |
This data type is used to report any user defined data bytes.
| Field Name | Byte Length | Description |
|---|---|---|
| User Defined Data | X | The format of the contents are defined by the user. It is suggested that the user sends a sequence number within this data to help with detection of lost data. |
This data type is used to report the accelerometer data from an onboard MPU-9250.
| Field Name | Byte Length | Description |
|---|---|---|
| X | 2 | The raw X accelerometer value (per network configured scale). Please consult the datasheet for the MPU-9250 for more information. |
| Y | 2 | The raw Y accelerometer value (per network configured scale). Please consult the datasheet for the MPU-9250 for more information. |
| Z | 2 | The raw Z accelerometer value (per network configured scale). Please consult the datasheet for the MPU-9250 for more information. |
| NETWORK TIME | 4 | The timestamp when the MPU-9250 recorded the data. This value is represented in Network Time, which is roughly 1.026 microseconds per tick. |
| Scale | 1 | The MPU-9250 full-scale representations in Gs. Valid values for the MPU-9250 currently are 2, 4, 8, and 16. |
| DLPF Rate | 2 | The MPU-9250 DLPF rate in Hz. Valid values for the MPU-9250 currently are 5, 10, 20, 41, 92, 184, and 460. |
This data type is used to report the gyroscope data from an onboard MPU-9250.
| Field Name | Byte Length | Description |
|---|---|---|
| X | 2 | The raw X gyroscope value (per network configured scale). Please consult the datasheet for the MPU-9250 for more information. |
| Y | 2 | The raw Y gyroscope value (per network configured scale). Please consult the datasheet for the MPU-9250 for more information. |
| Z | 2 | The raw Z gyroscope value (per network configured scale). Please consult the datasheet for the MPU-9250 for more information. |
| NETWORK TIME | 4 | The timestamp when the MPU-9250 recorded the data. This value is represented in Network Time, which is roughly 1.026 microseconds per tick. |
| Scale | 2 | The MPU-9250 full-scale representations in Degrees Per Second. Valid values for the MPU-9250 currently are 250, 500, 1000, and 2000. |
| DLPF Rate | 1 | The MPU-9250 DLPF rate in Hz. Valid values for the MPU-9250 currently are 5, 10, 20, 41, 92, and 184. |
This data type is used to report quaternion data from an onboard MPU-9250.
| Field Name | Byte Length | Description |
|---|---|---|
| X | 4 | The raw X quaternion value. Please consult the datasheet for the MPU-9250 for more information. |
| Y | 4 | The raw Y quaternion value. Please consult the datasheet for the MPU-9250 for more information. |
| Z | 4 | The raw Z quaternion value. Please consult the datasheet for the MPU-9250 for more information. |
| W | 4 | The raw W quaternion value. Please consult the datasheet for the MPU-9250 for more information. |
| NETWORK TIME | 4 | The timestamp when the MPU-9250 recorded the data. This value is represented in Global Network Time, which is roughly 1.026 microseconds per tick. |
This data type is used to transmit debug information. The messages can originate from the firmware, cuwb_server, or some other application.
| Field Name | Byte Length | Description |
|---|---|---|
| Log Level | 3b | Using the SysLog Severity levels of: 0 - Emergency 1 - Alert 2 - Critical 3 - Error 4 - Warning 5 - Notice 6 - Informational 7 - Debug |
| Identifier | 13b | Unique message identifier. Identifiers 0-999 are reserved for use by Ciholas. |
| Message | X | An ASCII string. The string may or may not be NULL terminated at the discretion of the sender. |
This data type is used to report the 3 dimensional position of the reporting device.
| Field Name | Byte Length | Description |
|---|---|---|
| COORDINATES | 12 | The coordinates from the origin (0, 0, 0). |
| QUALITY | 4 | Currently unused. |
| SMOOTHING | 2 | The effective smoothing factor (the number of positions averaged minus 1) |
| SEQUENCE | 2 | The sequence number of the packet from the reporting device that was used to calculate the position. This is helpful in determining if any packets have been missed. NOTE: Currently the sequence number is stored as a one byte number, so this will wrap at 255. The CDP will represent the sequence number as two bytes for future compatibility. |
| NETWORK TIME | 4 | The calculated timestamp of the transmission of the packet from the reporting device used to calculate the position. This value is represented in Network Time, which is roughly 1.026 microseconds per tick |
This data type is used to report the distance between the reporting device and a reflector device.
| Field Name | Byte Length | Description |
|---|---|---|
| REFLECTOR SERIAL NUMBER | 4 | The unique ID of the reflector device. |
| DISTANCE | 4 | The distance between the 2 devices in millimeters. This value is a signed two’s complement integer. |
| FIRST PATH | 2 | The first path signal quality in millibels. This value is a signed two’s complement integer. |
| TOTAL PATH | 2 | The total path signal quality in millibels. This value is a signed two’s complement integer. |
| SEQUENCE | 2 | The sequence number of the packet from the CUWB Server that was used to calculate the distance. This is helpful in determining if any packets have been missed. NOTE: Currently the sequence number is stored as a one byte number, so this will wrap at 255. The CDP will represent the sequence number as two bytes for future compatibility. |
| NETWORK TIME | 4 | The calculated timestamp of when the reflector device received the final packet of the TWR process. This value is represented in Network Time, which is roughly 1.026 microseconds per tick |
This data type is used to report the 3 dimensional position of a stationary device.
| Field Name | Byte Length | Description |
|---|---|---|
| NODE TYPE | 1 | Seeder = 0x01 Anchor = 0x02 |
| SERIAL NUMBER | 4 | The Infrastructure Node’s Serial Number |
| COORDINATES | 12 | The coordinates from the origin (0, 0, 0). |
This data type is used to report how a device configuration request was handled.
| Field Name | Byte Length | Description |
|---|---|---|
| DEVICE SERIAL NUMBER | 4 | The serial number of the device. |
| STATUS | 1 | 0 = Device configured as UWB Anchor 1 = Device configured as wired Anchor 2 = Device configured as Tag 3 = Device disabled [Note: Currently unused] 4 = Device not in configuration 5 = Not enough airtime to schedule the device 6 = The device is known to belong to another network 7 = Not enough room remaining in the Anchor reports |