Supported Message Formats
The MQTT JSON Schema A driver supports two message formats. In order for Geo SCADA Expert to process the data that it retrieves using the MQTT protocol and the MQTT JSON Schema A driver, the topics to which Geo SCADA Expert subscribes have to use these message formats. Additionally, an MQTT JSON Schema A Point of the appropriate type (analog, digital, or counter) has to exist in the database for each item of data that Geo SCADA Expert is to process from each message. Each Point has to be configured, amongst other things, to reference the name of the tag (item of data) that it represents.
MQTT JSON Schema A message content has to be enclosed in braces { } .
Each message always includes a timestamp. The timestamp is an integer, for which the value comprises the UNIX Epoch time in seconds. As part of the data processing, Geo SCADA Expert applies an offset to this timestamp, to convert the time into UTC. You specify the required offset using the 'Reported time offset from UTC' field on properties Form of the relevant MQTT JSON Schema A Device database item. (The Device item that represents the device that published the message.)
Periodic Format
Periodic Format messages are transmitted by the publishing device at regular intervals.
With such messages, the format for each item of data has the syntax:
"<Tag Name>":<Value>
with a comma separating each data item that is transmitted in a message.
The message has to include a timestamp, although this does not have to be the first entry in the tag list.
The tag names are case-sensitive.
For analogs, the <Value> can be any valid JSON number.
For digitals, the <Value> has to be 0 or 1 (for a 1-bit point).
For counters, the <Value> has to be an integer.
The following is an example of Periodic message format:
{
"time":1551869672,
"static pressure":16.09,
"differential pressure":679.003998,
"temperature":12.070,
"flow":2.764433
}
The message contains a timestamp, and data for 4 analog points.
To process all 4 items of data, 4 MQTT JSON Schema A Analog Points need to exist in the database, with each analog point configured to represent a different tag name.
So, for example, the analog point that represents the static pressure (for which the above message reports a value of 16.09) would be configured to have the Tag Name 'static pressure'. Additionally, the point's Device property would have to reference the MQTT JSON Schema A Device item that itself references both the broker from which Geo SCADA Expert retrieved the message, and the topic with which the message is associated (and to which Geo SCADA Expert has subscribed).
If a message includes an item of data for which the database does not contain a corresponding MQTT JSON Schema A Point that is In Service and has valid configuration, Geo SCADA Expert will discard that particular item of data. (So, with the above message, if suitably configured point does not exist in the database for the 'flow' tag, but points do exist for the 'static pressure', 'differential pressure', and 'temperature' tags, then Geo SCADA Expert will discard the data for the 'flow' value, but process the other 3 items of data.)
Alarm Format
Alarm Format messages are transmitted when a value change occurs that triggers the remote device to send such a message. The implementation varies, depending on the remote device's configuration. For example, the device might be configured to send Alarm Format messages when either:
- A point's value crosses an alarm threshold configured on the remote device on which that point is located. (Do not confuse this with the Alarm Limits that you can configure for the corresponding Point database item in Geo SCADA Expert.)
- A point's value changes, and the device is configured to send a message on such a value change. (Again, this configuration is on the remote device, rather than in Geo SCADA Expert.)
With this message format, a timestamp is followed by a data value, and then a status (which indicates the alarm state that is associated with the data value).
The data value has this syntax:
"<Tag Name>":<Value>
The status has the syntax:
"status":"<Tag Status>"
The following is an example of Alarm message format:
{
"time":155549007225,
"Pressure A":123.456,
"status":"high"
}
The message contains a timestamp, data for 1 analog point, and a status value.
To process the item of data, a suitable MQTT JSON Schema A Point needs to exist in the database. In this particular case, as the data is an analog, an MQTT JSON Schema A Analog Point has to exist in the database, with its Tag Name set to 'Pressure A'. Additionally, the point's Device property has to reference the MQTT JSON Schema A Device item that itself references both the broker from which Geo SCADA Expert retrieved the message, and the topic with which the message is associated (and to which Geo SCADA Expert has subscribed).
Geo SCADA Expert ignores the status value. (With both Periodic and Alarm message formats, Geo SCADA Expert uses the point's current value in conjunction with its Alarm Limit or State properties (as applicable and configured for that point in the database) to determine whether it needs to raise or clear the point's alarm status and/or log an event.)
If an Alarm format message contains an item of data for which the database does not contain a corresponding MQTT JSON Schema A Point that is In Service and has valid configuration, Geo SCADA Expert will discard that message.
With the MQTT driver and extension drivers, 'time' and 'status' are reserved words. As such, 'time' and 'status' cannot be used for tag names.
Tag names are case-sensitive.