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

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

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 flat

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

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.

Configuration Message

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:

1 2 3 4 5 6 7 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

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

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

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

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

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

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

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

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

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

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

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

Type [Size]

Description

Field

Type [Size]

Description

Gain

uint32_t [4]

Gain multiplied by 1000000

Offset

uint32_t [4]

Offset multiplied by 1000000

FFT/High Precision Data Message

The FFT Data message contains all the necessary information to process the amplitude data for a specific azimuth. The packet consists of 4 fixed length fields and a variable length byte array of amplitude data. Each byte of amplitude data represents a range bin. The total number of reported range bins can varying per packet depending on the radar configuration. The size of this message body is specified by the payload size field in the header. The FTT Data length can be calculated by subtracting the fixed length field sizes from the overall payload size (i.e. Payload Size – 14 bytes). FFT Data messages need to be switched on before they are sent. Once activated, FFT Data messages will be sent continuously for each sampled azimuth. FFT data will continue to be sent until the radar receives a message to stop. Clients should honour this mechanism and, where possible, send the radar a stop message before disconnecting.

FFT/High Precision Data Message Structure

Field

Type [Size]

Description

Field

Type [Size]

Description

FFT Data Offset

uint16_t [2]

The offset from the start of the payload where the FTT data starts. In this version the value will be 14 – the FFT starts at the 15th byte

Sweep Counter

uint16_t [2]

A counter that increments on each packet sent from the radar. The value will rollover once the maximum type size has been reached

Azimuth

uint16_t [2]

The azimuth at which this sample of FFT data was taken

Seconds

uint32_t [4]

Total number of seconds since the synchronised Epoch (In little Endian order)

Split Seconds

uint32_t [4]

Part seconds. This value rolls over each second (In little Endian order)

FFT Data

uint8_t [n]

Variable length byte array of amplitude data per range bin (If high precision then two bytes represent one bin)

Azimuth to Bearing Algorithm

To convert from an azimuth to bearing you can use the following algorithm, utilising information from the configuration message:

Bearing = (Azimuth / Encoder Size) * 360 e.g. (2800 / 5600) * 360 = 180°

This bearing is relative to the Zero/North point of the radar, for CDR/CIR radars this is a line perpendicular to the flat part of the base:

For HDR units this point is the line running from the rear hole to the middle hole of the three on the base of the radar:

The Navigation Data message contains the targets found for an azimuth that were above the threshold. The packet consists of 3 fixed length fields and a variable length byte array containing target information. The size of this message body is specified by the payload size field in the header. The Navigation Pairs Data length can be calculated by subtracting the fixed length field sizes from the overall payload size (i.e. Payload Size – 10 bytes).  Navigation Data messages need to be switched on before they are sent. Once activated, Navigation Data messages will be sent continuously for each sampled azimuth. Navigation data will continue to be sent until the radar receives a message to stop. Clients should honour this mechanism and, where possible, send the radar a stop message before disconnecting.

Field

Type [Size]

Description

Field

Type [Size]

Description

Azimuth

uint16_t [2]

The azimuth at which this sample of data was taken

Seconds

uint32_t [4]

Total number of seconds since the synchronised Epoch

Split Seconds

uint32_t [4]

Part seconds. This value rolls over each second

Navigation Data Pairs

uint8_t [n]

Pairs of ranges and powers representing targets

Field

Type [Size]

Description

Field

Type [Size]

Description

Range

uint32_t [4]

Range in metres multiplied by 1000000

Power

uint16_t [2]

Power of target dB multiplied by 10 e.g 75.6dB is 756

Health Message

The health message includes critical health information about the radar. The payload consists of a number of health status structures, each one provides data on a specific metric, for example temperature, and includes details on the current measurement and whether the metric is within expected bounds or not. The health message payload is a Protocol Buffer serialised byte array. In order to de-serialise the message the client will need to use the Google library as described in reference [2]. Metrics may be added or changed within the content of the Protocol Buffer message. This would not result in a new protocol version for this message. Client applications consuming this message will need the latest Protobuf definition file from Navtech. These are available on request. Health messages need to be switched on before they are transmitted. Once active, health messages will be sent every 5 seconds. Messages will continue to be sent until the radar receives a message to stop. Clients should honour this mechanism and, where possible, send the radar a stop message before disconnecting.

