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.

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	None Follow Alarm AlarmAndFollow
7	Priority	String	Lowest Low Medium High Highest
8	Severity	String	Unknown Friend Warning Threat
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	Person Stopped Slow Debris Reversing Queue ERA Enforcement Default
26	RuleClassification	String	None Unclassified Vehicle Person Debris Aeroplane Boat LargeVehicle Animal Drone Helicopter
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:

HealthAlarm
SystemAlarm

21

AssetCode

String

A name or code that can be used to identify a sensor or radar.

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:

{
    "AlarmSubType": "HealthAlarm"
    "AssetCode": "001",
    "_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"
}

Witness 4.0