SensorThings API - Getting Started with MQTT

MQTT or MQ Telemetry Transport, is a light-weight messaging protocol designed for IoT devices. It attempts to minimise network bandwidth and device resource requirements.

In addition to support HTTP protocol, SensorThings API supports MQTT protocol to enhance the SensorThings service publish and subscribe capabilities. SensorThings MQTT extension provides the capability of creating Observation entity using MQTT protocol. Moreover, to receive notifications from a SensorThings service when some entities updated, a client can send a MQTT Subscribe request to the SensorThings service.

In this tutorial we will learn how to receive notification for entity updates as well as how to create Observation using MQTT. The requirement for that is to connect to the MQTT broker. First we will see how to connect to a broker.

Connect to MQTT Broker

You can connect to MQTT broker using TCP, SSL, WebSocket, or SSL WebSocket. Note that MQTT brokers supports TCP by default, but WebSocket and SSL may need to be activated on them. The default port is 1883 for TCP and 8883 for SSL.

Here is the list of connection URLs for connecting to MQTT broker:

TCP: tcp://{SensorThings domain name}:1883
SSL/TLS: ssl://{SensorThings domain name}:8883
WebSocket: ws://{SensorThings domain name}:{websocket port}/mqtt
WebSocket SSL: wss://{SensorThings domain name}:{ssl websocket port}/mqtt

Please note that the connection URLs might be slightly different depending on the client you are using for connecting to MQTT broker.

Receive Updates from SensorThings API

We can get notified when a entity is created, updated, or deleted in SensorThings service using MQTT subscribe. There are multiple ways to subscribe to SensorThings MQTT for receiving updates based on your requirements. If you want to receive notifications for everything happens for all entities you can subscribe to v1.0/#.

MQTT Subscribe
Topic v1.0/#
Response When a new entity is added or an existing entity is updated or deleted, the service returns a JSON representation of the entity.

To receive notification for a specific entity type you can subscribe to v1.0/{entityType}. For example, by subscribing to v1.0/Datastreams you will get notification when a new Datastream is created in the system, or when a Datastream is being updated or deleted.

MQTT Subscribe
Topic v1.0/{entityType}
Example v1.0/Datastreams
Response When a new Datastream is added or an existing Datastream is updated or deleted, the service returns a JSON representation of the entity.

To receive notification for entities of a specific entity you can subscribe to v1.0/{entityType}({id})/{entityType}. For example, by subscribing to v1.0/Datastreams(1)/Observations you will get notified whenever a new Observation is added to Datastreams(1), and whenever an Observation of that Datastream is being updated or deleted.

MQTT Subscribe
Topic v1.0/{entityType}({id})/{entityType}
Example v1.0/Datastreams(1)/Observations
Response When a new Observation is added to Datastreams(1) or when and existing Observation of Datastreams(1) is updated or deleted, the service returns a JSON representation of the Observation.

Please note that only JSON messages that has "" are valid. You also receive messages sent to the system for creating Observations (as explained in next section) and those message are not from SensorThings service and are not valid for client use.

Create Observation with MQTT Publish

To create an Observation entity in MQTT, you should send a MQTT Publish with a valid Observation JSON as message and topic v1.0/Datastreams({id})/Observations. Note that you should either embed the FeatureOfInterest in the JSON or a FeatureOfInterest will be created automatically by system based on the Location of the specified Datastream's Thing representation.

MQTT Publish
Topic v1.0/Datastreams({id})/Observations
Example v1.0/Datastreams(1)/Observations
Example Message
Result An Observation will be created and added to Datastreams(1).