Protocol Overview

Brief Introduction

MQTT protocol is an instant messaging protocol for the IoT applications. It uses TCP/IP to provide network connections, and implements message block transmission for load contents. It has small overhead and can effectively reduce network traffic. 

Features and Functions

Persistent connection protocol

Terminal data points reporting, supported types of data points including:




JSON format

Message issuance from the platform

Can realize message unicast and multicast between devices based upon subscriptions and release of Topic, and message push

Access Process

Test access process is divided into platform domain and device domain, which helps you with your first access experience so that you can have a general understanding of the functionalities of the platform and access protocols.

Test Flow Chart


Refer to Access Procedures as below:

Step1 Create Product

First you need to create a product with access protocol as MQTT on the platform. Refer to Products Creation Procedures

If you don't have an OneNET account, click here to register

If you have already registered, click here to log in

After the product is created, record its Product ID

Step2 Create Device

Click "Add Device", and enter the Device Name and Authentication Information (Device Serial Number). Refer to Cloud Management for details.

Record its Device Serial Number and Device ID assigned by the platform

Step3 Establish TCP Connection

The domain name of MQTT server address is:  Port number: 6002

Step4 Establish Device Connection

Use the parameters in Step1 and Step2 as the login parameters, use the corresponding interface in SDK to organize the message of MQTT connection, then send the message to the platform and establish MQTT connection with the platform.

If the connection is successful, there will be an online tag in the device information.

Step5 Data Points Upload

Use the interface function provided in SDK to write codes and upload the data to the platform

Step6 View Data Stream

Click the Data Display in Device Management on OneNET. After the Data Display page is displayed, click the drop-down menu and view the data points uploaded recently; time interval can also be selected to view the historical time.

Step7 Application Generation

Carry out the creation of applications and triggers on the basis of data flow. Refer to Cloud Management for details. 

In the above test flow chart, users need to manually add devices on the platform, and then conduct the access process of device domain. When the access of a large number of devices is required, there will be a lot of unnecessary operations.

Therefore, when device batch access is needed, the Batch Access solution is suggested.

The Flow Chart of Device Batch Access


Refer to Access Procedures as below:

Step1 Create Product

First you need to create a product with an access protocol as MQTT on the platform. Refer to Products Creation Procedures

If you don't have an OneNET account, click here to register

If you have already registered, click here to log in

After the product is created, record its product ID and register code of the formal environment 

Step2 Create Device

OneNET offers an API for device creation, which is used by the terminal itself to create the corresponding device on the platform.

View Detailed Instructions of the API

URL parametersregister_code=6TM1OkhNsTjATvFx  //device register code (required)
HTTP contents


    "sn": "2015031401421",     //device unique identification string type, up to 512 characters

    "mac": "C89346DA4373",  //device unique mac identification, up to 32 characters

    "title": "mymqttdevice"  //device name (optional) up to 32 characters


Note: either sn or mac must be filled, and only one can be uploaded

Return Example


    "errno": 0,




        "key":"Q1VdWoEvdkCye=d1=HcCSP6LvCw=",  //device apikey

        "device_id": 3264518,   //device ID



After getting the device ID and key, you can perform operations as TCP connection, MQTT connection, and data upload according to the steps in the test process.

Protocol Details


OneNET provides documentations of device access using MQTT protocol, which users can download for learning. 

File Name


File Download

MQTT StandardsV3.1.1

Click to download

MQTT OneNET Implementation


Click to download




File Download



Click to download

Other standard libraries

Click to download

Debugging Tools

Change Details


  1. Supports Qos2 features

  2. Supports Retain features (data points upload does not support Retain)

  3. Supports "Auto KeepAlive" option

  4. The access method of the subscribed Topic list changes to pulling from the server

  5. Removed the "Description" control on the Subscribe Tab page

  6. Lists in "Received Topic" and "[OneNET] platform command receiving" support multiple delete

  7. All lists support ToolTip display

  8. After the icons of the task bar and title bar of the software are replaced, version tips are displayed on the title bar 


  1. The data upload interface is adjusted and supports multiple data types upload

  2. The display of debugging information window is optimized. The latest message is displayed by default

  3. The optimization of the Tab input box is released, supporting “Ctrl + A” to select all and enter


  1. Supports will message

      Note: because the feature of will message is supported, virtual devices of V1.0.1      (included) and previous versions cannot get connected to the platform. Please download the latest debugging software.


  1. Added disconnect function

  2. Added cleansession option, and keepalive parameter

  3. Optimized and integrated the login page and function page

  4. Removed the Create Topic button; when a new Topic is subscribed, the server will automatically create Topic

  5. Added debugging information window


Operating environment


Tools Download




Click to download


Q1: What should be entered for ClientIdentifier;UserName;UserPassword in Payload during MQTT connection authentication?

A:    ClientIdentifier: Device ID got when the device is created, numeric string

        UserName: Product ID assigned by the platform when the product is registered, numeric string

        UserPassword: Device authentication information (unique device serial number, SN), or apiKey, string

Q2: Does MQTT need to send other messages after the connection authentication is passed?

A: Yes, MQTT must send subsequent messages for interaction after the authentication is passed (ConnAck received), otherwise the server will discard the message directly.

Q3: Are there any restrictions on the Topic subscribed by MQTT? 

A: OneNET does not support subscription of system Topic beginning with “$” 

Q4: How to use MQTT protocol to upload data to the cloud platform?

A: After the device completes the connection authentication, the data is packaged according to a certain format (refer to protocol documentation), and sent to $dp system Topic.

Q5: Does Topic need to be created before subscription?

A: When the device performs a subscription, OneNET automatically determines whether the Topic exists, and automatically creates the Topic if it does not exist.

Q6: Can the device access the data flow information of other devices via subscription?

A: Yes, the latest data point information of a device can be accessed timely through subscription of “/device_id/data stream name”.

Q7: What are the limitations for the device to publish messages? 

A: Messages publishing can only be done under the same product ID and publish messages cannot be pushed across products