跳转至

常见问题 - 2026-08-23

数据日期：2026-08-23

1. 如果模块死机了怎么解决？

解答： 建议按以下顺序排查定位：

  1. 升级最新固件：先刷合宙官网该型号的最新正式版固件与默认 lib 脚本验证，大量已知问题在新版本中已修复；
  2. 区分是固件问题还是脚本问题：烧录官方对应 demo 空跑，若空跑也死机，基本可判定为固件/硬件问题；若只在加载业务脚本后死机，则需精简脚本定位；
  3. 提供最小复现脚本：在工程脚本基础上逐步删减代码，直至找到触发死机的最小逻辑段，连同死机时的 Luatools Trace 日志、模组型号和固件版本号一起反馈给合宙技术支持；
  4. 量产设备建议接入异常日志上报功能 errDump，可在设备运行异常后自动把错误日志上报到合宙云平台，便于远程定位，文档：https://docs.openluat.com/osapi/core/errDump/ ；
  5. 现场恢复：运行中发生死机（程序跑飞、无喂狗、无响应）时，模组无法自行恢复，需要重新上电复位；工业场景建议板载硬件看门狗芯片（如 Air153C/Air153D）实现掉电自动复位。

2. 合宙模块上有没有预留射频测试点（RF Test Point）？

解答： 合宙模组本体上没有额外预留独立的"RF Test Point"射频测试点焊盘。需要进行传导射频测试（如 CMW500 测发射功率、接收灵敏度等）时，按以下方式进行：

  1. 凡 LTE_ANT 射频信号引出了板载射频座（IPEX/天线座）的模组或开发板，均可直接从射频座用同轴线连接测试仪器，插入测试白卡、正常开机后即可测试，无需专门的测试点；
  2. 自研底板设计时，建议在射频链路（天线匹配位置或 IPEX 座处）预留 π 型匹配焊盘或 0Ω 串联电阻位，测试时可断开天线通道、串接仪器；
  3. 操作细节可参考官方文档《怎么仪器测试模块的输出功率》章节：https://docs.openluat.com/air780e/at/faq/ 。

3. Air780EPM EHV GPIO 上下拉的电阻是不是有区别？打样测试时用的EHV，GPIO设置高低正常，客户换780EPM之后就不正常了。

解答： Air780EPM 与 Air780EHV 属于同一芯片平台的不同型号，GPIO 内部上下拉电阻规格一致（同一套硬件设计规范，内部上拉/下拉均为弱上下拉，典型值约几十 kΩ 量级，且随电压域不同而不同），上下拉阻值差异不是该现象的原因。EHV 正常、换 EPM 后 GPIO 输出异常，通常由以下原因导致，请逐一排查：

  1. 管脚默认功能/复用不同：Air780EHV 内置音频 Codec（ES8311），部分管脚被内部音频功能占用，两款型号同名管脚的默认功能并不完全一致。务必以官方《Air780EPM&EHM&EHV...GPIO复用表》核对实际使用的 PIN 脚，并用 LuatIO 工具生成对应型号的 pins_xxx.json 配置文件随脚本下载（EPM 须用 pins_Air780EPM.json，不能直接沿用 EHV 的配置），确保该管脚被配置为 GPIO 功能，复用表与 LuatIO 说明见：https://docs.openluat.com/air780epm/luatos/hardware/gpio/ 、https://docs.openluat.com/air780epm/luatos/app/base/luatio/air780epm/ ；
  2. 代码显式配置：确认软件中调用了 gpio.setup(pin, 0/1) 将该管脚配置为输出，不要依赖管脚默认状态；
  3. 不要依赖内部上下拉驱动外部负载：内部上下拉为弱上下拉（驱动能力仅几十 μA 量级），外接 LED、三极管等负载时必须外加电阻（外部上下拉建议按硬件手册选取，普通 GPIO 驱动能力约 14mA@3.3V），同时检查 LED 极性、限流电阻和焊接；
  4. 上电瞬态：普通 GPIO 在上电/复位瞬间可能有约 1ms 异常高电平，必要时外加 10K 下拉消除；
  5. 用万用表/示波器实测 EPM 板该管脚电平，对照 EHV 板同位置波形，即可快速区分是管脚未复用成功、外部电路问题还是负载过重。

4. ai.luatos.com挂了不会回答怎么办？

解答： ai.luatos.com（合宙官方在线 AI 问答助手）后端依赖大模型 API，偶发无响应通常是服务端临时波动或网络问题，可稍等后刷新重试。若持续不可用，不影响开发进度，可改用以下官方渠道获取支持：

  1. 合宙官方文档中心，查阅产品硬件资料、开发手册与库函数说明：https://docs.openluat.com/ ；
  2. LuatOS 官方代码仓库，各型号 demo 与库脚本源码均可直接检索参考：https://gitee.com/openLuat/LuatOS/tree/master/module ；
  3. 加入合宙官方企业微信群（在 https://docs.openluat.com/ 网站底部扫描二维码），群内有官方技术支持答疑；
  4. 复杂问题建议整理为"模组型号 + 固件版本 + 最小复现脚本/日志"的完整信息后再提问，便于一次定位。

