如果你手头正好有一块合宙Air780EP想在最短时间内把设备数据送到OneNET平台上那么ATMQTT这条路应该是最直接的。不用写多层嵌入式代码不用折腾完整SDK只需要一条串口线、一台PC或者MCU串口用AT指令就能完成从模组开机、注册网络、配置MQTT参数到发布第一条数据的全部流程。这篇内容就是围绕这个目标来的我会把整个接入过程拆开讲清楚包括OneNET平台侧怎么创建产品、模组侧怎么配MQTT参数、发布订阅的Topic怎么写、以及我实际调试过程中踩过的坑。适合的人群很明确正在做设备联网打样的硬件工程师、想把现有MCU产品快速上云的开发者、以及做项目Demo演示的朋友。1. 为什么选ATMQTT而不是LuatOS二次开发很多人拿到Air780EP的第一反应是纠结用哪种方式开发。有人推荐LuatOS说可以用Lua脚本直接在模组里跑业务逻辑也有人推荐AT指令说配置简单、上手快。我两种方式都试过最后在速连OneNET这个目标下选了ATMQTT不是因为LuatOS不好而是因为AT指令在特定场景下真的足够省事。1.1 AT指令适合什么样的场景AT指令本质上就是模组已经帮你把网络协议栈跑好了你只需要通过串口发命令让它干活。MQTT这种应用层协议在Air780EP的AT固件里已经被封装成几条指令你不需要关心TCP连接怎么建立、MQTT报文怎么组包、心跳怎么发只需要关心业务参数。适合AT指令的情况大概有这几种现有产品里已经有主控MCU代码逻辑都是C写好的不想为了联网把整个架构迁到Lua脚本上。项目处于打样验证阶段需要快速验证硬件和平台之间能不能跑通AT指令一条条敲下去问题定位最快。维护和产线测试阶段直接拿串口助手或者PC发指令就能测模组好坏不依赖额外编译环境。团队里没有人熟悉LuatOS但大家都懂AT指令协作成本最低。如果你做的产品功能复杂、业务逻辑重而且主控性能很弱甚至没有主控那确实应该考虑LuatOS方案。但在OneNET上云远程监控简单下发这种需求下ATMQTT就是性价比最高的路。1.2 Air780EP在ATMQTT场景下的优势Air780EP作为合宙主推的Cat.1模组在这个场景里优势很直观网络制式是LTE Cat.1比传统2G快比NB-IoT延迟低国内的运营商网络覆盖已经很好不存在2G退网后的麻烦。模组自带TCP/IP协议栈MQTT协议栈也做进了AT固件里MCU这边只需要一个串口外设不需要额外的网络协议处理能力。支持低功耗模式虽然不是这篇的重点但至少说明这个模组后续做电池供电产品有空间不是一步到位的死胡同。封装和Air780E系列兼容PCB设计改起来方便后面真想从AT切到LuatOS硬件不用重画。1.3 我采用的整体链路我的方案很简单链路长这样MCU/PC串口 - Air780EP模组 - 4G基站 - OneNET MQTT服务器 - 应用端MCU侧只做一件事通过串口按帧发AT指令解析模组返回的结果。OneNET侧只需要创建一个MQTT产品加一台设备把产品ID、设备名、设备密钥这三个参数抄下来。真正麻烦的TCP长连接、MQTT会话管理、心跳保活Air780EP固件全包了。这个方案有一个很重要的好处故障隔离。哪天OneNET连不上了我可以直接用串口助手敲指令看返回判断是网络问题、参数问题还是平台问题不用在代码里到处打日志。2. 开工前准备硬件接线、SIM卡和OneNET产品配置先别急着接电源也别急着敲AT指令。接入OneNET之前有三件事没准备好后面大概率会反复折腾硬件接线是否正确、SIM卡是否能正常激活、OneNET平台侧产品是否已经创建。这三件事每一项都有一些容易忽略的细节。2.1 硬件接线与串口调试准备Air780EP模组是LCC封装的一般通过模组评估板来调试。如果你用的是合宙官方的开发板USB口一插就能看到串口设备如果你是自己画的板子那要注意几个点供电电压范围是3.6V到4.2V推荐用稳压电源稳定在4V左右。电流峰值可能在2A上下普通LDO带不动建议用支持大电流的DCDC。UART调试时模组的TXD接USB转串口工具的RXD模组的RXD接工具的TXD别把收发搞反了还要共地。电平匹配问题。Air780EP的UART口电平一般是1.8V或3.3V看具体模块。如果USB转串口工具是5V电平最好加电平转换芯片否则长时间调试有烧引脚的风险。官方评估板一般自带电平转换可以直接插。SIM卡用中国移动的物联网卡或普通SIM卡都行但需要确认能访问公网。OneNET虽然是中国移动的平台不代表只能用移动卡联通电信卡也能连只是APN配置不同。串口助手参数我习惯用115200、8位数据、无校验、1位停止位勾选发送新行。Air780EP的AT默认波特率通常是115200不同批次固件可能有差异如果敲AT没反应试试9600、230400这些常见波特率。2.2 在OneNET平台创建产品和设备打开OneNET开放平台新版叫OneNET Studio注册并登录账号后进入控制台按下面的流程操作选择产品开发点击创建产品。产品名称自己定比如Air780EP_TempMonitor产品分类按实际用途选联网方式选蜂窝网络协议类型选MQTT。创建完成后在产品详情页能看到产品ID和产品Secret这两个后面会用到。在设备管理里添加设备设备名称建议用有意义的名字比如dev01也可以填模组的IMEI后8位方便批量管理。添加完设备后能看到设备所属的产品ID、设备名称以及设备级密钥。OneNET新版的MQTT接入就是用这三个信息做鉴权的。这里我遇到过一个容易混淆的点旧版OneNET多协议接入的MQTT地址和鉴权方式跟新版不同网上很多教程用的还是旧版参数照抄会失败。建议直接使用新版OneNET Studio地址统一用mqtt.heclouds.com端口1883。2.3 MQTT接入参数和AT命令的对应关系OneNET Studio的MQTT接入需要三个关键参数平台参数在MQTT协议里的位置举例产品IDClientID374860设备名称Usernamedev01设备密钥Password63f2a8c1...这三个参数不会直接出现在你的业务代码里而是通过AT命令写入模组。后面的MQTT配置命令里会把它们分别填到对应的字段中。mqtt.heclouds.com这个域名是固定的端口1883是明文MQTT端口如果产品对安全性要求高可以选8883做TLS加密但Air780EP用TLS需要额外配置证书首次调试先别折腾。2.4 确认模组固件里的MQTT能力拿到模组后先不要默认它支持MQTT AT指令。有些出厂固件的版本比较老或者MQTT功能需要单独刷特定版本。先确认一下没什么坏处ATE0 OK ATCGMR V1020ATCGMR查询版本号后去合宙官网文档中心查一下对应版本的AT指令手册确认里面包含ATMQTTCFG、ATMQTTOPEN、ATMQTTSUB、ATMQTTPUB这几条指令。如果固件版本老到没有MQTT指令刷新版AT固件再继续。3. ATMQTT接入全流程一步一步把设备拉上线平台侧准备好了硬件也通了下面就是整个文章的核心通过AT指令把Air780EP串起来完成MQTT连接。我尽量按串口调试的顺序来写每一步都解释清楚参数含义不然你只能抄命令不知道为什么要这么配。3.1 开机、关回声、确认模块响应模组上电后首先在串口助手里发一个AT能收到OK说明串口通信正常。AT OK ATE0 OKATE0是关闭回声就是让模组不再把收到的指令原样回显出来。这样串口日志看起来干净排查问题时不容易被干扰。之后所有的AT指令我都会省略默认存在的OK返回重点看状态相关返回值。3.2 查信号和网络注册状态模块能响应不代表已经上网先看信号质量ATCSQ CSQ: 22,99CSQ返回的两个数字第一个是信号强度范围0到31越大越好一般大于15就能稳定工作第二个是误码率99表示无法测量或不可用只要不是持续丢数据不用太在意。再看网络注册状态ATCEREG? CEREG: 0,1第二个参数为1表示已注册上LTE网络为5表示已注册且处于漫游状态0或2、3就说明还没注册成功。如果卡在这一步先检查SIM卡是否插好、是否欠费、天线是否接上。3.3 配置APN和网络附着物联网卡通常有专用的APN。中国移动物联网卡接入OneNET建议使用cmnbiot部分地区用cmiot。普通SIM卡用cmnet也可以但稳定性不如物联网卡专用APN。ATCGDCONT1,IP,cmnbiot OK ATCGACT1,1 OKATCGDCONT设置PDP上下文第一个参数是上下文ID第二个是IP类型第三个就是APN。ATCGACT激活PDP上下文激活成功后模组才真正拿到了IP地址。这里有一个细节如果之后切换了SIM卡运营商APN要重新设置否则IP层都起不来。用ATCGACT?可以查询当前激活状态返回CGACT: 1,1表示第一个PDP上下文激活成功。激活失败的话大概率是APN不对。3.4 配置MQTT参数服务器、ClientID、用户名、密码网络层OK了开始配MQTT参数。这里以Air780EP AT固件的MQTT配置指令为例ATMQTTCFGmqtt.heclouds.com,1883,374860,dev01,63f2a8c1...,120,0,1 OK各参数对应含义如下参数含义本次的值mqtt.heclouds.comMQTT服务器域名OneNET固定地址1883MQTT端口明文端口374860客户端IDOneNET产品IDdev01用户名OneNET设备名称63f2a8c1...密码OneNET设备密钥120保活时间秒建议90~1200默认QoS0或11cleanSession开关1开启保险时间的含义是如果模组在120秒内没有和服务器之间有任何报文交互就主动发一个PINGREQ心跳包保持长连接不被服务端踢掉。OneNET平台有自己的超时策略保活时间设置太长可能被服务端断开120秒是比较稳的选择。注意不同模组厂家的AT指令设计风格不一样有的用ATMCONFIG有的用ATMQTTCFG参数顺序也可能不同。合宙Air780EP的具体命令名以官方AT指令手册为准但本质上都是填这六个要素域名、端口、ClientID、用户名、密码、保活时间。3.5 打开MQTT连接并确认状态参数配好了下面真正发起连接ATMQTTOPEN OK这条指令让模组主动连到配置的MQTT服务器。如果连接成功有些固件会主动上报一条URC消息比如MQTTCONNECT: 0,0如果用的是需要单独发起MQTT连接的固件还会有一条ATMQTTCONN。这里要养成一个习惯执行完ATMQTTOPEN后等几秒再查状态。ATMQTTSTATE? MQTTSTATE: 2不同固件返回的状态码含义不同一般是0未连接、1连接中、2已连接。看到状态为已连接说明Air780EP已经通过MQTT协议注册到OneNET了。此时去OneNET平台设备列表页面刷新设备状态通常会显示在线。3.6 订阅平台下发Topic设备在线之后先订阅一个Topic。OneNET的设备命令下发和属性设置都通过固定的Topic格式推送订阅之后你才能收到平台侧发来的数据。我演示的是物模型模式下的属性设置TopicATMQTTSUB$sys/374860/dev01/thing/property/set,0 OK第一个参数是Topic路径第二个是QoS级别。这里的路径规则是$sys/{产品ID}/{设备名}/thing/property/set用来接收平台下发的属性设置指令。订阅成功一般会有OK回复固件收到平台消息时也会主动上报URC消息。3.7 发布第一条数据到OneNET最激动人心的一步发布一条数据。OneNET物模型的属性上报Topic是$sys/{产品ID}/{设备名}/thing/property/postpayload是JSON格式。ATMQTTPUB$sys/374860/dev01/thing/property/post,0,0,{\id\:\1\,\version\:\1.0\,\params\:{\Temp\:25.6}} OK这个指令里三个逗号后面的字段分别是Topic、发送QoS、保留标志最后是payload字符串。需要注意JSON内部的引号在AT指令里要用反斜杠转义否则模组解析到一半就截断了。发完之后去OneNET平台的设备数据管理页面能看到属性Temp的最新值是25.6。如果能看到整个链路就通了Air780EP到OneNET的MQTT接入已经没有任何障碍。4. 数据上报与下发物模型、Topic和JSON报文能连上只是第一步真正做产品时你会发现数据上行下行怎么设计、报文怎么写直接决定了后期开发顺不顺畅。这一部分专门把OneNET物模型、Topic和JSON格式的关系讲明白减少你在协议细节上的摸索时间。4.1 OneNET的Topic规则与物模型设计OneNET Studio的设备接入逻辑是基于物模型的。所谓物模型通俗理解就是平台给设备定义了一份能力清单包括属性、事件和服务每个能力有自己的标识符。属性Property设备的某个状态量比如温度、湿度、开关状态可以上报也可以被平台设置。事件Event设备主动上报的异常或告警比如温度过高。服务Service平台可以调用的设备方法比如远程重启。在平台产品详情页定义好物模型后系统会自动生成一系列Topic设备端只需要往固定的Topic里填数据即可。以属性上报为例Topic格式如下$sys/{产品ID}/{设备名}/thing/property/post这个Topic是设备端发布平台端订阅。属性上报之后平台会根据JSON结构里的字段名自动匹配物模型如果字段没在物模型里定义平台可能直接丢弃或者报错。4.2 一条完整的属性上报报文拆解在AT指令里发属性上报本质上就是往MQTT Topic里塞一段JSON。这段JSON的格式要严格符合OneNET的要求{ id: 1, version: 1.0, params: { Temp: 25.6, Humidity: 60 } }id报文的唯一标识默认填个自增数字就行。version协议版本OneNET物模型统一用1.0。params属性集合key是物模型里定义的属性标识符value是实际值。在AT指令里这段JSON要压成一行并且要把双引号转义ATMQTTPUB$sys/374860/dev01/thing/property/post,1,0,{\id\:\1\,\version\:\1.0\,\params\:{\Temp\:25.6,\Humidity\:60}}如果一次要上报多个属性直接在params里加字段就行。这里我建议QoS至少用1否则在某些网络抖动场景下数据报文丢了模组根本不知道平台侧就会漏数据。4.3 接收平台下发指令并回执确认设备不仅要上报数据还要能响应平台的指令。OneNET属性设置的Topic是前面提到的$sys/{产品ID}/{设备名}/thing/property/set你订阅它之后平台下发数据时模组会主动上报一条URC消息类似下面这样MQTTURC: 0,$sys/374860/dev01/thing/property/set,0,{\id\:\22\,\version\:\1.0\,\params\:{\Switch\:1}}MCU收到这条消息后要解析出JSON中的params执行对应的动作比如把继电器打开。执行完成后最好回复一条指令执行完成的确认报文。OneNET提供了属性设置应答Topic$sys/{产品ID}/{设备名}/thing/property/set_reply应答报文同样遵循JSON格式需要带上原报文的id并有一个code字段表示执行结果0表示成功{ id: 22, code: 0, msg: ok }实际开发中很多人都忽略了这一步。平台下发指令后如果长时间收不到应答会判定设备响应超时业务层就可能误报。所以只要在业务逻辑里接收到了set指令一定要记得回执。4.4 上报时序与频率控制OneNET平台对单设备的单Topic上报频率有限制具体数值不同套餐可能不同但结论很明确不要无脑高频上报。有些人在测试时每秒发一条数据结果平台侧显示数据没问题但在量产场景下多设备并发很容易触发平台限流。我的建议是普通传感器属性5到60秒上报一次足够不需要更快的场景尽量别更短。事件告警可以即时上报比如温度越限立刻发一条事件。单次上报多个属性减少MQTT报文数量比单属性多次上报效率高得多。模组侧的MQTT连接只有一条如果上报请求过于密集AT指令队列会堆积串口响应变慢还可能出现指令丢失。MCU侧最好做一个简单的发送队列一条一条发不要同时堆多条ATMQTTPUB。5. 实测踩坑连接不稳定、发不出去、收不到下发的排查思路ATMQTT看起来简单但实际调试过程中容易出问题的点其实不少。这一部分我把常见的故障和解决思路整理出来每一条都是我在项目里真实踩过的坑。排查顺序很重要建议按先网络、再连接、后报文的顺序来。5.1 先确认网络层SIM卡和APN的问题MQTT连接不上的时候第一时间别怀疑MQTT参数先查网络层。我自己最常遇到的坑是SIM卡和APN不匹配。有一次设备老是连不上OneNET我反复检查MQTT参数都没问题最后发现那张物联网卡的APN是cmiot而我配置成cmnbiot导致PDP上下文一直激活不成功。查询当前APN设置ATCGDCONT? CGDCONT: 1,IP,cmnbiot,100.65.0.5,...返回里如果有IP地址说明PDP已经激活。如果只有APN没有IP那就是还没激活成功。另外直接用ATCGPADDR1查IP地址最直接能查到IP说明网络层基本OK。还有一次更离谱SIM卡装反了。LCC封装的SIM卡槽方向比较隐蔽插进去的时候没注意触面的正反导致模组一直报未检测到SIM卡。排查SIM卡是否识别的指令ATCPIN? CPIN: READY返回READY说明SIM卡识别正常返回ERROR或NOT INSERTED就得检查硬件和卡槽。5.2 MQTT连接失败参数和保活时间网络层正常但MQTT连不上大概率是鉴权参数问题。我建议把ClientID、用户名、密码三个参数单独校验一遍产品ID必须是纯数字在OneNET产品详情页能查到。注意不要和产品Secret搞混。设备名称是创建设备时填的字符串注意大小写。OneNET的鉴权是区分大小写的。设备密钥是设备级别的一长串字符抄写的时候最容易丢字符建议直接从平台页面复制。另外MQTT服务器域名解析也可能出问题。极少数情况下模组自带DNS解析会失败。如果确认参数没问题可以在AT指令里换用OneNET服务器的IP地址试试但这个方法不建议常态化使用因为平台IP可能调整正式产品还是要用域名。保活时间也是一个隐藏坑。如果设置太短比如10秒模组会频繁发心跳虽然在OneNET看来连接正常但加大了网络消耗如果设置太长比如300秒而中间链路有NAT超时连接可能被运营商网关静默回收模组自己还不知道直到发数据时才发现连接已经被断开。我实测下来120秒在OneNET上表现最稳。5.3 数据发不出去转义、QoS和payloadATMQTTPUB指令发出了串口也返回OK但平台侧看不到数据这种情况多半出在payload格式上。第一个是JSON转义问题。在串口助手里发AT命令时整条命令会经过串口工具的解析JSON里的双引号如果没加反斜杠模组会把JSON拆成多段导致命令不完整。建议先在电脑编辑器里把整条指令拼好再粘贴到串口助手发送。第二个是QoS和报文太小的极端情况。OneNET对payload默认没有太小的限制但MQTT协议要求即使QoS为0也需要一次完整的报文交互如果你在MCU里手动拼AT指令注意不要漏掉最后的双引号和回车换行。第三个是数据格式不符合物模型。OneNET会对上报的JSON做格式校验字段必须是物模型里定义过的并且值类型要匹配。比如物模型里Temp定义成浮点数你上传一个字符串25.6平台会返回参数错误。查询平台返回细节可以在OneNET日志服务里看到具体的错误码和原因。5.4 收不到平台下发订阅Topic和URC上报开关设备在线上报也正常但平台下发的指令设备收不到。这种情况先自查订阅Topic再检查URC通知开关。订阅Topic的$sys前缀不要漏手机或电脑上习惯写路径时容易忽略这个开头。正确格式是$sys/{产品ID}/{设备名}/thing/property/set如果订阅不成功先确认设备是否有权限订阅这个Topic。OneNET的一些服务调用类Topic需要产品下配置数据流或服务才能操作。URC消息上报开关这个坑比较隐蔽。有些固件默认关闭MQTT消息的主动上报或者需要在连接建立后再执行一条指令来打开。模组收不到平台消息时还要检查模组的URC通知是否使能。具体开关指令看固件手册通常和ATMQTTURC或ATMQTTCFG的某个标志位有关。5.5 OneNET平台侧的辅助排查手段模组侧查得差不多了平台侧的日志也要利用起来。OneNET Studio控制台里设备详情页面有日志功能可以看到设备的上线记录、上下行消息和错误码。当设备上报正常但平台显示离线或者平台显示上线但收不到数据时这里的日志是最直接的证据。我处理过一个问题模组侧显示MQTT已连接但OneNET平台里设备一直离线。后来查平台日志才发现是因为设备用相同的ClientID在别的地方重复登录了后登录的设备把前面的会话踢掉了。MQTT协议规定同一个ClientID只能存在一个会话如果有两台设备同时用了相同配置就会出现互踢现象。批量生产时尤其要注意每台设备的产品ID和密钥可以相同但ClientID必须全局唯一。6. 进阶断线重连、低功耗与量产化经验整条链路跑通之后你可能会觉得ATMQTT也不过如此。确实是协议本身的接入不复杂真正拉开差距的是工程化能力断线了怎么办怎么降功耗批量产线怎么管理这些问题早期版本的项目不太会遇到但一旦进入正式交付阶段它们就是决定项目成败的关键。6.1 断线重连不要盲目重启模组LTE网络环境下模组掉线是常态不是异常。模组可能会因为信号差、运营商网络刷新、服务器超时等原因断开MQTT连接。如何处理重连直接决定设备的长期稳定性。最笨但常见的做法是检测到断线后立即重启模组。这种方式简单但有时候会引发恶性循环尤其是网络信号本来就差的时候反复重启只会让设备永远处于没稳定连上的状态。更合理的重连策略是这样MCU定期查询MQTT连接状态比如每30秒查一次。如果发现连接断开先尝试直接重新建立MQTT连接而不是重启网络。重连失败3次后再考虑重新激活PDP或者重新搜网。连续重连多次都失败让设备进入低功耗休眠等一段时间后再恢复重试而不是死循环。模组侧可以把断线检测做成主动模式。几乎没有固件会自动重连都要MCU参与控制。这也是为什么AT方案下的重连逻辑要在MCU代码里实现算是AT方案唯一比LuatOS麻烦的地方毕竟Lua脚本可以直接在模组里写while循环。6.2 低功耗场景下的MQTT保活权衡Air780EP支持休眠模式但MQTT长连接和低功耗本质上是冲突的。因为要保持长连接模组就得定期发心跳无法进入深度睡眠。做电池供电的设备时需要想清楚产品逻辑实时在线且必须能秒级响应平台下发的设备建议保持MQTT连接保活时间选90秒电量消耗主要在这里。大部分时间只是定时上报、不需要频繁响应的设备可以选择上报完数据就断开MQTT连接下次上报前再连接。这种方式功耗最低代价是平台下发指令时设备可能不在线。OneNET平台对离线设备的下发采用的是离线消息机制前提是MQTT会话保持。如果你断开连接时cleanSession设成0平台在设备离线期间发的QoS1消息会在会话恢复后补发给设备。不过OneNET实际对离线消息的存储时长有限制不能完全依赖这个机制来保障消息必达关键指令最好还是让设备定期主动查询。6.3 量产化日志、防抖和产线与平台的关系从样机到量产有几个容易被忽视的小点第一AT命令的串口解析不能只做收到就清空。模组返回的数据可能分多段到达MCU侧要做缓冲拼接按行判断是否完整否则偶尔会出现指令返回被拆包导致误判失败。第二AT命令之间要有延时。模组处理每条指令都需要时间尤其是ATMQTTOPEN这类涉及网络操作的指令执行周期可能几秒。MCU侧要等待上一条命令返回后再发下一条不要像发普通串口字符串一样连续猛发。第三给每台设备一个独立的ClientID。量产批次中设备名称建议用SN或IMEI作为后缀比如dev_861234560123456保证全局唯一。如果产品ID相同、设备名唯一OneNET的管理后台也能做得更清晰。第四产线测试环节不要连生产环境。建议在OneNET平台上单独建一个测试产品产线上的板子先连测试产品跑通后再通过配置切换生产产品。这样避免产线调试消息污染生产数据也更安全。我在实践中会把MQTT服务器地址、产品ID、设备名、设备密钥四个参数统一放到一个配置结构体里MCU程序启动时从外部Flash读取这样同一套代码既能连测试环境也能连生产环境只是配置不一样而已。最后再分享一个我个人的习惯不管多简单的AT指令调试工程我都会把串口日志完整保存下来用时间戳逐条记录。很多问题不是复现不了而是第一次出现时日志没留全。MQTT连接类问题尤其需要这个习惯平台日志加模组串口日志两边一对照五分钟就能定位问题省下的调试时间有时候比省电还重要。
如果你手头正好有一块合宙Air780EP想在最短时间内把设备数据送到OneNET平台上那么ATMQTT这条路应该是最直接的。不用写多层嵌入式代码不用折腾完整SDK只需要一条串口线、一台PC或者MCU串口用AT指令就能完成从模组开机、注册网络、配置MQTT参数到发布第一条数据的全部流程。这篇内容就是围绕这个目标来的我会把整个接入过程拆开讲清楚包括OneNET平台侧怎么创建产品、模组侧怎么配MQTT参数、发布订阅的Topic怎么写、以及我实际调试过程中踩过的坑。适合的人群很明确正在做设备联网打样的硬件工程师、想把现有MCU产品快速上云的开发者、以及做项目Demo演示的朋友。1. 为什么选ATMQTT而不是LuatOS二次开发很多人拿到Air780EP的第一反应是纠结用哪种方式开发。有人推荐LuatOS说可以用Lua脚本直接在模组里跑业务逻辑也有人推荐AT指令说配置简单、上手快。我两种方式都试过最后在速连OneNET这个目标下选了ATMQTT不是因为LuatOS不好而是因为AT指令在特定场景下真的足够省事。1.1 AT指令适合什么样的场景AT指令本质上就是模组已经帮你把网络协议栈跑好了你只需要通过串口发命令让它干活。MQTT这种应用层协议在Air780EP的AT固件里已经被封装成几条指令你不需要关心TCP连接怎么建立、MQTT报文怎么组包、心跳怎么发只需要关心业务参数。适合AT指令的情况大概有这几种现有产品里已经有主控MCU代码逻辑都是C写好的不想为了联网把整个架构迁到Lua脚本上。项目处于打样验证阶段需要快速验证硬件和平台之间能不能跑通AT指令一条条敲下去问题定位最快。维护和产线测试阶段直接拿串口助手或者PC发指令就能测模组好坏不依赖额外编译环境。团队里没有人熟悉LuatOS但大家都懂AT指令协作成本最低。如果你做的产品功能复杂、业务逻辑重而且主控性能很弱甚至没有主控那确实应该考虑LuatOS方案。但在OneNET上云远程监控简单下发这种需求下ATMQTT就是性价比最高的路。1.2 Air780EP在ATMQTT场景下的优势Air780EP作为合宙主推的Cat.1模组在这个场景里优势很直观网络制式是LTE Cat.1比传统2G快比NB-IoT延迟低国内的运营商网络覆盖已经很好不存在2G退网后的麻烦。模组自带TCP/IP协议栈MQTT协议栈也做进了AT固件里MCU这边只需要一个串口外设不需要额外的网络协议处理能力。支持低功耗模式虽然不是这篇的重点但至少说明这个模组后续做电池供电产品有空间不是一步到位的死胡同。封装和Air780E系列兼容PCB设计改起来方便后面真想从AT切到LuatOS硬件不用重画。1.3 我采用的整体链路我的方案很简单链路长这样MCU/PC串口 - Air780EP模组 - 4G基站 - OneNET MQTT服务器 - 应用端MCU侧只做一件事通过串口按帧发AT指令解析模组返回的结果。OneNET侧只需要创建一个MQTT产品加一台设备把产品ID、设备名、设备密钥这三个参数抄下来。真正麻烦的TCP长连接、MQTT会话管理、心跳保活Air780EP固件全包了。这个方案有一个很重要的好处故障隔离。哪天OneNET连不上了我可以直接用串口助手敲指令看返回判断是网络问题、参数问题还是平台问题不用在代码里到处打日志。2. 开工前准备硬件接线、SIM卡和OneNET产品配置先别急着接电源也别急着敲AT指令。接入OneNET之前有三件事没准备好后面大概率会反复折腾硬件接线是否正确、SIM卡是否能正常激活、OneNET平台侧产品是否已经创建。这三件事每一项都有一些容易忽略的细节。2.1 硬件接线与串口调试准备Air780EP模组是LCC封装的一般通过模组评估板来调试。如果你用的是合宙官方的开发板USB口一插就能看到串口设备如果你是自己画的板子那要注意几个点供电电压范围是3.6V到4.2V推荐用稳压电源稳定在4V左右。电流峰值可能在2A上下普通LDO带不动建议用支持大电流的DCDC。UART调试时模组的TXD接USB转串口工具的RXD模组的RXD接工具的TXD别把收发搞反了还要共地。电平匹配问题。Air780EP的UART口电平一般是1.8V或3.3V看具体模块。如果USB转串口工具是5V电平最好加电平转换芯片否则长时间调试有烧引脚的风险。官方评估板一般自带电平转换可以直接插。SIM卡用中国移动的物联网卡或普通SIM卡都行但需要确认能访问公网。OneNET虽然是中国移动的平台不代表只能用移动卡联通电信卡也能连只是APN配置不同。串口助手参数我习惯用115200、8位数据、无校验、1位停止位勾选发送新行。Air780EP的AT默认波特率通常是115200不同批次固件可能有差异如果敲AT没反应试试9600、230400这些常见波特率。2.2 在OneNET平台创建产品和设备打开OneNET开放平台新版叫OneNET Studio注册并登录账号后进入控制台按下面的流程操作选择产品开发点击创建产品。产品名称自己定比如Air780EP_TempMonitor产品分类按实际用途选联网方式选蜂窝网络协议类型选MQTT。创建完成后在产品详情页能看到产品ID和产品Secret这两个后面会用到。在设备管理里添加设备设备名称建议用有意义的名字比如dev01也可以填模组的IMEI后8位方便批量管理。添加完设备后能看到设备所属的产品ID、设备名称以及设备级密钥。OneNET新版的MQTT接入就是用这三个信息做鉴权的。这里我遇到过一个容易混淆的点旧版OneNET多协议接入的MQTT地址和鉴权方式跟新版不同网上很多教程用的还是旧版参数照抄会失败。建议直接使用新版OneNET Studio地址统一用mqtt.heclouds.com端口1883。2.3 MQTT接入参数和AT命令的对应关系OneNET Studio的MQTT接入需要三个关键参数平台参数在MQTT协议里的位置举例产品IDClientID374860设备名称Usernamedev01设备密钥Password63f2a8c1...这三个参数不会直接出现在你的业务代码里而是通过AT命令写入模组。后面的MQTT配置命令里会把它们分别填到对应的字段中。mqtt.heclouds.com这个域名是固定的端口1883是明文MQTT端口如果产品对安全性要求高可以选8883做TLS加密但Air780EP用TLS需要额外配置证书首次调试先别折腾。2.4 确认模组固件里的MQTT能力拿到模组后先不要默认它支持MQTT AT指令。有些出厂固件的版本比较老或者MQTT功能需要单独刷特定版本。先确认一下没什么坏处ATE0 OK ATCGMR V1020ATCGMR查询版本号后去合宙官网文档中心查一下对应版本的AT指令手册确认里面包含ATMQTTCFG、ATMQTTOPEN、ATMQTTSUB、ATMQTTPUB这几条指令。如果固件版本老到没有MQTT指令刷新版AT固件再继续。3. ATMQTT接入全流程一步一步把设备拉上线平台侧准备好了硬件也通了下面就是整个文章的核心通过AT指令把Air780EP串起来完成MQTT连接。我尽量按串口调试的顺序来写每一步都解释清楚参数含义不然你只能抄命令不知道为什么要这么配。3.1 开机、关回声、确认模块响应模组上电后首先在串口助手里发一个AT能收到OK说明串口通信正常。AT OK ATE0 OKATE0是关闭回声就是让模组不再把收到的指令原样回显出来。这样串口日志看起来干净排查问题时不容易被干扰。之后所有的AT指令我都会省略默认存在的OK返回重点看状态相关返回值。3.2 查信号和网络注册状态模块能响应不代表已经上网先看信号质量ATCSQ CSQ: 22,99CSQ返回的两个数字第一个是信号强度范围0到31越大越好一般大于15就能稳定工作第二个是误码率99表示无法测量或不可用只要不是持续丢数据不用太在意。再看网络注册状态ATCEREG? CEREG: 0,1第二个参数为1表示已注册上LTE网络为5表示已注册且处于漫游状态0或2、3就说明还没注册成功。如果卡在这一步先检查SIM卡是否插好、是否欠费、天线是否接上。3.3 配置APN和网络附着物联网卡通常有专用的APN。中国移动物联网卡接入OneNET建议使用cmnbiot部分地区用cmiot。普通SIM卡用cmnet也可以但稳定性不如物联网卡专用APN。ATCGDCONT1,IP,cmnbiot OK ATCGACT1,1 OKATCGDCONT设置PDP上下文第一个参数是上下文ID第二个是IP类型第三个就是APN。ATCGACT激活PDP上下文激活成功后模组才真正拿到了IP地址。这里有一个细节如果之后切换了SIM卡运营商APN要重新设置否则IP层都起不来。用ATCGACT?可以查询当前激活状态返回CGACT: 1,1表示第一个PDP上下文激活成功。激活失败的话大概率是APN不对。3.4 配置MQTT参数服务器、ClientID、用户名、密码网络层OK了开始配MQTT参数。这里以Air780EP AT固件的MQTT配置指令为例ATMQTTCFGmqtt.heclouds.com,1883,374860,dev01,63f2a8c1...,120,0,1 OK各参数对应含义如下参数含义本次的值mqtt.heclouds.comMQTT服务器域名OneNET固定地址1883MQTT端口明文端口374860客户端IDOneNET产品IDdev01用户名OneNET设备名称63f2a8c1...密码OneNET设备密钥120保活时间秒建议90~1200默认QoS0或11cleanSession开关1开启保险时间的含义是如果模组在120秒内没有和服务器之间有任何报文交互就主动发一个PINGREQ心跳包保持长连接不被服务端踢掉。OneNET平台有自己的超时策略保活时间设置太长可能被服务端断开120秒是比较稳的选择。注意不同模组厂家的AT指令设计风格不一样有的用ATMCONFIG有的用ATMQTTCFG参数顺序也可能不同。合宙Air780EP的具体命令名以官方AT指令手册为准但本质上都是填这六个要素域名、端口、ClientID、用户名、密码、保活时间。3.5 打开MQTT连接并确认状态参数配好了下面真正发起连接ATMQTTOPEN OK这条指令让模组主动连到配置的MQTT服务器。如果连接成功有些固件会主动上报一条URC消息比如MQTTCONNECT: 0,0如果用的是需要单独发起MQTT连接的固件还会有一条ATMQTTCONN。这里要养成一个习惯执行完ATMQTTOPEN后等几秒再查状态。ATMQTTSTATE? MQTTSTATE: 2不同固件返回的状态码含义不同一般是0未连接、1连接中、2已连接。看到状态为已连接说明Air780EP已经通过MQTT协议注册到OneNET了。此时去OneNET平台设备列表页面刷新设备状态通常会显示在线。3.6 订阅平台下发Topic设备在线之后先订阅一个Topic。OneNET的设备命令下发和属性设置都通过固定的Topic格式推送订阅之后你才能收到平台侧发来的数据。我演示的是物模型模式下的属性设置TopicATMQTTSUB$sys/374860/dev01/thing/property/set,0 OK第一个参数是Topic路径第二个是QoS级别。这里的路径规则是$sys/{产品ID}/{设备名}/thing/property/set用来接收平台下发的属性设置指令。订阅成功一般会有OK回复固件收到平台消息时也会主动上报URC消息。3.7 发布第一条数据到OneNET最激动人心的一步发布一条数据。OneNET物模型的属性上报Topic是$sys/{产品ID}/{设备名}/thing/property/postpayload是JSON格式。ATMQTTPUB$sys/374860/dev01/thing/property/post,0,0,{\id\:\1\,\version\:\1.0\,\params\:{\Temp\:25.6}} OK这个指令里三个逗号后面的字段分别是Topic、发送QoS、保留标志最后是payload字符串。需要注意JSON内部的引号在AT指令里要用反斜杠转义否则模组解析到一半就截断了。发完之后去OneNET平台的设备数据管理页面能看到属性Temp的最新值是25.6。如果能看到整个链路就通了Air780EP到OneNET的MQTT接入已经没有任何障碍。4. 数据上报与下发物模型、Topic和JSON报文能连上只是第一步真正做产品时你会发现数据上行下行怎么设计、报文怎么写直接决定了后期开发顺不顺畅。这一部分专门把OneNET物模型、Topic和JSON格式的关系讲明白减少你在协议细节上的摸索时间。4.1 OneNET的Topic规则与物模型设计OneNET Studio的设备接入逻辑是基于物模型的。所谓物模型通俗理解就是平台给设备定义了一份能力清单包括属性、事件和服务每个能力有自己的标识符。属性Property设备的某个状态量比如温度、湿度、开关状态可以上报也可以被平台设置。事件Event设备主动上报的异常或告警比如温度过高。服务Service平台可以调用的设备方法比如远程重启。在平台产品详情页定义好物模型后系统会自动生成一系列Topic设备端只需要往固定的Topic里填数据即可。以属性上报为例Topic格式如下$sys/{产品ID}/{设备名}/thing/property/post这个Topic是设备端发布平台端订阅。属性上报之后平台会根据JSON结构里的字段名自动匹配物模型如果字段没在物模型里定义平台可能直接丢弃或者报错。4.2 一条完整的属性上报报文拆解在AT指令里发属性上报本质上就是往MQTT Topic里塞一段JSON。这段JSON的格式要严格符合OneNET的要求{ id: 1, version: 1.0, params: { Temp: 25.6, Humidity: 60 } }id报文的唯一标识默认填个自增数字就行。version协议版本OneNET物模型统一用1.0。params属性集合key是物模型里定义的属性标识符value是实际值。在AT指令里这段JSON要压成一行并且要把双引号转义ATMQTTPUB$sys/374860/dev01/thing/property/post,1,0,{\id\:\1\,\version\:\1.0\,\params\:{\Temp\:25.6,\Humidity\:60}}如果一次要上报多个属性直接在params里加字段就行。这里我建议QoS至少用1否则在某些网络抖动场景下数据报文丢了模组根本不知道平台侧就会漏数据。4.3 接收平台下发指令并回执确认设备不仅要上报数据还要能响应平台的指令。OneNET属性设置的Topic是前面提到的$sys/{产品ID}/{设备名}/thing/property/set你订阅它之后平台下发数据时模组会主动上报一条URC消息类似下面这样MQTTURC: 0,$sys/374860/dev01/thing/property/set,0,{\id\:\22\,\version\:\1.0\,\params\:{\Switch\:1}}MCU收到这条消息后要解析出JSON中的params执行对应的动作比如把继电器打开。执行完成后最好回复一条指令执行完成的确认报文。OneNET提供了属性设置应答Topic$sys/{产品ID}/{设备名}/thing/property/set_reply应答报文同样遵循JSON格式需要带上原报文的id并有一个code字段表示执行结果0表示成功{ id: 22, code: 0, msg: ok }实际开发中很多人都忽略了这一步。平台下发指令后如果长时间收不到应答会判定设备响应超时业务层就可能误报。所以只要在业务逻辑里接收到了set指令一定要记得回执。4.4 上报时序与频率控制OneNET平台对单设备的单Topic上报频率有限制具体数值不同套餐可能不同但结论很明确不要无脑高频上报。有些人在测试时每秒发一条数据结果平台侧显示数据没问题但在量产场景下多设备并发很容易触发平台限流。我的建议是普通传感器属性5到60秒上报一次足够不需要更快的场景尽量别更短。事件告警可以即时上报比如温度越限立刻发一条事件。单次上报多个属性减少MQTT报文数量比单属性多次上报效率高得多。模组侧的MQTT连接只有一条如果上报请求过于密集AT指令队列会堆积串口响应变慢还可能出现指令丢失。MCU侧最好做一个简单的发送队列一条一条发不要同时堆多条ATMQTTPUB。5. 实测踩坑连接不稳定、发不出去、收不到下发的排查思路ATMQTT看起来简单但实际调试过程中容易出问题的点其实不少。这一部分我把常见的故障和解决思路整理出来每一条都是我在项目里真实踩过的坑。排查顺序很重要建议按先网络、再连接、后报文的顺序来。5.1 先确认网络层SIM卡和APN的问题MQTT连接不上的时候第一时间别怀疑MQTT参数先查网络层。我自己最常遇到的坑是SIM卡和APN不匹配。有一次设备老是连不上OneNET我反复检查MQTT参数都没问题最后发现那张物联网卡的APN是cmiot而我配置成cmnbiot导致PDP上下文一直激活不成功。查询当前APN设置ATCGDCONT? CGDCONT: 1,IP,cmnbiot,100.65.0.5,...返回里如果有IP地址说明PDP已经激活。如果只有APN没有IP那就是还没激活成功。另外直接用ATCGPADDR1查IP地址最直接能查到IP说明网络层基本OK。还有一次更离谱SIM卡装反了。LCC封装的SIM卡槽方向比较隐蔽插进去的时候没注意触面的正反导致模组一直报未检测到SIM卡。排查SIM卡是否识别的指令ATCPIN? CPIN: READY返回READY说明SIM卡识别正常返回ERROR或NOT INSERTED就得检查硬件和卡槽。5.2 MQTT连接失败参数和保活时间网络层正常但MQTT连不上大概率是鉴权参数问题。我建议把ClientID、用户名、密码三个参数单独校验一遍产品ID必须是纯数字在OneNET产品详情页能查到。注意不要和产品Secret搞混。设备名称是创建设备时填的字符串注意大小写。OneNET的鉴权是区分大小写的。设备密钥是设备级别的一长串字符抄写的时候最容易丢字符建议直接从平台页面复制。另外MQTT服务器域名解析也可能出问题。极少数情况下模组自带DNS解析会失败。如果确认参数没问题可以在AT指令里换用OneNET服务器的IP地址试试但这个方法不建议常态化使用因为平台IP可能调整正式产品还是要用域名。保活时间也是一个隐藏坑。如果设置太短比如10秒模组会频繁发心跳虽然在OneNET看来连接正常但加大了网络消耗如果设置太长比如300秒而中间链路有NAT超时连接可能被运营商网关静默回收模组自己还不知道直到发数据时才发现连接已经被断开。我实测下来120秒在OneNET上表现最稳。5.3 数据发不出去转义、QoS和payloadATMQTTPUB指令发出了串口也返回OK但平台侧看不到数据这种情况多半出在payload格式上。第一个是JSON转义问题。在串口助手里发AT命令时整条命令会经过串口工具的解析JSON里的双引号如果没加反斜杠模组会把JSON拆成多段导致命令不完整。建议先在电脑编辑器里把整条指令拼好再粘贴到串口助手发送。第二个是QoS和报文太小的极端情况。OneNET对payload默认没有太小的限制但MQTT协议要求即使QoS为0也需要一次完整的报文交互如果你在MCU里手动拼AT指令注意不要漏掉最后的双引号和回车换行。第三个是数据格式不符合物模型。OneNET会对上报的JSON做格式校验字段必须是物模型里定义过的并且值类型要匹配。比如物模型里Temp定义成浮点数你上传一个字符串25.6平台会返回参数错误。查询平台返回细节可以在OneNET日志服务里看到具体的错误码和原因。5.4 收不到平台下发订阅Topic和URC上报开关设备在线上报也正常但平台下发的指令设备收不到。这种情况先自查订阅Topic再检查URC通知开关。订阅Topic的$sys前缀不要漏手机或电脑上习惯写路径时容易忽略这个开头。正确格式是$sys/{产品ID}/{设备名}/thing/property/set如果订阅不成功先确认设备是否有权限订阅这个Topic。OneNET的一些服务调用类Topic需要产品下配置数据流或服务才能操作。URC消息上报开关这个坑比较隐蔽。有些固件默认关闭MQTT消息的主动上报或者需要在连接建立后再执行一条指令来打开。模组收不到平台消息时还要检查模组的URC通知是否使能。具体开关指令看固件手册通常和ATMQTTURC或ATMQTTCFG的某个标志位有关。5.5 OneNET平台侧的辅助排查手段模组侧查得差不多了平台侧的日志也要利用起来。OneNET Studio控制台里设备详情页面有日志功能可以看到设备的上线记录、上下行消息和错误码。当设备上报正常但平台显示离线或者平台显示上线但收不到数据时这里的日志是最直接的证据。我处理过一个问题模组侧显示MQTT已连接但OneNET平台里设备一直离线。后来查平台日志才发现是因为设备用相同的ClientID在别的地方重复登录了后登录的设备把前面的会话踢掉了。MQTT协议规定同一个ClientID只能存在一个会话如果有两台设备同时用了相同配置就会出现互踢现象。批量生产时尤其要注意每台设备的产品ID和密钥可以相同但ClientID必须全局唯一。6. 进阶断线重连、低功耗与量产化经验整条链路跑通之后你可能会觉得ATMQTT也不过如此。确实是协议本身的接入不复杂真正拉开差距的是工程化能力断线了怎么办怎么降功耗批量产线怎么管理这些问题早期版本的项目不太会遇到但一旦进入正式交付阶段它们就是决定项目成败的关键。6.1 断线重连不要盲目重启模组LTE网络环境下模组掉线是常态不是异常。模组可能会因为信号差、运营商网络刷新、服务器超时等原因断开MQTT连接。如何处理重连直接决定设备的长期稳定性。最笨但常见的做法是检测到断线后立即重启模组。这种方式简单但有时候会引发恶性循环尤其是网络信号本来就差的时候反复重启只会让设备永远处于没稳定连上的状态。更合理的重连策略是这样MCU定期查询MQTT连接状态比如每30秒查一次。如果发现连接断开先尝试直接重新建立MQTT连接而不是重启网络。重连失败3次后再考虑重新激活PDP或者重新搜网。连续重连多次都失败让设备进入低功耗休眠等一段时间后再恢复重试而不是死循环。模组侧可以把断线检测做成主动模式。几乎没有固件会自动重连都要MCU参与控制。这也是为什么AT方案下的重连逻辑要在MCU代码里实现算是AT方案唯一比LuatOS麻烦的地方毕竟Lua脚本可以直接在模组里写while循环。6.2 低功耗场景下的MQTT保活权衡Air780EP支持休眠模式但MQTT长连接和低功耗本质上是冲突的。因为要保持长连接模组就得定期发心跳无法进入深度睡眠。做电池供电的设备时需要想清楚产品逻辑实时在线且必须能秒级响应平台下发的设备建议保持MQTT连接保活时间选90秒电量消耗主要在这里。大部分时间只是定时上报、不需要频繁响应的设备可以选择上报完数据就断开MQTT连接下次上报前再连接。这种方式功耗最低代价是平台下发指令时设备可能不在线。OneNET平台对离线设备的下发采用的是离线消息机制前提是MQTT会话保持。如果你断开连接时cleanSession设成0平台在设备离线期间发的QoS1消息会在会话恢复后补发给设备。不过OneNET实际对离线消息的存储时长有限制不能完全依赖这个机制来保障消息必达关键指令最好还是让设备定期主动查询。6.3 量产化日志、防抖和产线与平台的关系从样机到量产有几个容易被忽视的小点第一AT命令的串口解析不能只做收到就清空。模组返回的数据可能分多段到达MCU侧要做缓冲拼接按行判断是否完整否则偶尔会出现指令返回被拆包导致误判失败。第二AT命令之间要有延时。模组处理每条指令都需要时间尤其是ATMQTTOPEN这类涉及网络操作的指令执行周期可能几秒。MCU侧要等待上一条命令返回后再发下一条不要像发普通串口字符串一样连续猛发。第三给每台设备一个独立的ClientID。量产批次中设备名称建议用SN或IMEI作为后缀比如dev_861234560123456保证全局唯一。如果产品ID相同、设备名唯一OneNET的管理后台也能做得更清晰。第四产线测试环节不要连生产环境。建议在OneNET平台上单独建一个测试产品产线上的板子先连测试产品跑通后再通过配置切换生产产品。这样避免产线调试消息污染生产数据也更安全。我在实践中会把MQTT服务器地址、产品ID、设备名、设备密钥四个参数统一放到一个配置结构体里MCU程序启动时从外部Flash读取这样同一套代码既能连测试环境也能连生产环境只是配置不一样而已。最后再分享一个我个人的习惯不管多简单的AT指令调试工程我都会把串口日志完整保存下来用时间戳逐条记录。很多问题不是复现不了而是第一次出现时日志没留全。MQTT连接类问题尤其需要这个习惯平台日志加模组串口日志两边一对照五分钟就能定位问题省下的调试时间有时候比省电还重要。
