ICD-008 TDIS Plugin
Introduction
This page covers the configuration of the ICD-008 TDIS plugin for ClearWay™.
For customers and integrators intending to use the ICD-008 plugin, the documents assume a reasonable working knowledge of network communication. They are targeted at technical teams, typically with software development skills, who are integrating the output from Witness into external systems.
Contents
Overview
Witness supports integration with many different types of external systems through the use of plugins.
The ICD-008 TDIS Plugin enables ClearWay™ to provide all ClearWay™ alarm data to Trafikverket's traffic data recording TDIS/VANA system. This is used to collect incident, health and system alarm data centrally from all of their different traffic management systems and sensors. The plugin will send this data in real-time over the network using the MQTT protocol.
MQTT (Message Queuing Telemetry Transport) is a standards-based messaging protocol (or set of rules) used for machine-to-machine communication.
Additionally, the plugin will reduce the number of alarms being sent from ClearWay™ to the NTS system and provide an option to filter out all alarms with a severity of Warning.
Prerequisites
The ICD-008 TDIS plugin requires no pre-requisites.
Configuring the ICD-008 TDIS Plugin in ClearWay™
When the plugin is licensed, a plugin configuration with default settings is automatically generated. The settings can be viewed and edited by enabling the Config Function, then selecting the plugin in Integration Configurations, within the Configuration Tree. Configuration settings will then be available in the Configuration Panel:
ICD-008 TDIS Plugin Fields
Plugin Enabled: Select to enable the ICD-008 TDIS Plugin.
Name: Name of the plugin within the ClearWay™ UI.
Port: The serial port to which the plugin will connect to send/receive messages.
IP Address: This is the address that the MQTT client will connect to (in conjunction with the Port).
Topic: This is the topic that the plugin will publish alarm messages to. The default setting is "/clearway/alarms".
Normally, clients subscribe to topics but since the plugin client does not want to receive its own alarm messages it does not subscribe to this topic. The topic is only used for publishing alarms to, so other clients that want to receive the alarms will subscribe to this.
Use TLS: Enables TLS for the network connection. When disabled the link does not use any authentication or encryption.
TLS client certificates need to be stored in the local certificate store on the management server systems. To do this open Run and open Certlm.msc. Open Personal and right click on Certificates. Select All Tasks and Import. Select the Certificate required and follow the instructions through on default settings. The import will confirm it has been successful at finish.
Advanced
Will Topic: This is the topic that the LWT (Last Will and Testament) message will be sent to. If the client disconnects, the MQTT broker will automatically post the LWT message to the Will Topic. It is used to keep track of the clients connection state. If the client disconnects, it posts: "{"connected":false}" and when it connects, it posts: "{"connected":true}" to the Will Topic. By default, it is set to “/clearway/status”.
Quality of Service: This is the level of guarantee that a message has been sent successfully. The default setting is Exactly Once.
AtMostOnce: The message is sent once, and regardless whether or not the broker received it, the client will move on to sending the next message.
AtLeastOnce: If the server fails to receive the message, the client will reattempt to send the message until it is successful.
ExactlyOnce: The client will only reattempt to send the message if it knows for certain that it was not received. This ensures that the other side never receives duplicate messages (in the case that a message was taking too long to deliver).
Reconnect Delay (s): The delay before the client will automatically attempt to reconnect after a failed connection. By default is is set to 1s.
Max Pending Messages: The total number of pending alarm messages before messages are discarded according to the Overflow Strategy. By default this is set to 100.
Overflow Strategy: This determines which messages will be dropped when the Max Pending Messages is reached. Select one of two options - Drop New or Drop Oldest. Drop New is the default setting.
ICD-008 TDIS Alarms
We have created new TDIS Alarms which are a representation of the internal alarms used in the software. Alarm records will be sent when the alarm is first raised and then again when the alarm is cleared.
The ClearWay™ MQTT client will queue outgoing messages.
On a ClearWay™ system restart, any open or active alarms which are in the database and fall within a specified time period since activation will be sent to the TDIS system.
ClearWay™ TDIS Alarm Fields
Common Alarm Fields:
Ser | Field Names | Type | Notes |
1 | _Id | UUID | Internal unique Id of the alarm instance. |
2 | UserId | Int64 | Unique user-friendly numeric Id of the alarm instance. |
3 | Name | String | Contains the alarm title (for system alarms). |
4 | Description | String | Contains the alarm description. |
5 | RuleConfigUserId | Int64 | The user-friendly Id of the rule that generated the alarm. |
6 | AlarmType | String |
|
7 | Priority | String |
|
8 | Severity | String |
|
9 | Key | String | Combination of the rule and alarm location; unique for each alarm type and location. |
10 | Raised | Date/Time | When the alarm was first raised. |
11 | Updated | Date/Time | When it was last updated (meaning the rule is still being broken). |
12 | SensorUserId | Int64 | The user-friendly Id of the radar. |
13 | Position | Sub-Document | Position of the alarm based on WGS84 Lat / Long coordinates given in decimal degrees format. Note: it can be 0,0,0 if position is not relevant. |
14 | Active | Bool | Indicates if the alarm is currently active or closed. |
15 | Acknowledged | Date/Time | The time the alarm was acknowledged either by one of our users or from an external system. |
16 | Cleared | Date/Time | The time the alarm was cleared (this is an automatic process for AID alarms). |
17 | AcknowledgedByUser | String | The user-friendly display name of the user who acknowledged the alarm. |
18 | AcknowledgmentNotes | String | Notes provided by our user who acknowledged the alarm. |
19 | AcknowledgmentStatus | String | This is from a list of user-definable status strings that the customer can choose (our UI). |
Highways AID Alarm Fields:
Ser | Field Names | Type | Notes |
20 | ReportedLaneId | Int64 | User-friendly Id of the lane where the alarm occurred. |
21 | SectionUserId | Int64 | User-friendly Id of the section where the alarm occurred. |
22 | CarriagewayUserId | Int64 | User-friendly Id of the carriageway where the alarm occurred. |
23 | DistanceFromSensor | Double | Distance from the radar to the alarm location. |
24 | CarriagewayName | String | User-friendly name of the carriageway. |
25 | RuleSubType | String |
|
26 | RuleClassification | String |
|
27 | LastTrackSpeed | Double | Speed of the last track seen associated with this alarm. |
28 | LastTrackCourse | Double | Direction of the last track seen associated with this alarm. |
29 | LastTrackSize | Double | Size of the last track seen associated with this alarm. |
30 | LastTrackId | String | User-friendly Id of the last track seen associated with this alarm. |
31 | LastTrackClassification | String | Classification of the last track seen associated with this alarm (see RuleClassification). |
System Health Alarm Fields:
Ser | Field Names | Type | Notes |
20 | AlarmSubType | String | The alarm type:
|
TDIS Alarm Examples
All MQTT payloads will be JSON and encoded using UTF-8.
ClearWay™ TDIS Incident Alarm:
{
"_id" : UUID("f8aa8a10-3e91-492c-8608-f2cc42f7348b"),
"UserId" : NumberLong(115908),
"Name" : "Health Alarm",
"Description" : "Pedestrian in Section - 4",
"RuleConfigUserId" : NumberLong(7),
"AlarmType" : "AlarmAndFollow",
"Priority" : "Medium",
"Severity" : "Threat",
"Key" : "5e2cf96c-4407-422f-9534-3c6cc15fa80ccd75a650-bb64-47c5-bd04-c1cebbf9345fSlow",
"Raised" : ISODate("2023-01-15T17:06:55.160Z"),
"Updated" : ISODate("2023-01-15T17:06:58.458Z"),
"SensorUserId" : NumberLong(1),
"Position" : {
"Latitude" : 55.125678,
"Longitude": -1.539697932,
"Altitude" : 0.0
},
"Active" : false,
"Acknowledged" : ISODate("2023-01-15T17:07:08.738Z"),
"Cleared" : ISODate("2023-01-15T17:07:08.738Z"),
"AcknowledgedByUser" : "Navtech Management Server",
"AcknowledgmentNotes" : null,
"AcknowledgmentStatus" : null,
"ReportedLaneId" : NumberLong(0),
"SectionUserId" : NumberLong(4),
"CarriagewayUserId" : NumberLong(1),
"DistanceFromSensor" : 9.84669085702725,
"CarriagewayName" : "School Road",
"RuleSubType" : "Person",
"RuleClassification" : "Person",
"LastTrackSpeed" : 5.37717932967923,
"LastTrackCourse" : 52.5515141755066,
"LastTrackSize" : 23.1223161041835,
"LastTrackId" : "2142-5e2cf96c",
"LastTrackClassification" : "Person"
}
ClearWay™ System / Health Alarm:
{
"_id" : UUID("0fa2f451-d764-41da-9208-311587c924fd"),
"UserId" : NumberLong(907),
"Name" : "Health Alarm",
"Description" : "Radar 001 Connection status Warning",
"RuleConfigUserId" : NumberLong(0),
"AlarmType" : "Alarm",
"Priority" : "Lowest",
"Severity" : "Warning",
"Key" : "801f1239-38e8-1f12-9138-801f1239138eConnection",
"Raised" : ISODate("2023-01-17T15:26:16.640Z"),
"Updated" : ISODate("2023-01-17T15:26:16.640Z"),
"SensorUserId" : NumberLong(0),
"Position" : {
"Latitude" : 0.0,
"Longitude": 0.0,
"Altitude" : 0.0
},
"Active" : false,
"Acknowledged" : ISODate("2023-01-17T15:26:32.641Z"),
"Cleared" : ISODate("2023-01-17T15:26:32.641Z"),
"AcknowledgedByUser" : "Radar 001",
"AcknowledgmentNotes" : null,
"AcknowledgmentStatus" : null,
"AlarmSubType" : "HealthAlarm"
}