MQTT API

Modified on Tue, 26 Sep 2023 at 05:36 AM

MQTT API¶

You may enable the smartdirector to interface with external systems using MQTT publish-subscribe paradigm through a dedicated MQTT broker. The smartdirector works as a MQTT client performing publish or subscribe actions on topics defined that correspond to the data model attributes.

MQTT APIs are not enabled by default. To enable the APIs, you must configure the broker related settings before you enable the service.

Enabling MQTT API service

Navigate to the Commission System application in smartmanager and select the MQTT tab under the System Settings section.
Configure IP address of the MQTT Broker and client ID (smartdirector identity as reported to the broker)
Configure the other settings as appropriate based on your environment
Upload the certificates for the authentication
The MQTT service is automatically restarted upon saving the configuration changes
Check the the status of the connection to broker to ensure that the smartdirector is connected to the broker.

The external applications may now publish and subscribe to the attributes of the data model that are available as topics in the broker.

MQTT Brokers and Topics¶

Different MQTT Brokers may require the topics to be specified differently. These can be configured by setting the subscription topic and publishing topic settings in the MQTT configuration. Preset definitions exist for some of the common cloud providers like IBM Watson IOT, Microsoft Azure IOT, Amazon AWS IOT. You may also provide a custom definition that your broker expects.

The data formats follow the data model discussed in the HTTPs API reference¹.

The following are examples of publish and subscribe commands using Mosquitto² clients with its broker using the Default brokertype settings.

Subscribe for wall switch events in location with id 106

 mosquitto_sub -t "smartengine/event/type/location/id/106/wallSwitch/#" -u <USERID> -P <PASSWORD>

Response

{
  "location": [
    {
      "id": 106,
      "wallSwitch": {
        "lowLevelControl": {
          "brightness": 0.0
        }
      }
    }
  ]
}

Set the brightness for a location to 77%

 mosquitto_pub -t "smartengine/command/type/location/id/106/wallSwitch" -u <USERID> -P <PASSWORD> -m

request data

{
  "location": [
    {
      "id": 106,
      "wallSwitch": {
        "lowLevelControl": {
          "brightness": 77,
          "activated": 9999999999999
        }
      }
    }
  ]
}

Active an external event

 mosquitto_pub -t "smartengine/command/type/location/id/0/policyTrigger" -u <USERID> -P <PASSWORD> -m

request data

{
  "location": [
    {
      "id": 0,
      "policyTrigger":[
        {
          "name":"0:Emergency Drill",
          "activeValue": 1
        }

    }
  ]
}

Additional use cases can be implemented with MQTT in same manner as above using the examples and data models discussed in API reference guide¹.