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 there are known data items appearing later in the same CDP packet.
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 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. |
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 is used to report the 3 dimensional position of the reporting device.
| Field Name | Byte Length | Description |
|---|---|---|
| SERIAL NUMBER | 4 | The serial number of the reporting device. |
| 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 | 2 | The quality of the computed position, with 0 being an assessment of poor quality and 10,000 being an assessment of perfect quality. |
| ANCHOR COUNT | 1 | The number of anchors involved in the calculation of this position. |
| FLAGS | 1 | Reserved for future use. |
| SMOOTHING | 2 | The effective smoothing factor (the number of positions averaged minus 1). |
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 |
|---|---|---|
| TAG SERIAL NUMBER | 4 | The serial number of the tag. |
| NETWORK TIME | 8 | The network time of the position. |
| ANCHOR STATUS ARRAY | X | Array of Anchor Status Structures. See Anchor Status Structure for details. |
The ANCHOR STATUS ARRAY field in the Position’s Anchor Status data item is an array of these Anchor Status Structures.
| 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 synchronized |
| 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 current state of a device on the network.
| 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) for the last known position of the device. |
| ROLE ID | 1 | The identifier for the role this device is currently functioning as. Pair with the Role Report to match this identifier to the role’s name. |
| CONNECTIVITY STATE | 1 | See Device Connectivity State for details. |
| SYNCHRONIZATION STATE | 1 | See Device Synchronization State for details. |
This is a listing of what the bits in the CONNECTIVITY STATE field represent, starting from the lowest bit. Any bits not listed are currently unused.
| Bit Position | Flag | Description |
|---|---|---|
| 0 | Ethernet | Set to 1 when the device has ethernet connectivity to the CUWB Network Application. |
| 1 | UWB | Set to 1 when the device has UWB connectivity to the rest of the CUWB Network. |
This is a listing of what the bits in the SYNCHRONIZATION STATE field represent, starting from the lowest bit. Any bits not listed are currently unused.
NOTE: The only devices with a synchronization state are anchors. Thus, this field can be ignored for tags.
| Bit Position | Flag | Description |
|---|---|---|
| 0 | TX | Set to 1 when the device is Transmit Synchronized, which indicates that it can be used to spread synchronization to other anchors. |
| 1 | RX | Set to 1 when the device is Receive Synchronized, which indicates that it can be used in tag position calculations. |
This data type contains information about the current states of a device.
| Field Name | Byte Length | Description |
|---|---|---|
| SERIAL NUMBER | 4 | The serial number of the reporting device. |
| MEMORY | 4 | How much memory is free on the device. |
| FLAGS | 4 | See Device Hardware 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 Hardware 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 |
|---|---|---|
| SERIAL NUMBER | 4 | The serial number of the reporting device. |
| 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 |
|---|---|---|
| SERIAL NUMBER | 4 | The serial number of the reporting device. |
| 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 |
|---|---|---|
| SERIAL NUMBER | 4 | The serial number of the reporting device. |
| 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 |
|---|---|---|
| SERIAL NUMBER | 4 | The serial number of the reporting device. |
| 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 |
|---|---|---|
| SERIAL NUMBER | 4 | The serial number of the reporting device. |
| 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 |
|---|---|---|
| SERIAL NUMBER | 4 | The serial number of the reporting device. |
| 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 device names.
| Field Name | Byte Length | Description |
|---|---|---|
| SERIAL NUMBER | 4 | The serial number of the device. |
| NAME | X | The name of the device provide in the CUWB Manager. |
This data type is used to report current synchronization counts.
| Field Name | Byte Length | Description |
|---|---|---|
| MAX TX SYNC COUNT | 2 | The maximum possible number of anchors that can be Transmit Synchronized on this network. |
| CURRENT TX SYNC COUNT | 2 | The current number of anchors that are Transmit Synchronized on this network. |
| MAX RX SYNC COUNT | 2 | The maximum possible number of anchors that can be Receive Synchronized on this network. |
| CURRENT RX SYNC COUNT | 2 | The current number of anchors that are Receive Synchronized on this network. |
This data type is used to track the number of devices on a particular role.
| Field Name | Byte Length | Description |
|---|---|---|
| ROLE ID | 2 | The identifier of the given role. |
| MAX QUANTITY | 2 | The maximum number of devices that are configured to the given role. |
| ACTIVE QUANTITY | 2 | The current number of devices that are actively participating in the network as a member of the given role. |
| ROLE NAME | X | The name of the given role. |
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. |
| BEACONS LATE | 4 | The total quantity of tag beacons that were late 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. |
| INTER-ANCHOR COMMS ERROR CODE | 1 | See Inter Anchor Comms Error Code for details. |
| BAD PAIRED ANCHORS | X | An array of Full Device ID structures. These specify the neighboring anchors that this anchor is having trouble communicating with. |
Indicates whether there are any problems with inter-anchor communications involving this anchor. Any neighboring anchors involved in poor communications with this anchor are listed in the BAD PAIRED ANCHORS array. The error code will give an indication as to the severity of the current communications problems. Possible error codes are as follows:
| Error Code | Name | Description |
|---|---|---|
| 0 | No Error | The anchor appears to be successfully communicating with all of its neighbors. |
| 1 | Blacklisting | This anchor has poor comms to some of its neighbors. It is recommended that blacklist pairs are created between this anchor and all of the BAD PAIRED ANCHORS so they do not hinder each other’s performance. |
| 2 | Bad Survey | This anchor has poor comms to all of its neighbors. This is most often caused by poor survey, so it is recommended that the device is re-surveyed. If it has a proper survey, then the next most likely cause of this issue is some sort of UWB interference, for which the recommended solution is to move the device to a new location in order to avoid the interferer. |
This structure specifies the full identifier for a device, including both its serial number and interface identifier.
| Field Name | Byte Length | Description |
|---|---|---|
| SERIAL NUMBER | 4 | The serial number of the device. |
| INTERFACE IDENTIFIER | 1 | The identifier of the interface of the device. |
This data type is used to track the amount of relative delay between ping receptions from different anchors for the same tag transmission.
| Field Name | Byte Length | Description |
|---|---|---|
| INITIAL PING COUNT | 4 | The number of starting pings that were received (and thus the number of positions that were calculated). |
| POSITION CALCULATION DELAY | 4 | Time from reception of initial ping to start of position calculation. |
| ARRIVAL TIME COUNTS | 4 * 1001 | An array of 1001 counters that track the number of pings that were received X msec after the initial ping, where the index in the array is X-1. For example, all pings that arrived within 1 msec of the initial ping will be at index 0, pings within 2 msec will be at index 1, etc. Index 1000 represents all pings that were received at least 1 full second later than the initial ping. |
This data type is emitted by an anchor when it receives another anchor’s Network Time Synchronization packet over UWB. The serial number in the CDP Packet header will be the serial number of the receiving anchor.
NOTE: This data item is only emitted on the internal CDP stream.
| Field Name | Byte Length | Description |
|---|---|---|
| TX NETWORK TIME | 8 | The Global Network Time at which the UWB Packet was transmitted. |
| RX DECAWAVE TIME | 8 | The Decawave Time at which the UWB Packet was received. |
| RX NETWORK TIME | 8 | The Global Network Time at which the UWB Packet was received. |
| SOURCE SERIAL NUMBER | 4 | The serial number of the anchor that transmitted the UWB Packet. |
| SOURCE INTERFACE IDENTIFIER | 1 | Identifier of the interface from which the transmitting anchor transmitted the UWB Packet. |
| SIGNAL STRENGTH | 12 | See Signal Strength for details. |
| INTERFACE IDENTIFIER | 1 | Identifier of the interface on which the receiving anchor received the UWB Packet. |
| TX NETWORK TIME QUALITY | 1 | The quality of the Network Time Synchronization of the transmitting anchor at the time of its transmission. |
| RX NETWORK TIME QUALITY | 1 | The quality of the Network Time Synchronization of the receiving anchor at the time of its reception. |
| RX PACKET TYPE | 1 | The type of UWB Packet received. |
This data type is emitted by an anchor when it transmits a Network Time Synchronization packet. The serial number in the CDP Packet header will be the serial number of the transmitting anchor.
NOTE: This data item is only emitted on the internal CDP stream.
| Field Name | Byte Length | Description |
|---|---|---|
| NETWORK TIME | 8 | The Global Network Time at which this Network Time Packet was transmitted. |
| DECAWAVE TIME | 8 | The Decawave Time at which this Network Time Packet was transmitted. |
| NETWORK TIME QUALITY | 1 | The quality of the Network Time Synchronization of the anchor at the time of this transmittion. |
| INTERFACE IDENTIFIER | 1 | The identifier for the interface through which the device transmitted this Network Time Packet. |
This data type is emitted by an anchor when it receives a tag’s UWB Beacon. The serial number in the CDP Packet header will be the serial number of the receiving anchor.
NOTE: This data item is only emitted on the internal CDP stream.
| Field Name | Byte Length | Description |
|---|---|---|
| SOURCE SERIAL NUMBER | 4 | The serial number of the tag that transmitted the UWB Beacon. |
| SEQUENCE | 2 | The rolling sequence number of the Beacons emitted by the tag. |
| BEACON TYPE | 1 | There are several Beacon types which effect various properties of the UWB Beacon, such as the UWB packet length. NOTE: This does not effect the length of the Ping. |
| RX NETWORK TIME QUALITY | 1 | The quality of the Network Time Synchronization of the anchor at the time of the reception of this UWB Beacon. |
| RX DECAWAVE TIME | 8 | The Decawave Time at which the UWB Beacon was received at this anchor. |
| RX NETWORK TIME | 8 | The Global Network Time at which the UWB Beacon was received at this anchor. |
| SIGNAL STRENGTH | 12 | See Signal Strength for details. |
| INTERFACE IDENTIFIER | 1 | Identifier of the interface on which this anchor received the UWB Beacon. |
| PAYLOAD | X | Additional data received in the UWB Beacon. |