UDP Networking
Introduction
The radar acts as a UDP client/server and therefore can send and receive UDP datagrams. The radar supports a UDP IP address that can be a multicast address and defaults to 239.69.69.69 on port 6317, which, is IANA-allocated to Navtech. The IP addresses and the port are all configurable via the radar management software.
Contents
UDP Message Structure
Each message includes a header of 8 bytes followed by a variable length payload. The header includes the message type and payload size enabling the client software to reliably decode the payload data as required. When sending messages to a radar if the Radar Serial number field is set to 0 then the message is considered a broadcast and all radar will respond. To send a message to specific radar set the serial number to that of the radar that is required to respond.
Typically there are 2 types of payloads;
Byte array representing a structure made up from standard C++ data types
Byte array representing a serialised Protocol Buffer message
Byte arrays that represent both of the above
For more information on Google Protocol Buffers please see reference [https://developers.google.com/protocol-buffers/ ]. Navtech can provide Protobuf message files on request.
All network data is sent in Network Order i.e. big-endian.
The Complete UDP Message Structure
The UDP Message Header
This is the first part of every message sent using this protocol. The provides information about the body of the message.
UDP Message Header Structure
Field | Type [Size] | Description |
|---|---|---|
Version | uint8_t [1] | Protocol version – indicates the revision of the protocol messages |
Message Id | uint8_t [1] | Message type – indicates the type of the payload |
Radar Serial | uint16_t [1] | Serial number of radar only used when receiving will be set to 0 on send |
Payload Size | uint32_t [1] | The size, in bytes, of the main body of the message |
UDP Message Types
Message Name | Message Id | Direction | Description |
|---|---|---|---|
Discovery | 10 | From Radar | Sends minimal radar configuration properties required to connect the client software to correctly receive data |
Update Network Settings | 20 | To Radar | Update network settings on radar and a reboot |
Keep Alive | 30 | From Radar | Keep-alive ping |
Point Cloud | 40 | From Radar | Point-cloud data message |
The UDP Message Body
The body of the message will contain one of the message types outlined in section 2.3.2. This payload will be variable length, the size being specified in the message header. The rest of this document describes the message types.
Discovery Message
The discovery message contains the minimal information a client application needs to connect to the radar. The message provides all critical data in fixed length fields at the beginning of the message. These values are the minimum required in order to successfully connect a client to the TCP server. These fields can be accessed using the normal process of decoding a byte stream coming across the network. The remainder of the message is made up from a variable length Protocol Buffer message which contains additional information about the radar, such as serial numbers and service dates. Advanced customer applications would be expected to decode this message data however the information is optional. The size of this message body is specified by the payload size field in the header. The size of the Protocol Buffer message can be calculated by subtracting the size of the fixed length fields from the payload size (i.e. Payload Size – 22 bytes). A configuration message is always sent when a client first connects and is also sent in response to a request from the client.
Discovery Message Structure
Field | Type [Size] | Description |
|---|---|---|
Azimuth Samples | uint16_t [2] | Number of azimuth samples taken per rotation |
Bin Size / Resolution | uint16_t [2] | The range resolution per bin. In tenths of millimetres. For example 0.2997m would be 2997. |
Range In Bins | uint16_t [2] | Configured detection range, in bins. |
Encoder Size | uint16_t [2] | The total number of available steps on the encoder wheel. |
TCP IP Address | uint8_t [4] | The TCP server IP address e.g. 192.168.0.1 - 192 = [0], 168 = [1] |
TCP Port | uint16_t [2] | The TCP server port. |
Radar Serial | uint16_t [2] | Radar serial number. |
MAC Address | uint8_t [6] | MAC Address e.g. 7E:0C:08:34:0E:19 – 7E = [0], 0C = [1] |
Discovery Protocol Buffer Payload
Field | Type [Size] | Description |
|---|---|---|
Model | RadarModel PB Message | Model information of Radar. |
Max Clients Allowed | uint32_t [4] | Maximum number of clients this radar supports. |
Clients | String list | List of IP addresses connected to the radar. |
Feature Flag | uint32_t [4] | See below for details. |
Has Extended Feature Flags | bool | If true, the radar provides extended feature information. |
Feature Flag layout
The Feature Flag is a 32-bit word. All radars support basic feature information. If the ‘has extended feature flags’ field is true, the radar will also provide additional feature information.
Basic Feature Information
Extended Feature Information
Update Network Settings
The Update Network Settings message contains all of the information required to change the IP settings of the radar. The message provides all critical data in fixed length fields at the beginning of the message. These values are the minimum required in order to successfully configure the IP settings of the radar. These fields can be accessed using the normal process of decoding a byte stream coming across the network.
Update Network Settings Message Structure
Field | Type [Size] | Description |
|---|---|---|
IP Address | uint8_t [4] | The Radar IP address e.g. 192.168.0.1 - 192 = [0], 168 = [1] |
Subnet Mask | uint8_t [4] | The Subnet Mask e.g. 255.254.0.0 - 255 = [0], 254 = [1] |
Gateway | uint8_t [4] | The Gateway IP address e.g. 192.168.0.4 - 192 = [0], 168 = [1] |
Primary DNS | uint8_t [4] | The Primary DNS IP address e.g. 192.168.0.4 - 192 = [0], 168 = [1] |
Secondary DNS | uint8_t [4] | The Secondary DNS address e.g. 192.168.0.4 - 192 = [0], 168 = [1] |
NTP Server | uint8_t [4] | The NTP Server IP address e.g. 192.168.0.4 - 192 = [0], 168 = [1] |
Point Cloud Data
Point Cloud data messages are emitted by the radar if the Point Cloud output is enabled.
A point cloud data message represents one azimuth of data. The message payload consists of zero or more points, which represent a set of radar returns along the azimuth that exceed some configured threshold. The parameters for controlling the point cloud output are controlled via the Navigation Configuration Colossus TCP message.
Point Cloud Data Message Structure
Field | Type [Size] | Description |
|---|---|---|
Azimuth number | uint16_t [2] | The return azimuth number [0 .. (azimuths per rotation - 1)]. |
NTP seconds | uint32_t [4] | The number of seconds since the epoch. |
NTP split seconds | uint32_t [4] | The nanosecond component of the time since the epoch. |
Bearing | float [4] | The azimuth angle, in degrees, from radar North. [0.0 <= bearing < 360.0]. |
Point count | uint8_t [1] | The number of points that exceed the defined threshold. [0 .. max peaks per azimuth] (see Navigation Configuration) |
Points |
| Range/power pairs, as defined below. |
Point Cloud Point Structure
Field | Type [Size] | Description |
|---|---|---|
Range | float [4] | Range, in metres |
Power | float [4] | Power, in dB |
IMU Data
Inertial Measurement Unit (IMU) data is emitted from the radar if the radar has an IMU fitted and enabled.
An IMU message contains linear acceleration, rotational velocity and angular displacement information. The data is output at a fixed frequency of 50Hz. The IMU data is synchronised to the radar’s FFT data via a timestamp and encoder count. The timestamp and encoder account will always match an FFT frame emitted from the radar. This allows the client to align internal measurement data with the radar image data for post-processing.
IMU Data Reference Frames
IMU data is measured relative to the radar as follows:
Measurement | Description |
|---|---|
x | The axis perpendicular to the radar’s back plate, passing through the radar’s axis of rotation. Positive x defines radar ‘North’. |
y | The axis perpendicular to the x axis and the radar’s axis of rotation. Positive y defines radar ‘West’. |
z | The radar’s axis of rotation. Positive z is down. |
φ (phi) - roll | Rotation around the radar’s North-South (x) axis. Positive is roll to starboard. |
θ (theta) - pitch | Rotation around the radar's East-West (y) axis. Positive is radar 'nose down'. |
ψ (psi) - yaw | Rotation around the radar’s z axis. Positive is clockwise. |
IMU Data Message Structure
Field | Type [Size] | Description |
|---|---|---|
Seconds | uint32_t [4] | Timestamp - whole seconds since 00:00 Jan 01 1970. |
Sub-seconds | uint32_t [4] | Timestamp - nanoseconds past the timestamp whole second. |
Encoder count | uint16_t [2] | Encoder step where the IMU data was sampled. |
x acceleration | int16_t [2] | Linear acceleration in the x direction in milli-g. LSB => 0.001g. |
y acceleration | int16_t [2] | Linear acceleration along the y axis, in milli-g. |
z acceleration | int16_t [2] | Linear acceleration along the z axis, in milli-g. |
Roll velocity | int16_t [2] | Rotational velocity around the radar y axis, in deg/sec * 10. |
Pitch velocity | int16_t [2] | Rotational velocity around the radar x axis, in deg/sec * 10. |
Yaw velocity | int16_t [2] | Rotational velocity around the z axis, in deg/sec * 10. |
phi | int16_t [2] | Roll angle from horizontal in deg * 10. |
theta | int16_t [2] | Pitch angle from horizontal, in deg * 10. |
psi | int16_t [2] | Yaw angle from radar North, in deg * 10. |