Field

Type [Size]

Description

Field

Type [Size]

Description

Temperature

HealthInfo PB Message

Temperature health information including current operating temperature

Rotation

HealthInfo PB Message

Rotation health information including current speed

Packet Rate

HealthInfo PB Message

Network health information including current packet rate

RF Health Check

HealthInfo PB Message

RF health information including current noise deviation from the norm

Motor Current

HealthInfo PB Message

Motor health information including current draw

Contour Update Message

The Contour Update message controls the contour mode and contour map. The contour map is held on the radar and provides a mechanism to restrict the radar detection area. The map consists of a variable range per degree (i.e. 360). When a contour map is active, data is sent out from the radar for each degree up to the range specified. If the range is zero then no data is sent for that bearing. If the contour map is disabled or in its default configuration then the full range of data is sent for every azimuth (i.e. all data). There is also a test mode which can be set on the radar – this activates a pre-configured map which exhibits a distinctive data pattern. To disable the contour map the client should send an empty update message (just header). This will leave the contour configuration intact but tell the radar to stop using it. Alternatively the client can send a full contour map, in other words a maximum range value for each azimuth. This will have the same effect. The contour map, once active, restricts the amount of data sent over the network. The more restrictive the contour map, the less data that is sent.

Contour Update Message Structure

Log Levels Get/Set Messages

The log levels get and set messages enable a user to get the logging levels and set the logging levels of the radar software. The LoggingLevelRequest message is an empty payload message, the radar will respond with a LoggingLevel message that contains a Protocol Buffer object which is a list of Log Levels. The get log levels payload is a Protocol Buffer serialised byte array. In order to de-serialise the message the client will need to use the Google library as described in reference: https://developers.google.com/protocol-buffers/.

Version 2 Hardware Only

Log Levels Structure

Log Levels Buffer Payload

Field

Type [Size]

Description

Field

Type [Size]

Description

Items

List of LogLevel PB Messages

A list of Log Level Items

Calibrate Accelerometer Message

This message contains no body / payload. The message is sent just as a header. On receiving this
message the radar will start start the calibration process and store the values in the NVRAM.

Start Accelerometer Data Message

This message contains no body / payload. The message is sent just as a header. On receiving this
message the radar will start sending accelerometer data messages.

Stop Accelerometer Data Message

This message contains no body / payload. The message is sent just as a header. On receiving this
message the radar will start sending accelerometer data messages.

Accelerometer Data Message

This message contains the three angles representing the tilt of the radar, Θ (theta), Ψ (psi) and ɸ (phi).

Accelerometer Data Message Structure

Field

Type [Size]

Description

Field

Type [Size]

Description

Θ (theta)

float [4]

Angle around axis running perpendicular to zero/north - +ve Tilted Forward, -ve Tilted Backward

Ψ (psi)

float [4]

Angle around axis running from base to stop of radome

ɸ (phi)

float [4]

Angle around axis running through radar zero/north - +ve Tilted Right, -ve Tilted Left

This messages contains the six alarm states of the SafeGuard Lite feature

Field

Type [Size]

Description

Field

Type [Size]

Description

Alarm States

uint8_t[6]

Each byte represents the alarm state of an areas so state[4] is the fifth alarms sate a value of 1 means alarm in area, 0 means no alarm 

This message configures the SafeGuard Lite feature with up to six areas that can cause an alarm state if a target is detected above the area threshold inside the area

