LuatOS-Air AT应用指南--MQTT指令流程

概述
Air724模块内置MQTT协议，提供AT，LuatOS-Air，CSDK，DTU可供选择使用，接口简单使用方便。

MQTT简介
优势：长连接，低带宽，高可靠。
实用场景：需要服务器下发消息给设备，需要及时收到。例如，远程开关，充电桩等
几个重要名词
username用户名，password密码，clientid用户标识，mqtt可以通过前两个参数保证连接的安全，通过clientid确保设备唯一性。
qos消息质量，分为0，1，2三个等级，分别表示只发一次，至少收到一次和只收到一次，通过qos可以根据数据的重要性灵活选择发送方式以节省带宽和保证数据可靠。例如不重要的数据采集可使用qos0只发一次不关心服务器是否收到，重要的消息通过qos1确保能收到，付款信息危险设备开关等场景使用qos2保证数据到达的同时且不重复。
host主机，port端口，mqtt需要连接的服务器参数。host可以说ip或者域名。
topic主题，根据主题区别消息类型和来源，主要用来分类数据。同时mqtt是发布订阅模型，topic是发布和订阅者通信的重要通道。
payload消息内容，发布和订阅的具体数据。
retain保留消息，保留消息是一条将保留标志（retained flag）置为true的普通MQTT消息。broker会针对主题依照QoS级别保留最后一条保留消息，当订阅者订阅主题时会立即收到保留消息。broker仅为每个主题保留一条保留消息。
AT方式
连接网络
开机
通过拉低powerkey2秒进行开机，开机以后通过串口循环发送AT直到收到OK，如果90秒没有收到OK请拉低 RESET_IN_N 引脚 150ms 以上。或使用其他方法见开关机章节

查询卡状态
AT+CPIN?查询卡状态，直到收到+CPIN: READY，如果10s内没有收到建议重启模块

查询网络注册情况
AT+CGATT?查询是否注册网络收到+CGATT: 1值是1即为注册成功，正常情况下注册时间不会超过两分钟，如果超过两分钟没有注册可以进入飞行模式五秒后退出再查询，或者直接重启模块。

激活网络
AT+CSTT配置网络，非私有APN以外Cat1的固件支持根据卡自动配置APN，直接输入AT+CSTT即可，模块会按照自动获取的APN设置CSTT的APN。

AT+CIICR激活网络，在IP START的状态使用AT+CIICR激活网络，激活以后通过AT+CIFSR查询是否获取IP，如果成功就可以开始配置TCP连接了，如果不成功使用AT+CIPSHUT关闭移动网络，从AT+CSTT重新进行。

连接服务器
设置 MQTT 相关参数：AT+MCONFIG

命令类型 语法 返回 说明
设置命令 AT+MCONFIG=[,, [,<will_qos>,<will_retain>, <will_topic>,<will_message>]] OK
ERROR 正常返回
输入格式有误
测试命令 AT+MCONFIG=? +MCONFIG: [,,[,(0-2),(0,1 ),<will_topic>,<will_message>]]
OK
参数定义

参数 定义 取值 对取值的说明
client identity 字符串 最大 256 个字节。可以用"“括住，也可以不用”"
username to login server 字符串 最大 256 个字节。可以用"“括住，也可以不用”"
password to login server 字符串 最大 256 个字节。可以用"“括住，也可以不用”"
<will_qos> Quality of Service for will message 0
1
2 见前文说明
<will_retain> retain flag 0
1 the server will restore the will meassge and its QoS
the server must not restore the will meassge and must not remove or replace any existing retained message
<will_topic> the topic of the will meassage 字符串 最大 256 个字节。可以用"“括住，也可以不用”"
<will_message> the will message content 字符串 最大 1360 个字节。可以用"“括住，也可以不用”"
**PS：**说明一下will_retain这个参数

终端设备publish消息时，如果retain值是true，则服务器会一直记忆，哪怕是服务器重启。因为会本地持久化。

如果服务器接收到终端publish某主题的消息，payload为空且retain值是true，则会删除这条持久化的消息。

如果服务器接收到终端publish某主题的消息，payload为空且retain值是false，则不会删除这条持久化的消息。

will_topic和will_message是遗嘱相关。

建立 TCP 连接：AT+MIPSTART

语法规则：

普通链接： AT+MIPSTART=,

ssl连接：AT+SSLMIPSTART=,

返回OK表示成功，返回ERROR表示格式错误。

发送完这条指令后会有一些列URC上报。

1)单链接（AT+CIPMUX=0）

如果链接成功地建立，则上报： CONNECT OK

如果链接已经存在，则上报： ALREADY CONNECT

如果链接失败，则上报： STATE: CONNECT FAIL

多链接（AT+CIPMUX=1） 如果链接成功地建立，则上报： 7,CONNECT OK
如果链接已经存在，则上报： ALREADY CONNECT

如果链接失败，则上报： 7,CONNECT FAIL

客户端向服务器请求会话连接：AT+MCONNECT

命令类型 语法 返回 说明
设置命令 AT+MCONNECT=<clean_session>, OK 设置成功
测试命令 AT+MCONNECT=? +MCONNECT:(0-1),(1-65535)OK 测试命令的返回的是 <clean_session>和 的取值范围
URC 设置命令设置成功，返回OK后，后续会根据连接情况自动上报URC。 如果连接成功则返回：CONNACK OK 如果连接失败则返回：ERROR
clean_session是清除会话标志取值为0或1

