TCP Networking

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



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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Set Navigation Gain and Offset Message Structure

Field