常见问题 - 2026-09-08
数据日期:2026-09-08
1. Air8000A核心板怎么实现上电自动开机?
解答: 结论:把 CHG_DET 引脚接到 GND 即可实现上电自动开机,也可以直接把开机键的两个焊点短接(或用焊锡连起来)。
说明:CHG_DET 是充电检测脚,硬件上把它拉低等于让模组一上电就满足开机条件,不需要再按开机键。两种做法都可行,按产品形态选择:
- CHG_DET 接 GND(推荐):只改一处电路,模组上电(或插入充电器/电源)即自动启动。适用于整机常年通电、不需要用户手动开关机的场景。
- 短接开机键两个焊点:最省事,但要一次成型,焊死之后就失去手动关机能力。若不希望用户能关机,可用这个方式。
注意:需要保留“按键开关机”功能的产品不要焊死按键,改走 CHG_DET 方案;量产前建议在实机上各跑一批验证上电启动的稳定性。
参考文档:Air8000 系列产品资料见 https://docs.openluat.com/air8000/product/ 。
2. Air8000/Air8000A核心板在哪里能找到GND/开机键?
解答: 结论:这两个位置都在核心板的引脚图(产品手册/硬件资料里的管脚定义图和板卡丝印)上,按图找到对应焊盘/测试点后,把它和 GND 焊(或用飞线连)在一起即可。
定位方法:
- 到 https://docs.openluat.com/ 对应型号的“产品手册 / 硬件资料”章节,打开引脚图或核心板原理图,找到 GND 网络和 CHG_DET / 开机键(PWRKEY)对应的管脚编号。
- 对照板子上的丝印,确认模组焊盘或板上的测试点位置(核心板一般把关键脚引到排针或测试点,比直接焊模组更方便)。
- 用飞线把开机脚与 GND 短接,不要用大功率烙铁长时间压焊模组焊盘,避免损伤。
提示:如果只是想验证“上电自动开机”,用官方开发板(EVB)比在核心板上动焊更方便,确认方案后再改产品板。
参考文档:https://docs.openluat.com/air8000/product/ 。
3. LuatOS在macOS上能开发烧录吗?
解答: 结论:Luatools 只支持 Windows,不能在 macOS 上运行;macOS 目前只能走 VSCode 插件 / luatos-cli 这条命令行路线,官方并未在 macOS 上实测过,也没做兼容性承诺。
可选做法:
- 命令行路线:用 LuatOS VSCode 插件(https://docs.openluat.com/osapi/markdown/vscode/ )做代码编辑与串口操作;烧录可配合 luatos-cli(https://gitee.com/openLuat/luatos-cli )在终端执行,理论上不依赖 Windows,但需自行验证串口驱动和下载时序。
- 最稳妥路线(推荐):macOS 上写代码,烧录放到 Windows 机器上做;或在 Mac 上用 Parallels Desktop / VMware 跑一个 Windows 虚拟机,在虚拟机里用 Luatools(注意把 USB 设备直通给虚拟机,否则识别不到模组串口)。
- 若项目对烧录/量产依赖重,建议直接用一台 Windows 电脑作为烧录机,避免在未验证的工具链上消耗时间。
参考文档:LuatOS 插件 https://docs.openluat.com/osapi/markdown/vscode/ ;Luatools 教程 https://docs.openluat.com/common/Luatools/ 。
4. Air8781P模组低功耗时功耗偏高(有看门狗芯片1.4mA,无看门狗55uA)是什么原因?
解答: 结论:1.4mA 与 55µA 差了近 25 倍,说明多出来的电流基本来自看门狗芯片及其外围电路(看门狗本身静态耗电 + 它带动的 LED、DCDC 使能等),属于板级硬件漏电,不是模组休眠没进到位。
排查步骤(按“先摘外设、再逐个装回”的顺序做,用功耗分析仪看电流波形):
- 确认看门狗型号与工作状态:确认喂狗周期与 PSM+ 下的供电策略(如用 Air153x 系列,参考 https://docs.openluat.com/osapi/ext/exair153x_wdt/ )。看门狗若在休眠期间仍保持振荡/供电,会直接叠加到底电流上。
- 先摘 LED:LED 与其限流电阻是常见漏电点(尤其被 GPIO 或看门狗输出悬空驱动时 LED 半亮),摘掉后复测。
- 再看 DCDC:确认 DCDC 的使能脚在休眠时是否被拉对、DCDC 静态电流是否偏高;必要时改用低静态电流的 LDO 或带 EN 控制的 DCDC。
- 检查未使用管脚:悬空或带上/下拉的 GPIO、上拉电阻分压通路都会漏电,逐个断开对比。
- 不需要看门狗就选 Air8781P3 / P4 版本,从硬件上省掉这颗芯片和它的外围。
参考文档:低功耗设计与实测方法 https://docs.openluat.com/common/airpower/ 。
5. Air153C模块功耗是多少?有没有现成点8781P1模组使用的Air153D?
解答: 结论:新项目不要再选 Air153C,改用 Air153D——Air153D 实测静态功耗约 2.9µA。当前 Air8781P1 上仍是 Air153C,合宙会寄新的 Air153C 给客户做验证。
说明与建议:
- Air153D 面向低功耗场景,尺寸/封装与用法见配件文档 https://docs.openluat.com/accessory/Air153D/ ,驱动请用官方扩展库 exair153x_wdt(https://docs.openluat.com/osapi/ext/exair153x_wdt/ ),不要沿用老 demo 里手工搬运的脚本。
- 正在用 Air153C 的存量项目:先用官方最新 lib 替换后复测底电流,确认是否满足指标;若要压到微安级,建议直接切 Air153D。
- 新设计的板子直接在 BOM 里选 Air153D,避免量产后二次改板。
6. 模块能识别但烧不进程序/下载失败怎么办?
解答: 结论:这类“能识别串口但下载失败”绝大多数是烧录链路或本地环境问题(工具、USB 线、供电、驱动、杀软),少数是模组 bootloader 异常,按下面的顺序排查即可覆盖 90% 的情况。
排查步骤:
- 先抓日志:完全关闭 Luatools → 删除其安装目录下的
log目录 → 重新打开 Luatools。工具目录下的main/trace日志是定位的关键证据。 - 更新工具:把 Luatools 升到最新版(https://docs.openluat.com/common/Luatools/ ),旧版本对新型号支持不全。
- 换线换口:换一根短(<1m)且确认带数据功能的 USB 线,直接插电脑主机 USB 口,不要用 USB 扩展坞/前面板。
- 手动强制进 Boot:点“下载”进入等待后,按住 BOOT 键(或按提示)再点按一下 RESET;Air8000 等需要组合键的型号按对应硬件手册操作。
- 排除干扰:关闭 360 等杀毒软件,结束残留的 Luatools 进程,拔掉其他占用串口的设备,必要时重启电脑。
- 查供电:用稳压电源给 VBAT 供 4V、限流 2A 试一次,电源跌落也会导致下载失败。
以上都无效时,把工具目录下当天的 main/trace 日志发到官方企业微信群,由技术确认是否为 bootloader 损坏。参考:https://docs.openluat.com/common/howtodown/ 。
7. Air780EPM在2036以上版本不支持fatfs文件系统,需要驱动SD卡怎么办?
解答: 结论:要用 SD 卡(fatfs)就换 Air780EHM,Air780EPM 从 V2036 起的固件不再提供 fatfs 文件系统与 SD 卡驱动。
说明与替代方案:
- 两者是不同型号、不同功能配置:Air780EPM 定位数传/低功耗,文件系统侧走外挂 Flash(little_flash)路线;Air780EHM 保留 fatfs 与 SD 卡能力。需求是 SD 卡读写,就必须选 EHM(或带 SD 卡能力的其他型号)。
- 如果只是要“大容量存储”而并非必须 SD 卡物理形态:可在 EPM 上外挂 SPI Flash,用 little_flash 管理(挂载/读写/擦除),详见 https://docs.openluat.com/osapi/core/little_flash/ 。
- 选型前先确认固件功能编号:同一型号不同编号固件内置的库不同,务必对照该型号固件版本页的“支持核心库列表”(EPM:https://docs.openluat.com/air780epm/luatos/firmware/780epm_version/ )再定方案。
8. Air724UG用PDU模式发短信报+CMS ERROR: 517是什么原因?
解答: 结论:517 表示 PDU 格式错误,即模组按 PDU 模式(AT+CMGF=0)提交时,收到的数据不符合 GSM 03.40 的 PDU 结构要求,与卡和运营商无关,是发送侧的数据组包问题。
常见成因(按出现频率排序):
- 长度字段算错:
AT+CMGS=<length>里的 length 是 TPDU 的字节数(不含 SMSC 部分),多算或少算 1 个字节就会被判 517。 - 编码与 DCS 不匹配:中文短信用 UCS-2(DCS=0x08)时,一个汉字占 2 字节,长度必须按字节数算,不是按字符数;用 ASCII 长度提交是最常见的错误。
- 短信中心号码格式错误:SMSC 字段要求“长度 + 号码半字节交换 + 91 类型位”,号码前不能带
+,长度含类型位。 - 号码长度/格式问题:目标号码未做半字节交换,或长度与实际不一致。
- 字符串被截断:串口一次发送太长、或结尾的 Ctrl+Z(0x1A)以转义形式发出,导致模组收到的字节不完整。
排查方法:用标准 PDU 编码/解码工具(或直接打印出即将发送的 PDU 字符串)逐字段核对长度、SMSC、DCS、目标号码,再在模组上用 AT+CMGF=0 + AT+CMGS 单条提交验证。建议先用一条纯英文短信(GSM 7bit)打通链路,再换中文 UCS-2。
9. 4G模组有MAC地址吗?
解答: 结论:4G 模组没有 MAC 地址的概念,模组侧的设备唯一标识用 IMEI;只有 WiFi 型号才有 MAC(STA/BSSID)。
说明:
- MAC 是链路层地址,属于以太网 / WiFi 这类共享介质网络;4G(LTE/Cat.1)是蜂窝空口,接入过程用的是 IMSI/ICCID,设备身份由 IMEI 标识,不存在“蜂窝网卡 MAC”。
- 通过 USB 以 RNDIS/ECM 模式接电脑时,电脑上会看到一个虚拟网卡并分配一个 MAC,那是 USB 网卡驱动侧生成的地址,不是模组的蜂窝身份,也不适合作为产品唯一标识。
- 做设备唯一标识请用 IMEI(AP 侧可用
mobile.imei()读取);WiFi 型号需要唯一标识时可用 STA MAC。
参考文档:https://docs.openluat.com/osapi/core/mobile/
10. 合宙模组/开发板可以把C程序移植进去吗?
解答: 结论:不能。合宙模组对外只开放 Lua 脚本层 + 官方扩展库(lib),既不能把已有的 C 程序移植进去,也不能把第三方库加入到 LuatOS 层。
说明:
- 固件不开放编译入口:LuatOS 固件的底层(RTOS、协议栈、内置 C 模块)由合宙统一维护和发布,用户侧没有编译链和烧录入口,无法把自己的 C 代码/第三方 C 库编进固件。
- LuatOS 层不接受第三方库并入:
require到的核心库与扩展库都来自合宙官方仓库,库的引入、适配与版本维护由合宙统一负责,第三方库不能加入到 LuatOS 的库体系里(不要指望“提交一个库就被合进固件”)。 - 能做的事:①业务逻辑用 Lua 脚本实现,这是模组的标准开发方式;②需要额外能力时,优先在官方扩展库里找现成的(例如各类传感器、外设、协议库),放到自己工程目录随脚本一起打包即可;③只在 Lua 层做不到、确有 C 级性能或驱动需求时,联系合宙商务走定制评估,由合宙决定是否需要动底层。
补充:从 Air724 时代的 Luat(C 语言)工程迁移到 LuatOS 的差异,参考 https://docs.openluat.com/common/Luatos-air_to_LuatOS/ ;扩展库与核心库清单见 https://docs.openluat.com/osapi/ 。
11. 8000W等固件代码空间不够,网页等文件是否可以放到文件系统?
解答: 结论:可以。代码(Lua 脚本)空间的不足要靠文件系统来分担——把网页、图片、字体等非脚本资源放进模组的文件系统,脚本运行时用 io.readFile 等接口读取,而不是把它们塞进脚本区。
做法:
- 在 Luatools 项目管理里把要烧进文件系统的文件(html/css/js/图片/字库等)加入下载资源列表,随固件一起烧录到文件系统。
- 脚本侧用
io.readFile("/路径/文件")读取,配合http/socket做网页服务;注意文件名和路径用英文、不含中文和特殊字符,且要控制在文件系统剩余空间内。 - 若文件系统空间也不足,可外挂 SPI Flash 用 little_flash 存放(https://docs.openluat.com/osapi/core/little_flash/ ),或换脚本区/文件系统分区更大的固件编号——同一型号不同编号固件(如 14 号 / 19 号 / 21 号)分区大小不同,选型方法见该型号固件版本页(Air8000:https://docs.openluat.com/air8000/luatos/firmware/ )。
12. Air780EPM的wakeup IO接3.3V单片机需要电压转换吗?
解答: 结论:不需要。Air780EPM 的 IO 电平为 3.3V,与 3.3V 单片机可以直接对接。
注意两点:
- 确认模组 IO 供电(VDD_EXT/IO 电源域)确实是 3.3V 而不是 1.8V 配置,两边电平一致才能直连。
- Wakeup 脚是中断唤醒输入,接单片机输出时注意:单片机侧输出建议开漏或推挽可控,避免休眠时被外部持续拉低/拉高造成误唤醒或漏电;中断触发沿(上升/下降)要与
gpio.setup的配置一致。
参考文档:https://docs.openluat.com/air780epm/luatos/hardware/
13. Air780EHU可以用Air780EHT的AT固件吗?你们是否有海外AT型号模组?
解答: 结论:①不能用 Air780EHT 的 AT 固件刷 Air780EHU,两者固件不可混刷;②目前合宙没有海外 AT 型号模组。
说明:
- 不同型号的固件(含 AT 固件)是按型号与硬件平台发布的,固件与型号不匹配会刷写失败,甚至导致模组无法启动。有客户自行刷 AT 固件后“看着能用”,但海外频段/运营商兼容性没有得到验证,不能作为量产依据。
- 海外项目建议直接选海外 LuatOS 型号做二次开发(如 Air780EHU 为欧亚版本、Air780EHN 为北美版本),自行在 Lua 层实现业务,而不是去刷不确定来源的 AT 固件。
- 固件下载与型号对应关系见 https://docs.openluat.com/ (对应型号的“固件和 demo”栏目)。
14. 小程序入口能用合宙的小程序吗?
解答: 结论:不行。合宙的小程序是官方自用的业务入口,不开放给客户作为自己产品的小程序使用;要做面向终端用户的小程序,需要自己申请小程序 + 自备服务器和已备案域名。
说明与替代方案:
- 微信小程序的合法域名要求 HTTPS 且域名已备案,因此必须有自己(或公司名下)的服务器与域名,合宙不提供这项资质代持。
- 推荐架构:设备 → 合宙 AirCloud / IoT 平台 →(开放 API)→ 你自己的后端/小程序。设备侧用 aircloud 库连接上报,小程序侧调用合宙开放接口取数据、下发指令,链路是“小程序→云→模组”,设备端不需要公网 IP。开放接口说明:https://docs.openluat.com/protocols/aircloud_api/wx_support/ 。
- 若只是内部调试,可以先不做小程序,用平台自带的网页后台或 AirCloud 上报记录页查看数据(如 iot.luatos.com 的相关菜单)。
15. 合宙对OTA请求频率有限制吗?
解答: 结论:有。同一台设备 20 分钟内只允许发起一次 OTA(FOTA)请求,超出的请求会被拒绝,需要等下一个窗口。
说明与建议:
- FOTA 不是“发一次请求就马上升级”的推送机制,设备重启后会在最长 24 小时的窗口内去查询一次升级任务;把查询周期做得很短(每秒/每分钟轮询)没有意义,只会被平台限流。
- 调试期反复触发升级时,注意每次修改完升级包/任务后等够间隔再让设备重启查询,否则会以为“没生效”。
- 相关机制与回调码说明见 https://docs.openluat.com/osapi/ext/libfota2/ ;平台侧操作见 https://docs.openluat.com/air780epm/luatos/app/ota/fota3rd/ 。
16. 设备重启后能把断网期间的日志上传吗?
解答: 结论:能。运维日志保存在可写文件系统里,FOTA 升级只刷固件与脚本运行区,不动可写文件系统,所以重启后未传完的日志会继续上传。
说明:
- 关键在于“日志落在可写文件系统/外挂 Flash”,而不是落在脚本区或内存里——落在内存里的数据重启即丢。
- FOTA 的分区刷写范围决定了这一点:脚本升级只覆盖脚本区、core 升级覆盖固件区,用户文件系统(/luadb 或外挂 Flash 上的分区)与会话数据不受影响。
- 若要保证“断网期间数据无损”,除落盘外,应用层还应记录已上传位置并在恢复联网后按序补传(断点续传),避免重复上报或漏报。存储与文件系统接口见 https://docs.openluat.com/osapi/core/io/ 与 https://docs.openluat.com/osapi/core/little_flash/ 。
17. PM关闭WIFI后4G断网是什么原因?
解答: 结论:这是产品硬件版本相关的问题:早期 A10/A11 版本的 WiFi 由 GPIO 控制 PA 供电,关 WiFi 时把共用的电源/GPIO 也带下去了,导致 4G 侧断网;A13 版本应已修正,需要按实际硬件版本和代码逻辑确认。
排查步骤:
- 确认硬件版本(A10 / A11 / A13),不同版本的 WiFi 供电与使能设计不同。
- 查代码里
pm/ WiFi 电源相关的 GPIO 操作:确认关闭 WiFi 时没有误动 4G 侧共用的电源使能脚,也没有把 IO 电源域关掉。 - 用示波器观察关 WiFi 前后 4G 侧供电和 PA 使能脚的波形,确认是电源跌落还是逻辑误操作。
- 若确为 A10/A11 硬件限制,联系合宙技术支持确认是否有改板或规避方案。
参考文档:多网与电源管理说明见 https://docs.openluat.com/air8000/luatos/hardware/ 。
18. 700ECT是否支持三大运营商?
解答: 结论:不支持。Air700ECT 受硬件(射频/频段与认证配置)限制只支持中国移动,与软件固件版本无关。
说明与选型建议:
- 这类小尺寸 4G 模组普遍只支持中国移动,不是固件能改的问题;换固件、换工具都无法让它支持联通/电信。
- 选型前务必确认目标运营商:需要三网通用/联通/电信的场景,请从选型指南里挑支持全网通的型号(https://docs.openluat.com/SelectionGuide/SelectionGuide/ ),不要按尺寸先选型再回头发现不支持。
- 拿不准时把需求(运营商、频段、尺寸、成本)发到官方企业微信群确认。
19. Air780EPM用V2007 AT固件支持串口PPP拨号吗?
解答: 结论:不支持。Air780EPM 是 LuatOS 二次开发模组(AT 固件是配套的辅助形态),并不提供串口 PPP 拨号能力;需要 AT PPP 拨号请选用支持该功能的 AT 模组。
说明与替代方案:
- 想用串口把 4G 网络“喂”给主控 MCU,正规做法是让主控侧跑 PPP 协议、模组侧提供对应的透传/AT 通道;Air780EPM 上请改用 LuatOS 二次开发,直接 socket/mqtt 上传数据,把业务逻辑放在模组里,比 PPP 链路更简单可靠。
- 若主控必须拿到“一条网线”,可考虑带 RNDIS/ECM 虚拟网卡能力的型号(USB 接 Linux 主机出 ECM 网卡),用法见 https://docs.openluat.com/air780epm/luatos/app/common/rndis/ 。
- AT 固件与 LuatOS 固件是两条不同路线,选型时先确定“谁写业务逻辑”,再定型号。固件列表见 https://docs.openluat.com/air780epm/luatos/firmware/780epm_version/ 。
20. Air8000支持TTS库吗?tts.synthesize函数是否存在?
解答: 结论:没有单独名为 tts 的库,也没有 tts.synthesize 这个函数。Air8000 的语音合成请用新音频框架 audio_v2(或扩展库 exaudio),接口与旧框架不同。
说明与用法:
- 新框架下播放 TTS 的入口是
audio_v2相关接口(audio_v2.tts等),旧文档/demo 里的tts.xxx写法属于老框架,在新固件上不适用。 - 更推荐直接用扩展库 exaudio:
exaudio.setup时按硬件选对 model,再用它的播放/合成接口,它已封装好音频通路初始化。文档:https://docs.openluat.com/osapi/ext/exaudio/ - 前提是固件里已勾选 audio_v2 / exaudio 库且固件编号带音频能力;烧录时在 Luatools 里确认库已打包,避免运行时报“库不存在”。Air8000 固件列表见 https://docs.openluat.com/air8000/luatos/firmware/ 。
21. Air780EPM模组传文件速度只有10-20K每秒,如何提升传输速度?
解答: 结论:改用 httpplus 扩展库以 HTTP 方式上传文件。它避免了逐包确认/往返等待,实测上行理论可达 5Mbit/s,“200KB/s 很轻松”。
优化建议:
- 换协议:把自定义的“小块 TCP 一问一答”改成 HTTP POST 整体上传(httpplus 支持一次把文件写上去),这是提升幅度最大的一步。
- 加大单次发送块:无论走 socket 还是 HTTP,单包 payload 太小(几百字节)会把时间全花在往返上;适当加大发送缓冲。
- 减少确认:避免应用层自己再实现一层“收到才发下一包”的可靠传输,交给 TCP 和库处理。
- 看信号与频段:弱信号下射频会降速重传,先用
mobile.rsrp()确认信号正常(CSQ 只作参考)。 - 上传前可先在局域网侧用合宙测试服务器验证模组侧吞吐,排除服务器侧带宽/鉴权耗时影响。
参考文档:https://docs.openluat.com/osapi/ext/httpplus/
22. 8201G支持PDM数字麦吗?
解答: 结论:不支持。
说明:Air8201G 的音频输入走的是常规模拟 Mic 通路(配合板载音频 Codec),不提供 PDM 数字麦克风接口;若项目必须用数字麦,需要在选型阶段就确认——合宙带音频的型号(如 Air8000 系列、Air780EHV 等)也是以模拟 Mic/Codec 方案为主,具体以其硬件手册的音频章节为准。选型可参考 https://docs.openluat.com/SelectionGuide/SelectionGuide/ 。
23. 换物联网卡无法使用合宙OTA是什么原因?
解答: 结论:大概率是卡的定向流量/白名单限制——换成新卡后,OTA 域名不在运营商白名单里,模组连不上升级服务器。
处理步骤:
- 确认卡类型:是“公网通用流量”还是“定向流量”。定向流量只能访问套餐白名单内的地址,OTA 必然失败。
- 把 OTA 域名加入白名单:合宙 IoT 平台 OTA 使用的域名是 iot.openluat.com;若用自建升级服务器,则要把你自己的域名/IP 加入白名单。
- 换卡对照验证:用一张确定能上网的通用流量卡测试,能升级成功即可确认是原卡的定向限制,而不是平台或配置问题。
- 同时确认设备已归属在当前账号项目下、升级包版本号符合三段式规则。归属规则见 https://docs.openluat.com/air780epm/product/attributioniot/ ,FOTA 说明见 https://docs.openluat.com/osapi/ext/libfota2/ 。
24. Air780EG有MAC地址吗?
解答: 结论:没有。Air780EG 是 4G(+GNSS)型号,蜂窝侧没有 MAC 地址概念,设备唯一标识用 IMEI。
说明:MAC 属于以太网/WiFi 链路层地址;4G 空口用的是 IMSI/ICCID,设备身份由 IMEI 标识。通过 USB 以 RNDIS/ECM 接电脑时看到的网卡 MAC 是 USB 网卡侧生成的,不代表模组的网络身份,也不适合作为产品唯一标识。读 IMEI 用 mobile.imei(),参考 https://docs.openluat.com/osapi/core/mobile/ 。
25. Air8202是否有扩展串口/GPIO?
解答: 结论:Air8202 本身没有扩展能力,它的定位是免开发整机(接电池就是一个完整的定位器,上电即用);需要较多扩展口请选 Air8203(扩展能力强,但体积较大)。
选型建议:
- 只要定位/追踪、不需要外接丰富外设 → Air8202(整机形态,省硬件设计)。
- 要接多路串口、GPIO、传感器 → Air8203,先按需求估一下引脚数再定。
- 若既想要模组的灵活性又要小体积,可看 Air8201 系列(带 GNSS 的 SoC 模组,需自行做板)。
选型对比见 https://docs.openluat.com/SelectionGuide/SelectionGuide/ ,Air8202 资料见 https://docs.openluat.com/air8202/product/ 。