Message types
←Overview · Index↑ · Event types→
This document specifies the supported message types and the strategies employed to define them.
Other sections can be accessed from the Overview.
1. Introduction
The main concern of the Event & Tally specification is to make possible for emitters to transmit their state changes to any interested consumer.
A secondary concern is to give connected entities a mechanism by which to highlight issues in the linkage between them. In order to address this concern the message_type field will be added as a field in every single event message being sent.
These are the supported message types:
- state
- reboot
- shutdown
- connection_lost (only used by MQTT connections)
- health (only used by WebSocket connections)
For clarity, all MQTT message types are sent using the same MQTT topic defined through the transport parameter broker_topic.
1.1. The state message type
The state message type will always be sent when the emitter changes state and issues a new event or in a response to a query state request to the Event & Tally REST API.
These will be the predominant message types being sent in an Event & Tally system.
The message structure shall have the following items:
- identity [mandatory]
- event_type [mandatory]
- timing [mandatory with some optional fields]
- payload [mandatory]
- message_type [mandatory]
Message structure
{
"identity":
{
"source_id": "6cbd0441-7882-44cd-9557-842243a0d618",
"flow_id": "ff455cf3-fb17-448b-8f4c-e6c0e294f5ed"
},
"event_type": "boolean",
"timing":
{
"creation_timestamp": "1531680501:280709600",
"origin_timestamp": "1531680501:280401700",
"action_timestamp": "1531680501:320000000"
},
"payload":
{
"value": true
},
"message_type": "state"
}
The "creation_timestamp" represents the timestamp at which an event has been created (for sensors this is the acquisition time). This field is mandatory.
The "origin_timestamp" represents the timestamp which led to the creation of an event due to external factors (a trigger). This field is optional.
The "action_timestamp" represents the timestamp at which an event should be treated or result in an action (for synchronising and dealing with delays). This field is optional.
The "action_timestamp" is not intended to be associated with delays of more than a few seconds, not for example to allow events scheduled in the future, it allows synchronisation of events in complex workflows.
The payload depends on the associated event_type (see Event types).
The flow_id will NOT be included in the response to a rest apy query state because the state is held by the source which has no dependency on a flow. It will, however, appear when being sent through one of the two specified transports because it will pass from the source through a flow and out on the network through the sender.
1.2. The reboot message type
The reboot message type will only be sent when the event emitter (source) is going to experience a planned restart. This message will announce any connected consumers that the emitter will momentarily be unavailable. The recommendation for receivers is to attempt to reconnect to the sender after a user configurable amount of time (on the receiver side) and if the WebSocket connection cannot be established or the consumer does not receive a fresh state from the MQTT broker (fresh in this context meaning more recent timestamps) to park the subscription and update the IS-04 model in the registry.
The message structure shall have the following items:
- identity [mandatory]
- timing [mandatory]
- message_type [mandatory]
Message structure
{
"identity":{
"source_id": "6cbd0441-7882-44cd-9557-842243a0d618",
"flow_id": "ff455cf3-fb17-448b-8f4c-e6c0e294f5ed"
},
"timing":{
"creation_timestamp": "1531680501:280709600"
},
"message_type": "reboot"
}
The "creation_timestamp" represents the timestamp at which the emitter established that a reboot action will follow. This field is mandatory.
1.3. The shutdown message
The shutdown message type will only be sent when the event emitter (sender) is going to experience a planned shutdown. This message will announce any connected consumers that the emitter will become unavailable. The recommendation for receivers is to park their subscription and update their IS-04 model in the registry.
The message structure shall have the following items:
- identity [mandatory]
- timing [mandatory]
- message_type [mandatory]
Message structure
{
"identity":{
"source_id": "6cbd0441-7882-44cd-9557-842243a0d618",
"flow_id": "ff455cf3-fb17-448b-8f4c-e6c0e294f5ed"
},
"timing":{
"creation_timestamp": "1531680501:280709600"
},
"message_type": "shutdown"
}
The "creation_timestamp" represents the timestamp at which the emitter established that a shutdown action will follow. This field is mandatory.
1.4. The connection lost message
The connection_lost message is going to be sent by all emitters as an MQTT WILL message to the MQTT broker. This shall be done upon first connection to the broker.
If the emitter ungracefully disconnects from the MQTT broker, the connection_lost WILL message will be sent by the broker to all consumers subscribed to its topic. Hence, the connection_lost message will only be used with MQTT connections.
The recommendation for receivers is to check for a fresh state (fresh in this context meaning more recent timestamps) after a user configurable amount of time, and if no state is received from the broker to park the subscription and update the IS-04 model in the registry.
The message structure shall have the following items:
- identity [mandatory]
- message_type [mandatory]
Message structure
{
"identity":{
"source_id": "6cbd0441-7882-44cd-9557-842243a0d618",
"flow_id": "ff455cf3-fb17-448b-8f4c-e6c0e294f5ed"
},
"message_type": "connection_lost"
}
For more information about MQTT WILL messages consult the MQTT specification and other MQTT materials:
- http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/csprd02/mqtt-v3.1.1-csprd02.html
- https://www.hivemq.com/blog/mqtt-essentials-part-9-last-will-and-testament
1.5. The health message
The health message will only be sent on a WebSocket connection as a response to a health command see Websocket transport.
The recommendation for receivers is to detect missing health responses (no health response is sent back within 5 seconds) and after a 12 seconds timeout (two consecutive missed health responses plus 2 seconds to allow for latencies) either attempt to reconnect to the WebSocket and re-initialise the subscriptions list or park the subscription and update the IS-04 model in the registry.
The message structure shall have the following items:
- timing [mandatory with some optional fields]
- message_type [mandatory]
Message structure
{
"timing":{
"origin_timestamp": "1441974485:12300000",
"creation_timestamp": "1441974485:23400000"
},
"message_type": "health"
}
The "creation_timestamp" represents the health timestamp introduced by the sender. This field is mandatory.
The "origin_timestamp" represents the original health timestamp sent by the receiver. This field is optional.