• CUWB 3.3 (Bernoulli)
Ciholas Data Protocol

# Overview

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.

# Data Format

## Endianess

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.

## Scale Conversion

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. $\frac{value\cdot scale}{maxint}$

Value Size Max Int
1 127
2 32767
4 2147483647

## CDP Packet Structure

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.

## Data Items

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

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.

#### Cartesian Coordinates

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.

#### Signal Strength

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.

# Unknown Data Items

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.

# Known Data Items

## 0x010D - Node Status Change V2

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

## 0x011A - CDP Stream Information

This datatype is used to send the information that defines a stream the server is using.

Field Name Byte Length Description
DESTINATION PORT 2 The port of this stream.
INTERFACE IP 4 The interface ip address 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.

## 0x011B - Hostname Announce

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.

## 0x011C - Instance Announce

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.

## 0x0127 - Distance V2

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.

## 0x0135 - Position V3

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).

## 0x0136 - Position’s Anchor Status V3

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.

### Anchor Status Structure

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

## 0x0137 - Device Activity State

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.

### Device Connectivity State

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.

### Device Synchronization State

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.

## 0x0138 - Device Hardware Status V2

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.

### Device Hardware Status Flags

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

### Device Hardware Status Error Patterns

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

## 0x0139 - Accelerometer V2

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.

## 0x013A - Gyroscope V2

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.

## 0x013B - Magnetometer V2

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.

## 0x013C - Pressure V2

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.

## 0x013D - Quaternion V2

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 $\frac{1}{\sqrt{x^{2}+y^{2}+z^{2}+w^{2}}}$

## 0x013E - Temperature V2

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.

## 0x013F - Device Names

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.

## 0x0140 - Synchronization

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.

## 0x0141 - Role Report

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.

## 0x014A - Anchor Health Information V5

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.

### Inter Anchor Comms Error Code

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.

### Full Device ID

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.

## 0x014C - Global Ping Timing Report V1

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.

## 0x802C - Timed Reception V5

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.

## 0x802D - Tick V4

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.

## 0x802F - Ping V5

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.

# Revision History

## 2018-12-05

• Compatible with CUWB Network Bernoulli 3.3 and greater
• New types:
• 0x014A - Anchor Health Information V5
• 0x014C - Global Ping Timing Report V1
• Deprecated types:
• 0x0125 - Replaced by 0x014A

## 2018-09-03

• Compatible with CUWB Network Bernoulli 3.2 to 3.3
• New types:
• 0x0125 - Anchor Health Information V4
• 0x0135 - Position V3
• 0x0136 - Position’s Anchor Status V3
• 0x0137 - Device Activity State V5
• 0x0138 - Device Hardware Status V2
• 0x0139 - Accelerometer V2
• 0x013A - Gyroscope V2
• 0x013B - Magnetometer V2
• 0x013C - Pressure V2
• 0x013D - Quaternion V2
• 0x013E - Temperature V2
• 0x013F - Device Names
• 0x0140 - Synchronization
• 0x0141 - Role Report
• 0x802C - Timed Reception V5
• 0x802D - Tick V4
• 0x802F - Ping V5
• Deprecated types:
• 0x0007 - Removed
• 0x00FD - Removed
• 0x0102 - Replaced by 0x0111
• 0x0104 - Removed
• 0x0107 - Replaced by 0x0111
• 0x010E - Replaced by 0x0136
• 0x0111 - Replaced by 0x0137
• 0x0123 - Removed
• 0x0124 - Removed
• 0x0126 - Removed
• 0x0128 - Replaced by 0x0138
• 0x0129 - Replaced by 0x0139
• 0x012A - Replaced by 0x013A
• 0x012B - Replaced by 0x013B
• 0x012C - Replaced by 0x013C
• 0x012D - Replaced by 0x013D
• 0x012E - Replaced by 0x013E
• 0x012F - Replaced by 0x0135
• 0x0130 - Removed

## 2018-04-20

• Compatible with CUWB Network Bernouli 3.0 to 3.1
• New types:
• 0x0104 - Announcement Status V1
• 0x0107 - Infrastructure Position V2
• 0x010D - Node Status Change V2
• 0x010E - Anchor Position Status V2
• 0x0111 - Infrastructure Position V4
• 0x011A - CDP Stream Information
• 0x011B - Hostname Announce
• 0x011C - Instance Announce
• 0x0123 - Magnetometer Calibration
• 0x0124 - Anchor Health Information V3
• 0x0126 - Magnetometer Calibration Response
• 0x0127 - Distance V2
• 0x0128 - Device Status
• 0x0129 - Accelerometer V1
• 0x012A - Gyroscope V1
• 0x012B - Magnetometer V1
• 0x012C - Pressure V1
• 0x012D - Quaternion V1
• 0x012E - Temperature V1
• 0x012F - Position V2
• Deprecated types:
• 0x0003 - Replaced by 0x012B
• 0x0005 - Replaced by 0x012C
• 0x0006 - Replaced by 0x012E
• 0x0008 - Replaced by 0x0129
• 0x0009 - Replaced by 0x012A
• 0x000A - Replaced by 0x012D
• 0x0100 - Replaced by 0x012F
• 0x0101 - Replaced by 0x0127
• 0x0103 - Replaced by 0x010E

## 2016-07-15

• Initial release of documentation
• Compatible with CUWB Server Archimedes release 2.0
• New types:
• 0x0007 - User Defined V1
• 0x00FD - Log Message V1
• 0x0100 - Position V1
• 0x0101 - Distance V1
• 0x0102 - Infrastructure Position V1
• 0x0103 - Anchor Status V1
• 0x0104 - Announcement Status V1
• Deprecated types:
• 0x0001 - Replaced by 0x0008
• 0x0002 - Replaced by 0x0009
• 0x0004 - Replaced by 0x000A