Introduction

The protocol is based on a very simple binary message format which includes a small binary header and an XML payload all sent in UTF-8 format. The messages are sent over a TCP/IP network connection. If using TCP then the Witness software will act as a TCP Server and the 3rd party application is expected to connect as a TCP client. The client is responsible for logic to reconnect in the event of a break in communications. The protocol supports a 2-way heartbeat message to facilitate clean and early termination of unresponsive links.

The protocol is capable of both sending out messages and also receiving incoming commands. Outgoing data are usually driven by events in the Witness system, such as alarms or reporting track movement, and incoming messages are used to alter the behaviour of the Witness suite.

Contents

Key Concepts

Sensor (Radar)

This ICD refers to sensors which encompasses a range of device capable of providing data to the Witness software. In practise these must be intelligent sensors capable of delivering continuous location data enabling the acquisition and tracking of targets. Currently this covers the complete range of radars offered by Navtech but could easily be extended to other devices if required.

Track 

A track is an acquired target. Once the tracking software has identified a track this target data can be supplied to a third party. The data associated with a track may vary depending on the tracking software being used and the configuration of the Witness software. Basic data available will include range, speed and bearing but more complex data can include size or latitude / longitude.

Alarm

Alarms are generated in the Witness software as a result of certain rules being broken or conditions being met. At the most simple level this may be a target moving into a specific area but could also be a result of a set of more sophisticated inter-dependant rules being broken. Alarms are uniquely identified and can be associated directly with one or more tracks through the alarm information which is carried by each track.

Status

The primary status message is intended to provide health and status data for all the sensors. In addition status information can be provided about the software modules, alarm zone status and the current system profile.

Camera

A camera refers to a PTZ camera which is being used to track targets identified as threats by the software system. These cameras rely on the Navtech software telling them where to move. This can be done either directly or via a third party camera control application.

Subscriber

A subscriber is a system which connects to the Navtech software to receive data. Although the name suggests a formal method of subscription, at this stage this is not required. A subscriber is a device / system which simply connects to the relevant network point being used by the Navtech software to broadcast and receive data.

Report

A report is a XML document being transmitted or received by the Navtech software. This ICD will describe the various different reports that the software supports. Each report will support its own specification so a status report will take a different format to a track report.

Command

Commands are messages being passed into the Witness system. Commands offer the ability to request additional data or change the behaviour of the Witness software. Typically a command message would always elicit a response message, either containing the requested data or confirmation of whether the command action has been successfully received.

Messaging Transport

This document does not cover the specifics of the messaging transport mechanism. It is assumed that a suitable network link is available between the Navtech system and third-party. The network may implement security and encryption but these facilities remain independent of this ICD and therefore are not discussed. The ICD-001 interface which is available within Witness offers support for TLS 1.2. Further information on the plugin and the use of certificates can be found here: https://navtechradar.atlassian.net/wiki/spaces/TUN/pages/68485229.

XSD Files

XML is plain text based data exchange protocol. It is widely supported in most modern development languages and tools. There are XSD files to support the protocol which can be used to validate incoming and outgoing messages. These can be found here: https://navtechradar.atlassian.net/wiki/spaces/TUN/pages/794787865. Navtech Radar recommends the use of the XSD in order to check the XML format. The Witness system uses the XSD and therefore will reject incorrectly formatted XML data.

Technical Skill Requirements

The use of this protocol will require a reasonable understanding of XML and some basic knowledge on developing a simple TCP client to decode the message structure and extract the XML. This is not difficult and there are plenty of examples online, however we would not recommend a non-software developer undertake this work.

Related Information