Using the ICD-001 Plugin
- Guy Avery (Deactivated)
- Former user (Deleted)
ICD-001 is a network communication protocol based on XML. The protocol is used over standard TCP/IP client-server connections.
There are two documents that describe the protocol in detail. The primary document, RND-S0053, covers the protocol, including message structure, message framing and all the outgoing messages. The second document, RND-S0058, covers all the commands, these are the incoming message, in other words control messages that an external application or system can send to Witness.
For customers and integrators intending to use ICD-001, the documents assume a reasonable working knowledge of network communications, XML and XSD. They are targeted at technical teams, typically with software development skills, who are integrating the output from Witness into external systems.
Technical Overview
When Witness generates events, such as alarms, or processes targets, it passes all this information to Witness Canary. Witness Canary then converts this information into a suitable data format to send to external systems.
The data is transmitted as the events occur, leading to near-real time reporting.
The ICD-001 Plugin
Witness Canary supports integration with many different types of external systems through the use of plugins. These are stand-alone software libraries which are dynamically loaded by Canary and contain code which knows how to convert the Witness data into the required format for the external system. Navtech Radar can easily develop bespoke plugins to interface with a specific type of equipment or application, however ICD-001 has been developed to provide a comprehensive communication protocol which is based on open standards in order to make it as easy as possible to integrate with a large number of different systems.
The ICD-001 plugin file is entitled Witness.Plugin.ICD001Interface.dll and must be present in the Witness Plugin folder which is inside the main application folder.Â
The plugin can be selected during setup and will automatically be installed in the correct location.
Configuring the ICD-001 Plugin
When the plugin is installed and Canary starts, the plugin configuration settings are saved to the PluginConfiguration.xml file. This file is located in the Witness main application folder. To change the settings this file should be opened in a text editor, such as Notepad, however we would recommend an editor which is XML aware, such as Notepad++.
Once the file is open, locate the ICD001 section, as illustrated below:
Example of ICD-001 Plugin Configuration
<?xml version="1.0" encoding="utf-8"?>
<Config>
<Plugins>
<ICD001Interface>
<PluginConfig>
<PumpTimerInterval>500</PumpTimerInterval>
<StatusReportInterval>10</StatusReportInterval>
<AutoSendCameraReport>False</AutoSendCameraReport>
<AutoSendAlarmReport>False</AutoSendAlarmReport>
<AutoSendStatusReport>False</AutoSendStatusReport>
<TrackOutputMode>None</TrackOutputMode>
<BufferTrackOutput>True</BufferTrackOutput>
<MaxTracksPerMessage>0</MaxTracksPerMessage>
<TcpServer Enabled="True" Port="10000" />
<UdpServer RemoteIPAddress="127.0.0.1" Enabled="False" Port="10000" />
<TrackTransmitInterval>1000</TrackTransmitInterval>
<MonitorClientHealth>True</MonitorClientHealth>
<HeartbeatInterval>10</HeartbeatInterval>
</PluginConfig>
</ICD001Interface>
</Plugins>
</Config>Once you have made changes to the plugin configuration file then you must restart the Canary application / service for the new settings to be applied. No other modules need to be restarted.
The setting options are as follows:
TcpServer
This is used to configure the ICD-001 plugin to act as a TCP server.
Enabled - when set to True the server is enabled. Default is True.
Port - the TCP port that the server listens on. This is the port that TCP clients connect to.
UdpServer
This is used to configure the ICD-001 plugin to communicate with clients via UDP.
Enabled - When set to True, UDP communications are enabled. Default is False.
RemoteIPAddress - The IP address used for clients to access the UDP data.
Port - The port used for the UDP communications.
TrackOutputMode
None - No tracks reports are sent.
BrokenRule - Report all tracks which have broken rules, regardless of whether this resulted in an alarm.Â
AlarmOnly -Report only tracks which have broken rules that results in an active alarm.
All - Reports all tracks.Â
BufferTrackOutput
True - Tracks are buffered and sent in batches. This can optimise network load but has the drawback of not sending data in real time. The TrackTransmitInterval setting specifies how often the buffered tracks are sent. (Default)
False - Tracks are sent as they arrive.
TrackTransmitInterval
Period, in milliseconds, between each batch of tracks being sent. Default is 1000ms (1 second).
MaxTracksPerMessage
Specifies how many tracks are sent in a single packet when using track buffering. This should be used on busy sites when using UDP to avoid the packet size exceeding the maximum allowed for the UDP protocol. If the number of tracks in the buffer exceeds this value then multiple UDP packets will be sent each containing tracks up to the maximum value. The default value is 0 which means there is no maximum limit per message, This is only suitable for the TCP protocol.
AutoSendCameraReport
True - Camera reports are sent every time a camera is moved automatically.
False - No camera reports are sent. (Default)
AutoSendAlarmReport
True - Alarm reports are sent.
False - No alarm reports are sent. (Default)
AutoSendStatusReport
True - Status reports are sent at a regular interval based on the StatusReportInterval.
False - No status reports are sent. (Default)
StatusReportInterval
Period, in seconds, between each status report being sent. Default is 10 seconds.
MonitorClientHealth
True - The plugin monitors the health of client connections. If a client is either not connected or connected but not sending heartbeats, then an alarm will be raised in Witness.
False - No monitoring is performed.
HeartbeatInterval
Period, in seconds, between each heartbeat being sent to every connected client. Default is 10 seconds.