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.
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.
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 "@iot.id" 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.
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). |
