Message Queue and how to use it

About Message Queue (MQ)

In order to support near-real-time data communication, the PDi Digital system provides customers and partners data via message queues.

A message queue is a form of asynchronous service-to-service communication. Messages are stored on the queue until they are processed and deleted. Each message is processed only once, by a single consumer.

How to subscribe to the MQ

Cloud sepioo®

Listening to queues in Cloud Sepioo

This feature is disabled by default for the Cloud version of sepioo®.

Access needs to be requested to PDI Digital Support by sending us an email (support@pdi-digital.com).
After the MQ is activated, next step is to receive the MQ credentials.

https://industrial-api.azure-api.net/v2.0/{YOUR_ACCOUNT}/mqaccess

The response of this requests contains the credentials for the different queues:

[{
  "domain": "{YOUR_ACCOUNT}.button_press",
  "namespace": "industrial-messagequeue.servicebus.windows.net",
  "primaryConnectionString": "XXX", 
  "secondaryConnectionString": "XXX",
  "headers": {
    "auth": "XXX"
  },
  "url": "https://industrial-messagequeue.servicebus.windows.net/{YOUR_ACCOUNT}.button_press",
  "expires": 1898838640,
  "from": "2021-03-15T07:10:40.0902672Z"},
...
]

Different examples on how to listen to the MQs can be found on the officially Microsoft documentation site: Get started with Azure Service Bus queues (Azure.Messaging.ServiceBus) – Azure Service Bus | Microsoft Docs

On Premise sepioo®

Listening to queues in On Premise sepioo®

In the On-Premise version of the platform, the MQ is implemented with a RabbitMQ. The default credentials are “root:example”.

The queue names are:

button_press
device_data
status_update
action

Listen to queues

Different examples on the officially RabbitMQ documentation can be found on the following site: Get started with RabbitMQ queues – RabbitMQ | Docs

Which information does the MQ contain?

The Message Queue system supports different types of messages, which will be stored in different queues:

Button Press Event Queue
Device Data Queue
Status Update Queue
Action Queue

Button press event queue

This queue delivers all button press in the following format:

location: string
deviceId: string
deviceType: string
messageType: string: ”BUTTON_PRESSED”
status: string: ”SUCCESSFUL|ERROR|FAILED|DELAYED|TIMEOUT”
date: date
type: int:1|2|3|4
typeDescription: string: “TOP|BOTTOM|UP|DOWN”
duration: string: “SHORT|LONG”
data: int32: 0-2.147.483.647
page: int
counter: int
confirmedLate: boolean
customFields: object

Sample Message:
{
  "location": "{YOUR_ACCOUNT}.{YOUR_LOCATION}",
  "deviceId": "BBFFBB03",
  "deviceType": "label",
  "messageType": "BUTTON_PRESS",
  "status": "SUCCESSFUL",
  "date": "2021-01-01T00:00:00.000Z[Etc/UTC]",
  "payload": {
    "type": 1,
    "typeDescription": "TOP",
    "duration": "SHORT",
    "data": 0,
    "page": 1,
    "counter": 1,
    "confirmedLate": false,
    "customFields": {ANY_DATA},
  }
}

Device data queue

This queue delivers all device data in the following format:

location: string
deviceId: string
deviceType: string
messageType: string: ”DEVICE_DATA”
eventId: int: optional –> eventId is optional and only available if data has been actively queried by the API
externalEventId: string: optional –> externalEventId is optional and only available if data has been actively queried by the API with an external event id
status: string:”SUCCESSFUL|ERROR|FAILED|DELAYED|TIMEOUT”
date: date
type: int: 5|40|41|42|43
data: int32: 0-2.147.483.647
weight: int –> only if the device type is a scale

Sample Message:
{
  "location": "{YOUR_ACCOUNT}.{YOUR_LOCATION}",
  "deviceId": "BBFFBB03",
  "deviceType": "scale",
  "messageType": "DEVICE_DATA ",
  "status": "SUCCESSFUL",
  "date": "2021-01-01T00:00:00.000Z[Etc/UTC]",
  "payload": {
    "type": 1,
    "data": 0,
    "weight": 1,
 }
}

Status update queue

This queue delivers all device (labels, modules and access points) related status updates in the following format:

location: string
deviceId: string: optional à deviceId is filled out when labels and module data is transmitted
deviceType: string
messageType: string: ”ACCESSPOINT_STATUS_UPDATE|DEVICE_STATUS_UPDATE|EVENT_STATUS_UPDATE”
eventId : int: optional à eventId is optional and only available if data has been actively queried by the API
eventStatus: string: ”SUCCESSFUL|ERROR|FAILED|DELAYED|TIMEOUT|RUNNING”
taskId: string
taskType: string: “IMAGE|FLASHING|GET_CONFIG|SET_CONFIG|PING|REFRESH|SWITCH_PAGE|NDEF_MESSAGE|REGISTER_LABEL|REFRESH|REFRESH_DISPLAY”
taskStatus: string: ”SUCCESSFUL|ERROR|FAILED|DELAYED|TIMEOUT”
rssi: int
syncQuality: int
syncQualityLevel: “PERFECT|GOOD|AVERAGE|BAD|UNKNOWN” // from version v1.11
lqi: int
connectionStatus: string: “ONLINE|OFFLINE|DISCOVERED|UNKNOWN”,
powerStatus:string:”GOOD|BAD”,
accessPointId: int: optional à accessPointId is filled when device and accesspoint related updates are transmitted
wakeupTime: date,
date: date
currentPage: string “none, 1, 2, 3, …”
eventStatusCode: int
eventStatusCodeType: string

Sample message for an ACCESSPOINT_STATUS_UPDATE:
{
"location": "{YOUR_ACCOUNT}.{YOUR_LOCATION}",
"deviceType": "AccessPoint",
"messageType": "ACCESSPOINT_STATUS_UPDATE",
"accessPointId": 1,
"date": "2021-01-01T00:00:00.000Z[Etc/UTC]"
}

Sample message for a failed EVENT_STATUS_UPDATE:
{
"location": "{YOUR_ACCOUNT}.{YOUR_LOCATION}",
"deviceId": "BBFFBB03",
"deviceType": "label",
"messageType": "EVENT_STATUS_UPDATE",
"eventId": 1,
"eventStatus": "ERROR",
"taskId": "xxxx-yyyy-zzzz-aaaa",
"taskType": "IMAGE",
"taskStatus": "ERROR",
"date": "2021-01-01T00:00:00.000Z[Etc/UTC]"
}

Action queue

This queue delivers status updates triggered by Action Commands in the following formatting:

location: string
date: date
payload: object

The payload property is a dynamically value and will be configured separately for each action.

Sample message for a ACTION:
{
  "location": "{YOUR_ACCOUNT}.{YOUR_LOCATION}",
  "date": "2021-01-01T00:00:00.000Z[Etc/UTC]",
  "payload": {
      ...
  }
}