5. Trae CN升级后没有多页签切换了，每次只能打开一个文件，原来的多页签切换文件设置在哪里？

解答： 该问题属于编辑器（Trae CN 基于 VSCode 内核）自身设置，与 LuatOS 无关。恢复多文件页签（标签页）的方法：

  1. 打开设置：快捷键 Ctrl+,（或菜单栏 文件 → 首选项 → 设置），搜索 showTabs，将 Workbench › Editor: Show Tabs 项勾选启用（对应配置项 "workbench.editor.showTabs": true）；
  2. 检查是否误进入禅模式/居中布局干扰界面，可按 Ctrl+K 再按 Z 退出禅模式，或按 F1 输入 "View: Toggle Zen Mode"；
  3. 若设置后仍不显示标签栏，可用 Ctrl+Tab 在已打开的多个文件间快速切换，或通过资源管理器双击文件在新页签打开；
  4. 也可直接在 VSCode 中安装 LuatOS 官方开发辅助插件（在扩展市场搜索 LuatOS），配合 docs.openluat.com 文档进行开发。

6. 新的luatools3.4.6怎么错误这么多，搜索框乱指定结果行数，打印时不会自动更新，需要自己下拉到底部？

解答： LuaTools 3.4.6 上反馈的搜索行数异常、Trace 打印窗口不自动滚动等属于工具软件界面层面的问题，建议按以下方式处理：

  1. 优先升级到官网最新正式版 LuaTools（新版会持续修复界面与日志窗口缺陷），下载地址：https://docs.openluat.com/common/Luatools/ ；升级后仍异常的，可关闭 LuaTools、删除其安装/工作目录下的缓存配置后重新打开对比验证；
  2. 临时规避：日志搜索时用完整关键字精确匹配并核对跳转到的行号；Trace 窗口可点击日志区域后按 Ctrl+End 跳到最新输出，或勾选"自动滚动/暂停打印"相关按钮（不同版本位置略有差异），观察是否为暂停接收状态；
  3. 烧录与 Trace 端口确认：在 LuaTools 主界面正确选择打印口（USB 打印 Trace / UART 打印 Trace 需与固件烧录时选择的日志端口一致），端口选错也会表现为日志不更新；
  4. 问题反馈：若最新版仍可稳定复现，请记录 LuaTools 具体版本号、操作系统版本，并附上问题截图/录屏，通过合宙官方企业微信群（https://docs.openluat.com/ 网站底部二维码入群）反馈给官方技术支持修复。

7. air8700p的gpio19外接一个led不亮，怎样解决？

解答： 该现象的根因是：Air8700P 上对应管脚是多功能复用脚，默认功能并非 GPIO（GPIO19 与 I2C1_SDA 等功能复用同一管脚），不做管脚功能初始化时，该脚处于默认功能状态，调用 GPIO 输出不会生效，LED 自然不亮。按以下步骤处理：

  1. 用 LuatIO 工具配置管脚复用：在 LuaTools 中打开 LuatIO 可视化配置工具，选择对应模组型号，将该管脚显式配置为 GPIO 功能，保存生成 pins 配置 json 文件（pins_$model.json，如 pins_Air8700P.json），随脚本一起下载到模组，管脚才会切换为 GPIO 功能，LuatIO 使用说明：https://docs.openluat.com/air780epm/luatos/app/base/luatio/air780epm/ ；各管脚默认功能以 Air8700 官方 GPIO 复用表为准：https://docs.openluat.com/air8700/luatos/hardware/module/circuit/pins/ ；
  2. 代码中正确初始化：配置复用后再调用 gpio.setup(19, 0)（或 1）设置为输出，并用返回的电平函数或 gpio.set(19, 1/0) 控制电平，API 说明：https://docs.openluat.com/osapi/core/gpio/ ；
  3. 检查 LED 硬件：确认 LED 极性方向、限流电阻取值（普通 GPIO 单脚驱动能力有限，不要超出手册电流上限）、焊接与共地；
  4. 用万用表/示波器实测该管脚电平：若电平可正常翻转但 LED 不亮，问题在 LED 电路；若电平不翻转，说明管脚复用未生效（json 未下载或型号选错），重新用 LuatIO 生成配置即可。

8. 调试modbus tcp功能，一直显示TCP连接未建立或已断开，无法发送请求。