C# Example of how to encode rules

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 public static class Utility {     public static uint SwapUInt32(uint value)     {         return (uint)((SwapUInt16((ushort)((value & 0x000ffff))) << 0x10)) | (SwapUInt16((ushort)((value >> 0x10) & 0xffff)));     }       public static ushort SwapUInt16(ushort value)     {         return (ushort)(((value & 0xff) << 8) | ((value >> 8) & 0xff));     } }   public class NavVector {     public NavVector() { }       public NavVector(float x, float y)     {         X = x;         Y = y;     }       public float X { get; set; }     public float Y { get; set; }       public byte[] ToBytes()     {         var x = (short)(X * 10.0f);         var y = (short)(Y * 10.0f);         var data = (uint)(x << 16) | (uint)y;         return BitConverter.GetBytes(Utility.SwapUInt32(data));     } }   public class NavArea {     public NavArea()     {         Points = new List<NavVector>();     }       public List<NavVector> Points { get; set; }       public byte[] ToBytes()     {         var data = new List<byte>();         data.AddRange(BitConverter.GetBytes(Utility.SwapUInt16((ushort)Points.Count)));         Points.ForEach(point => { data.AddRange(point.ToBytes()); });         return data.ToArray();     } }   public class NavAreaRule {     public NavAreaRule()     {         Enabled = true;         InvertBreakLogic = false;         ThresholdDelta = 0.0f;         BreakAllowance = 16;         AllowanceCurveDecrement = 4;         AreaToCheck = new NavArea();     }       public byte Id { get; set; }     public bool Enabled { get; set; }     public bool InvertBreakLogic { get; set; }     public float ThresholdDelta { get; set; }     public ushort BreakAllowance { get; set; }     public ushort AllowanceCurveDecrement { get; set; }     public NavArea AreaToCheck { get; set; }       public byte[] ToBytes()     {         var ruleData = new List<byte> { Id, Enabled ? (byte)1 : (byte)0, InvertBreakLogic ? (byte)1 : (byte)0 };         ruleData.AddRange(BitConverter.GetBytes(Utility.SwapUInt16((ushort)(ThresholdDelta * 10.0f))));         ruleData.AddRange(BitConverter.GetBytes(Utility.SwapUInt16(BreakAllowance)));         ruleData.AddRange(BitConverter.GetBytes(Utility.SwapUInt16(AllowanceCurveDecrement)));         ruleData.AddRange(AreaToCheck.ToBytes());         var data = new List<byte>();         data.AddRange(BitConverter.GetBytes(Utility.SwapUInt32((uint)ruleData.Count)));         data.AddRange(ruleData);         return data.ToArray();     } }   public class NavUpdateAreaRules {     public NavUpdateAreaRules()     {         Rules = new List<NavAreaRule>();     }       public List<NavAreaRule> Rules { get; set; }       public byte[] ToBytes()     {         var data = new List<byte> { (byte)Rules.Count };         Rules.ForEach(rule => { data.AddRange(rule.ToBytes()); });         return data.ToArray();     } }

The Navigation Configuration Get/Set message allows the client to request the current Navigation Configuration from the Radar, and provide an update to supersede the current configuration. This is only supported by NavOS radars running firmware version 3.0.0.131 or later. A Navigation Configuration Request message is an empty payload message sent to the Radar, to which the Radar responds by sending a Navigation Configuration message. The client may sent an update of the Navigation Configuration parameters by sending a Set Navigation Configuration message.

The Navigation Configuration message is a fixed-structure message.

 

Field

Type [Size]

Description

Field

Type [Size]

Description

Bins to operate on

uint16_t [2]

Defines the search window in bins for peak detection.

Minimum bin

uint16_t [2]

The earliest bin for which peak detection will be enabled.

Navigation Threshold

float [4]

The threshold level for target detection. This should be a value between 0 - 96.5 dB multiplied by 10 e.g 75.6dB is 756

Max Peaks Per Azimuth

uint32_t [4]

The maximum number of detection peaks that will be reported. Once the maximum number of peaks have been detected, further peaks will be ignored.

Sector Blanking Message

A Sector Blanking message allows the client to update the set of blanking sectors for the Radar.

The payload for the message consists of a contiguous sequence of up to eight Blanking Sector structures. A Blanking Sector structure defines a start angle and finish angle for a blanking sector. The angles are stored as a pair of floating point values, as defined above. The first byte of the payload holds the number of Blanking Sectors to follow.

Sector Blanking Message Structure

Field

Type [Size]

Description

Field

Type [Size]

Description

Number of Sectors

uint8_t [1]

Specifies the size of the message payload, as a number of Blanking Sector structures. [0 .. 8]

Blanking Sectors

uint8_t [Payload Size - 1]

Up to 8 Blanking Sector structures, held as a sequence of bytes

Blanking Sector Structure

Field

Type [Size]

Description

Field

Type [Size]

Description

Start Angle

float [4]

The start angle of the sector [0 .. 360.0]

Finish Angle

float [4]

The end angle of the sector [0 .. 360.0]