Air8301 整机使用说明

作者：王城钧　|　最后修改：2026-10-22

一、默认出厂固件

本板有默认的出厂固件，包含每个功能对应的脚本；插上 USB 线供电即可运行，不需要自己烧录。

固件打包下载地址：固件下载；
内核：Air8000 114 号固件（2052-114），理论 2026.10.9 之后的 114 号固件都支持；
平台：主控 Air8000W，出厂固件工程名（PROJECT）Air8301_Factory，版本（VERSION）001.999.000。

1、最新版本固件

固件：Air8301_Factory_001.999.001_LuatOS-SoC_V2052_Air8000W_114.soc

固件更新说明（2026-10-10）

更新第一版出厂固件。

2、历史版本固件

固件：Air8301_Factory_001.999.001_LuatOS-SoC_V2052_Air8000W_114.soc

固件更新说明（2026-10-10）

更新第一版出厂固件。

二、源码链接

出厂固件源码（LuatOS 仓库）：

注意：烧录此工程时需要将readme文件删除，否则会报超出脚本区大小错误

https://gitee.com/openLuat/LuatOS/tree/master/module/Air8301/project/factory

配套工程：

硬件测试工程（逐项验证板载外设）：module/Air8301/project/hardware_test
业务示例工程：module/Air8301/project/electric_device

更多软件资料见软件开发资料-总体说明。

三、图文使用说明

1、界面框架

屏幕 UI（AirUI + exwin）统一采用「顶部状态条 + 中部内容区 + 底部 Dock 分区导航」框架，共四个主分区：主页、通信、IO、系统；分区页内点击磁贴进入功能详情页，详情页左上角「<」返回上级分区页。

顶部状态条：左侧固定显示产品名「合宙工业网关Air8301」，右侧显示当前时间；
中部内容区：主页为时间 / 天气仪表盘，通信、IO、系统分区为磁贴矩阵（图标 + 名称 + 实时状态摘要）；
底部 Dock：主页 / 通信 / IO / 系统四个分区入口，当前分区高亮，点击即可切换；
开机时先显示 LOGO 开机画面，初始化完成后自动进入主页。

开机界面

开机动画

主页：当前时间、天气、联网方式、4G 信号、本机 IP

通信分区：网络状态、WiFi、RS485-1、Modbus、多网融合

通信分区

IO 分区：DI 输入、DO 输出（GPIO24 / GPIO25）、继电器、蜂鸣器、状态灯

IO分区

系统分区：外部看门狗、Flash 挂载、系统信息、FOTA 远程升级、RELOAD 恢复出厂

系统分区

2、上手流程

按电路和使用说明的「屏幕怎么装」装好屏幕；
插入 DC 电源或 USB Type-C 供电（两种可同时接，板载自动切换），上电即运行，屏幕自动点亮；
用 USB Type-C 连接电脑，用 Luatools 看日志，详见下载和调试；
根据module/Air8301/project/factory · 合宙Luat/LuatOS - 码云 - 开源中国搭建好硬件环境
逐项验证外设（网口看 LINK/ACT、串口用回环或对端设备、DI/DO 用万用表量通断）。

3、分页说明

按底部 Dock 的四个分区逐页说明，图片均为出厂固件实际界面。

3.1 主页（时间与天气仪表盘）

主页中部为两张卡片：左侧当前时间（大号时钟 + 秒 + 日期 + 星期），右侧天气（城市 / 当前温度 / 天气现象 / 湿度与风 / 今日高低温）；底部依次显示联网方式（多网融合当前生效链路）、4G 信号等级、本机 IP。

天气数据来自 Open-Meteo（免费、无需 Key），断网时天气区显示「--」，取到数据后自动刷新；默认城市为深圳，点击天气卡上的城市名可进入「城市设置」页（见 3.5）切换城市。

3.2 通信分区

通信分区页共 5 个磁贴：网络状态 / WiFi / RS485-1 / Modbus / 多网融合，磁贴右侧指示灯表示通断（绿色正常、红色异常），点击进入对应详情页。

网络状态：显示 4G 信号等级、WiFi 连接状态、以太网 1 / 以太网 2 连接状态与 IP 地址。

网络状态

WiFi：进入后扫描周边 WiFi 并列出信号强度，可像手机一样点击 WiFi 名输入密码连接；也支持「手动输入」名称与密码添加网络，列表分页显示（如「1/5」），已保存的网络标注「已保存」。

