MQTT

NUBISON IoT's standard MQTT/S protocol.

This is a guide to connect devices using the MQTT protocol to the Nubison IoT platform.

Before proceeding with the steps below, Getting Started the procedures described must be completed first.

Server Connection

Information to connect to the Nubison IoT platform's MQTT message broker.

• Server URL: Guidance during integration

• Username: Issue authentication key The authentication key created when Client ID

• Password: Issue authentication key The authentication key created when Client secret

Terms

deviceKey: The following strings constitute a device identification key for the NUBISON IoT platform.

{productCode}_{deviceIdentifier}

Getting Started > Configure Device Key Refers to the device key described in that section.

sessionId: A temporary value issued by the Nubison IoT platform server to identify transactions with a device. Used when requests and responses are exchanged between the device and the Nubison IoT server.

Basic

MQTT/S-compatible devices can connect to the NUBISON IoT platform using this communication protocol. Regardless of whether the protocol is MQTT or MQTTS, the device must attempt to connect with the specified authentication values. Initially, devices must be registered on the NUBISON IoT platform. To register the device, please refer to the manual provided below.

Add Device📘 Description of NUBISON IoT Functions > 📖 IoT Management > 📖 Device Management

Following is a description of the exchanged topics between the device and the NUBISON IoT platform. The topic varies depending on the issuer, and the device publishes and subscribes only to the topic with the relevant items.

Topic Subscription

When a device successfully connects to MQTT/S, subscribe to the following topics so the device can communicate with the Nubison IoT platform server.

{deivceKey}/#

Topic List

Device → NUBISON IoT Platform

Topics that the device publishes and the Nubison IoT platform server subscribes to.

(1) connect/{deviceKey}

Connects the device to the Nubison IoT platform server.

(2) data/{deviceKey}

Sends the device's data to the Nubison IoT platform server.

(3) heartbeat/{deviceKey}

Published to periodically update the device's connection status.

(4) res/{deviceKey} or res/{sessionId}/{deviceKey}

Published when sending a response after receiving a request from the server.

When responding to a control request, you must include the received sessionId in the topic.

(5) disconnect/{deviceKey}

Published when the device disconnects from the Nubison IoT platform.

Nubison IoT Platform → Device

Topics that the Nubison IoT platform server publishes and the device subscribes to.

(1) {deviceKey}/{sessionId}/command

Published when the Nubison IoT platform server sends a command to the device.

Case	Function	Payload
Connection Check	Published when the Nubison IoT platform server directly asks the device about its connection status.
Control Transmission	Published when the Nubison IoT platform server sends a control command to the device. On the device side, res/{deviceKey} you must reply with an ack to the topic.	control|${unitNumber}|${controlValue}
Request Latest Data	Published when the Nubison IoT platform server requests the device to send its latest data. On the device side, res/{deviceKey} you must reply with the data to the topic.

(2) {deviceKey}/res

Published when responding after receiving a request from a device.

When the Nubison IoT platform server sends an Ack to the device, it sends "the topic type that was sent to the platform" + "|1" on success, or "the topic type that was sent to the platform" + "|0" on failure.

For example, a response to the data/{deviceKey} topic is returned as "data|1" or "data|0".

Default Data Format When Using Auto Driver

If you use the auto driver, structure the data as follows.

• Send a series of strings separated by "|". (When using an auto-generated driver, the Nubison IoT platform server splits the device-sent data by "|" and stores the data in order by unit number.)

• Numeric and location data in numeric format,

• Text data in text format,

• Numeric array data as numbers concatenated with ","

• Text array data as texts concatenated with ","

• Images as base64-encoded strings

For example, set the product model units as follows

Unit 0: Temperature (number)
Unit 1: Humidity (number)
Unit 2: Mode (text)
Unit 3: Latitude (location)
Unit 4: Longitude (location)
Unit 5: Temperature data array (number array)
Unit 6: Mode data array (text array)
Unit 7: Captured image (image)

If you send data as follows

Unit 0 "Temperature" data value: 32
Unit 1 "Humidity" data value: 46
Unit 2 "Mode" data value: "default"
Unit 3 "Latitude" data value: 38.23
Unit 4 "Longitude" data value: 128.34
Unit 5 "Temperature data array" data value: [27,28,24,23,25]
Unit 6 "Mode data array" data value: ["default", "sleep", "mood"]
Unit 7 "Image" data value: /9j/4AAQSkZJRgABAQAAAQABAAD/2w...

The payload can be sent as follows.

payload =  "32|46|default|38.23|128.34|27,28,24,23,25|default,sleep,mood|/9j/4AAQSkZJRgABAQAAAQABAAD/2w..."

User Scenario

In the example below, the deviceKey is

ABCDEF_123:AB:123

We will use this for the explanation.

Device Connect (timeline record)

1. connect/ABCDEF_123:AB:123 The topic is published from the device.

2. If you receive the following from the server, the device connection topic processing has been completed successfully. - Topic: ABCDEF_123:AB:123/res - Payload: 1

Device Disconnect (timeline record)

1. disconnect/ABCDEF_123:AB:123 The topic is published from the device.

2. If you receive the following from the server, the device disconnect topic processing has been completed successfully. - Topic: ABCDEF_123:AB:123/res - Payload: 1

Data Transmission

1. data/ABCDEF_123:AB:123 Publish the topic and send data in the payload according to the specification.

Devices using the MQTT protocol do not manage device connect/disconnect state. Therefore, it is not strictly necessary to publish connect/disconnect topics before or after sending data.

Publish the device connect/disconnect topics if you want the Nubison IoT platform to keep a timeline record for tracking.

Control Handling

1. When you create a control unit and send a command from the Nubison web interface, data is sent as follows. - Topic: deviceKey/sessionID/command - Payload: control|unitNumber|controlCommandValue For the previously used example device ABCDEF_123:12:123,

   assume unit 0 exists and it controls the "power" value.

   OFFsending this means power OFF, ONsending this means power ON,

   To turn power ON, ONif you send the following, it goes as follows. (Assume the sessionID is 00eeffaa) - Topic: ABCDEF_123:AB:123/00eeffaa/command - Payload: control|0|ON

2. On the device, handle the action accordingly and return to the server as follows. - Topic: res/00eeffaa/ABCDEF_123:AB:123 - Payload: 1

Device Connection Check

A method to check whether the device is connected to the broker and able to send/receive messages.

From the service screen > Device Management > click the device and then click the following icon,

The Nubison IoT platform server sends the following connection check topic to the device. (Assume the sessionID is 00eeffaa)

• Topic: ABCDEF_123:AB:123/00eeffaa/connect

• Payload: none

When the device receives the above topic, it should respond as follows.

(Assume the sessionID is 00eeffaa)

• Topic: res/00eeffaa/ABCDEF_123:AB:123

• Payload: none