> For the complete documentation index, see [llms.txt](https://doc.yuncitys.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.yuncitys.com/xie-yi-jie-kou/mqtt-1.md).

# MQTT协议

### 入门 <a href="#ru-men" id="ru-men"></a>

**MQTT基础**

[MQTT](https://en.wikipedia.org/wiki/MQTT)是一种轻量级的发布-订阅消息传递协议，它可能最适合各种物联网设备。

你可以在[此处](http://mqtt.org/)找到有关MQTT的更多信息，ThingsBoard服务器支持QoS级别0（最多一次）和QoS级别1（至少一次）以及一组预定义主题的MQTT代理。

**客户端**

你可以在网上找到大量的MQTT客户端库，本文中的示例将基于Mosquitto和MQTT.js您可以使用我们的[Hello World](http://www.ithingsboard.com/docs/getting-started-guides/helloworld/)指南中的说明。

**MQTT连接**

我们将在本文中[使用令牌凭据](/she-bei-jie-ru/chuang-jian-she-bei.md#huo-qu-fang-wen-ling-pai)对进行设备访问，这些凭证稍后将称&#x4E3A;**$ACCESS\_TOKEN**应用程序需要发送用户名包&#x542B;**$ACCESS\_TOKEN**的MQTT CONNECT消息。

连接状态码说明：

* **0x00 连接成功** - 成功连接
* **0x04 连接失败** - 用户名或密码错误。
* **0x05 连接未授权** - -用户名包含无效的 **$ACCESS\_TOKEN**。

### Key-value格式 <a href="#keyvalue-ge-shi" id="keyvalue-ge-shi"></a>

支持以JSON格式的key-value字符串，值可以是string、bool、float、long或者二进制格式的序列化字符串；

### MQTT连接配置

```
47.106.143.1:1883
```

**userName**: GP1109N12345678（[在平台获取访问令牌](/she-bei-jie-ru/chuang-jian-she-bei.md#huo-qu-fang-wen-ling-pai)）\
**password**: (无)

### &#x20;**TOPIC主题发布接口列表**

|   | **topic**             | **Qos-级别** | **认证方式**    | **注释** |
| - | --------------------- | ---------- | ----------- | ------ |
| 1 | v1/gateway/connect    | 1          | accessToken | 连接到网关  |
| 2 | v1/gateway/disconnect | 1          | accessToken | 断开网关   |
| 3 | v1/gateway/attributes | 1          | accessToken | 设备属性   |
| 4 | v1/gateway/telemetry  | 1          | accessToken | 数据遥测   |

payload格式例如:

```
{
	"DEVICE": [{
		"ts": "1609144280398",
		"values": {
        "stringKey":"value1", 
        "booleanKey":true, 
        "doubleKey":42.0, 
        "longKey":73, 
        "jsonKey": {
           "someNumber": 42,
           "someArray": [1,2,3],
           "someNestedObject": {"key": "value"}
        }
       }
	}]
}

```

### v1/gateway/telemetry

网关心跳包实例：

```
{
	"WG12345678": [{
		"ts": "1609145640724",
		"values": {
			"H": "60",
			"mode": "2",
			"NET4GSTA": "1,0",
			"mT": "3,0,1",
			"mFifo": "618,618,1389,1389",
			"DDA": "1",
			"boxSta": "0",
			"TH": "30.40,42.4",
			"NR": "1247,1254",
			"Lat": "22.540456",
			"Lon": "113.928825",
			"SDR": 1,
			"power": {
				"0": 0,
				"1": "6.80",
				"2": "29",
				"9": "11.48",
				"10": "3800",
				"11": "3300",
				"12": "0",
				"13": "3300",
				"14": "40"
			}
		}
	}]
}
```

终端数据包实例：

```
{
	"WG12345678/sf_2_0_340000": [{
		"ts": "1609144280398",
		"values": {
			"T": "1609144280355",
			"SN": "00006500",
			"da": "010CE735CA7C271E21FFFFFF"
		}
	}]
}
```

###

在上面的示例中我们"ts":"1609144280398"，是具有毫秒精度的[Unix时间戳](https://en.wikipedia.org/wiki/Unix_time)。例如：值’1609140420031’转换后是’2020-12-28 16:31:20’。