WiFi 扫描

WiFi 连接

手动输入

RS485-1：对应板载 485 串口板（UART1），页面为串口终端，可查看收发数据，并在下方输入框输入数据后点击「发送」。

RS485-1

Modbus：以卡片形式监视 Modbus 寄存器数据，包括 0x0000-04 继电器状态、0x0020 网口 TCP 温湿度、0x0005-06 CPU 温度、0x0007-08 VBAT 电压、0x001D 4G 信号强度、0x0038-39 时间戳。

Modbus

多网融合：可配置网卡优先级（默认 wifi > eth1 > eth2 > 4g），并显示当前生效链路与各网卡状态。

多网融合

3.3 IO 分区

IO 分区页共 5 个磁贴：DI 输入 / DO 输出 / 继电器 / 蜂鸣器 / 状态灯，磁贴摘要显示实时状态（如「DI1 ON | DI2 OFF」「2/4 接通」）。

DI 输入：采集 DI1 / DI2 的开关通断、高低电平，并记录历史变化。

DI 输入

DO 输出：控制板载 DO 输出（GPIO24 / GPIO25）。

DO 输出

继电器：控制外接的 4 路继电器模块通断（RS485_2 非隔离口作 Modbus RTU 主站，9600 8N1）。

继电器

蜂鸣器：测试板载蜂鸣器（PWM2 / PIN98）。

蜂鸣器

状态灯：控制板载状态灯（LED）亮灭。

状态灯

3.4 系统分区

系统分区页共 5 个磁贴：看门狗 / Flash / 系统信息 / 远程升级 / RELOAD。

看门狗：显示外部看门狗（Air153D）的启用 / 停用状态、上次喂狗时间与超时时间（默认 240 秒），可手动喂狗、开启或关闭看门狗。

看门狗

Flash 存储：显示 SPI Flash 的挂载状态、芯片容量与文件系统占用大小。

Flash 存储

系统信息：显示固件版本、累计运行时长、内存占用、文件系统可用空间，可一键恢复出厂设置（进入产测模式）。

系统信息

远程升级：显示当前脚本版本与升级状态，可主动请求检测升级，并查看升级记录（libfota3）。

远程升级

RELOAD：显示板载 RELOAD 按键的按下 / 抬起状态与按住时长，下方进度条同步长按 5 秒恢复出厂的进度。

RELOAD

3.5 城市设置

主页天气卡上的城市名点击进入本页，内置城市列表选择，选中后立即保存并刷新天气，无需等待基站定位。

4、内置网页

内置网页有两种连接方式：一种是用网线连接电脑网口与 8301 网口1，按日志中的 IP 地址访问；另一种是 PC 连接 8301 的 WiFi 热点后，按日志中的 IP 地址访问。

网口1（静态 IP）：http://192.168.1.183
WiFi 热点：http://192.168.4.1（SSID Air8301 / 密码 12345678）

开机日志中会打印两个访问地址，如下（httpsrv 行）：

内置网页访问地址

网页顶部有 6 个页签：概览 / 继电器 / 网络 / 通讯 / 升级 / 配置，下面逐个说明。

4.1 概览

分「设备信息」和「运行数据」两块：

设备信息：项目（Air8301_Factory）、脚本版本、内核固件（LuatOS-SoC_V2052_Air8000）、设备名称、IMEI、ICCID、系统时间、网页版本；
运行数据：环境温度、环境湿度、CPU 温度、VBAT 电压、4G 信号（dBm）、LBS 定位（经纬度）。

网页-概览

4.2 继电器

对应 485 继电器模块（UART11 主站 / 非隔离口），4 个通道开关：

通道 0~3 依次对应从站寄存器 0x0001~0x0004（写 1 = 接通 / 写 0 = 断开）；
按钮：全部接通 / 全部断开 / 回读状态；
下方「主站通讯日志」实时打印 Modbus RTU 主站的读写过程。

网页-继电器

4.3 网络

网络状态：网口1（内含网页）、网口2（Modbus TCP）的 IP 与通断，WiFi 的 SSID 与信号强度，4G 在线状态与运营商；
WiFi 配置：填 SSID（密码留空表示不修改）后点「保存并重启」，或点「扫描WiFi」搜索周边热点。

网页-网络

4.4 通讯

