MQTT Topics

BADGER

MQTT topics have grown somewhat organically, with an inspiration from the Homie IoT Convetion - albeit v1. However, things have expanded from there and there are various attempts to extend the approach, some of which worked, and others which didn’t. This page will try to enumerate the entire known SMC mqtt universe…​

Structure

There is no single mental model that captures all of our topics neatly. Very roughly though, there is a sort-of structure, in that topics typically:

  • start with sets of key-value pairs

  • revolve around an 'anchoring' topic, which has a raw message on it

  • and may have optional 'suffix' topics to add some metadata about the topic

There are exceptions, including notably in cases where we actually have a 'collection' of messages against some id, where our rough structure would ideally have had an 'anchor' topic.

This will hopefully all make more sense when you read the actual topic structure below…​

Devices

The concept of a 'device' is a little hazy (see the Glossary).

Services also report themselves as Devices

Devices Topic Tree

Topic Purpose Message Notes

devices

devices is always the first term.

None

As this term never varies it could be considered redundant. Its purpose at this time is really therefore just to indicate that the topics underneath it follow the SMC conventions. We can create new namespaces alongside if we want. There is no agreement on whether and what these additional namespaces might actually be yet.

devices/<device_id>

devices is always followed by the Device ID

None

There is no convention around Device IDs

devices/<device_id>/$<property>

'dollar-topic' declare (ideally static) properties for the Device

See the following section for details of the specific properties available

Static Device Properties

Topic Purpose Message Notes

devices/<device_id>/$name

The display name for this device

String. e.g. Faccombe Scada Pi

A static property of the device

devices/<device_id>/$fwname

A firmware name

String.

All nodejs services report @dgcsdev/edge-service-wrapper

A static property of the device

devices/<device_id>/$fwversion

The firmware version

Semver. e.g. 1.2.3

A static property of the device

devices/<device_id>/$srvname

The service name

String. e.g. @dgcsdev/influx-writer

A static property of the device
Typically only used by the nodejs services to differentiate between the underlying firmware and the specific module running in this service

devices/<device_id>/$srcversion

The service version

Semver. e.g. 1.2.3

A static property of the device

devices/<device_id>/$host

The hostname of the OS on which the agent reporting this device data is running

String. e.g. syrah or 9dc9243

A static property of the device

devices/<device_id>/$localip

The ip address of the OS on which the agent reporting this device data is running

IPv4. e.g. 10.0.0.99

A static property of the device

devices/<device_id>/$nodes
TBD by Miles

Dynamic Device Properties

These should probably be signals, rather than properties
Topic Purpose Message Notes

devices/<device_id>/$online

The status of the device

true or false

This can be set either explicitly by the device, or via an MQTT last-will-and-testament

devices/<device_id>/$uptime

How long the device has been 'up'.

Integer
It’s not clear whether this is in milliseconds or seconds

devices/<device_id>/$signal

The strength of the wifi signal

Integer. 0-100

Deprecated Device Topics

Topic Notes

devices/<device_id>/$uiversion

This was relevant when the UI service was part of the infra structures. I do not think it is used anymore

Signals

Signals are 'owned' by Devices, and all the following topics live underneath devices/<device_id>/, which is represented by the shorthand prefix '…​'.

Signals Topic Tree

Topic Purpose Message Notes

…​/signal

signal declares this part of the topic tree

None

…​/signal/<signal_id>

signal is always followed by the Signal ID

The raw signal message.
This takes the form:

{
    "time": <ISO-8601-timestamp>,
    "value": ...
}

There is no convention around Signal IDs.

…​/signal/<signal_id>/properties

This declares the existence of a signal, along with its properties

See Signal Properties

…​/signals/<signal_id>/alert

An alert generated against this signal

See Signal Alerts

This alert may be generated by the device itself, or on behalf of the device by another service

…​/signals/<signal_id>/warning
TBD by Miles

…​/signals/<signal_id>/collection/<sub-id>

Used when a Signal is actually comprised of a number of signals, each with their own sub-id

Same as a signal:

{
    "time": <ISO-8601-timestamp>,
    "value": ...
}
This is mostly used by the Dashboard generator, but for a context which can and should be moved over to ArangoDB.

Service Topics

Some services expose or consume non-standard topics.