# MQTT

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

Before proceeding with the steps below, [Getting Started](/master.md) the procedures described must be completed first. 

## Server Connection <a href="#mqtt-connection" id="mqtt-connection"></a>

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

* **Server URL**: Guidance during integration
* **Username**: [Issue authentication key](/master.md#issue-authentication-key) The authentication key created when **Client ID**
* **Password**: [Issue authentication key ](/master.md#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](/master.md#configure-device-key) Refers to the device key described in that section.&#x20;

**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.

{% content-ref url="/spaces/YdPl31s74kDY5kc1afMV/pages/-M1cY8NnF2D\_lk-HVbcX" %}
[Add Device](https://docs.en.nubison.io/nubison-iot-features/iot-management/device-management/add-device)
{% endcontent-ref %}

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 <a href="#subscription" id="subscription"></a>

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 <a href="#topics" id="topics"></a>

### Device → NUBISON IoT Platform <a href="#topics-from-device-to-server" id="topics-from-device-to-server"></a>

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

#### (1) connect/{deviceKey} <a href="#id-1-connect" id="id-1-connect"></a>

Connects the device to the Nubison IoT platform server.

> For topic publishing to simply maintain a connection status, it is recommended to publish with an empty payload. If a payload is included, the value is interpreted as the device firmware version; if it differs from a registered version, the device's firmware version information is updated. Please publish without a payload unless you intend to report the firmware version.

#### (2) data/{deviceKey} <a href="#id-2-data" id="id-2-data"></a>

Sends the device's data to the Nubison IoT platform server. Publishing this topic updates the device to a **connected** state.

#### (3) heartbeat/{deviceKey} <a href="#id-3-heartbeat" id="id-3-heartbeat"></a>

Published to periodically update the device's connection status. Publishing this topic updates the device to a **connected** state.

#### (4) res/{deviceKey} or res/{sessionId}/{deviceKey} <a href="#id-4-res" id="id-4-res"></a>

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} <a href="#id-5-disconnect" id="id-5-disconnect"></a>

Published when the device disconnects from the Nubison IoT platform. When this topic is received, the server updates the device to a **disconnected** state and records it on the timeline.

#### (6) lwt/{deviceKey}

This is a topic for MQTT's Last Will & Testament (LWT). Since a device cannot directly publish a disconnect topic in the event of an abnormal termination due to network disconnection or other reasons, you can pre-register this topic to have the broker publish messages to it on its behalf.

The configuration method involves specifying the Will message as follows when the device connects to the broker via MQTT:

* Will Topic: lwt/{deviceKey}
* Will Payload: Can be left blank

With this configuration, when the device disconnects abnormally, the broker automatically publishes lwt/{deviceKey}, and the server updates the device's status to disconnected (offline) and records it on the timeline. When terminating the connection normally, you simply publish disconnect/{deviceKey}.

### Nubison IoT Platform → Device <a href="#topics-from-server-to-device" id="topics-from-server-to-device"></a>

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

#### (1) {deviceKey}/{sessionId}/command <a href="#id-1-topics-with-sessionid" id="id-1-topics-with-sessionid"></a>

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

<table><thead><tr><th width="146">Case</th><th width="376">Function</th><th>Payload</th></tr></thead><tbody><tr><td>Connection Check</td><td>Published when the Nubison IoT platform server directly asks the device about its connection status.</td><td></td></tr><tr><td>Control Transmission</td><td><p>Published when the Nubison IoT platform server sends a control command to the device.</p><p><br>On the device side, <a href="#4-res-devicekey">res/{deviceKey}</a> you must reply with an ack to the topic.</p></td><td>control|${unitNumber}|${controlValue}</td></tr><tr><td>Request Latest Data</td><td>Published when the Nubison IoT platform server requests the device to send its latest data.<br>On the device side,  <a href="#4-res-devicekey">res/{deviceKey}</a> you must reply with the data to the topic.</td><td></td></tr></tbody></table>

#### (2) {deviceKey}/res <a href="#id-2-res" id="id-2-res"></a>

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 <a href="#default-payload" id="default-payload"></a>

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&#x20;

```
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&#x20;

```
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 <a href="#scenarios" id="scenarios"></a>

In the example below, the deviceKey is `ABCDEF_123:AB:123` We will use this for the explanation.&#x20;

### Device Connect (connection status update + timeline recording) <a href="#connect-scenario" id="connect-scenario"></a>

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`&#x20;

> Unlike TCP/IP, the MQTT protocol does not automatically track the device's connection status through socket connections and disconnections. Therefore, if you are only transmitting data, you do not necessarily need to publish connect/disconnect topics. However, if you wish to manage the device's connection status (online/offline) or track connection and disconnection timelines on the Nubizen IoT Platform, please publish connect/disconnect topics or periodically publish heartbeat topics. To automatically detect abnormal terminations, you can use LWT settings in conjunction with these.

### Data Transmission (connection status update) <a href="#send-data-scenario" id="send-data-scenario"></a>

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

### Control Handling (timeline recording) <a href="#control-scenario" id="control-scenario"></a>

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.&#x20;

   `OFF`sending this means power OFF, `ON`sending this means power ON, To turn power ON, `ON`if you send the following, it goes as follows. (Assume the sessionID is 00eeffaa)\
   \- **Topic**: `ABCDEF_123:AB:123/00eeffaa/command`\
   \- **Payload**: `control|0|ON`<br>
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 Disconnect (connection status update + timeline recording) <a href="#disconnect-scenario" id="disconnect-scenario"></a>

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`&#x20;

### Automatic abnormal termination detection (LWT, timeline recording)

This is a method to handle cases where the device cannot directly publish the disconnect topic due to network disconnection or other reasons.

1. When the device connects to the broker via MQTT, set the Will Topic to lwt/ABCDEF\_123:AB:123. (The Will Payload can be left empty.)
2. If the device disconnects abnormally, the broker automatically publishes the corresponding topic, and the server updates the device to a disconnected (offline) state and records it on the timeline.

### Device Connection Check <a href="#connect-scenario" id="connect-scenario"></a>

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,&#x20;

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

<figure><img src="/files/XqXSj7y9zvVtE0ZtNcHo" alt=""><figcaption></figcaption></figure>

When the device receives the above topic, it should respond as follows. (Assume the sessionID is 00eeffaa)

* Topic: `res/00eeffaa/ABCDEF_123:AB:123`&#x20;
* Payload: none


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.en.nubison.io/mqtt-s.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.