MQTT Channel Subscription

The Alerts and Notifications sends messages to the MQTT broker specified in the channel configuration using either TCP or TCPS network protocols.

Info

If Edge Xpert is running in secure mode, you need to replace localhost in the URL with the IP address for the service. See CLI Service Ports for details.

To create a subscription with the MQTT channel, you can use the POST /subscription REST API as follows:

curl -X POST \
'http://localhost:59860/api/v2/subscription' \
-H 'Content-Type: application/json' \
-d '[
{
  "apiVersion": "V2",
  "subscription": {
    "name": "Subscription-mqtt",
    "description": "test data for subscription",
    "channels": [{
      "type": "MQTT",
      "host": "test.mosquitto.org",
      "port": 1883,
      "publisher": "notification-service",
      "topic": "test-topic",
      "qos": 0,
      "secretPath": "mqtt",
      "authmode": "none"
      }
    ],
    "categories": [
      "DEVICE_CHANGED"
     ],
    "labels": [
      "metadata"
      ],
    "receiver": "test-mqtt",
    "adminState": "UNLOCKED"
    }
  }
]'

The fields are described in the following table

Name	Description	Value
type	Channel Type	MQTT
scheme	Protocol scheme	tcp (default) tcps
host	Broker Host	For example, 127.0.0.1
port	Broker Port	For example, 1883
publisher	The MQTT client id to publish message	For example, test-client
topic	The MQTT topic to subscribe to	For example, test-topic
qos	Quality of Service (QoS) in MQTT Messaging is an agreement between sender and receive on guarantee of delivering a message	0 - at most once (default) 1 - at least once 2 - exactly once
secretPath	specify the path to read the secret data from secrets store, Vault	mqtt
authmode	authentication method	none usernamepassword cacert clientcert
skipCertVerify	indicates if the server certificate should be skipped	true false (default)

You can also take advantage of Edge Xpert Manger to manage subscriptions, which is the graphical user interface (GUI) of Edge Xpert.

To launch Edge Xpert Manger, use the following command:

edgexpert up xpert-manager

MQTT notifications Example

The following examples use the mosquitto_sub utility to demonstrate receiving notifications from the MQTT channel.

The examples require the Alerts and Notifications to be running. A command to start the required Edge Xpert Services is as follows:

edgexpert up support-notifications

For the examples using encrypted transport or authenticated client, add an additional option --secret to launch the Secret Store (i.e. Vault):

edgexpert up --secret support-notifications

The MQTT broker test.mosquitto.org used in the following examples is hosted by the Eclipse Foundation.

Note

The legacy Common Name field of X.509 certificate has been deprecated and replaced by Subject Alternative Name (SAN) extension since Golang 1.15 (release note).However, most public MQTT brokers, such as the test.mosquitto.org mentioned in this document, have not yet updated their certificates to use SAN. The following examples using encrypted transport (i.e. TCPS) will not work as expected until the certificate of test.mosquitto.org is updated.

Create a Subscription

Unencrypted Transport

In the following example, the MQTT broker supports unencrypted transport and unauthenticated clients. To create a subscription, use the following command:

curl -X POST \
'http://localhost:59860/api/v2/subscription' \
-H 'Content-Type: application/json' \
-d '[
{
  "apiVersion": "V2",
  "subscription": {
    "name": "Subscription-mqtt",
    "description": "test data for subscription",
    "channels": [{
      "type": "MQTT",
      "host": "test.mosquitto.org",
      "port": 1883,
      "publisher": "notification-service",
      "topic": "iotech/notification",
      "authmode": "none"
      }
    ],
    "labels": [
      "mqtt"
      ],
    "receiver": "test-mqtt",
    "adminState": "UNLOCKED"
    }
  }
]'

Send a notification using the Support Notifications REST API using the following command:

curl http://localhost:59860/api/v2/notification \
-X POST -H "Content-Type: application/json" \
  -d '[
  {
    "apiVersion": "v2",
    "notification": {
      "content": "hello",
      "Category":"",
      "labels": [
        "mqtt"
      ],
      "modified": 0,
      "sender": "a",
      "severity": "NORMAL",
      "status": "NEW"
    }
  }
]'

To receive the notifications through unencrypted transport and unauthenticated client, use the following command:

mosquitto_sub -v -h test.mosquitto.org -p 1883 -t iotech/notification

You should see notifications as follows:

iotech/notification hello

Unencrypted Transport, Authenticated Client

In the following example, the MQTT broker supports unencrypted transport and authenticated clients.

For the username and password of the authenticated clients, refer to test.mosquitto.org. Before creating a subscription, use the POST /secret REST API to add the username and password to the Secret Store (Vault). Note that the keys must be username and password. For example:

curl -X POST \
'http://localhost:59860/api/v2/secret' \
-H 'Content-Type: application/json' \
-d '
{
  "apiVersion": "v2",
  "path": "mqtt",
  "secretData": [
    {
      "key": "username",
      "value": "rw"
    },
    {
      "key": "password",
      "value": "readwrite"
    }
  ]
}'

Also make a note of the path specified in the request body, it will be used as secretPath in the MQTT channel configuration below.

To create a subscription, use the following command:

curl -X POST \
'http://localhost:59860/api/v2/subscription' \
-H 'Content-Type: application/json' \
-d '[
{
  "apiVersion": "V2",
  "subscription": {
    "name": "Subscription-mqtt",
    "description":"sample",
    "channels": [{
      "type": "MQTT",
      "scheme": "tcp",
      "host": "test.mosquitto.org",
      "port": 1884,
      "publisher": "notification-service",
      "topic": "iotech/notification",
      "secretPath": "mqtt",
      "authMode": "usernamepassword"
      }
    ],
    "labels": [
      "mqtt"
      ],
    "receiver": "test-mqtt",
    "adminState": "UNLOCKED"
    }
  }
]'

Send a notification using the Support Notifications REST API using the following command:

curl http://localhost:59860/api/v2/notification \
-X POST -H "Content-Type: application/json" \
  -d '[
  {
    "apiVersion": "v2",
    "notification": {
      "content": "hello",
      "Category":"",
      "labels": [
        "mqtt"
      ],
      "modified": 0,
      "sender": "a",
      "severity": "NORMAL",
      "status": "NEW"
    }
  }
]'

To receive the notifications through unencrypted transport and authenticated client (username/password), use the following command:

mosquitto_sub -v -h test.mosquitto.org -p 1884 -u rw -P readwrite -t iotech/notification

You should see notifications as follows:

iotech/notification hello