ICD-001 Detection Command

Introduction

This page covers the ICD-001 Detection Command.

<!-- MsgId is the unique id of the message being sent -->
<!-- Unique Id must be unique across all tracks being sent to Witness -->
<?xml version="1.0" encoding="utf-8"?>
<DetectionCommand xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="ICDNAV001-DetectionCommand" MsgId="1" MsgTimeStamp="2020-03-01T23:32:11.6298253+00:00"> 
  <TrackDetection xsi:type="TrackDetection" UniqueId="03b48a2d-1709-4617-af18-12b5bce40c68" DetectionStatus="Update" ExpiryPeriod="4">
    <DetectionData DetectedTime="2020-03-01T23:32:10.6298233+00:00" Latitude="51.678901" Longitude="-3.456642" Altitude="0" Speed="6.5" Course="231.2" Classification="Vehicle" Tag="Patrol Car 1" Friend="false"/>
  </TrackDetection>
  <!-- The sender element is optional -->
  <Sender SenderId="XFSControlSuite:1" NetworkAddress="10.0.5.1" NetworkPort="5079" />
</DetectionCommand>

Detection Command Element

The Detection Command can be used to send in track detection reports to display on the primary Witness map display. This can be very simple target reports with just a location or more complex ones with speed, course and classification. Witness will display these tracks in the same way it does radar tracks. The software will assume that an external system will send one or more track updates for the same track. Each track is identified using the UniqueId attribute. Each Detection Command can contain one or more Track Detection updates for different tracks.

Detection Command Attributes

Attributes	Description	Type	Notes
MsgId	Unique message Id	Long	This must be globally unique across all message types
MsgTimeStamp	Date and time that the message was sent	DateTime

Track Detection Element

Each Track Detection represents an update for a track from the external system. One or more of these detections can be included in each Detection Command message.

Be aware that if you include multiple Track Detections for the same track in the same Detection Command, then the last detection wins - so all previous detections will be ignored. This may not result in the expected outcome. We recommend that only track detections from different tracks are included in the same command.

Track Detection Attributes

Attributes	Description	Type	Notes
UniqueId	Unique track Id. This can be any form Id represented as a string, such an integer, name or a GUID.	String	This must be globally unique across all tracks being sent to Witness
DetectionStatus	Type of track detection. Options are: Update - indicates the track detection is an update Delete - indicates the track has been lost and should be deleted	DetectionStatusList
ExpiryPeriod	Amount of time, in seconds, that a track will live in Witness without receiving any further updates before it is automatically deleted. This value should be greater zero and less than 30 seconds.	Integer

Detection Data Element

This element contains data for the track, including key data for location, speed and course. Not all attributes are compulsory however the latitude and longitude are mandatory.

If sending a Track Detection to delete an existing track using the Delete status, you do not need to include the Detection Data element because none of these values will be processed.

Detection Data Attributes

Optional attributes are formatted in italics and highlighted with an asterisk.

Attributes	Description	Type	Notes
DetectedTime	The time that the track update was detected or created by its source	DateTime
Latitude	Latitude in decimal degrees. Uses the WGS84 datum	Double
Longitude	Longitude in decimal degrees. Uses the WGS84 datum	Double
*Altitude	The height of the target	Double	The datum for the height is not important. However we would expect the height to be above local ground level if you are expecting to follow the target with a camera on the local site.
*Speed	Speed of the track in metres per second	Double	If no speed is specified it will be reported as zero
*Course	The track’s course in degrees	Double	If no course is specified it will be reported as zero
*Classification	Classification of the track. Options are: Unclassified Person Vehicle Large Vehicle Airplane Boat Animal Drone Debris	ClassificationTypeList	If no classification is specified the track will be reported as unclassified
*Tag	The tracks visible Id or name that will appear on the UI	String	Each track will always be allocated a unique display number Id. If a tag is not provided then the number Id will be displayed otherwise the supplied tag will be used in the UI
*Friend	If true, the track is treated as a friend and can never trigger an alarm. It will be displayed like any other track but it will be displayed as a friend	Boolean	If Friend is not set then it will be false meaning the track will have an unknown severity unless it is changed by a rule

Managing a Track's Lifespan

Witness will interpret track detection reports in the following way:

When the first detection is received with a DetectionStatus of Update it will a create a new track with the supplied UniqueId.
When additional detections are received with the same UniqueId and a DetectionStatus of Update then Witness will update the existing track with all the supplied attributes.
When an additional detection is received with the same UniqueId but with a DetectionStatus of Delete then Witness will delete the track and it will be removed from the UI and the rest of the system.

So all new and updated track detections should be sent with a DetectionStatus of Update and the final detection should be sent with a a DetectionStatus of Delete.

Track Expiry

As a fallback option or where the external system cannot send an explicit delete detection update, the ExpiryPeriod can be set. This specifies how long a track will be kept alive in Witness whilst it waits for an update. If a Track Detection update is not received during this expiry period then the track will be automatically deleted and purged from the Witness system. The time is specified in whole seconds.

Network Sender Element

Each incoming message can include an optional Sender element. This must include the IP address and port that the client is using to send instructions.

If the Sender element is included the NetworkAddress value will be checked against the subscriber IP address and the command rejected if they do not match.

In addition the Sender element is included in the Command Reply. This is a duplicate of the incoming details (i.e. the subscribers IP address and port). The subscriber can use this to verify that they authored the message.

Related Information

Page:

ICD-001 Track Filter Command (Witness 4.0)
Page:

ICD-001 Acknowledge Alarm Command (Witness 4.0)
Page:

ICD-001 Request Status Command (Witness 4.0)
Page:

ICD-001 Detection Command (Witness 4.0)
Page:

ICD-001 Update Entity Command (Witness 4.0)
Page:

ICD-001 System Profile Command (Witness 4.0)
Page:

ICD-001 External Trigger Command (Witness 4.0)
Page:

ICD-001 Command Reply (Witness 4.0)
Page:

ICD-001 Camera Command (Witness 4.0)
Page:

ICD-001 Track Command (Witness 4.0)

Witness 4.0