Skip to content

MQTT Channel Subscription

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

To create a subscription with an MQTT channel, you can use the POST /subscription REST API such as the following example:

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 EdgeXpert Manger to manage subscriptions, which is the graphical user interface (GUI) of EdgeXpert. To launch EdgeXpert Manger, use the following command:

edgexpert up xpert-manager

Example MQTT notifications

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

The examples require the Alerts and Notifications Service to be running. A suitable 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 the above command 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

Using 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"
    }
  }
]'

Using Unencrypted Transport, Authenticated Client (Username/Password)

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"
    }
  }
]'

Using Encrypted Transport, Unauthenticated Client

In the following example, the MQTT broker supports encrypted transport and unauthenticated clients.

Before creating a subscription, download the server's certificate authority file (mosquitto.org.crt (PEM format)) then add it to Vault using the POST /secret REST API Note that the key must be cacert. For example:

curl -X POST \
'http://localhost:59860/api/v2/secret' \
-H 'Content-Type: application/json' \
-d '
{
  "apiVersion": "v2",
  "path": "mqtt",
  "secretData": [
    {
      "key": "cacert",
      "value": "-----BEGIN CERTIFICATE-----\nMIIEAzCCAuugAwIBAgIUBY1hlCGvdj4NhBXkZ/uLUZNILAwwDQYJKoZIhvcNAQEL\nBQAwgZAxCzAJBgNVBAYTAkdCMRcwFQYDVQQIDA5Vbml0ZWQgS2luZ2RvbTEOMAwG\nA1UEBwwFRGVyYnkxEjAQBgNVBAoMCU1vc3F1aXR0bzELMAkGA1UECwwCQ0ExFjAU\nBgNVBAMMDW1vc3F1aXR0by5vcmcxHzAdBgkqhkiG9w0BCQEWEHJvZ2VyQGF0Y2hv\nby5vcmcwHhcNMjAwNjA5MTEwNjM5WhcNMzAwNjA3MTEwNjM5WjCBkDELMAkGA1UE\nBhMCR0IxFzAVBgNVBAgMDlVuaXRlZCBLaW5nZG9tMQ4wDAYDVQQHDAVEZXJieTES\nMBAGA1UECgwJTW9zcXVpdHRvMQswCQYDVQQLDAJDQTEWMBQGA1UEAwwNbW9zcXVp\ndHRvLm9yZzEfMB0GCSqGSIb3DQEJARYQcm9nZXJAYXRjaG9vLm9yZzCCASIwDQYJ\nKoZIhvcNAQEBBQADggEPADCCAQoCggEBAME0HKmIzfTOwkKLT3THHe+ObdizamPg\nUZmD64Tf3zJdNeYGYn4CEXbyP6fy3tWc8S2boW6dzrH8SdFf9uo320GJA9B7U1FW\nTe3xda/Lm3JFfaHjkWw7jBwcauQZjpGINHapHRlpiCZsquAthOgxW9SgDgYlGzEA\ns06pkEFiMw+qDfLo/sxFKB6vQlFekMeCymjLCbNwPJyqyhFmPWwio/PDMruBTzPH\n3cioBnrJWKXc3OjXdLGFJOfj7pP0j/dr2LH72eSvv3PQQFl90CZPFhrCUcRHSSxo\nE6yjGOdnz7f6PveLIB574kQORwt8ePn0yidrTC1ictikED3nHYhMUOUCAwEAAaNT\nMFEwHQYDVR0OBBYEFPVV6xBUFPiGKDyo5V3+Hbh4N9YSMB8GA1UdIwQYMBaAFPVV\n6xBUFPiGKDyo5V3+Hbh4N9YSMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQEL\nBQADggEBAGa9kS21N70ThM6/Hj9D7mbVxKLBjVWe2TPsGfbl3rEDfZ+OKRZ2j6AC\n6r7jb4TZO3dzF2p6dgbrlU71Y/4K0TdzIjRj3cQ3KSm41JvUQ0hZ/c04iGDg/xWf\n+pp58nfPAYwuerruPNWmlStWAXf0UTqRtg4hQDWBuUFDJTuWuuBvEXudz74eh/wK\nsMwfu1HFvjy5Z0iMDU8PUDepjVolOCue9ashlS4EB5IECdSR2TItnAIiIwimx839\nLdUdRudafMu5T5Xma182OC0/u/xRlEm+tvKGGmfFcN0piqVl8OrSPBgIlb+1IKJE\nm/XriWr/Cq4h/JfB7NTsezVslgkBaoU=\n-----END CERTIFICATE-----\n"
    }
  ]
}'

