MQTT¶
Station Signals¶
Real-time data from stations is collected over MQTT, an open-source, lightweight messaging protocol designed for IoT.
The specific types of data accepted by Busroot are called 'Signals'. The following signals are currently supported:
| Signal Key/Field | Description |
|---|---|
production_complete_good production_complete (alias) |
The number of new (good) production units created. |
production_count_good production_count (alias) |
The running count of new (good) production units created. (i.e. the number of new units is this count minus the previously received count) |
production_complete_bad bad_production_complete (alias) |
The number of new bad/reject production units created. |
production_count_bad bad_production_count (alias) |
The running count of new bad/reject production units created. (i.e. the number of new units is this count minus the previously received count) |
| bad_production_reason | Quality reason code for the bad production reported in the same message, so quality losses can be analysed by cause. Should match a reason code of type quality configured on the account — an unrecognised code is still recorded and displayed as the raw code, and bad production without a reason is recorded as "Unknown". |
| productive | A binary value indicating if the station is currently engaged in production. |
| electrical_kwh | The total cumulative amount of kWh consumed. This is typically from a meter reading. |
| electrical_kwh_interval | The amount of kWh consumed since the last data point. |
| electrical_kw | The power being drawn on the electrical supply in kilowatts. |
line_speed speed (alias) |
A number indicating the speed of the station. No units are assumed, so this could be a percentage or a speed such as m/s. |
| status_code | A code indicating the current status of the station. |
| non_production_reason | Declares that the station is currently in a period of non-production, and gives the reason code for it. The presence of the field is the declaration — see Non-Production Signal below. |
| rssi | The signal strength of the IoT device. |
| timestamp | The time these signals were generated, as a Unix epoch in milliseconds. Best omitted: the time of receipt is then used, which is correct for anything publishing live. |
These signals are accepted as a JSON string published to an MQTT topic for the station. e.g.
MQTT Topic: busroot/v1/[Account ID]/[Station Code]
Payload:
{
"production_count_good": 12.4,
"electrical_kwh": 15774.45
}
Non-Production Signal¶
Sometimes external logic knows a station is legitimately idle for a reason Busroot cannot detect — for example, two interlocked stations that can only run one at a time. The non_production_reason signal lets that logic declare the idle period, so the time is excluded from utilisation in the same way as a planned non-production schedule and the station is not penalised for it.
- The field's presence is the declaration. There is no separate on/off flag and no end message — to end the period, simply stop sending the field. The value is the reason code for the period, which should match a reason of type
non-productionconfigured on the account. An unrecognised code is still honoured, and is displayed as the raw code. - It is a heartbeat. Each message re-asserts non-production for the one-minute window it lands in, so publish at least once per minute for continuous coverage. If the sender stops — deliberately or through a failure — the period ends on its own, so a station can never be left stuck in non-production.
- While the period is open, the time is excluded from utilisation, no downtime is raised, and production signals from the station are not recorded. The station is presented exactly like a scheduled non-production period — Planned Non-Production (blue) on the Cockpit and tablet, with the tablet showing a "Current Planned Non-Production" card carrying the declared reason. The card has no start or end times, since the period is controlled entirely by the sender.
- It is not a schedule. No schedule is created, ended or modified — a running production schedule continues underneath and takes over again as soon as the declaration stops. A non-production schedule's reason takes precedence over the signal's, and an ongoing manual downtime takes precedence over the signal entirely.
MQTT Access¶
In order for IoT device to communicate with the Busroot MQTT broker, they must use valid credentials consisting of a Device ID and Access Token.
The Device ID is made up of the account ID followed by a / and a unique value for that device.
When using these credentials with the MQTT broker, a username, password and client ID must be provided as follows:
| MQTT Field | Value |
|---|---|
| Username | Device ID |
| Password | Access Token |
| Client ID | Device ID + / + [optional string] |
After MQTT authentication, the device is connected but can only publish and subscribe to topics prefixed with its own Account ID:
Busroot Signals Topic: busroot/v1/[Account ID]/[Station Code]\
Raw Data Topic: busroot/v1/dau/ + Device ID
Data published to the Busroot Signals topic will be processed directly by Busroot according to the signals mentioned at the top of this page.
Data published to the Raw Data topic is not processed directly by Busroot. Its purpose is to allow raw data to be sent from the device in its native format and processed in a second stage (e.g. using Node-RED), which converts the device's payload into Busroot Signals and re-publishes it to the Busroot Signals topic.
Registering Devices¶
.png)
New Device¶
The 'Add New' button will create a new device with a unique Device ID and Access Token.
Removing Access for a Device¶
When it is required that a device no longer be able to send data to Busroot, the device ID should be deleted from Busroot. Its credentials will no longer authenticate, so the device cannot reconnect to the MQTT broker.