通信模组 AT 接入
通信模组 AT 接入
单片机或嵌入式设备在使用通信模组接入云平台时,可利用 TCP 或 MQTT 的相关 AT 命令,快速接入 ThingsCloud 云平台。
准备工作
在模组接入云平台之前,我们需要一些准备工作。
创建项目和设备
首先,在云平台创建项目,点此进入控制台。在创建项目时,选择适合您的公有区。
接着,进入项目中,创建一个设备,只需要为设备起一个名字即可。
获得设备连接参数
设备创建成功后,进入设备详情页,在【连接】页面中,找到用于 MQTT 连接的一些重要信息,包括:
- 设备的普通证书,包括
ProjectKey
和AccessToken
,在接下来的 AT 命令中会用到。 - MQTT 接入点域名和端口,例如:
mqtt://<domain>:<port>
合宙 4G 模块 AT 接入
合宙 4G CAT.1 系列模组的 AT 命令支持 MQTT,请参考以下步骤,只需几分钟就可以接入云平台并上报数据,还可以从云平台下发命令实现远程实时控制。
提示
如果您还不了解云平台的 MQTT 接入协议,可以点击 设备 MQTT 接入 详细了解。
支持模组
以下 AT 指令来自官方 AT 固件 AirM2M_720U_V301836_LTE_AT.pac,支持以下模组型号。
- Air724UG
- Air720UG/UH
- Air722UG
- Air820UG
检查网络
查询卡状态
AT+CPIN?
+CPIN: READY
OK
查询网络注册情况
AT+CGATT?
+CGATT: 1
OK
配置网络
AT+CSTT
OK
激活网络
AT+CIICR
OK
查询网络信号
AT+CSQ
+CSQ: 29,99
OK
以上 AT 命令均返回 OK
,表示网络正常。
设置 MQTT 相关参数
接下来是设置 MQTT 连接参数,这里只需要设置 MQTT 的 clientId
、username
、password
,可以在设备详情页的【连接】选项中复制这些标识,按以下格式发送 AT 命令。
AT+MCONFIG=thingscloud,<AccessToken>,<ProjectKey>
OK
建立 TCP 连接
在设备详情页的【连接】选项中,找到当前可用区的 MQTT 服务器域名和端口,例如:
mqtt://<domain>:<port>
然后发送以下 AT 命令:
AT+MIPSTART=<domain>,<port>
OK
CONNECT OK
需要特别注意的是,此时模组和云平台成功建立了 TCP 连接,但还没有完成 MQTT 身份验证,此时服务器会等待 5 秒,如果 5 秒内没有发送下边的 AT 指令,云平台将会自动断开 TCP 连接。模组会收到以下消息:
CLOSED
如果收到云平台关闭连接的消息,请再次发送上边的 AT 命令。
完成 MQTT 身份验证
发送以下 AT 命令,完成 MQTT 身份验证,成功完成 MQTT 连接。
AT+MCONNECT=0,300
OK
如果云平台已经主动关闭了连接,此时该 AT 指令会产生以下错误码。这种情况下,需要重新回到上一个 AT 命令。
AT+MCONNECT=0,300
+CME ERROR: 767
上报属性
至此,模组和云平台已建立 MQTT 连接,我们可以向云平台发布消息或订阅消息。
我们先来发送一个简单的属性上报,消息内容为符合属性上报协议的 JSON
结构,如下:
{
"temperature": 31.6
}
实际传输中,JSON
是ASCII
字符串形式,过滤调换行和缩进,如下:
{"temperature":31.6}
在合宙系列模组的 AT 命令中, "
双引号要替换成转义符\22
,所以处理后如下:
{\22temperature\22:31.6}
接下来,使用以下 AT 命令,发送这个属性结构到云平台。
AT+MPUB=attributes,0,0,{\22temperature\22:31.6}
OK
此时,在云平台的设备详情页,可以看到出现了名为 temperature
的属性和值。如下图:
![查看设备属性](https://img-1300291923.cos.accelerate.myqcloud.com/docs/site/images/at-1.png)
通过在属性 JSON
结构中放置更多属性,您可以将设备上更多数据上传到云平台。
如果 JSON
中有多个属性,在合宙系列模组的 AT 命令中,,
也需要转义为 \2C
,例如:
{"temperature":31.6, "humidity":65}
发送给模组的字符串处理后如下:
{\22temperature\22:31.6\2C\22humidity\22:65}
如果以上 AT 命令是通过单片机程序发送给模组,在程序中记得还要做一次转义,用 \\
来表示 \
,例如:
"{\\22temperature\\22:31.6\\2C\\22humidity\\22:65}"
自定义数据上报
通过自定义数据上报,我们可以创建自定义的发布主题和订阅主题。
这里假设我们已创建了名为 message
的自定义数据流,云平台自动生成了新的主题 data/message
,这里发送一个 ASCII
字符串到该主题,AT 命令如下:
AT+MPUB=data/message,0,0,hello_thingscloud
OK
发送消息前,在设备详情页的【消息】选项中,打开【调试状态】,便可以看到消息日志。
自定义消息不会自动生成设备属性,您可以利用【规则引擎】对自定义数据进行分析处理,从而生成需要的设备属性。
订阅属性下发
如果希望设备能够实时接收云平台下发的属性数据,模组发送以下 AT 命令:
AT+MSUB=attributes/push,0
OK
SUBACK
订阅命令下发
如果希望设备能够实时接收云平台下发的命令消息,模组发送以下 AT 命令:
AT+MSUB=command/send/+,0
OK
SUBACK
订阅自定义消息
同样以上边的自定义数据流 message
为例,云平台会同时生成一个用于下发数据的主题,模组可以订阅该主题。
AT+MSUB=data/message/set,0
OK
接收订阅数据下发
通过上边的主题订阅,一旦云平台有相应的消息下发,模组便会将消息透传到使用 AT 的串口。
AT+MQTTMSGGET
例如,我们在云平台手动下发一条命令,如下图:
![下发命令](https://img-1300291923.cos.accelerate.myqcloud.com/docs/site/images/at-2.png)
当云平台下发了命令消息后,模组立即收到以下消息:
+MSUB: "command/send/1000",53 byte,{"method":"restart","params":{"timeout":10},"id":1000}
收到的命令消息结构如下:
{
"method": "restart",
"params": {
"timeout": 10
},
"id": 1000
}
查询 MQTT 连接状态
通过以下 AT 命令,可以查询 MQTT 当前连接状态。
AT+MQTTSTATU
+MQTTSTATU :1
以上表示处于连接中。
AT+MQTTSTATU
+MQTTSTATU :0
以上表示连接已关闭或未连接。
移远 4G 模组 AT 接入
移远 4G 系列模组的 AT 命令支持 MQTT,请参考以下步骤,只需几分钟就可以接入云平台并上报数据,还可以从云平台下发命令实现远程实时控制。
提示
如果您还不了解云平台的 MQTT 接入协议,可以点击 设备 MQTT 接入 详细了解。
支持模组
使用官方 AT 固件,支持以下模组型号。
- EC200x:EC200T 系列、EC200S 系列、EC200N-CN
- EC600x:EC600S-CN、EC600N-CN
- EG912Y:EG912Y 系列
检查网络
查询卡状态
AT+CPIN?
+CPIN: READY
OK
查询网络注册情况
AT+CREG?
+CREG: 0,1
OK
以上 AT 命令均返回 OK
,表示网络正常。
参数配置
配置 MQTT 接收模式
AT+QMTCFG="recv/mode",0,0,1
建立 TCP 连接
在设备详情页的【连接】选项中,找到当前可用区的 MQTT 服务器域名和端口,例如:
mqtt://<domain>:<port>
然后发送以下 AT 命令:
AT+QMTOPEN=0,<domain>,<port>
OK
+QMTOPEN: 0,0
以上 AT 命令的第一个参数 0
,表示 MQTT 客户端标识符,取值范围是 0~5。
需要特别注意的是,此时模组和云平台成功建立了 TCP 连接,但还没有完成 MQTT 身份验证,此时服务器会等待 5 秒,如果 5 秒内没有发送下边的 AT 指令,云平台将会自动断开 TCP 连接。
如果收到云平台关闭连接的消息,请再次发送上边的 AT 命令。
完成 MQTT 身份验证
在设备详情页的【连接】选项中找到设备证书标识 <AccessToken>
和 <ProjectKey>
。
发送以下 AT 命令,完成 MQTT 身份验证,成功完成 MQTT 连接。
AT+QMTCONN=0,"thingscloud","<AccessToken>","<ProjectKey>"
OK
+QMTCONN: 0,0
上报属性
至此,模组和云平台已建立 MQTT 连接,我们可以向云平台发布消息或订阅消息。
我们先来发送一个简单的属性上报,消息内容为符合属性上报协议的 JSON
结构,如下:
{
"temperature": 31.6
}
实际传输中,JSON
是ASCII
字符串形式,过滤调换行和缩进,如下:
{"temperature":31.6}
接下来,使用以下 AT 命令,发送这个属性结构到云平台。
发送前,需要先计算消息字符串的长度,这里是 20 个字节。
AT+QMTPUBEX=0,0,0,0,attributes,20
>
该 AT 命令告诉模块将要发送一条 20 字节的消息,收到返回的 >
后,继续向模组串口发送字符串即可。若实际发送的长度超过了 20 个字节,多出来的字节会被删除。
发送成功后,模组会返回以下消息:
OK
+QMTPUBEX: 0,0,0
此时,在云平台的设备详情页,可以看到出现了名为 temperature
的属性和值。
通过在属性 JSON
结构中放置更多属性,您可以将设备上更多数据上传到云平台。
订阅属性下发
如果希望设备能够实时接收云平台下发的属性数据,模组发送以下 AT 命令:
AT+QMTSUB=0,0
,attributes/push,0
OK
+QMTSUB: 0,0,0
订阅命令下发
如果希望设备能够实时接收云平台下发的命令消息,模组发送以下 AT 命令:
AT+QMTSUB=0,0
,command/send/+,0
OK
+QMTSUB: 0,0,0
接收订阅数据下发
通过上边的主题订阅,一旦云平台有相应的消息下发,模组便会将消息透传到使用 AT 的串口。
AT+QMTRECV=0
例如,当云平台下发了命令消息后,模组立即收到以下消息:
+QMTRECV: 0,0,command/send/1000,{"method":"restart","params":{"timeout":10},"id":1000}
OK
收到的命令消息结构如下:
{
"method": "restart",
"params": {
"timeout": 10
},
"id": 1000
}
关闭 MQTT 连接
AT+QMTDISC=0
OK
+QMTDISC: 0,0
关闭 TCP 连接
AT+QMTCLOSE=0
OK
+QMTCLOSE: 0,0