跳转至

常见问题 - 2026-11-14

数据日期:2026-11-14

1. 合宙带4G的板子是否自带流量卡?

解答: 尚未解答

2. 项目用到合宙4G,有推荐的型号吗?

解答: 结论:先按「封装形态 + 是否需要整机 + 是否有音频/定位/网口等附加需求」在选型指南里圈出 2~3 个候选,再让商务按价格与交期确认。 说明:合宙 4G 产品线分两层——一层是 SoC 模组(Air780Exx / Air700Exx 系列,LGA 或邮票孔,需要自己画底板、自己做射频与认证),一层是已经做成整机的工业模组与控制板(Air8780 / Air8781P / Air8300 等,插针或端子直接接线,省掉射频调试与整机认证)。只做数据透传、追求极致成本与尺寸,选 SoC 模组;要快速量产、客户不愿碰射频与认证,选工业模组;还需要语音、定位、双网口、多路 485 时再往上选带对应外设的型号。海外项目必须按目标地区频段选对应区域版本,频段是硬件差异,换固件改不了。 处理步骤:① 打开选型指南「二、选型指南 → 2.1 需要 4G 通信功能」,按表里的功能、开发方式、Flash+RAM、尺寸封装、关键词先筛;② 需要语音看 2.3,需要定位看 2.4,需要 4G+WiFi+蓝牙+定位四合一 看 2.5;③ 海外项目直接跳到「海外需求」一节按频段选;④ 把候选型号连同月用量、目标价、认证要求一起交给合宙商务或对接 FAE,出正式报价与交期;⑤ 拿不到明确结论时先用 ai.luatos.com 问一轮,再人工确认。 参考文档:https://docs.openluat.com/SelectionGuide/SelectionGuide/

3. Air8603测试时RS485测试点击确定/跳过无反应,应用市场安装APP点确定/取消无反应且无法退出界面,USB Host接口插鼠标无光标,是否是操作问题?

解答: 尚未解答

4. Air780系列芯片如何在Mac电脑上烧录程序?