Note that the original secret files contain some newline characters that can cause a JSON parsing error, so you cannot copy/paste them directly. Use the following command to parse the secret files to get JSON-valid strings:

awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' YOUR_SECRET_FILE

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": "tcps",
      "host": "test.mosquitto.org",
      "port": 8883,
      "publisher": "notification-service",
      "topic": "iotech/notification",
      "secretPath": "mqtt",
      "authMode": "cacert"
      }
    ],
    "labels": [
      "mqtt"
      ],
    "receiver": "test-mqtt",
    "adminState": "UNLOCKED"
    }
  }
]'

Using Encrypted Transport, Authenticated Client (TLS certificate)

In the following example, the MQTT broker supports encrypted transport and client authentication.

Before creating a subscription, follow the instructions on https://test.mosquitto.org/ssl/ to prepare a TLS client key and certificate and download the server's certificate authority file (mosquitto.org.crt (PEM format)). Then add them to Vault using the POST /secret REST API Note that the keys must be clientkey, clientcert and cacert respectively. For example:

curl -X POST \
'http://localhost:59860/api/v2/secret' \
-H 'Content-Type: application/json' \
-d '
{
  "apiVersion": "v2",
  "path": "mqtt",
  "secretData": [
    {
      "key": "cacert",
      "value": "-----BEGIN CERTIFICATE-----\nMIIEAzCCAuugAwIBAgIUBY1hlCGvdj4NhBXkZ/uLUZNILAwwDQYJKoZIhvcNAQEL\nBQAwgZAxCzAJBgNVBAYTAkdCMRcwFQYDVQQIDA5Vbml0ZWQgS2luZ2RvbTEOMAwG\nA1UEBwwFRGVyYnkxEjAQBgNVBAoMCU1vc3F1aXR0bzELMAkGA1UECwwCQ0ExFjAU\nBgNVBAMMDW1vc3F1aXR0by5vcmcxHzAdBgkqhkiG9w0BCQEWEHJvZ2VyQGF0Y2hv\nby5vcmcwHhcNMjAwNjA5MTEwNjM5WhcNMzAwNjA3MTEwNjM5WjCBkDELMAkGA1UE\nBhMCR0IxFzAVBgNVBAgMDlVuaXRlZCBLaW5nZG9tMQ4wDAYDVQQHDAVEZXJieTES\nMBAGA1UECgwJTW9zcXVpdHRvMQswCQYDVQQLDAJDQTEWMBQGA1UEAwwNbW9zcXVp\ndHRvLm9yZzEfMB0GCSqGSIb3DQEJARYQcm9nZXJAYXRjaG9vLm9yZzCCASIwDQYJ\nKoZIhvcNAQEBBQADggEPADCCAQoCggEBAME0HKmIzfTOwkKLT3THHe+ObdizamPg\nUZmD64Tf3zJdNeYGYn4CEXbyP6fy3tWc8S2boW6dzrH8SdFf9uo320GJA9B7U1FW\nTe3xda/Lm3JFfaHjkWw7jBwcauQZjpGINHapHRlpiCZsquAthOgxW9SgDgYlGzEA\ns06pkEFiMw+qDfLo/sxFKB6vQlFekMeCymjLCbNwPJyqyhFmPWwio/PDMruBTzPH\n3cioBnrJWKXc3OjXdLGFJOfj7pP0j/dr2LH72eSvv3PQQFl90CZPFhrCUcRHSSxo\nE6yjGOdnz7f6PveLIB574kQORwt8ePn0yidrTC1ictikED3nHYhMUOUCAwEAAaNT\nMFEwHQYDVR0OBBYEFPVV6xBUFPiGKDyo5V3+Hbh4N9YSMB8GA1UdIwQYMBaAFPVV\n6xBUFPiGKDyo5V3+Hbh4N9YSMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQEL\nBQADggEBAGa9kS21N70ThM6/Hj9D7mbVxKLBjVWe2TPsGfbl3rEDfZ+OKRZ2j6AC\n6r7jb4TZO3dzF2p6dgbrlU71Y/4K0TdzIjRj3cQ3KSm41JvUQ0hZ/c04iGDg/xWf\n+pp58nfPAYwuerruPNWmlStWAXf0UTqRtg4hQDWBuUFDJTuWuuBvEXudz74eh/wK\nsMwfu1HFvjy5Z0iMDU8PUDepjVolOCue9ashlS4EB5IECdSR2TItnAIiIwimx839\nLdUdRudafMu5T5Xma182OC0/u/xRlEm+tvKGGmfFcN0piqVl8OrSPBgIlb+1IKJE\nm/XriWr/Cq4h/JfB7NTsezVslgkBaoU=\n-----END CERTIFICATE-----\n"
    },
    {
      "key": "clientkey",
      "value": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAuUn4gIM+nufWO+qKUEJGDu9KspYbx+vmEuu8Nev2dNjdCMo4\nXLuE9e9O1Xkbke50+HeqPksrekJ6rOpR1tMYcNqyyCXpZepvcbEQ67mUVkYw/8At\n71P6RebtVKseXvtBLheYHC0WgIxU6l6Lq624gQFnCoDaSdeDnW9mplNdsUhX7pb9\npXdVtPjHEX/el47s9LhatshvEm+UBFyUS6IrALDOeX3uAvBGgY2V9UJbvQULs6xQ\nNgS48Cc+tT+J945YTy2zl/2h6r4nmW7pkI0AaoTQTkSeKCEWIEbsYlpoJ1AuNos0\nFgnqXifeWjGILahX9wnyTQcSsMc0uDU5Da6vOQIDAQABAoIBADIc5H31gTE/KL0J\nwSDV29bcN0q3uInIrnA9m6jFyeFuadGfx8Ck4uAVOjAYUjGU2cP9sWipsfeeFUnB\nEiNU8o5LSAFD560ty7hnGFl41rrCvyvckU/iWZUgUN4ObedocweBUB2GwEhCLBE7\nQvFKydTySSkZEnDYPfuNjqi7cWKp5Qr6xzC4P5KJdPHywehHmk3O3I33EQxESp3B\nR7bZfZAJoWbUqrlJo/U92l6KchunAoaIuz5WDprOhyTycmR0sXtWndl3uVZO8h+4\nxF/agrUWP8RR8VNGfzu13qA3wLNWkXOay/rYlbpCwtN4Gu/ZegkqhAyFRpkEI33a\nipoF+AECgYEA7QfloQ+URa+O9njeTzMhI/fWmXetAKFT2xRmVAjS30bjWKj/gSd8\n8glNtIWO5A+odMo9JoT0NDqBEHJuFMaDjZ3aTPrN0W7yOuGlNF2K95c055GptTun\neYc1euKBKuBloddl3y/n3z0ZZ6HNWFUv0x3AhwgbEIhhlb3UD2p43QECgYEAyB4G\nrFxayjFkN+3c4Q1COz1PI9YKauJSM9/cDy6lAEhzvBY5GxjFC1F5H5QOcsAxiF/c\ns2r/bu6CQxD7UqGUbuwT9wqkHHtFxeLFgOg1vw6ZzQ5TvZAk8LIgAui2fbDhNPJJ\nSTSUGuN3CxpjJCIQ0hvf+6AQ85wPL//EKXhzejkCgYAxmLJqtgjPYAGo/vd9WPR5\nQzWLHSh89kTGlYkn0kTVZU7S0WHNE4coWdwBhuS0QbZ84YhUFAPJHei9mUQBYtxJ\n+Jqh+uSwCufyfB6GS4B1eBUg0zDQdDAB1NHS6awfXZ7Gc3yka7C33GABeDCwZ/q+\n0P3lA0QufGr22yaRJzUtAQKBgQCRowB6SdAtHBrydSJtiqer0yeYTfpQ5Rqr8/wD\n9I9SkGfh905iAPnODeIXcDm/m02xEQrebD0vL1cPlflBnqQWwaqZ/F2I+NHDfRD9\nioEq5WZbDFU3PQMVRJz1YQUGnkaXsMhTBXfPxcDqDK8gKcaSEoVEa65KjEWlSf8p\nqyZnSQKBgAonBamLiiNoIkCWZrggVeZC4Yyq3Tok0V92Q1Yp0A+Uj6BhFU5dl8fF\nue/QYWNIIPf8y+5IPrlia7d3O9M8bb19tRNGN80me/GmeYcLYE5TDfpqvxfrzqv7\nuqAofGgD0MuIAeOivS4VgJ4xGhALG6sY8gFStoythBWsJZA0PzUq\n-----END RSA PRIVATE KEY-----\n"
    },
    {
      "key": "clientkey",
      "value": "-----BEGIN CERTIFICATE-----\nMIIDgTCCAmmgAwIBAgIBADANBgkqhkiG9w0BAQsFADCBkDELMAkGA1UEBhMCR0Ix\nFzAVBgNVBAgMDlVuaXRlZCBLaW5nZG9tMQ4wDAYDVQQHDAVEZXJieTESMBAGA1UE\nCgwJTW9zcXVpdHRvMQswCQYDVQQLDAJDQTEWMBQGA1UEAwwNbW9zcXVpdHRvLm9y\nZzEfMB0GCSqGSIb3DQEJARYQcm9nZXJAYXRjaG9vLm9yZzAeFw0yMjAxMDQxNjM2\nNTlaFw0yMjA0MDQxNjM2NTlaMFsxCzAJBgNVBAYTAlRXMQ8wDQYDVQQIDAZUYWl3\nYW4xDzANBgNVBAcMBlRhaXBlaTENMAsGA1UECgwEVGVzdDEMMAoGA1UECwwDREVW\nMQ0wCwYDVQQDDARURVNUMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA\nuUn4gIM+nufWO+qKUEJGDu9KspYbx+vmEuu8Nev2dNjdCMo4XLuE9e9O1Xkbke50\n+HeqPksrekJ6rOpR1tMYcNqyyCXpZepvcbEQ67mUVkYw/8At71P6RebtVKseXvtB\nLheYHC0WgIxU6l6Lq624gQFnCoDaSdeDnW9mplNdsUhX7pb9pXdVtPjHEX/el47s\n9LhatshvEm+UBFyUS6IrALDOeX3uAvBGgY2V9UJbvQULs6xQNgS48Cc+tT+J945Y\nTy2zl/2h6r4nmW7pkI0AaoTQTkSeKCEWIEbsYlpoJ1AuNos0FgnqXifeWjGILahX\n9wnyTQcSsMc0uDU5Da6vOQIDAQABoxowGDAJBgNVHRMEAjAAMAsGA1UdDwQEAwIF\n4DANBgkqhkiG9w0BAQsFAAOCAQEATD1vpwSuhDJ2xyNI2Mtw39J/EuDZCE3JxWtL\nbtCM0/MUKQhePvXCoEmHzWvBTcetIakrvlhy7KkqRabtJ+n/Zc6EhgO6RMsgS014\nuh7xq4tZZYdV8kOxHjwo04ZdKVUu7AKZanWB1XZUxAIyh5Wt9r/qbmV5lyhKR7Zq\nodQqgveCGfSXk7AGAj/qXvSHLdwqeAp09xnd4o+8hV3LBhrGkoSQpayCkEkS47rK\nxOHNcCtrjti+4ZyrjZqcqLDJtEW+o579XWqzbfmPj45e3vuARVNz725uzrDFOawP\nDvs211WhtW40426jqXAGKiEi+fD5AkxPPHQ9x8SfyZBHJkAcUA==\n-----END CERTIFICATE-----\n"
    }
  ]
}'

