As explained in the Getting Started with Busroot document, Busroot provides an MQTT broker as a first point of contact for your sensor data.

Connecting to the MQTT Broker

There are many MQTT clients and libraries you can use depending on your platform. e.g.:

Regardless of which client you choose, you will need to provide it with the MQTT details provided to you at account creation:

  • Host (aka server)
  • Port (default: 1883)
  • Username
  • Password
  • If a secure connection is required, enable TLS in your client and ensure port is set to 8883.

Once you have your client connected to Busroot, you can begin sending sensor reading using the message structures below.

MQTT Config
Example of setting MQTT details in Node-RED.

Understanding the ‘Source’ and the ‘Type’ of Data

Busroot uses 2 tags to group all sensor data, the source of the data and the type of data.

The value you provide for the source should be a unique identifier for the ‘thing’ the data refers to. Often this is the machine being monitored, or a specific location. e.g. machine_926 or serverroom_6

The value you provide for the type should be a general, but consistent, term for the type of reading being taken. We advise underscores are used to clarify the unit if required. e.g. humidity, pressure_psi, temperature_c, temperature_f.

MQTT Message Structure

When creating any MQTT message, you need a topic and a payload.

Busroot accepts 2 message styles via MQTT. Each is designed for a slightly different use-case and are provided to make configuring your data-source/application as simple as possible.

Method 1: Simple MQTT Message Format

We refer to this as the simple format because the message payload is just the sensor reading, no additional formatting required. The source and type of data is contained in the topic.

Topic: data/[account_id]/[source]/[type]
Payload: [sensor_value]

Example:

Topic: data/abcdefg/machine_1/temperature
Payload: 54.7

The advantage of this method is that the payload does not need to be formatted as JSON. However only 1 data point can be provided per message and the timestamp of the reading will always be the time the message is sent.

Method 2 - JSON Payload

This method involves defining only the source of the data in the MQTT topic, and then providing in the payload the data points formatted as JSON.

Topic: data/[account_id]/[source]

Example:

Topic: data/hf83nvs73nf/machine1
Payload:
{
    "temp": 24.6,
    "humidity": 45.5,
    "timestamp": 1546304461000 //optional
}

Each key/value pair (apart from reserved keys) is treated as a separate data point with the key being used as the data type (in this example, temp & humidity).

The first advantage of this method is that multiple types of readings for the same source can be provided in one message.

The second advantage is that the key ‘timestamp’ can be used to explicitly set the timestamp to be used for these data points. This is useful if you are inputting historical data.

The timestamp should be provided as number (aka unix timestamp) or as a RFC 3339 string (e.g. 2020-04-28 13:15:56.456). If a timestamp is not provided, the timestamp of the reading will be the time the message is sent.