从站与主站配置：RS485 主站（继电器）UART11 / GPIO153 / 9600 / 从站1、RS485 从站（串口板）UART1 / GPIO2 / 115200 / 从站1、Modbus TCP 从站 192.168.1.185:502；
寄存器映射表：列出地址 / 数量 / 数据项 / 当前值，如 0x0000 继电器状态位编码、0x0001-04 继电器各路开关、0x0005-06 CPU 温度、0x0007-08 VBAT 电压、0x0009-12 LBS 纬度、0x0013-1C LBS 经度、0x001D 4G 信号强度、0x001E-29 设备 IMEI、0x002A-37 SIM ICCID、0x0038-39 时间戳、0x003A-3D 温湿度传感器、0x0050 继电器控制字（可写）；
下方「从站请求日志」「TCP 请求日志」按行打印收到的 Modbus RTU / TCP 请求与应答报文。

网页-通讯

4.5 升级

远程升级（FOTA）：显示当前状态、目标版本、升级进度条，可点「立即检测更新」；
升级历史：每条记录包含时间与结果，例如「发现新版本 001.999.001（185KB）成功」。

网页-升级

4.6 配置

可修改设备名称、NTP 服务器（默认 ntp.aliyun.com）、时区（默认 UTC+8）；
底部按钮为 保存配置 / 恢复默认。

网页-配置

4.7 网页 API 接口

网页是「HTTP + JSON」接口，除浏览器页面外，也可以直接用 curl / Postman 请求（IP 换成实际的 192.168.1.183 或 192.168.4.1）：

方法	路径	说明
GET	`/api/status`	传感器 + 设备 + 网络 + 通讯全部状态
GET	`/api/sensor`	继电器状态 + 温湿度 + 系统数据
GET	`/api/temp`	网口 TCP 温湿度
GET	`/api/network`	网络状态（WiFi / 以太网1 / 以太网2 / 4G）
GET	`/api/comm/status`	通讯状态：主从站配置 + 寄存器表 + 通讯日志
GET	`/api/relay/status`	继电器状态（数组，元素依次对应通道 0、1…）
POST	`/api/relay/control`	继电器控制，body 如 `{"action":"open","channel":0}`
GET / POST	`/api/config`	读取 / 保存配置（设备名、NTP、时区、WiFi 等）
POST / GET	`/api/wifi/scan`	触发扫描 / 取扫描结果
GET / POST	`/api/priority`	读 / 写多网融合网卡优先级
POST	`/api/reset`	恢复默认配置
GET	`/api/fota/status`	FOTA 状态
POST	`/api/fota/check`	触发检测更新
GET / POST	`/api/fota/config`	读 / 写 FOTA 自动升级配置（`auto` / `interval`）
GET	`/api/log?msg=xxx`	把前端操作日志写进设备日志

/api/relay/control 的 action 可取 open、close、toggle、all_open、all_close、read；open/close/toggle 需带 channel（0~3）。接口只回「已受理」（{"code":0,"msg":"accepted",...}），开关实际状态由前端轮询 /api/relay/status 获取。

# 读全部状态
curl http://192.168.1.183/api/status

# 接通继电器通道0
curl -X POST http://192.168.1.183/api/relay/control \
     -H "Content-Type: application/json" \
     -d '{"action":"open","channel":0}'

# 回读继电器状态
curl http://192.168.1.183/api/relay/status

# 读温湿度
curl http://192.168.1.183/api/temp

5、上云与运维

出厂固件默认接入合宙 AirCloud，把设备运行数据上报云端，并接收云端下发的命令（如继电器控制）；定位支持 airlbs 基站 / WiFi 定位。

5.1 上报记录

在 AirCloud 平台的「AirCloud上报记录」页，可按设备号筛选、按 Tag 查询，逐条查看上行（设备→云）与下行（云→设备）消息：消息序号、入库时间、类型、Tag、消息名称、数据类型、长度、消息内容及原始 HEX，右侧可下载。

常见上报项：4G 信号强度、ICCID、温度、湿度、CPU 环境温度、实际电压、GNSS 经纬度、时间、控制响应等；下行项如 RTU 下行命令。

AirCloud 上报记录

5.2 设备管理平台