keepalive是心跳时间取值1-65535单位秒

发布消息
发布消息：AT+MPUB

命令类型 语法 返回 说明
设置命令 AT+MPUB=,, , OK qos=0
OK
PUBACK qos=1
OK
PUBREC
PUBCOMP qos=2
ERROR 失败
参数定义：

参数 定义 取值 取值说明
消息质量 0 只发一次
1 最少到达一次
2 只有一次
消息保留标志 0 不保留
1 保留
主题 字符串 最大 256 个字节。可以用"“括住，也可以不用”"
消息内容 字符串 最大 1360个字节。可以用"“括住，也可以不用”" 注:消息中内嵌的双引号请用\22 表达；控制字符 \r(0x0D)请用\0D 表达；控制字符\n（0x0A） 请用\0A 表达 如果是 MCU 发消息，请用\22，\0D，\0A 来 表达，即\需要转义成\
订阅消息
订阅主题：AT+MSUB

命令类型 语法 返回 说明
设置命令 AT+MSUB=, OK
SUBACK 成功
ERROR 失败
当输入设置命令成功以后，后续会有相应的URC上报。 当AT+MQTTMSGSET=0： +MSUB：,,
当AT+MQTTMSGSET=1： +MSUB：<store_addr>
参数定义：

参数 定义 取值 取值说明
主题 字符串 最大 256 个字节。可以用"“括住，也可以不用”"
消息质量 0 1 2 同前文
数据长度 0到1360 单位：字节
消息内容 字符串 最大1360字节
<store_addr> 消息编号 0到3 当订阅方式设置为缓存模式的时候收到消息会上报一条URC+MSUB：<store_addr>
设置订阅消息的打印模式：AT+MQTTMSGSET

命令AT+MQTTMSGSET=成功返回OK失败返回ERROR,mode的取值是0或1，0为主动上报到串口。有新订阅消息时，上报的 URC 为： +MSUB：,,；1为缓存模式。有新订阅消息时，上报的 URC 为： +MSUB：<store_addr> 然后用 AT+MQTTMSGGET 来读消息。

打印收到的所有的订阅消息：AT+MQTTMSGGET

命令类型 语法 返回 说明
执行命令 AT+MQTTMSGGET [+MSUB: ,,] [+MSUB: ,,] [+MSUB: ,,] [+MSUB: ,,]
OK 执行命令将会打印收到的保 存在cache中的主题订阅消 息。执行完以后， 将会变成invalid。
查询命令 AT+MQTTMSGGET? +MQTTMSGGET：0, +MQTTMSGGET：1, +MQTTMSGGET：2, +MQTTMSGGET：3,
OK
测试命令 AT+MQTTMSGGET=? OK
注意：当 AT+MQTTMSGSET=1，执行命令可以打印订阅消息。一次最多打印4条。如果一次上报多于4条，则打 印最新的4条，最老的那条将被覆盖。

参数定义

参数 定义 取值 取值说明
主题 字符串 最大256字节
消息长度 0到1360 字节
消息内容 字符串 最大1360字节
消息状态 VALID 有数据, AT+MQTTMSGGET 执行模块 可以打印这些消息
INVALID 没有数据
MQTT 消息编码格式切换：AT+MQTTMODE

命令AT+MQTTMODE=，成功返回OK失败返回ERROR,mode的取值是0或1，0为ASCII格式，1为HEX格式。

查询 MQTT 连接状态：AT+MQTTSTATU

命令AT+MQTTSTATU，成功返回+MQTTSTATU :OK，失败返回ERROR。

取值说明

值 状态
0 离线
1 已经认证可以发送数据
2 未认证，需要发送 MCONNECT 命令
常见问题
1、MPUB命令中，payload包含"如何发送？
消息中内嵌的双引号请用\22 表达；控制字符 \r(0x0D)请用\0D 表达；控制字符\n（0x0A） 请用\0A 表达 如果是 MCU 发消息，请用\22，\0D，\0A 来 表达，即\需要转义成\

连接服务器失败
检查下模块信号、网络注册、网络附着、PDP激活状态
检查下SIM卡是否欠费【4G模块有一种欠费表现：无法注册4G网络，可以注册2G网络】
使用mqtt.fx，连接服务器确认一下是否可以连接成功，排除服务器故障
部分国外的开源项目提供免费的MQTT代理服务器，因为网络的原因，国内存在严重的延迟或者丢包现象，导致程序运行出现问题，此现象在AT开发时影响严重
确认是不是域名解析失败导致，可以通过AT+CDNSGIP=确认一下域名是否能正常解析（注意：该命令只有在执行完at+cstt、at+ciicr、at+cifsr后才能正常工作），不能正常解析，可以通过AT+CDNSCFG=ip1,ip2设置域名解析服务器。
在 MIPSTART /SSLMIPSTART返 回 CONNECT OK后 才 能 发 MCONNECT命令，而且要立即发，否则会被服务器踢掉
通过抓取日志进行分析，AP日志的抓取与分析