MQTT Example Asynchronous Read

Introduction

Asynchronous Read is used in the subscribing flow, which means that the Device Service must subscribe to the topic and then wait for the message. When it receives the message, it parses it and converts it to reading data.

Case 1 - define the device profile with the simple value case

Asynchronous Read Simple value

The real devices can publish a single value in different formats. The user can set the expected data format as needed, such as String, Int16 or Float64.

Required attribute

subTopic (subscription topic) is used for subscribing to the topic and wait for the asynchronous value coming.
qos (Quality of Service level) is an agreement between the sender of a message and the receiver of a message that defines the guarantee of delivery for a specific message.

Device Profile Example

name: "MQTT-Device-Simulator"
manufacturer: "IOTech"
model: "MQTT-Device"
labels:
  - "mqtt"
  - "mock"
description: "The MQTT-Device is a Simulator for mocking a MQTT device"
deviceResources:
  - name: "message"
    description: "device notification message"
    attributes:
      subTopic: "${deviceName}/message"
      qos: "0"
    properties:
      # Real device publishes a binary message, which is encoded from String value. The Device Service receives the message and decodes the binary to String value.
      valueType: "String"
      readWrite: "W"
  - name: "humidity"
    description: "device humidity"
    attributes:
      subTopic: "${deviceName}/humidity"
      qos: "0"
    properties:
      # Real device publishes a binary message, which is encoded from INT16 value. The Device Service receives the message and decodes the binary to INT16 value.
      valueType: "Int16"
      readWrite: "W"  
  - name: "temperature"
    description: "device temperature"
    attributes:
      subTopic: "${deviceName}/temp"
      qos: "0"
    properties:
      # Real device publishes a binary message, which is encoded from FLOAT64 value. The Device Service receives the message and decodes the binary to Float64 value.
      valueType: "Float64"
      readWrite: "W"       
deviceCommands:
  -
    name: "testmessage"
    isHidden: false
    readWrite: "W"
    resourceOperations:
      - { deviceResource: "message"}
      - { deviceResource: "humidity"}
      - { deviceResource: "temperature"}

Case 2 - Define the device profile with the JSON string case

Asynchronous Read JSON string

The most common method is to use a message in JSON format. The real devices publish the JSON data and the Device Service parses the reading value from the specified JSON field. Then the Device Service parses the message in JSON format and gets the value from the target field.

Required attribute

msgFormat specifies the message format for device service to parse the message from the MQTT broker.
jsonPath specifies target json field to fetch.

Note

In the following device profile example, the Device Service subscribes to the topic ${deviceName}/humidity, ${deviceName}/temp and ${deviceName}/room/metric only once. When the message arrives, the Device Service can retrieve the values defined in the corresponding deviceResources section from the JSON data.

For example,

if the JSON data is {"humidity": 70,"temp": 25}, the Device Service can retrieve resources humidity and temperature
if the JSON data is {"temps":["14.5","-29.1"],"humidities":[77,67,63],"logs":["Hello","World","!"]}, the Device Service can retrieve resources temperatures, humidities and logs

name: "MQTT-Device-Simulator"
manufacturer: "IOTech"
description: "The MQTT-Device is a Simulator for mocking a MQTT device"
deviceResources:
  - name: "humidity"
    description: "room humidity"
    attributes:
      subTopic: "${deviceName}/humidity"
      qos: "0"
      msgFormat: "json"
      jsonPath: "humidity"
    properties:
      valueType: "Bool"
      readWrite: R
  - name: "temperature"
    description: "room temperature"
    attributes:
      subTopic: "${deviceName}/temp"
      qos: "0"
      msgFormat: "json"
      jsonPath: "temp"
    properties:
      valueType: "Float32"
      readWrite: R     

  - name: "temperatures"
    isHidden: true
    description: "room temperatures"
    attributes:
      subTopic: "${deviceName}/room/metric"
      qos: "0"
      msgFormat: "json"
      jsonPath: "temps"
    properties:
      valueType: "Float32Array"
      readWrite: "R"
  - name: "humidities"
    isHidden: true
    description: "room humidities"
    attributes:
      subTopic: "${deviceName}/room/metric"
      qos: "0"
      msgFormat: "json"
      jsonPath: "humidities"
    properties:
      valueType: "Int32Array"
      readWrite: "R"
  - name: "logs"
    isHidden: true
    description: "room logs"
    attributes:
      subTopic: "${deviceName}/room/metric"
      qos: "0"
      msgFormat: "json"
      jsonPath: "logs"
    properties:
      valueType: "StringArray"
      readWrite: "R"
deviceCommands:
  -
    name: "room"
    isHidden: false
    readWrite: "R"
    resourceOperations:
      - { deviceResource: "humidity"}
      - { deviceResource: "temperature"}

Sequence Diagram

Asynchronous Diagram