常见问题 - 2026-08-08
数据日期：2026-08-08
1. 对端手机开启飞行模式后，能收到短信，但收不到状态报告，是什么原因？
解答： 这是正常现象：短信"能收到"指短信已成功提交到短信中心（SMS_SENT 的 result=true 仅代表提交成功）；而状态报告（SMS_REPORT）反映的是接收方手机的真实投递结果，对端开启飞行模式/关机期间短信中心只缓存短信，要等对端重新入网后短信中心投递成功才会回送状态报告。 排查与配置要点： 1. 发送时必须请求回执：sms.send(phone, msg, auto_phone_fix, need_report, vp) 的第 4 个参数 need_report 要传 true，否则不会触发 SMS_REPORT 事件； 2. 固件版本要求：SMS_REPORT 事件自 V2048 固件起支持，老版本固件收不到该事件，请升级到 V2048 及以后固件； 3. 对端长时间不开机时，短信中心的缓存时长受短信有效期（vp 参数，V2050 及以后固件支持）和运营商 SMSC 最大有效期约束，超期未送达会返回 status=0x46（消息丢弃）； 4. 收到状态报告后用回调中的 msg_ref 与 SMS_SENT 返回的 msg_ref 做匹配，确认对应关系。 接口文档：https://docs.openluat.com/osapi/core/sms/
2. 设备会自动发起重连，导致Mqtt发送中的数据丢失，如何解决？
解答： MQTT 底层不缓存断线期间的数据：连接断开（"disconnect"事件）后，正在发送或排队中的数据不会自动补发，重连成功（"conack"事件）后需要由应用层重新发送。解决方法： 1. 维护应用层发送队列：业务数据先进队列，收到 mqttc:on 回调中 event=="sent"（消息ID确认）或 QoS1 的 PUBACK 后再出队； 2. 关键数据使用 QoS1 发布（mqttc:publish(topic, data, 1)），QoS1 在收到服务器确认前会持续重试；QoS0 只发一次，断线即丢； 3. 连接状态门控：未收到 "conack" 前不要发布（未连接时 publish 会失败返回 nil），在 "disconnect"/"error" 事件中暂停发送、缓存数据，"conack" 后补发队列； 4. 需要跨重启可靠的数据，应写入文件持久化，开机后重发； 5. 自动重连可用 mqttc:autoreconn(true, 3000) 配置（重连间隔最小 1000ms、默认 3000ms）；注意：使用多网卡（exnetif 多网融合）时不要调用 autoreconn，否则重连可能绑定错误网卡导致无法上网，多网卡场景需自行管理重连。 接口文档：https://docs.openluat.com/osapi/core/mqtt/
3. 设备重启后，之前发的短信一直没有状态报告，是否重启后本地绑定关系丢失导致不推送？
解答： 与"本地绑定关系"无关。短信状态报告的链路是：短信中心在接收方手机成功收件后，按短信协议（TP-Status-Report）向发送方回送投递状态；设备重启不影响短信中心侧的回送，但状态报告是异步事件，重启期间设备未在网或协议栈未就绪时无法接收，运营商对状态报告也没有类似短信正文的长时间重传机制，因此重启前发送、重启后才产生的投递回执大概率收不到。 正确处理方式： 1. 固件升级到 V2048 及以后版本，发送时 sms.send 第 4 个参数 need_report 传 true，并 sys.subscribe("SMS_REPORT", cb) 常驻订阅回执事件； 2. 业务上对"必须确认送达"的短信建立本地状态表（号码、内容、发送时间、msg_ref）持久化到文件，设备重启后对超时未收到 SMS_REPORT 的短信重新发送或走业务通道（如 MQTT/HTTP）补报，不要依赖重启后补收回执； 3. 可配合 vp 参数（V2050 及以后支持）延长短信中心对离线接收方的投递有效期。 接口文档：https://docs.openluat.com/osapi/core/sms/
4. msgref字段需要改成时间戳加序号的生成方式，避免重复，能修改吗？
解答： 不能修改。msg_ref（短信消息参考编号，TP-MR）是由模组协议栈按 3GPP 短信协议生成和维护的底层字段，取值 0-255 循环分配，用于 SMS_SENT 与 SMS_REPORT 事件之间的消息匹配，LuatOS 脚本层没有修改其生成规则的接口，也不建议用该字段做业务唯一键。 建议做法：业务侧自行生成"时间戳+序号"（或 UUID）作为业务流水号，随短信内容或业务通道（MQTT/HTTP 上报）一起传递；msg_ref 仅用于在 SMS_SENT/SMS_REPORT 回调中匹配"哪一次发送对应哪一条回执"。注意文档明确提示：常量/回调字段的取值仅供日志排查，不要写死进业务判断逻辑。 接口文档：https://docs.openluat.com/osapi/core/sms/
5. 空号能否区分开？FAILED_PERM和FAILED_QOS对应哪些具体状态？
解答： 模组侧可以区分空号，需结合两个回调的错误码判断： 1. 提交阶段（SMS_SENT 回调）：rp_cause 为 3GPP RP-Cause 错误码，其中 1、30 表示空号，10、50 表示停机，27 表示用户不在线；error_code 为 SDK 层错误码（0 成功、330 短信中心地址未知、331 无网络服务/SIM 未开通短信、332 网络超时等）； 2. 送达阶段（SMS_REPORT 回调，需 V2048 及以后固件且 need_report=true）：status 为 ST 状态码，0x00 成功送达、0x20 网络拥塞临时失败、0x22 用户关机/不在线、0x23 服务拒绝（大概率停机）、0x43 不可达（空号/停机）、0x46 超过 VP 有效期丢弃。 关于 FAILED_PERM/FAILED_QOS：这两个名称不是 LuatOS 模组侧的事件或常量，属于贵方短信平台/云平台自定义的失败状态枚举，LuatOS 无法对其含义负责；模组侧透传的只有上述 rp_cause 和 ST status 原始码（另有协议原始字段，如 1048 字段为直接透传的原始码）。建议平台侧按原始码映射状态：永久类失败（空号/停机/不可达，如 rp_cause 1/30、ST 0x43/0x23）可归为 FAILED_PERM，临时类失败（拥塞/超时/关机暂不可达，如 ST 0x20/0x22/0x46）可归为 FAILED_QOS，具体枚举定义以贵平台协议文档为准，必要时与短信通道运营商核对。 接口文档：https://docs.openluat.com/osapi/core/sms/
6. 设备压测时，设备端有对发送频率做限制吗？
解答： LuatOS 脚本层和协议栈本身不限制业务调用频率（如 MQTT 的 mqttc:publish、HTTP 请求等接口均无内置节流），但压测时需注意以下实际瓶颈，否则会出现丢消息、发送失败返回 nil 或内存上升： 1. 网络侧限速：空口带宽（Cat.1 上行峰值约 5Mbps）、运营商核心网和服务器接收能力有限，短时间高频发送会造成排队和丢包； 2. 确认机制：MQTT 建议以 "sent" 事件/PUBACK 作为一条消息发完的依据，收到确认后再发下一条；QoS0 无确认，高频连发更容易丢； 3. 自动重连间隔有保护：mqttc:autoreconn 的重连周期最小被强制为 1000ms，避免过频重连； 4. MQTT 客户端对象数量有上限（Air780/Air8000 系列最多 64 个、Air8101 系列 32 个），异常路径务必调用 mqtt.close 释放，避免重连反复创建对象报 "adapter no more ctrl!"。 建议压测时在应用层自行做令牌桶/队列限速（如每秒 N 条、按 sent 事件驱动发送），结果更平稳。接口文档：https://docs.openluat.com/osapi/core/mqtt/
7. 登录AI问答网页失败/报错，提示账户已存在，无法登录，是什么问题？
解答： 该问题属于 AI 问答网站账号系统侧问题，与模组/LuatOS 开发无关。"账户已存在"通常出现在网站账号体系升级（如统一身份认证/单点登录切换）期间，同一手机号或邮箱在旧账号体系与新账号体系中产生冲突。建议按以下顺序处理： 1. 先清除浏览器缓存或使用无痕窗口重新打开页面，再尝试登录； 2. 如页面提供"找回密码/忘记密码"入口，通过原手机号或邮箱重置密码后登录； 3. 仍无法登录时，将报错页面截图、注册手机号/邮箱、操作时间提供给合宙官方技术支持（企业微信群或官网联系方式），由后台协助合并账号； 4. 合宙官方文档与资料可直接访问 https://docs.openluat.com/ ，不受该登录问题影响。
8. Air780E模块支持RTP协议吗？有支持RTP协议的模块吗？
解答： LuatOS 目前不提供独立的 RTP 协议接口。网络语音通话场景通过 exsip（SIP 通话）扩展库实现：SIP 完成呼叫信令，SDP 协商双方 RTP 收发的 IP、端口和编解码参数（当前仅支持 PCMU/PCMA 两种编码），媒体面 RTP 由协议栈内部处理，脚本层不直接操作 RTP 报文。 选型建议： - Air780E 等无数传语音型号不支持通话功能； - 需要 VoLTE/网络电话功能，请选用支持 SIP 通话的型号，如 Air780EHV（产品资料：https://docs.openluat.com/air780ehv/product/ ），以及 Air780EHM/Air780EGH/Air8000 系列等带音频能力的型号； - 纯广播式语音通话目前不支持，SIP 通话需经 SIP 服务器建立。 exsip 接口文档：https://docs.openluat.com/osapi/ext/exsip/
9. Air724UG NFM的VoLTE下行语音可否不走SPK或EAR直接输出I2S？
解答： 不可以。Air724UG 属于 LuatOS-Air（AT/Luat 脚本）体系的老型号，其 VoLTE 通话语音在协议栈内部固定路由到模拟音频通道（SPK 喇叭/EAR 听筒），固件未提供把通话下行语音直接旁路输出到 I2S 数字接口的 API；I2S 在该型号上主要用于多媒体音频播放场景，通话链路与 I2S 通路不互通。 可行的替代方案： 1. 通话下行语音经 SPK/EAR 模拟输出后，若后端需要数字音频，可在板级外加 Codec/ADC 做模拟转数字； 2. 新项目建议改用 LuatOS 主推的带音频能力的 4G 型号（如 Air780EHV/Air780EHM/Air780EGH、Air8000 系列），通话与音频功能在 LuatOS 上持续维护，可配合 AirAUDIO_1020（板载 TM8211，I2S 接口）等音频配件评估数字音频方案； 3. 若需求是通话中播放自定义音频/TTS，LuatOS 新固件提供 cc.extern_source 等接口支持。 选型与配件资料：https://docs.openluat.com/SelectionGuide/SelectionGuide/ 、https://docs.openluat.com/accessory/airaudio_1020/
10. Air724UG有降价计划吗？Air780未来有涨价计划吗？
解答： 合宙产品定价以官方淘宝店实时售价为准，目前没有 Air724UG 降价或 Air780 系列涨价的价格调整通知。 说明：Air724UG 定位为带语音能力的型号，硬件配置和功能集不同，且属于出货量较小的系列，成本与定价相对较高；Air780 系列（如 Air780E/EPM 等）是合宙主力走量的 4G Cat.1 型号，价格长期保持在极具竞争力的水平。新品选型建议优先参考《合宙产品选型指南》并以官方店铺最新标价为准： - 选型指南：https://docs.openluat.com/SelectionGuide/SelectionGuide/ - 官方购买：https://luat.taobao.com/ 如有批量采购需求，可联系合宙官方销售获取批量报价。
11. Air724UG的LuatOS固件什么时候能放到docs文档？现在是只有LuatOS-Air版本吗？
解答： Air724UG 原有成熟版本为 LuatOS-Air（AT/Luat 脚本体系）；LuatOS（SoC 版）固件已推出第一版，型号资料与固件正在整理上架中，后续会随版本发布同步到合宙官方文档站（docs.openluat.com）对应型号目录下。 建议： 1. 目前可先在文档站型号列表中确认是否已上架：https://docs.openluat.com/ ； 2. 急需 LuatOS 版固件或 demo 的用户，可通过合宙官方企业微信群（官网底部二维码扫码加入）联系技术支持获取当前版本和适配进度； 3. 新项目若评估语音+数传等功能，也可直接选用文档资料已完备的主推型号（Air780EHV/Air780EHM/Air8000 系列等），开发资源更完整。
12. Air8000U支持2G/3G吗？
解答： 不支持 2G/3G。Air8000U 是面向欧亚地区的 4G Cat.1 型号，仅支持 4G LTE 网络，频段为：LTE-TDD B38/B40/B41，LTE-FDD B1/B3/B5/B7/B8/B20/B28；上行理论峰值 5Mbps、下行 10Mbps。 选型注意：若项目部署地区存在 2G/3G 退网外的网络环境需求，或当地运营商 4G 覆盖频段不在上述范围内，请先确认目标运营商频段后再选型。型号频段等资料见 https://docs.openluat.com/air8000/product/
13. 设备显示未注册，信号强度为0，但是设备联网正常，是什么原因？
解答： 既然数据联网正常，说明模组实际已在网并完成 PDP 激活，"未注册、信号强度为0"基本是显示/查询侧的问题，而非真正脱网。按以下顺序排查： 1. 确认读取方式：4G 模组的 CSQ 仅供参考，真正的信号强度指标是 RSRP/RSRQ，可用 mobile.csq()、mobile.rsrp()、mobile.rsrq()、mobile.rssi() 等接口交叉确认，用 mobile.status() 获取移动网络注册状态；CSQ 返回 99 或 RSRP 返回 -999 时，文档说明一般是卡状态异常，需联系运营商确认卡状态； 2. 确认查询时机：网络注册、信号上报是异步过程，开机搜网阶段或刚切网时短时间显示未注册/0 属正常，建议在网络就绪事件（如 IP_READY）后再读取，不要在开机瞬间轮询下结论； 3. 确认显示链路：如果信号值是经应用服务器/平台展示，检查平台侧解析的字段和单位是否正确（如 RSRP 与 CSQ 混用），可同时用 AT 指令 AT+CEREG?、AT+CSQ、AT+CGATT? 直接核实模组真实状态（AT+CGATT? 返回 +CGATT: 1 即已附着）； 4. 若 AT 指令也显示未注册但业务又能联网，需抓完整串口日志核对是否为双卡/多网卡环境下读到了非在用卡的状态； 5. 硬件层面，SIM 卡接触、天线匹配、贴片焊接问题通常会表现为真的无法联网，与本现象不符；只有在 AT 指令确认注册状态确实异常时，才进一步排查 SIM 卡座焊接、天线连接和模组焊接。 网络状态接口文档：https://docs.openluat.com/osapi/core/mobile/
14. 8000N使用VSIM卡，途鸽已下发卡但拨号不上，是什么原因？
解答： 途鸽虚拟卡（VSIM）"已下发"只表示卡资源已分配，模组还需先完成搜网、注册、与云卡平台交互并激活配置文件后才能拨号，任一环节异常都会导致拨号失败。按以下顺序排查： 1. 射频与天线（最常见原因）：云卡激活流程对信号质量敏感，需确认 4G 天线已正确连接到天线座、无虚接，天线频段覆盖 Air8000N 北美频段（LTE-FDD B2/B4/B5/B7/B12/B13 等、LTE-TDD B38/B41）；用 mobile.rsrp()/mobile.rsrq() 确认 RSRP 优于 -95dBm，信号差时云卡交互超时会直接失败； 2. SIM 切换：虚拟卡与实体卡需正确切换（参考 mobile.vsimOnOff 等接口说明，注意虚拟卡需要对应固件支持，且通常需要在飞行模式下切换或切换后重启协议栈）； 3. 网络注册状态：用 mobile.status() 或 AT+CEREG?、AT+CGATT? 确认是否已注册、已附着；云卡首次激活必须先能通过引导网络注册到平台； 4. 卡资源与区域：与途鸽确认下发的卡套餐是否覆盖设备所在地区/运营商、是否已生效、是否有机卡绑定限制； 5. 日志定位：抓取完整串口日志（Luatools 全量 trace），重点看云卡 SDK 交互日志、注网失败原因码（rp_cause/error_code）和拨号失败提示，将日志连同设备型号、固件版本、天线照片反馈给合宙技术支持与途鸽对接人联合定位。 网络接口文档：https://docs.openluat.com/osapi/core/mobile/
15. Air8000使用了多网连接，4G也会消耗流量，主要是什么原因？
解答： 多网融合（4G+WiFi+以太网同时在线）时，业务数据走哪张网卡由 socket 绑定的 adapter 和默认网卡优先级决定，4G 链路本身也有保活流量，常见原因有： 1. 业务连接未指定网卡：socket.create/mqtt.create/http.request 的 adapter 参数不填时使用默认网卡；如果默认网卡是 4G，或 WiFi/以太网断开瞬间发生网卡切换，数据就会走 4G。请用 exnetif.set_priority_order 配置优先级，并为关键业务显式绑定目标网卡； 2. 网卡切换机制：开启 auto_socket_switch 后，切换网卡时会断开原网卡所有 socket 并用新网卡重建，切换期间业务可能临时走 4G； 3. 4G 链路保活与系统流量：4G 注网后运营商网关的 PDP 保活、FOTA 检查、errDump 日志上传、NTP 对时、云平台心跳等若未绑定 WiFi/以太网，也会经 4G 产生流量； 4. MQTT/自动重连注意事项：多网卡场景下不要使用 mqttc:autoreconn，否则重连时可能绑定错误网卡（误用 4G）导致无法上网或额外耗流，多网卡重连应由应用层配合 exnetif 自行管理。 排查建议：用 socket.dft() 确认当前默认网卡，逐一检查各 socket/http/mqtt 创建时的 adapter 绑定，并在平台侧统计各链路连接的源 IP 即可定位流量来源。 多网融合文档：https://docs.openluat.com/osapi/ext/exnetif/ ，网络教程：https://docs.openluat.com/luatos_lesson/012_luatos_network/
16. Air8783产品的DCDC有推荐的型号吗？
解答： Air8783 是基于 Air780ER2 设计的 4G Cat.1 USB dongle 成品（USB 供电、免驱 RNDIS 上网），整机供电方案已板载设计，用户使用时无需自行选配 DCDC。 如果是基于 Air780ER2/Air780 系列模组自行设计底板： 1. 合宙官方不强制指定 DCDC 品牌型号，选型原则是满足模组发射峰值电流能力（4G Cat.1 模组 VBAT 需保证瞬态 2A 以上电流能力、低压差）、输出电压在模组推荐供电范围内，并按官方硬件参考设计完成电源走线和去耦； 2. 最稳妥的方式是直接参考合宙官方开发板/成品板原理图与硬件设计手册，或直接选用集成 DCDC 电源、SIM 卡座、天线、看门狗等全套外围电路的 Air878X 工业成品模组（如 Air8782P 板载 DCDC，支持 5-12V 宽压输入），规避自行设计电源带来的风险； 3. 具体型号的硬件设计资料在对应型号文档目录（产品资料：https://docs.openluat.com/air8783/product/ ），选型可参考《合宙产品选型指南》https://docs.openluat.com/SelectionGuide/SelectionGuide/ ，电源设计细节也可咨询合宙官方技术支持确认。
17. build.openluat.com网站打不开，需要云编译启用iconv模块，怎么做？
解答： iconv（字符编码转换，支持 ucs2/ucs2be/GB2312/UTF-8 互转）是 LuatOS 内置核心库，不是需要在云编译中单独勾选的扩展模块： 1. Air8000W 等型号的标准官方固件已内置 iconv，脚本中直接 require/调用即可（官方 demo 见 module/Air8000/demo/iconv/iconv_test.lua），无需云编译定制； 2. 因此无需依赖 build.openluat.com 云编译站点，直接到文档站对应型号的"固件版本"页面下载最新版标准固件烧录即可，例如 Air8000 固件历史版本页：https://docs.openluat.com/air8000/luatos/firmware/ ； 3. 若烧录最新标准固件后调用 iconv 报"库不存在"，请确认固件是否为合宙官方标准固件、型号是否选对，并将固件版本号与报错日志反馈合宙技术支持； 4. 云编译站点若暂时无法访问，可稍后重试或更换网络，固件下载和文档查阅不受影响（https://docs.openluat.com/ ）。 iconv 相关接口说明见 LuatOS 库函数开发手册：https://docs.openluat.com/osapi/