MQTT Driver
The MQTT Driver allows an end/leaf device to connect to the Edge Compute Platform using the MQTT protocol.
For each end/leaf device a Thing needs to be defined with @type set to "swx:mqtt-device" and Properties, Actions and Events to reflect the device's capabilities. An example can be seen below.
The driver will create a user for each "MQTT Thing" to allow publishing and subscribing to property value updates, raw data, action status updates and events. The topics for publishing and subscribing are shown below.
Logic to process property value updates sent from the cloud or action requests need to be handled by the code (on the end/leaf device) written to connect to the Edge Compute Platform using MQTT.
Installation
The Core Services of the Edge Compute Platform (v0.0.54 or higher) need to have been installed.
- ase-mqtt-driver
These services can be deployed by adding the "App - ECP MQTT Driver" application from the Marketplace to your own space (see Marketplace).
Figure 1.
Using the MQTT Driver
MQTT Host and Port
- ssl connection: 30142
- plain connection: 30143
The host is the IP address of the cluster.
When using the ssl connection be aware that the broker uses a self-signed certificate and that strict certificate verification will fail.
MQTT Users
The MQTT user for a "MQTT Thing" is auto-generated by the driver.
The following API endpoint can be used to retrieve these users. Specifying the
thingId as a query parameter will filter the list (omit to
retrieve the full list):
GET /drivers/mqtt/users?thingId=<thing-id>It is possible to manually manage the users, however, only one user may exist per thing:
POST /drivers/mqtt/users
GET /drivers/mqtt/users/<thing-id>
PUT /drivers/mqtt/users/<thing-id>
DELETE /drivers/mqtt/users/<thing-id>The request body for the POST and PUT requests is as follows, using sample values (for a POST request, the id should be left blank):
{
"id": "01G1NYJKKGHMM67YMHA1M1V5VD",
"thingId": "01G1GX3TJ1NHAAMDNQJP9CX9D5",
"username": "pOFEymkYHdts@ecp",
"password": "XTdGKFWgQKtqpUkucdUjyuqx"
}The thingId needs to be of an existing MQTT Thing.
The username must be unique.
MQTT Topics
The MQTT user can only publish and subscribe to topics for the associated Thing.
PUB/SUB things/{thingId}/data
PUB things/{thingId}/properties
SUB things/{thingId}/properties/#
PUB things/{thingId}/actions
SUB things/{thingId}/actions/#
PUB things/{thingId}/events
SUB things/{thingId}/events/#The message body structure is the same as used on the Altair IoT Studio cloud.
Thing Description
See the section Things for documentation on how to manage Things in Studio.
A Thing for this device driver uses a schema as described on this page.
The properties, actions and events need to be defined to suit the device's needs. The schema below is just an example with "arbitrary" Property, Action and Event definitions.
Once it exists in Studio it can be synced to the cluster (asset) as shown on the Sync Things page.
{
"@type": [
"swx:mqtt-device"
],
"id": "<leave blank when creating a thing>",
"title": "MQTT Device",
"description": "MQTT Device",
"category": "<set to the cloud category to be used>",
"properties": {
"level": {
"type": "integer"
},
"temperature": {
"readOnly": true,
"type": "number"
}
},
"actions": {
"fan": {
"input": {
"properties": {
"on": {
"type": "boolean"
}
},
"type": "object"
}
}
},
"events": {
"overheat": {
"data": {
"type": "number"
}
}
}
}