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.

Important Notice!

This article describes using the legacy Message Queue V1, and is only valid when MQ V1 is used.

Most new MQ activations will be V2 by default, and the documentation for MQ V2 is located directly in sepioo:

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@sepioo.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": {
      ...
  }
}