在设备管理平台（web网页）的「运营总览」可查看设备总数 / 在线 / 告警 / 离线 / 失联、设备分布地图与设备状态；点进单个设备后，页签包含概览 / 历史数据 / 趋势 / 轨迹 / 控制，右侧显示最后上报时间、固件版本、实时数据（温度、湿度、CPU、VOC、信号）与设备位置。

设备管理平台-运营总览

5.3 手机端查看

手机端「合宙IOT」（微信小程序）同样有概览 / 历史数据 / 控制三个页签：概览页显示最近上报数据（温度、湿度、CPU 环境温度、4G 信号、GNSS 经纬度、电压）与设备位置地图，点「刷新数据」即可拉取最新值。

手机端-合宙IOT

5.4 云端下行命令与应答

平台下行的业务内容通过 CONTROL_COMMAND(19)（或 IRTU_DOWN(21) 透传）下发，内容是 JSON，用 type 区分命令字：

type	附加字段	说明	应答中的字段
`relay_open`	`channel`（0~3）	接通指定通道	`result` / `relay` / `channel`
`relay_close`	`channel`	断开指定通道	`result` / `relay` / `channel`
`relay_toggle`	`channel`	翻转指定通道	`result` / `relay` / `channel`
`relay_all_open`	—	全部接通	`result` / `relay`
`relay_all_close`	—	全部断开	`result` / `relay`
`relay_read`	—	回读 4 路状态	`relay`
`read_temp`	—	回读温湿度传感器温度	`temperature`
`read_humi`	—	回读温湿度传感器湿度	`humidity`
`read_vbat`	—	回读 VBAT 电压	`vbat`
`read_cpu`	—	回读 CPU 温度	`cpu_temp`
`read_csq`	—	回读 4G 信号	`csq`
`read_iccid`	—	回读 SIM ICCID	`iccid`
`read_time`	—	回读设备时间戳	`timestamp`

下发示例与设备应答：

// 下发：接通继电器通道0
{"type":"relay_open","channel":0}
// 应答
{"cmd":"relay_open","channel":0,"result":"success","relay":[1,0,0,0]}

// 下发：回读温度
{"type":"read_temp"}
// 应答
{"cmd":"read_temp","temperature":26.7}

上报字段编号（AirCloud 数据点）：4G 信号强度 782、SIM ICCID 783、温度 256、湿度 257、CPU 温度 263、VBAT 电压 799、GNSS 经度 512、GNSS 纬度 513、继电器状态 268（ASCII，英文逗号分隔，1=吸合）。

6、Modbus 请求指令

设备既是 Modbus 从站（供电脑 / 网关访问），也是 Modbus RTU 主站（控制外接 485 继电器模块）。

6.1 从站访问参数

通道	参数
RS485_1（隔离口，接电脑串口板）	UART1，115200 8N1，RE/DE = GPIO2（供电 GPIO29），从站地址 1
网口2 Modbus TCP	`192.168.1.185:502`，单元号（从站地址）1

两者共用同一份寄存器表（rtu_slave_regmap.lua）与同一套功能码。

6.2 支持的功能码

功能码	名称	说明
`0x03`	读保持寄存器	读 0x0000~0x0050 任意连续区间
`0x04`	读输入寄存器	与 `0x03` 同样处理
`0x06`	写单个保持寄存器	可写 0x0001~0x0004（每路继电器开关）、0x0050（控制字）
`0x10`	写多个保持寄存器	支持一次写入 0x0001~0x0004

其它功能码返回异常码 0x01（非法功能）。

6.3 寄存器表

地址	类型	数据项	寄存器数	来源
0x0000	INT16	继电器状态位掩码（bit0 = 通道0）	1	485 继电器模块
0x0001~0x0004	INT16	继电器通道 0~3 开关	4	读 = 实际状态（0 断开 / 1 接通），写 = 开关
0x0005~0x0006	FLOAT	CPU 温度	2	模块内部
0x0007~0x0008	FLOAT	VBAT 电压	2	模块内部
0x0009~0x0012	STRING	LBS 纬度	10	定位模块
0x0013~0x001C	STRING	LBS 经度	10	定位模块
0x001D	INT16	4G 信号强度	1	移动网络
0x001E~0x0029	STRING	设备 IMEI	12	移动网络
0x002A~0x0037	STRING	SIM ICCID	14	移动网络
0x0038~0x0039	INT32	时间戳	2	NTP 同步
0x003A~0x003B	FLOAT	温湿度传感器-温度	2	网口 TCP 主站读取
0x003C~0x003D	FLOAT	温湿度传感器-湿度	2	网口 TCP 主站读取
0x0050	INT16	继电器控制字（可写）	1	见下表

