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

On this page:

Publish / Subscribe

MQTT Endpoint

Protocol	Address:Port

Protocol	Address:Port
MQTT	mqtt://m.thingscale.io:1883
MQTTS	mqtts://m.thingscale.io:8883
Websocket	ws://m.thingscale.io:8083
Secure Websocket	wss://m.thingscale.io:8084

Version: 3.1 and 3.1.1
Support:
- QoS0(At most once) and QoS1(At least once) and QoS2(Exactly once)
- Wills:Yes
- Retained Message:Yes
- Clean sesson/Durable connections:Yes
Limitation:
- Publish API cannot support QoS2

MQTT Parameters

Client ID is between 1 and 23 characters long.We recommned <Device_ID>_<random suffix>
Username:ThingScale_ID(U******)
Password:DEVICE_TOKEN

MQTT Topic

Pub/Sub	Topic	Payload

Pub/Sub

Topic

Payload

Publish

DEVICE_TOKEN/json/DEVICE_ID/[TAG_NAME]

(NOTE)TAG_NAME is OPTIONAL

JSON or Numeric

Publish(binary_mode)

DEVICE_TOKEN/binary/DEVICE_ID/[TAG_NAME]

(NOTE)TAG_NAME is OPTIONAL

Binary(raw stream)

Subscribe

DEVICE_TOKEN/DEVICE_ID/subscribe

JSON

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)

For more information about the MQTT device connector, please refer Using MQTT

Tutorial

Publish

Publish data to ThingScale (API v2.x)

mosquitto_pub -h m.thingscale.io -t '<DEVICE_TOKEN>/json/<DEVICE_ID>' -m '{"temp":20, "humidity":50}' -d -u <ThingScale_ID> -P <DEVICE_TOKEN>

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

mosquitto_pub -h m.thingscale.io -p 8883 -t '<DEVICE_TOKEN>/json/<DEVICE_ID>' -m "23.5" --cafile /etc/pki/tls/certs/ca-bundle.crt -d -u <ThingScale_ID> -P <DEVICE_TOKEN>

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

Subscribe

Retrieve the commands from the Publish Service

mosquitto_sub -h m.thingscale.io -t '<DEVICE_TOKEN>/<DEVICE_ID>/subscribe' -u <ThingScale_ID> -P <DEVICE_TOKEN>