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:

Info

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

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 Edge Xpert 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

ZeroMQ notifications Example

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 receiving notifications of Device Changed notifications from the ZeroMQ channel:

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

Note

The location of the zmcat binary file may vary depending on your operating system.

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