TCP Networking
- Charlotte Dakin-Norris
- Glennan Carnie
- Benedict Dakin-Norris (Unlicensed)
- Guy Avery (Deactivated)
Introduction
The radar acts as a TCP/IP server and therefore listens for connections once started. The server will support up to 3 concurrent client connections, therefore the first 3 clients attempting to connect will succeed, but subsequent attempts from other clients will fail. The radar supports a primary IP address and streams data over a single port, which, by default, is the IANA allocated port of TCP 6317. The IP addresses and the port are all configurable via the radar management software. Please refer to reference Vertex documentation for more information.
Note that the radar TCP server maintains state on the client connections therefore message start / stop requests, such as FFT Data, are applied on a per client basis.
Typically there are 3 types of payload:
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 Protocol Buffers. Navtech can provide Protobuf message files on request.
All network data is sent in Network Order i.e. big-endian.
Contents
- 1 The Complete TCP Message Structure
- 1.1 The TCP Message Header
- 1.2 Field
- 1.3 Type [Size]
- 1.4 Description
- 1.5 TCP Message Types
- 1.6 Signature
- 2 The TCP Message Body
- 2.1 Keep Alive Message
- 2.2 Configuration Message
- 2.3 Configuration Request Message
- 2.4 Start FFT Data Request Message
- 2.5 Stop FFT Data Request Message
- 2.6 Start Health Message
- 2.7 Stop Health Message
- 2.8 Reset RF Health Check System
- 2.9 System Restart Message
- 2.10 Start Navigation Data Message
- 2.11 Stop Navigation Data Message
- 2.12 Set Navigation Threshold
- 2.13 Set Navigation Threshold Message Structure
- 2.14 Set Navigation Gain and Offset
- 2.15 FFT/High Precision Data Message
- 2.16 Navigation Data Message
- 2.17 Health Message
- 2.18 Contour Update Message
- 2.19 Log Levels Get/Set Messages
- 2.20 Calibrate Accelerometer Message
- 2.21 Start Accelerometer Data Message
- 2.22 Stop Accelerometer Data Message
- 2.23 Accelerometer Data Message
- 2.24 Navigation Alarm Data
- 2.25 Navigation Area Rules Get/Set Messages
- 2.26 Navigation Configuration Get/Set Messages
- 2.27 Sector Blanking Message
- 2.28 Time Source Status Get/Set messages
- 2.29 Start / Stop radar
- 3 Related Information
The Complete TCP Message Structure
The TCP Message Header
This is the first part of every message sent using this protocol. The header serves 2 purposes: the first is to provide a byte sequence for synchronisation purposes; and secondly to provide information about the body of the message.
TCP Message Header Structure
Field | Type [Size] | Description |
|---|---|---|
Signature | uint8_t [16] | Unique synchronisation byte sequence |
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 |
Payload Size | uint32_t [4] | The size, in bytes, of the main body of the message |
TCP Message Types
Message Name | Message ID | Direction | Description |
|---|---|---|---|
Keep Alive | 1 | From Radar | An empty payload message to confirm client connection |
Configuration | 10 | From Radar | Sends all the radar configuration properties required to configure the client software to correctly receive data |
Configuration Request | 20 | To Radar | Requests a configuration message from the radar |
Start FFT Data | 21 | To Radar | Instructs the radar to start sending FFT data until told to stop |
Stop FFT Data | 22 | To Radar | Instructs the radar to stop sending FFT data |
Start Health Msgs | 23 | To Radar | Instructs the radar to start sending regular health messages until told to stop |
Stop Health Msgs | 24 | To Radar | Instructs the radar to stop sending health messages |
Reset RF Health | 25 | To Radar | Instructs the radar to reset RF Health check system |
FFT Data | 30 | From Radar | An azimuth of raw radar data |
High Precision FFT Data | 31 | From Radar | An azimuth of high precision radar data |
Health | 40 | From Radar | Sends a radar health status message |
Contour Update | 50 | To Radar | Enables the client to update the contour map on the radar |
Sector Blanking Update | 51 | To Radar | Updates the blanking sectors on the radar |
System Restart | 76 | To Radar | Request system reboot |
Logging Levels | 90 | To/From Radar | A list of logging levels - v2 Hardware only |
Logging Levels Request | 100 | To Radar | Request a list of logging levels - v2 Hardware only |
Start Nav Data | 120 | To Radar | Request system to start sending navigation data |
Stop Nav Data | 121 | To Radar | Request system to stop sending navigation data |
Set Nav Threshold | 122 | To Radar | Set navigation threshold |
Navigation Data | 123 | From Radar | Navigation data records |
Set Nav Range Gain and Offset | 124 | To Radar | Set navigation threshold |
Calibrate Accelerometer | 125 | To Radar | Radar will store current accelerometer value as float |
Start Accelerometer | 126 | To Radar | Start receiving accelerometer data |
Stop Accelerometer | 127 | To Radar | Stop receiving accelerometer data |
Accelerometer Data | 128 | From Radar | Accelerometer Data |
Navigation Alarm Data | 143 | From Radar | SafeGuard Lite Alarms |
Navigation Area Rules | 144 | To Radar | SafeGuard Lite Area Rules |
Navigation Configuration Request | 203 | To Radar | Request the current navigation configuration from the Radar |
Navigation Configuration | 204 | From Radar | The current navigation configuration |
Set Navigation Configuration | 205 | To Radar | Updates the Radar’s navigation configuration |
Request Navigation Area Rules | 206 | To Radar | Request the current Navigation Area Rules |
Request Time Server Status | 207 | To Radar | Request the current status of time server sources |
Time Server Status | 208 | From Radar | NTP and/or PTP time server status |
Start Radar | 209 | To Radar | Start radar rotation and transmitter |
Stop Radar | 210 | To Radar | Stop radar transmitter and rotation |
Signature
The 16 byte signature differs very slightly from the older Navtech RMB protocol. This does enable existing software to differentiate between the two protocols if required.
The new signature is as follows:
The TCP Message Body
This payload will be variable length, the size being specified in the message header. The rest of this document describes the message types.
Keep Alive Message
Message | ID | Direction |
|---|---|---|
Keep alive | 1 | From radar |
Keep-alive messages are sent by the radar to monitor client connections. If a client connects to a radar, but does not request radar data (FFT, health messages, navigation data, etc.) the radar will send a keep-alive message every 5 seconds. Once a client requests any data from radar, the radar will stop sending keep-alive messages to that client. Similarly, should a client disable all radar data requests, the radar will resume sending keep-alive messages to the client.
The keep-alive message has no payload. Clients are not required to process, or respond to, keep-alive messages.
Configuration Message
Message | ID | Direction |
|---|---|---|
Configuration | 10 | From radar |
The configuration message contains all the relevant information a client application needs to process raw data from 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 a client. 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.
Configuration 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 |
Rotation Speed | uint16_t [2] | The configured rotation speed for the radar. In milliHertz i.e. 2000 = 2 Hz |
Packet Rate | uint16_t [2] | Expected packet rate based on sample time and rotation speed |
Range Gain | float [4] | Gain applied to calculated ranges based on radar calibration |
Range Offset | float [4] | Fixed offset in metres, applied to calculated ranges based on radar calibration |
Floats transmitted over the network are IEEE 754 compatible values converted to 32 bit unsigned integers in network order. They will need to be reverted to host order and then cast back to floats on the client.
In C++ the radar converts floats using the following code snippet:
union v {
float f;
uint32_t i;
};
v value;
value.f = 186.4f;
uint32_t networkData = htonl(value.i); |
Configuration Protocol Buffer Payload
FIeld | Type [Size] | Description |
|---|---|---|
Model | string | Customer friendly model name |
MAC Address | string | Networking MAC Address |
Service Date | uint32_t [4] | The date the last service was completed |
Software Version Numbers | SoftwareVersion PB Message | Collection of software version numbers |
NVRAM Contents | NVRAM PB Message | Contents of NVRAM, including radar serial number |
Range Resolution Hz | float | Resolution of each bin in Hz |
Module Serial Number | string | Processing Module Serial Number |
Auto Tune Value | int16_t [2] | Current Auto Tune Value |
Radar Unique Id | string (Guid) | Radar's Unique Id |
Data Width | int32 | 1 for 8-bit 2 for 16-bit |
Range Resolution Metres | float | Range of each bin in metres |
Radar Feature Flag | uint32 | Feature Flag bit field 1 = AutoTune, 2 = Secondary Processing Module Present |
Staring Mode | int32 | Boolean to represent staring mode enabled on radar |
On-Board MAC Address | string | On-Board Networking MAC Address - 00:00:00:00:00:00 indicates no module |
Converting Bins to Range (m)
This information can be used to calculate the range of the radar in metres and also when receiving FFT data the range of each bin can be calculated. The following algorithm should be used:
Range = Range In Bins * Range Resolution (m) i.e. 3768 * 0.175 = 659.4 m (This radar has a total range of 659.4 m)
Range of single bin = Bin Number * Range Resolution (m) i.e. 100 * 0.175 = 17.5 m (Bin 100 is 17.5 m from the radar)
Configuration Request Message
Message | ID | Direction |
|---|---|---|
Configuration request | 20 | To radar |
This message contains no body / payload. The message is sent just as a header. On receiving this
message the radar will respond by sending a single configuration message.
Start FFT Data Request Message
Message | ID | Direction |
|---|---|---|
Start FFT Data | 21 | To radar |
This message contains no body / payload. The message is sent just as a header. On receiving this
message the radar will respond by starting the raw radar data stream.
Stop FFT Data Request Message
Message | ID | Direction |
|---|---|---|
Stop FFT Data | 22 | To radar |
This message contains no body / payload. The message is sent just as a header. On receiving this
message the radar will respond by stopping the raw radar data stream.
Start Health Message
Message | ID | Direction |
|---|---|---|
Start Health Messages | 23 | To radar |
This message contains no body / payload. The message is sent just as a header. On receiving this
message the radar will start sending regular health messages. By default the interval is every 5
seconds.
Stop Health Message
Message | ID | Direction |
|---|---|---|
Stop Health Messages | 24 | To radar |
This message contains no body / payload. The message is sent just as a header. On receiving this
message the radar will stop sending regular health messages.
Reset RF Health Check System
Message | ID | Direction |
|---|---|---|
Reset RF Health | 25 | To radar |
This message contains no body / payload. The message is sent just as a header. On receiving this
message the radar will reset the long term health check system.
System Restart Message
Message | ID | Direction |
|---|---|---|
System Restart | 76 | To radar |
This message contains no body / payload. The message is sent just as a header. On receiving this
message the radar will reboot.
Start Navigation Data Message
Message | ID | Direction |
|---|---|---|
Start Nav Data | 120 | To radar |
This message contains no body / payload. The message is sent just as a header. On receiving this
message the radar will start sending navigation data messages.
Stop Navigation Data Message
Message | ID | Direction |
|---|---|---|
Stop Nav Data | 121 | To radar |
This message contains no body / payload. The message is sent just as a header. On receiving this
message the radar will stop sending navigation data messages.
Set Navigation Threshold
Message | ID | Direction |
|---|---|---|
Set Nav Threshold | 122 | To radar |
This message is used to set the threshold for the navigation system
Set Navigation Threshold Message Structure
Field | Type [Size] | Description |
|---|---|---|
Threshold | uint16_t [2] | Threshold to use for navigation data. This should be a value between 0 - 96.5 dB multiplied by 10 e.g 75.6dB is 756 |
Set Navigation Gain and Offset
Message | ID | Direction |
|---|---|---|
Set Nav Rage Gain and Offset | 124 | To radar |
This message is used to set a gain and offset that is used when by the onboard navigation system, this gain and offset are applied to the ranges found using the formula [(Target Range * Range Gain * Range Resolution) + Offset].