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. |
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 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 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 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 |
This data type is used to report the 3 dimensional position of a stationary device.
| Field Name | Byte Length | Description |
|---|---|---|
| SERIAL NUMBER | 4 | The Infrastructure Node’s Serial Number |
| COORDINATES | 12 | The coordinates from the origin (0, 0, 0). |
| NODE TYPE | 1 | Seeder = 0x01 Anchor = 0x02 |
| NODE STATUS | 1 | Inactive = 0x01 Active = 0x02 |
This data type is used to report when the status for a node has changed.
| Field Name | Byte Length | Description |
|---|---|---|
| NODE SERIAL NUMBER | 4 | The serial number of the node. |
| NODE INTERFACE IDENTIFIER | 1 | The interface identifier of the node. |
| NODE STATUS | 1 | Inactive = 0x01 |
This data type is used to report the status of an anchor that provided location data about the reporting device.
| Field Name | Byte Length | Description |
|---|---|---|
| ANCHOR SERIAL NUMBER | 4 | The serial number of the anchor. |
| ANCHOR INTERFACE IDENTIFIER | 1 | The interface identifier of the anchor. |
| STATUS | 1 | 0 = Anchor data is good 1 = Anchor is unknown 2 = Anchor data does not match other anchors 3 = Anchor data is inconsistent with previous data 4 = Network Time not locked |
| 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. |
| QUALITY | 2 | A number from 0 to 10000, with 0 being poor quality, 10000 being high quality |
This data type is used to report the 3 dimensional position of a stationary device.
| Field Name | Byte Length | Description |
|---|---|---|
| SERIAL NUMBER | 4 | The Infrastructure Node’s Serial Number |
| INTERFACE IDENTIFIER | 1 | The infrastructure node’s interface identifier. |
| COORDINATES | 12 | The coordinates from the origin (0, 0, 0). |
| NODE TYPE | 1 | Seeder = 0x01 Anchor = 0x02 |
| NODE ACTIVE STATE | 1 | Inactive = 0x01 Active = 0x02 |
| NODE LOCK STATE | 1 | Unlocked = 0x01 Locked = 0x02 |
This datatype is used to send the information that defines a stream the server is using.
| Field Name | Byte Length | Description |
|---|---|---|
| DESTINATION IP ADDRESS | 4 | The IP address of this stream. |
| DESTINATION PORT | 2 | The port of this stream. |
| INTERFACE IP | 4 | The interface ip address for this stream. |
| INTERFACE NETMASK | 4 | The interface netmask for this stream. |
| INTERFACE PORT | 2 | The interface/listening port being used by the net app. 0 indicates this field is not being used. |
| TTL | 1 | The ttl of this stream. |
| STREAM NAME | X | The name for this stream. |
This datatype is used to send the hostname of the computer that is running the server.
| Field Name | Byte Length | Description |
|---|---|---|
| HOSTNAME | X | The hostname of the sending computer. |
This datatype is used to send the instance name (name of database file) for the server.
| Field Name | Byte Length | Description |
|---|---|---|
| INSTANCE NAME | X | The instance name (name of database file) for the sending net app. |
Tells the server to send the magnetometer calibration values to a device.
| Field Name | Byte Length | Description |
|---|---|---|
| SERIAL NUMBER | 4 | The serial number of the device the calibrations are for. |
| CALIBRATION X | 2 | Signed two byte calibration value for the X axis |
| CALIBRATION Y | 2 | Signed two byte calibration value for the Y axis |
| CALIBRATION Z | 2 | Signed two byte calibration value for the Z axis |
This data type is used to report the health of anchors in the network.
| Field Name | Byte Length | Description |
|---|---|---|
| ANCHOR SERIAL NUMBER | 4 | The serial number of the anchor. |
| ANCHOR INTERFACE IDENTIFIER | 1 | The interface identifier of the anchor. |
| TICKS REPORTED | 4 | The total quantity of anchor ticks that were reported by the anchor since the last Anchor Health Information. |
| TIMED RXS REPORTED | 4 | The total quantity of anchor timed rxs that were reported by the anchor since the last Anchor Health Information. |
| BEACONS REPORTED | 4 | The total quantity of tag beacons that were reported by the anchor since the last Anchor Health Information. |
| BEACONS DISCARDED | 4 | The total quantity of tag beacons that were discarded from the anchor since the last Anchor Health Information. |
| AVERAGE QUALITY | 2 | The average of the quality number from 0 to 10,000; with 0 being poor quality, 10,000 being high quality for the anchor since the last Anchor Health Information. |
| REPORT PERIOD | 1 | Period of the packet in seconds. |
Wired Device response after receiving a set magnetometer calibration command.
| Field Name | Byte Length | Description |
|---|---|---|
| CALIBRATION X | 2 | Signed two byte calibration value for the X axis |
| CALIBRATION Y | 2 | Signed two byte calibration value for the Y axis |
| CALIBRATION Z | 2 | Signed two byte calibration value for the Z axis |
This data type is used to transmit the distance data from two devices.
| Field Name | Byte Length | Description |
|---|---|---|
| SERIAL NUMBER 1 | 4 | The serial number of the first device. |
| SERIAL NUMBER 2 | 4 | The serial number of the second device. |
| INTERFACE IDENTIFIER 1 | 1 | The interface identifier of the first device. |
| INTERFACE IDENTIFIER 2 | 1 | The interface identifier of the second device. |
| RX TIMESTAMP | 8 | Time at which the last packet was received. |
| DISTANCE | 4 | The distance, in millimeters, between the two devices. |
| QUALITY | 2 | The quality of the computed distance. |
This data type contains information about the current states of a device.
| Field Name | Byte Length | Description |
|---|---|---|
| MEMORY | 4 | How much memory is free on the device. |
| FLAGS | 4 | See Device Status Flags for details. |
| MINUTES REMAINING | 2 | When charging (FLAGS.Charging=1) this indicates the estimate of minutes until the device is fully charged. When discharging (FLAGS.charging=0) this indicates the estimate of minutes until the device is fully discharged. When 65535, the time remaining is unknown. |
| BATTERY PERCENTAGE | 1 | Percentage of battery charge left from 0-100. A value of 255 means no measurable battery is present. |
| TEMPERATURE | 1 | 2s compliment temperature in degrees Celsius. |
| PROCESSOR USAGE | 1 | Percentage of processor usage from 0-100. A value of 255 represents an unknown value. |
| ERROR PATTERN | X | Array of current error states by their LED pattern. See Device Status Error Patterns for details. |
This is a listing of what the bits in the flags field represent, starting from the lowest bit. Any bits not listed are currently unused.
| Bit Position | Flag | Description |
|---|---|---|
| 0 | Powered | Set to 1 when the device has power from an external source |
| 1 | Charging | Set to 1 when the device is charging the battery |
The ERROR PATTERN field is an array of patterns. Each pattern is a single byte made of three 2-bit color codes. The patters correspond the to the Errors being indicated by the devices LEDs.
| Error Pattern | |||||||
|---|---|---|---|---|---|---|---|
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
| RES | C1 | C2 | C3 | ||||
| Field | Length | Description |
|---|---|---|
| RES | 2 bits | Reserved |
| C1 | 2 bits | The first color code |
| C2 | 2 bits | The second color code |
| C3 | 2 bits | The third color code |
| Color Code | Color |
|---|---|
| 0 | White |
| 1 | Yellow |
| 2 | Blue |
| 3 | Green |
This data type is used to report the accelerometer data from an onboard MPU-9250.
| Field Name | Byte Length | Description |
|---|---|---|
| NETWORK TIME | 8 | The timestamp when the sensor recorded the data. This value is represented in Network Time, which is roughly 15.65 picoseconds per tick. |
| X | 4 | The 2s compliment X accelerometer value. |
| Y | 4 | The 2s compliment Y accelerometer value. |
| Z | 4 | The 2s compliment Z accelerometer value. |
| SCALE | 1 | The full-scale representations in Gs. |
See Scale Conversion for details on how to interpret the X, Y, and Z values.
This data type is used to report the gyroscope data from an onboard MPU-9250.
| Field Name | Byte Length | Description |
|---|---|---|
| NETWORK TIME | 8 | The timestamp when the sensor recorded the data. This value is represented in Network Time, which is roughly 15.65 picoseconds per tick. |
| X | 4 | The 2s compliement X gyroscope value. |
| Y | 4 | The 2s compliement Y gyroscope value. |
| Z | 4 | The 2s compliement Z gyroscope value. |
| Scale | 2 | The full-scale representations in Degrees Per Second. |
See Scale Conversion for details on how to interpret the X, Y, and Z values.
This data type is used to report the magnetometer data from an onboard MPU-9250.
| Field Name | Byte Length | Description |
|---|---|---|
| NETWORK TIME | 8 | The timestamp when the sensor recorded the data. This value is represented in Network Time, which is roughly 15.65 picoseconds per tick. |
| X | 4 | The 2s compliment X magnetometer value. |
| Y | 4 | The 2s compliment Y magnetometer value. |
| Z | 4 | The 2s compliment Z magnetometer value. |
| Scale | 2 | The full-scale representations in μT |
See Scale Conversion for details on how to interpret the X, Y, and Z values.
This data type is used to report the pressure measured by an onboard LPS25H.
| Field Name | Byte Length | Description |
|---|---|---|
| NETWORK TIME | 8 | The timestamp when the sensor recorded the data. This value is represented in Network Time, which is roughly 15.65 picoseconds per tick. |
| PRESSURE | 4 | The 2s compliment pressure value. |
| SCALE | 4 | The full-scale representation in millibar. |
See Scale Conversion for details on how to interpret the Pressure value.
This data type is used to report quaternion data from an onboard MPU-9250.
| Field Name | Byte Length | Description |
|---|---|---|
| NETWORK TIME | 8 | The timestamp when the sensor recorded the data. This value is represented in Network Time, which is roughly 15.65 picoseconds per tick. |
| X | 4 | The X quaternion value. |
| Y | 4 | The Y quaternion value. |
| Z | 4 | The Z quaternion value. |
| W | 4 | The W quaternion value. |
| NORMALIZED | 1 | 1 for normalized, 0 for unnormalized |
Unnormalized quaternions need to be normalized multiplying X,Y,Z, and W by
This data type is used to report the temperature measured by an onboard LPS25H.
| Field Name | Byte Length | Description |
|---|---|---|
| NETWORK TIME | 8 | The timestamp when the sensor recorded the data. This value is represented in Network Time, which is roughly 15.65 picoseconds per tick. |
| TEMPERATURE | 2 | The 2s compliment temperature value. |
| SCALE | 2 | The full-scale representation in degrees Celsius. |
See Scale Conversion for details on how to interpret the Temperature value.
This data type is used to report the 3 dimensional position of the reporting device.
| Field Name | Byte Length | Description |
|---|---|---|
| NETWORK TIME | 8 | The timestamp when the sensor recorded the data. This value is represented in Network Time, which is roughly 15.65 picoseconds per tick. |
| 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). |
Tells the server to send the gyroscope calibration values to a device.
| Field Name | Byte Length | Description |
|---|---|---|
| SERIAL NUMBER | 4 | The serial number of the device the calibrations are for. |
| CALIBRATION X | 4 | Signed four byte calibration value for the X axis |
| CALIBRATION Y | 4 | Signed four byte calibration value for the Y axis |
| CALIBRATION Z | 4 | Signed four byte calibration value for the Z axis |
| SCALE | 2 | The full-scale representations in Degrees Per Second |