解答： Modbus TCP 的底层是 TCP socket 连接，"连接未建立或已断开"说明链路层 TCP 未连通，Modbus 请求无从发出。按以下顺序排查：

  1. 先确认模组自身联网正常：SIM 卡未欠费、注网成功（mobile 状态正常）、已拿到 IP（等待 IP_READY 消息后再建链），可用 socket 先做一次普通 TCP 连接测试，确认基础网络通路；
  2. 先用官方测试服务器排除服务器侧问题：使用合宙自建 TCP/UDP 测试服务器 https://netlab.luatos.com/ ，在页面"打开 TCP"获取测试 IP 和端口，填入脚本连接，若能连通则说明模组网络正常，问题在对端 Modbus 服务器（IP/端口、服务是否启动、防火墙/白名单）；
  3. 核对 Modbus 服务器参数：IP 地址与端口号（Modbus TCP 默认 502 端口）是否正确，服务器是否允许该客户端接入，使用定向卡/专网时需把服务器地址加入白名单；
  4. 以官方 demo 为基准对比：直接烧录官方 Modbus TCP 主站 demo 验证（参考 https://docs.openluat.com/air8101/luatos/app/mulu/modbus/modbus_TCP_master/ ，demo 源码：https://gitee.com/openLuat/LuatOS/tree/master/module/Air8000/demo/modbus ），在此基础上只改 IP/端口/寄存器参数，确认 demo 可连通后再移植业务代码；
  5. 打开 socket 调试日志（如 socket.debug(netCB, true)）观察 connect 结果与断开事件，连接成功后再发 Modbus 请求；若建链后很快断开，检查是否缺少心跳/轮询间隔、服务器从站地址与功能码是否匹配。

9. 工业模组（8781，8782）的看门狗以后会换成153D吗？

解答： 目前 Air8780/Air8781P 等工业模组板载的是合宙自研看门狗芯片 Air153C（喂狗信号 GPIO24，喂狗超时约 200~280 秒，随 VBAT 电压不同而变化），短期内不会直接变更为 Air153D。

给自研项目的建议：新设计看门狗电路时直接选用升级款 Air153D。二者是同一颗芯片、仅软件不同，主要区别和注意点：

  1. Air153D 可通过 STRAP1(PIN1)/STRAP6(PIN6) 配置 4 档喂狗超时时间（10 分钟 / 60 分钟 / 12 小时 / 24 小时），主控不必再为喂狗频繁唤醒，对低功耗更友好；而 Air153C 超时固定约 240 秒，低功耗下约 200 秒内必须醒来喂狗，功耗较大；
  2. Air153D 不能直接替换 Air153C：硬件上需按所选档位增加 STRAP 配置电阻（10K），参考官方参考设计；
  3. 软件可直接使用官方 exair153x_wdt 扩展库，Air153C/Air153D 均支持；使用 FOTA 时注意升级期间喂狗处理；
  4. Air153D 芯片使用说明与参考电路见官方文档：https://docs.openluat.com/accessory/Air153D/ 。

10. 在AirCloud添加账号下上报过数据的设备imei，提示错误，项目和设备有什么特别要求？

解答： AirCloud（合宙 IoT 云平台，iot.luatos.com / iot.openluat.com）按"账号 → 项目 → 设备（IMEI）"层级管理，设备必须先归属到当前登录账号下的项目中才能添加和查看。添加 IMEI 报错通常由以下原因导致，请逐一核对：

  1. IMEI 未归属到当前账号：设备归属在采购时默认账号（采购人手机号账号）或其他账号/项目下，需先做归属转移。登录 iot.openluat.com 在"我的设备"中输入 IMEI 可查询当前归属；归属转移按官方文档操作：https://docs.openluat.com/air780epm/product/attributioniot/ （官方淘宝渠道采购的设备可在 crm.luatos.com 凭订单自助转移；非官方渠道/第三方购买的设备需联系合宙客服凭 IMEI 核实后处理）；
  2. 项目不存在或未选对：在平台"项目管理/我的项目"中先新建项目（如 https://iot.openluat.com/lbs/project-list ），再在该项目下添加设备序列号（IMEI），项目下没有设备时下拉选择会显示无结果；
  3. 输入格式问题：检查 IMEI 是否输入完整（15 位）、末尾或中间不要多带空格、不要缺位，IMEI 最后一位为校验位；
  4. 脚本侧项目 key 与平台一致：设备端 demo 中配置的 auth_key（项目 key）必须与该设备所属项目的 key 完全一致，key 不匹配会导致认证/鉴权失败；AirCloud 由 excloud 扩展库实现，平台配置步骤与 key 获取可参考：https://docs.openluat.com/air8101/luatos/app/base/aircloud_up/ ，demo 源码：https://gitee.com/openLuat/LuatOS/tree/master/module/Air8101/demo/aircloud ；
  5. 排查顺序建议：先在"我的设备"用 IMEI 查归属 → 归属不对就转移到当前账号 → 在目标项目下添加设备 → 核对脚本中的项目 key → 重新上电让设备上报，刷新平台即可看到设备在线。
搜索