MQTT Protocol

MQTT, which stands for MQ Telemetry Transport, is a lightweight communication protocol that targets embedded devices with limited connectivity. MQTT is a mechanism that allows for:

MQTT Clients

Losant provides MQTT clients that easily wrap up the communication between Losant and a device for the following languages:

If you are not working in one of the languages above, you can use the Losant MQTT Broker directly with any MQTT client. See below for more information.

Learning MQTT

The core concept of MQTT involves publishing and subscribing to topics. Clients can publish any data they choose to any topics they choose. Other clients can then subscribe to those topics to receive that data.

What facilitates this communication is a central service called a message broker. All clients open a connection to the message broker and the broker is responsible for properly routing messages to subscribers.

The Losant Message Broker

In order to support the existing MQTT implementations, Losant provides an MQTT message broker that can be used for any arbitrary topics and payloads. To make use of Losant features including data collection, visualization, and workflows, Losant provides an opinionated MQTT implementation that must be followed.

The Losant Message Broker can be reached using several transports:

  • TCP—mqtt://broker.losant.com:1883
  • TLS—mqtts://broker.losant.com:8883
  • WebSockets—ws://broker.losant.com:80
  • Secure WebSockets—wss://broker.losant.com:443

Broker Authentication

Losant requires the client ID, username, and password fields be correctly set on all MQTT connect calls:

  • client id—Must be set to a valid Device ID that is already registered with the Losant Platform.
  • username—Must be set to a Losant Access Key.
  • password—Must be set to a Losant Access Secret, which is generated when creating an Access key.

For example, a connect call using the Javascript MQTT client is displayed below:

var client = mqtt.connect('mqtts://broker.losant.com', {
  clientId: 'my-device-id',
  username: 'my-access-key',
  password: 'my-access-secret',
})

Access Control

To connect your devices to the Losant MQTT Broker, you must use Access Keys. By default, access keys only allow access to the device-specific topics (e.g. state(/devices/state/) and commands(/devices/commands/) for every device you have allowed.

For additional control, see Additional MQTT Topics Access.

MQTT Version and Limitations

Losant supports MQTT version v3.1.1 with the following exceptions:

  • QoS 2 is not supported for publishing or subscribing, only QoS 0 and 1.
  • Retained messages are not supported.
  • CleanSession 0 is not supported.
  • Maximum message payload size is 256KB.

Losant MQTT Topics

A Losant topic is anything that starts with losant. Messages published to Losant topics gain access to the full features of the Losant IoT Platform, including data collection, visualization, and workflows.

For Losant to properly parse and understand these messages, a defined JSON-based payload format must be followed.

Publishing Device State

Device State is likely the most commonly published message. When thinking in terms of sensor data, the device state is typically the value of one or more sensors.

State Topic Form

losant/DEVICE_ID/state

State Payload Form

{
  "data" : {
    "an_attribute_name": "an_attribute_value",
    "another_attribute_name": "another_attribute_value"
  },
  "time": <Optional Timestamp>,
  "flowVersion": <Optional Workflow Version Name>
}

data (required)—Required. An object where the keys are device attribute names and the values are the values for those attributes.

time—Optional. When it is not included, Losant assumes that the reported state is for the current time. Reporting a timestamp can be beneficial, however, depending on your use case.

flowVersion—Optional. Specifies which version of a workflow(/workflows/versioning/#triggering-specific-versions) will run when triggered by the payload. When not included, the default versions of any triggering workflows will run.

Publish State Example

You’ll generally have an attribute for each sensor attached to your device. For example, if a device with ID 575ecf887ae143cd83dc4aa2 has a temperature sensor, you might report a state that has an attribute named “temperature” by publishing to the topic below with the following payload:

losant/575ecf887ae143cd83dc4aa2/state
{
  "data": {
    "temperature": 72
  },
  "time": { "$date": "2016-11-04T19:42:06.710Z" }
}

When a device publishes data in this format, Losant automatically stores the data and makes it available in our Dashboards as well as exposing it through Workflows. The attributes you send must be configured on the device before Losant will accept the data.

Subscribing to Commands

Device Commands instruct your device to perform a specific action. Commands are typically initiated using Losant Workflows. Commands include a name and an optional payload.

Command Topic Form

losant/DEVICE_ID/command

Payload Topic Form

{
  "name": "command-name",
  "payload": {}
}

name—Command name.

payload—Any JSON value that provides necessary arguments to your command.

Commands do not have to be pre-registered with Losant for them to be received. What commands your device supports is entirely up to your specific application and your device’s firmware.

Example Command Subscription

Below is a command example that instructs a thermostat associated with the device ID 575ecf887ae143cd83dc4aa2 to set itself to a specific temperature. The following payload is published on the topic below, and the device is listening on that topic for command messages:

losant/575ecf887ae143cd83dc4aa2/command
{
  "name": "set-temperature",
  "payload": {
    "temperature": 72
  }
}

Custom Topics

The Losant Broker also supports custom topics. Custom topics must be valid MQTT topics, and they cannot be an MQTT system topic or a Losant device-specific topic.

Example:

alert/machine

Custom topics can trigger workflows with the MQTT Trigger Node, and you can publish to custom topics using the MQTT Output Node.

Custom Topic Access Control

By default, access keys only allow access to the Losant device-specific topics (e.g. state and commands) for every device you have allowed. Optionally, you can give access to all custom topics or specific custom topics. See Additional MQTT Topics Access for more information.

Wildcard Topics

The Losant Broker supports wildcard topics. Both single-level and multi-level wildcards are supported in Application Workflows:

Single-level: custom/+/temperature

Multi-level: custom/#

Edge MQTT Broker

The Edge Agent exposes a local MQTT broker to be used for local machine-to-machine (M2M) communication, or trigger Edge Workflows using the MQTT Trigger to process and forward sensor data to the cloud.

You may learn more in the Edge Agent broker documentation.