Note that the original secret files contain some newline characters that can cause a JSON parsing error, so you cannot copy/paste them directly. Use the following command to parse the secret files to get JSON-valid strings:

awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' YOUR_SECRET_FILE

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 http://localhost:59860/api/v2/subscription -X POST -H "Content-Type: application/json" \
  -d '[
   {
      "apiVersion":"v2",
      "subscription":{
         "name":"Subscription-mqtt",
         "description":"sample",
         "channels":[
            {
                "type": "MQTT",
                "scheme": "tcps",
                "host": "test.mosquitto.org",
                "port": 8884,
                "publisher": "notification-service",
                "topic": "iotech/notification",
                "secretPath": "mqtt",
                "authMode": "clientcert"
            }
         ],
         "labels":[
            "mqtt"
         ],
         "receiver":"test-mqtt",
         "adminState":"UNLOCKED"
      }
   }
]'

Send a Notification

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"
    }
  }
]'

Receiving the Notifications

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

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

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

mosquitto_sub -v -h test.mosquitto.org -p 8883 --cafile mosquitto.org.crt -t iotech/notification

To receive the notifications through encrypted transport and authenticated client (TLS certificate), use the following command:

mosquitto_sub -v -h test.mosquitto.org -p 8884 --cafile mosquitto.org.crt --cert client.crt --key client.key -t iotech/notification

You should see see a notification as follows:

iotech/notification hello
Back to top