ICD-001 External Trigger Command

Owned by Guy Avery
Last updated: Sept 21, 2021 by Charlotte Dakin-Norris
3 min read

Introduction

This page covers the ICD-001 External Trigger Command.

Contents

External Trigger Example

<!--MsgId is the unique id of the message being sent --> <!--TriggerId is the unique id of the external trigger to be enabled/disabled --> <!--Enable sets desired state of the trigger --> <?xml version="1.0" encoding="utf-8"?> <ExternalTriggerCommand MsgTimeStamp="2019-02-01T12:14:01+00:00" MsgId="1" TriggerId="1" Enable="true" Timeout="10" xmlns="ICDNAV001-ExternalTriggerCommand"> <Sender SenderId="SenderId1" NetworkAddress="127.0.0.1" NetworkPort="10000" /> </ExternalTriggerCommand>

External Trigger Command Element

The external trigger command instruction provides the ability to trigger an action in Witness based on the provided trigger Id and Enable state. Different actions can be associated with different Ids. In addition the command includes a timeout option allowing the state of the trigger to be automatically reversed after the specified timeout.

External Trigger 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



TriggerId


 

Id of the external trigger

Integer


This is the Id of the external trigger that needs to be changed. Actions in Witness can be configured to respond to specific Ids

Enable

Desired state of the trigger

Boolean

This is the state that needs to be applied to the trigger. Actions can be configured in Witness to respond to either the true or false state. True = Enable, False = Disable

Timeout*

Optional attribute that provides the option to reverse a state once the timeout has expired

Integer

Timeout is in 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.

Using the Timeout

The optional timeout can be used to avoid the external system having to send a separate Enable and Disable command. A single command message can be sent with a timeout and the original state will be reversed once the timeout has elapsed.

The timeout will reverse the original message state, so this applies to both True and False. If the original message had a state of true (Enable = true) and a 10 second timeout, then the state will be set to true, however after 10 seconds the state will be automatically changed back to False. Likewise If the original message is sent with Enable = false and a 10 second timeout, then the trigger state will be set to false and after 10 seconds it will automatically change to true.

If the timeout is set to 0 (zero) (or the optional attribute is excluded altogether) then the timeout will have no effect. The trigger state will remain unchanged until another message is sent to change the state.

If a command is sent with a timeout, this timeout can be cancelled by sending another command with a timeout of 0 (zero) for the same trigger Id. The Enable state in the last message will be the state set for the specified trigger.

Be aware that the state will be based on the last command message that was successfully received. If the third party system fails to send a trigger message and a timeout is not used then the state will remain unchanged indefinitely. If there is a concern over network reliability we would recommend that a timeout is used or the 3rd party software builds in message retry logic based on the response message sent from Witness.

 

Safety is everything.