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.

The following services need to be installed on the edge in order to use the MQTT Driver:
  • 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

The MQTT Driver opens ports on the cluster to connect:
  • 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",
    "properties": {
        "level": {
            "type": "integer"
        },
        "temperature": {
            "readOnly": true,
            "type": "number"
        }
    },
    "actions": {
        "fan": {
            "input": {
                "properties": {
                    "on": {
                        "type": "boolean"
                    }
                },
                "type": "object"
            }
        }
    },
    "events": {
        "overheat": {
            "data": {
                "type": "number"
            }
        }
    }
}