控制字 0x0050 的取值：

值	含义
`0x0000`	全部断开
`0xFFFF`	全部接通
`0x0001~0x0004`	开通道 N（N = 1~4）
`0x0101~0x0104`	关通道 N
`0x0201~0x0204`	翻转通道 N

（高字节为动作：0x00 开 / 0x01 关 / 0x02 翻转；低字节为通道号 1~4。）

6.4 读指令

下表为请求帧体（不含 CRC），从站地址固定为 01：

用途	请求帧体	说明
读继电器掩码 + 4 路状态	`01 03 00 00 00 05`	0x0000~0x0004
读 CPU 温度 + VBAT 电压	`01 03 00 05 00 04`	两个 FLOAT
读 4G 信号强度	`01 03 00 1D 00 01`
读时间戳	`01 03 00 38 00 02`	低字在前
读温湿度	`01 03 00 3A 00 04`	温度 2 个 + 湿度 2 个寄存器
读完整系统数据区	`01 03 00 05 00 39`	0x0005~0x003D，共 57 个寄存器

实际发送时需在帧体后补 2 字节 CRC16-Modbus（低字节在前），串口工具按 115200 8N1（无校验）发即可；TCP 工具则用「MBAP 头 + 上面的帧体 + CRC 可省」。设备侧「从站请求日志」会逐条打印收到的请求与应答，形如：

[RTU] 请求:01 03 00 38 00 02  应答:01 03 04 70 7E 68 CD
[TCP] 请求:01 03 00 00 00 05  应答:...

6.5 写指令（继电器控制）

用途	请求帧体
通道0 接通	`01 06 00 01 00 01`
通道0 断开	`01 06 00 01 00 00`
一次写 4 路（通、断、通、断）	`01 10 00 01 00 04 08 00 01 00 00 00 01 00 00`
全部接通（控制字）	`01 06 00 50 FF FF`
全部断开（控制字）	`01 06 00 50 00 00`
开第 1 路（控制字）	`01 06 00 50 00 01`
关第 1 路（控制字）	`01 06 00 50 01 01`
翻转第 1 路（控制字）	`01 06 00 50 02 01`

说明：

继电器动作是「指令投递」，从站先正常应答，实际动作在随后几十毫秒完成；需要确认时再读 0x0000 或 0x0001~0x0004；
用 0x10 一次写多路时，数据域为 字节数 + 各寄存器值（每路 2 字节，1 = 接通 / 0 = 断开），上面例子是「通道0 通、通道1 断、通道2 通、通道3 断」。

6.6 Modbus TCP 报文

TCP 帧 = 7 字节 MBAP 头 + 上面的帧体（Modbus TCP 不含 CRC）：

00 01 00 00 00 06 01 03 00 00 00 05
↑事务号  ↑协议号  ↑长度  ↑单元号 ↑功能码 ↑起始地址 ↑数量

事务号（前 2 字节）可自增，主要用于匹配请求与应答；
长度 = 后续字节数（单元号 + PDU），上面为 6；
单元号即从站地址 01。

6.7 数据格式

FLOAT：IEEE-754 单精度，小端（低字在前）——0x0005 为低 16 位、0x0006 为高 16 位；
STRING：每个寄存器存 2 字节，高字节在前，例如 "116" → 0x3131、0x3600，剩余寄存器补 0；
INT32：低字在前，例 0x0038 为低 16 位、0x0039 为高 16 位。

6.8 设备作为主站的指令（RS485_2 → 外接 4 路继电器模块）

设备通过 RS485_2（非隔离口，UART11，RE/DE = GPIO153，9600 8N1）作 Modbus RTU 主站，使用的指令：

功能码	用途	说明
`0x01`	读线圈	读继电器模块各路状态
`0x05`	写单个线圈	数据域 `0xFF00` = 接通、`0x0000` = 断开、`0x5500` = 翻转（翻转不重试，避免重复翻转）
`0x0F`	写多个线圈	全部接通 / 全部断开

四、出厂固件视频教程

整机使用教程（烧录调试、固件功能 + Web 前端 + 小程序综合演示）：

Air8301工业模组开箱实测_哔哩哔哩_bilibili