ICD-001 Detection Command
Introduction
This page covers the ICD-001 Detection Command.
Contents
Example 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:
| 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:
| 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
-
ICD-001 Track Filter Command (Witness 4.0)
-
ICD-001 Acknowledge Alarm Command (Witness 4.0)
-
ICD-001 Request Status Command (Witness 4.0)
-
ICD-001 Detection Command (Witness 4.0)
-
ICD-001 Update Entity Command (Witness 4.0)
-
ICD-001 System Profile Command (Witness 4.0)
-
ICD-001 External Trigger Command (Witness 4.0)
-
ICD-001 Command Reply (Witness 4.0)
-
ICD-001 Camera Command (Witness 4.0)
-
ICD-001 Track Command (Witness 4.0)