Using MQTT

By using a MQTT Transport in this chapter, we describe the publish/subscribe ThingScale built-in MQTT Broker.

Publish / Subscribe

MQTT Endpoint

• Broker:
  • mqtt://m.thingscale.io:1883
  • mqtts://m.thingscale.io:8883
• Version : 3.1 and 3.1.1
• Support
  • QoS0(At most once)
  • QoS1(At least once)
  • QoS1(At exactly once)
• Limitation
  • Publish API cannot support QoS2

MQTT Parameters

• Client_ID
  • Client ID is between 1 and 23 characters long.We recommned <Device_ID>_<random suffix>
• Authentication
  • Username:ThingScale_ID(U******)
  • Password:DEVICE_TOKEN
• Topic
  • Publish:DEVICE_TOKEN/json/DEVICE_ID/[TAG_NAME]
  • Publish(binary):DEVICE_TOKEN/binary/DEVICE_ID/[TAG_NAME]
  • Subscribe:DEVICE_TOKEN/DEVICE_ID/subscribe
  • (NOTE)TAG_NAME is OPTIONAL
• Payload
  • JSON or Numeric or binary

About MQTT Topic

When Publish,device token that is included in the sometimes topic invalid, ThingScale will refuse the receipt of data that has been publish.
Topic is correct, if the device ID (DEVICE_ID) does not exist in the device registry, ThingScale to register in the registry as a new device. (Auto provisioning)
Subscribe at the time you are allowed to only subscribe to the <DEVICE_TOKEN> / # of topics. To send a command to the device from ThingScale, it is possible to receive a payload that has been transmitted from the Publish Service (v1/publish) in that you subscribe to <DEVICE_TOKEN> / <DEVICE_ID> / subscribe topics on the device side.

About binary(packed)

When dealing with binary data, please store the byte character as it is in the MQTT payload to specify the topic for the binary message.

Binary message as the payload of value1, is converted to the format of the hex dump string can be referenced from the Stream API.

Serialization of binary message is recommended that you store in MessagePack(http://msgpack.org)

(NOTE)

There are some questions here on how to handle failure to send(device_token missmatch,etc),as there is no mechanisum to report failure back to the device.

For more additional MQTT-related information,referMQTT V3.1 Protocol Specificationfrom IBM

Tutorial

Publish

Publish data to ThingScale (API v2.x)

Publish data to ThingScale with MQTTS(API v2.x)

In this case,root cafile=CentOS default root ca-bundle.

Subscribe

Retrieve the commands from the Publish Service