Skip to content

ZeroMQ Channel Subscription

Services can subscribe to the ZeroMQ channel by specifying the host and port of the Alerts and Notifications microservice to receive notifications.

To create a subscription with a ZeroMQ channel, you can use the 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-ZeroMQ",
          "channels": [
            {
              "type": "ZeroMQ",
              "host": "*",
              "port": 5663,
              "topic": "iotech/notification"
            }
          ],
          "labels": [
            "zmq"
          ],
          "receiver": "test-group",
          "adminState": "UNLOCKED"
        }
      }
    ]'

The fields are described in the following table

Name Description Value
type Channel Type ZeroMQ
host The local address interface used when creating a socket for ZeroMQ. For further information, refer to ZeroMQ API Reference.
  • The wild-card *, meaning all available interfaces.
  • The primary IPv4 or IPv6 address assigned to the interface, in its numeric representation.
  • The non-portable interface name as defined by the operating system.
port TCP port of the ZeroMQ channel. Note that the port must be exposed by the container running the the Alerts and Notifications microservice. For example: 5663
topic The topic to use when filtering messages. This is used in the ZeroMQ channel as the key of the Pub/Sub envelope. For example: iotech/notification

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 ZeroMQ notifications

This example require the Alerts and Notifications Service and Virtual Device Service to be running. A suitable command to start the required Edge Xpert Services is as follows:

edgexpert up support-notifications device-virtual

Creating a subscription

To create a subscription with a ZeroMQ channel, use the following command:

curl -X POST \
'http://localhost:59860/api/v2/subscription' \
-H 'Content-Type: application/json' \
-d '[
{
  "apiVersion": "V2",
  "subscription": {
    "name": "Subscription-ZeroMQ",
    "description": "test data for subscription",
    "channels": [{
      "type": "ZeroMQ",
      "host": "*",
      "port": 5663,
      "publisher": "notification-service",
      "topic": "iotech/notification"
      }
    ],
    "categories": [
      "DEVICE_CHANGED"
     ],
    "labels": [
      "metadata"
      ],
    "receiver": "test-zmq",
    "adminState": "UNLOCKED"
    }
  }
]'

Receiving the Notifications

The following example use the zmcat utility to demonstrate the receipt of Device Changed notifications from the ZeroMQ channel:

*Note: The zmcat utility can only be installed in Python2.7 To make sure the zmcat is installed in Python2.7, use this command python2.7 -m pip install zmcat. Also make sure you are running the correct zmcat binary file, for example: /path/to/Library/Python/2.7/bin/zmcat sub tcp://127.0.0.1:5663 --key=mytopic (The location of the zmcat binary file may vary depending on OS.)

To receive the notifications, use the following commands:

# retrieve support-notification container ip address
HOST_IP=$(docker inspect support-notifications --format\='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}')

# run zmcat command to receive the notifications
/path/to/Library/Python/2.7/bin/zmcat sub tcp://${HOST_IP}:5663 --key=iotech/notification

Follow the instructions here to create a Device Changed notification.

Now you should see a notification as follows:

Meatadata notice:  {"deviceName":"Random-Boolean-Device","deviceServiceName":"device-virtual","actionType":"Device update","operatingState":"UP","adminState":"UNLOCKED"}
Back to top