解答: 结论:Luatools 只在 Windows 上发布,Mac 上可以用开源的 luatos-flasher(社区维护的图形化工具,已在 MacBook Pro M2 Pro 与 MacBook Air M4 上跑通全流程)或 luatos-cli 命令行工具完成固件与脚本烧录,不必装 Windows 虚拟机。 说明:LuatOS 的烧录分两步——先把内核固件(.soc)通过 USB 写进模组,再把 lua 脚本打包下载到脚本区,两步依赖的都是 USB 下载协议,与操作系统无关,只要有工具实现了这套协议,Mac 同样能烧。官方 Luatools 是基于 Windows 串口与图形界面的集成工具(量产、差分包制作等功能都只在它里面),仅发布 Windows 10 及以上版本;Mac 侧由社区工具和命令行工具补齐。需要注意 luatos-flasher 是社区作品、不是合宙官方产品,目前只提供 Apple 芯片(M1 及以后)的安装包,Intel Mac 要自行编译;内核引擎用的是 luatos-cli。另一个常见卡点是 USB 转串口:开发板 Type-C 直连时 780/700/8201/8000 全系列免驱,若经板载 CH343/CH347 这类转换芯片,需要先装该芯片的 Mac 驱动。 处理步骤:① 先用 luatos-flasher(https://github.com/Cris20010204/luatos-flasher)图形化烧录,选择 .soc 固件与脚本目录;② 首次打开若被系统拦住,到「系统设置 → 隐私与安全性」点「仍要打开」,或执行 xattr -dr com.apple.quarantine "/Applications/LuatOS 烧录器.app" 去掉隔离属性;③ 需要脚本化或批量时用 luatos-cli(https://gitee.com/openLuat/luatos-cli),命令行指定串口与文件;④ 识别不到设备时先看「系统信息 → USB」里有没有出现模组或转换芯片,没有就补装驱动;⑤ 仍不通换一根数据线、直连本机 USB 口、不要过 HUB;⑥ 量产文件与差分包制作仍只有 Luatools 能做,这部分需要 Windows。 参考文档:https://github.com/Cris20010204/luatos-flasher · https://gitee.com/openLuat/luatos-cli

5. Air8000 I2S接收:时钟正常输出、外部ADC数据已在PIN20上、i2s.recv返回true,但RX回调一次不触发,如何解决?

解答: 尚未解答

6. FOTA3升级固件包失败是什么原因?

解答: 结论:先确认设备当前运行的固件落在升级配置的「基础固件」列表里,并等平台侧升级包状态变成「已完成」,再发起升级;基础固件没配对,差分包生成不出来,设备一升就失败。 说明:libfota3 走的是差分包升级,平台需要「旧版本(基础固件)→ 新版本(目标固件)」两端都明确才能生成差分升级包,设备上报的版本必须命中基础固件列表里的某一项,否则平台没有可用的差分基线,升级请求会被判失败。另外升级配置提交后有一个从「生成中」到「已完成」的过程,生成期间发起升级同样失败,而且平台页面不会自动刷新,需要手动刷。「所有固件」只表示「列表内任一版本都允许触发」,它不能替代「基础固件」这一栏的明确选择。 处理步骤:① 在合宙 IoT 平台的 libfota3 升级配置里核对目标固件是否为要升到的新版本;②「基础固件」不要只依赖「所有固件」,把现场实际在跑的旧版本逐个列进去(支持多选);③ 提交后手动刷新,等「升级包状态」从「生成中」变成「已完成」;④ 设备侧先用旧版本量产文件(.soc)烧一台样机,确认版本号与基础固件一致,再发起检测;⑤ 仍失败就把 on_status 回调里的状态码和完整日志给 FAE,状态码能直接区分是检测、下载、SHA256 校验还是刷写环节。 参考文档:https://docs.openluat.com/osapi/ext/libfota3/

7. 第三方50PIN屏幕能否用于Air8603/Air8607?

解答: 结论:接口对得上的第三方 50PIN RGB565 屏大概率能点亮,但合宙只保证自家配套屏,第三方的排线方向、逐脚定义、显示时序与触摸 FPC 都要自己核对,不能插上就用。 说明:Air8607 / Air8607A 只有一路 50PIN 连接器(RGB565,常见 7 / 9 / 10.1 寸,1024×600 起、最高 1280×800);Air8603 上有 40PIN(P1)和 50PIN(J2)两个连接器,两者共用显示信号,不是双屏独立输出,所以同时插两块屏不可能各显各的。50PIN 只是物理连接器规格,不同厂家的脚序、RGB 位序、DE/HSYNC/VSYNC 极性、背光升压方式、触摸 IC 与 I2C 地址都可能不同,硬件能插上不等于能直接点亮,这也是合宙只对配套屏做保证的原因。 处理步骤:① 拿屏的规格书逐脚比对合宙 50PIN 定义(数据位序、同步信号、背光与使能、地脚);② 确认驱动 IC 是否在 LCD 库已适配列表里,不在就要补初始化序列;③ 核对分辨率与偏移,配置要和屏一致;④ 触摸走 6PIN FPC(I2C1),确认触摸 IC 型号与从机地址;⑤ 点亮后先跑纯色与边框测试,确认无偏移、无色序颠倒,再上业务界面;⑥ 要批量用建议先寄一块样屏给合宙做适配确认。 参考文档:https://docs.openluat.com/air8607/product/ · https://docs.openluat.com/air8603/product/

8. 串口屏有没有内置RTC?

解答: 结论:主控 Air1603 内部有硬件 RTC,但要能断电保时,必须给 VRTC 持续供电;不给 VRTC 供电时,主电源一断时间就退回默认的 2020-01-01 并且不再走。 说明:RTC 要分两层看——一层是 SoC 内部的 RTC 计数器,由 VRTC(PIN36,输入范围 1.8~3.3V)供电维持;一层是板上有没有为 VRTC 配后备电源。Air8603 的原理图上预留了 U19 可充电纽扣电池位专门做 RTC 备份,按实际器件配置使用,注意它是时钟保时用的,不是整机后备电池。软件侧用 rtc.set / rtc.get 读写(两者都是 UTC 时间),联网 NTP 同步成功后就不必再手动 set,直接用 os.date() 取本地时间更方便。 处理步骤:① 先确认手上这块板有没有实际装 U19 纽扣电池;② 没装就临时外接一路 1.8~3.3V 到 VRTC 做验证;③ 用 rtc.set() 设一个已知时间,断电静置十分钟再上电,看时间是否连续;④ 验证时断开网络,避免 NTP 校时掩盖问题;⑤ 需要长期稳定的场景,开机后再做一次 NTP 校时兜底。 参考文档:https://docs.openluat.com/air1603/luatos/hardware/ · https://docs.openluat.com/osapi/core/rtc/

9. Air780EHM上GPIO27/26驱动LED点亮瞬间会误触发GPIO24上的按键,是什么原因?

解答: 结论:优先按硬件干扰排查——LED 支路缺限流电阻、与按键共用回流地、走线过长,都会在点亮瞬间把按键脚耦合出一次假触发;软件侧再把中断改成单边沿加消抖做兜底。 说明:LED 点亮瞬间是一个阶跃电流,几十毫安的跳变会在线路电感和共地阻抗上产生压降;若按键脚上拉偏弱、走线又长,就会耦合出足以被识别为按下的脉冲。GPIO24 属于 AGPIO 组(GPIO24~GPIO28),本身就是可做唤醒与中断的脚,配置成双边沿触发时上升沿和下降沿都会进回调,等于把干扰放大了一倍;而且 gpio 中断默认是没有防抖时间的。 处理步骤:① LED 串限流电阻并按目标电流算阻值,不要让 GPIO 直接硬拉 LED;② 按键脚加 4.7~10k 上拉 + 100nF 对地滤波,LED 回流地与按键地分开走到主地;③ 中断改单边沿触发,并调用 gpio.debounce(pin, 50) 设防抖;④ 软件上再判电平持续时间,短于 20~30ms 的脉冲直接丢弃;⑤ 用示波器双通道同时抓 GPIO24 与 LED 驱动脚,若误触发与 LED 上升沿严格对应,就能确认是硬件耦合而不是按键真的被按了。 参考文档:https://docs.openluat.com/air780epm/luatos/hardware/design/gpio/ · https://docs.openluat.com/osapi/core/gpio/

10. 如何用AI生成美观的LuatOS UI界面?

解答: 结论:走「先让 AI 出 HTML 效果图 → 再让它按这份 HTML 生成 AirUI 工程 → 用 PC 仿真逐屏比对迭代」这条链路,比直接让 AI 写界面代码效果好得多。 说明:AI 对 HTML/CSS 的布局与配色能力,远强于它对 AirUI 控件体系的掌握;所以先让它在浏览器里把视觉做对(也可以用图片方式增强效果),再把这份 HTML 连同 AirUI 接口文档一起交给它,让它逐个控件做映射。之后让它调用 PC 模拟器把工程跑起来、截图、和原 HTML 比对,把差异(间距、字号、颜色、控件尺寸)反馈给它再改,几轮就能收敛。合宙官方有现成教程走的正是这条路,AirMaster 还把文档检索、PC 仿真、烧录、日志读取收进同一个工作台,让 Agent 自己闭环。 处理步骤:① 先让 AI 产出静态 HTML,截图确认视觉;② 把 HTML + AirUI 接口文档一起交给 AI,生成 lua 工程;③ 用 PC 仿真跑起来,截图与原 HTML 逐屏比对;④ 把差异点列给 AI 迭代,直到观感一致;⑤ 再烧到 Air8607 / Air8603 真机,注意真机分辨率与仿真配置要保持一致。 参考文档:https://docs.openluat.com/ai/air8607-ui/ · https://docs.openluat.com/ai/airmaster/

11. AI能否自动完成编译、运行模拟器和烧录?

解答: 结论:可以。让 AI 调 PC 模拟器做界面与逻辑验证,再用 luatos-cli 做命令行烧录;把串口号告诉它,它就能自己烧、自己读日志、自己迭代。 说明:LuatOS 没有传统意义上的编译——脚本是 lua,改完直接下载即可,所谓「编译」只是把脚本打包成下载镜像。真正的门槛在两处:一是要有可被程序调用的烧录入口(Luatools 是图形界面,不适合 AI 调用,luatos-cli 才是命令行的),二是要把设备日志读回来给 AI 判断。AirMaster 提供了 MCP 接口,把文档检索、PC 仿真、烧录与日志读取都暴露成工具,Claude / Cursor / Trae 这类客户端接上就能形成完整闭环。 处理步骤:① 装 luatos-cli(https://gitee.com/openLuat/luatos-cli),先在命令行手动烧一次,确认串口号与参数;② 硬件接好,记下串口名(Windows 是 COMx,Mac 是 /dev/tty.usbserial-*);③ 把串口号、固件号、脚本目录告诉 AI;④ 让它执行「烧录 → 采启动日志 → 判断结果 → 改码 → 再烧」的循环;⑤ 量产与差分包制作仍回到 Luatools。 参考文档:https://docs.openluat.com/ai/airmaster/ · https://docs.openluat.com/ai/mcp_cli/

12. Air780EPM的这几个引脚是否可以使用?

解答: 结论:某个引脚能不能用,要以「GPIO 复用表 + 该完整型号的管脚说明」两份资料对齐后为准,同一脚号在不同 Air780Exx 型号上功能不同,不能照搬别的型号的结论。 说明:Air780EPM 的物理管脚大量复用——同一个 PIN 在不同配置下可能是 UART、PWM、I2C 或普通 GPIO,另有一部分是固定功能脚(VBAT、GND、USB、SIM、RF 等)不能当 IO 使用。判断时要两份东西一起看:一份是 Air780Exx 系列管脚说明(含多款型号的管脚对比),一份是随硬件资料发布的 GPIO 复用表 xlsx。还要注意有些对比表整段被 HTML 注释包住、线上不渲染,grep 得到但页面看不见,所以「文档上没写」不等于没有,最终以 xlsx 与 Luatools 管脚配置界面为准。 处理步骤:① 先按完整型号(EPM / EHM / EHV / EGH / EGG / EGP / EHN / EHU)在管脚说明页定位;② 打开 GPIO 复用表 xlsx 查该 PIN 的可选功能与默认电平;③ 用 Luatools 的管脚配置界面再核一遍,那里反映的是当前固件实际支持的复用;④ 拿不准就把型号 + 管脚截图发群里或问 ai.luatos.com;⑤ 定稿前用万用表实测该脚默认电平,避免与外部电路打架。 参考文档:https://docs.openluat.com/air780epm/luatos/hardware/design/air780exxpins/ · https://docs.openluat.com/air780epm/luatos/hardware/design/gpio/

13. 蓝牙+屏+外放声音的是哪块板?

解答: 尚未解答

14. 如何购买8201开发板?

解答: 结论:8201 的开发套件按子型号区分(BLMQ / BQ / LM / 基础版),BLMQ 是全功能高配版,可从 Air8201G 硬件资料页给出的购买链接下单。 说明:Air8201G 的几个子型号差别主要在外设与天线配置上:BLMQ 功能最全(BLE 蓝牙 + 音频 + G-sensor + 气压传感器),BQ / LM / 基础版按需裁剪,天线配置也随之不同。所以买之前要先确认自己到底要验证什么能力——要蓝牙配网、语音播报、外接传感器就选 BLMQ;只要 4G + 定位,基础版就够,成本也更低。另外套件通常不含 SIM 卡,天线是否随附要看具体型号的装箱清单。 处理步骤:① 在 Air8201G 硬件资料页核对子型号与功能差异;② 通过页面上的购买链接(或合宙淘宝店)下单对应型号;③ 收货后核对丝印与包装上的完整型号,避免与 BQ / LM 混料;④ 按出厂固件说明装 SIM 卡、接 4G 与 GNSS 天线,靠近窗边或室外做首次定位;⑤ 批量采购、开票与定制需求找商务对接。 参考文档:https://docs.openluat.com/air8201/hardware/8201G/

15. 红外对射板有五组红外对射但只配置了四个GPIO、仅两组接口,只有两组能检测到,是设计如此吗?

解答: 结论:这是这块板的设计取舍,不是坏了——五组对射并不是各占一个 GPIO,而是分组复用,横向布置时同一时刻一般只有一组被遮挡,所以两组接口、四个 GPIO 就够覆盖。 说明:对射式传感器每一组本质上就是一个开关量输出(遮挡 / 未遮挡两个电平),要同时读五组就得五个独立输入脚。板上只引出四个 GPIO、两组接口,说明做的是「分组并联 + 分时判断」:多组对射的信号并在同一条线上,靠安装方向保证同一时刻只有一组会触发,因此软件读到的是「哪一组被挡」,而不是「五组各自的状态」。这种设计适合做「有人通过」的判定,不适合做「五组独立检测」。 处理步骤:① 逐组单独遮挡,记录每组触发时是哪个 GPIO 变化,画出实际的对应关系;② 同时遮挡两组,确认是否只读到一个电平变化,用来验证并联假设;③ 业务逻辑按「一次只判一组」来设计,不要按五路独立开关写;④ 确实需要五路独立检测,就得换板或改线,把每组单独引到一个 GPIO。 参考文档:无(该配件板暂无独立文档页,实际接法请以随板资料或对接 FAE 确认为准)。

16. 红外对射板检测异常是接线还是板子问题?

解答: 结论:先按「板子本身」的方向查——把同一块对射板换到另一套确认正常的线束与主板上仍然异常,基本就能判定是对射板的问题,而不是接线。 说明:区分接线问题与板子问题,最有效的手段是换件对照:同一块对射板换到另一套确认正常的线束 / 主板,或把一套确认正常的对射板换到这块板的位置。前者仍异常、后者正常,就是板子的问题。对射板常见的板级故障有三类:发射端供电不足或红外管老化(限流电阻虚焊会导致亮度不够)、接收端比较器阈值漂移(环境光或温度变化就误判)、光轴没对准导致长期处于遮挡态。 处理步骤:① 用万用表量发射端与接收端的供电,确认在规格范围内;② 用手机摄像头对着发射管看有没有红外光(人眼看不见、摄像头能看到);③ 遮住光路看接收端输出电平是否翻转,不翻转就是接收侧的问题;④ 换一块对射板交叉验证,锁定是板还是线;⑤ 确认是板子问题后按售后流程处理,附上型号、批次与实测现象。 参考文档:无(属硬件排查与售后事项,请通过购买渠道或对接 FAE 处理)。

17. 新发货的SIM卡不兼容,旧卡无需设置即可正常使用,如何处理?

解答: 结论:这批卡换了制卡商(前批楚天龙、后批握奇),卡侧参数与旧批不同,导致部分设备识别异常;先在老批次和新批次之间做同机对照,再把异常卡寄给合宙复现,同时找运营商核对开卡参数。 说明:SIM 卡并不是完全同质化的器件,不同制卡商在 ATR、时钟频率容限、供电电压档位、文件系统结构以及是否预置某些应用上存在差异。模组的 SIM 检测与初始化流程对时序敏感,换批卡后出现「有的设备认、有的不认」或「旧卡正常新卡异常」,多半是卡侧差异落在模组容限的边缘,而不是模组本身损坏。这类问题靠单台设备单张卡无法定性,必须做批次对照。 处理步骤:① 在同一台设备、同一版固件下,分别插旧批(楚天龙)与新批(握奇)卡各测 5 次,记录能否识别、能否注册上网络;② 换 2~3 台不同设备重复,确认是批次性问题还是个体问题;③ 对比两批卡的模组日志(AT+CPIN?、AT+CSQ、SIM 电压档位),找出差异点;④ 把异常卡寄给合宙复现,同时联系运营商核对开卡参数(是否定向卡、是否限速、是否绑定 IMEI);⑤ 结论出来前不要批量改硬件,先按能用的那批卡安排生产。 参考文档:https://docs.openluat.com/air780epm/luatos/hardware/design/sim/

搜索