SnapLog 串口日志云桥 · 规格书
固件 V3.26.0-CLOUD · 后台 iot.snapwhere.app · 2026-10-23
一、基本规格
| 型号 | SnapLog 串口日志云桥（基于 ESP32-C3 SuperMini） |
|---|
| 主控 | ESP32-C3FH4 / FN4，32 位 RISC-V 单核，160 MHz |
|---|
| SRAM | 400 KB（实测可用 heap 约 290 KB） |
|---|
| Flash | 4 MB（芯片内封），双 OTA 分区，无 PSRAM |
|---|
| 供电 | USB 5 V；可用充电头、电脑 USB 口、充电宝 |
|---|
| 存储扩展 | TF（microSD）卡槽 1 个，仅支持 FAT32，建议 32 GB 以内 |
|---|
| 固件升级 | 支持 OTA（远程 / 本地网页） |
|---|
| 掉电记忆 | Wi-Fi、波特率、过滤规则、开关状态、TF 落档模式、编号水位全部存 NVS |
|---|
二、串口规格
| 抓取通道 | 1 路 UART：GPIO20 = 收（RX），GPIO21 = 发（TX） |
|---|
| 电平 | 3.3 V |
|---|
| 波特率 | 300 ~ 3,000,000 bps，默认 115200 |
|---|
| 格式 | 数据位 5–8，校验 N / E / O，停止位 1 / 2，默认 8N1 |
|---|
| 接线方式 | 旁路嗅探，不占用目标设备串口；收发交叉接，GND 必须共地 |
|---|
| USB 桥接 | 原生 USB CDC，免驱，波特率自适应，可与抓取同时进行 |
|---|
| 远程串口 | TCP 端口 3333 |
|---|
| 接收缓冲 | 硬件 UART 接收 FIFO 8 KB |
|---|
三、无线与配网
| 无线标准 | Wi-Fi 4，802.11 b/g/n，仅 2.4 GHz（不支持 5 GHz） |
|---|
| 工作模式 | AP + STA 同时在线：一边连路由器上云，一边保留本地热点 |
|---|
| 配网方式 | 连热点自动弹配置页（强制门户），无需 App |
|---|
| 默认热点 | 名称 SnapLog-XXXX（XXXX = 设备号后 4 位），密码 12345678 |
|---|
| 配置页地址 | http://192.168.4.1 |
|---|
| 本地网页账号 | 默认 admin / admin123（建议首次使用后修改） |
|---|
| 蓝牙 | 硬件支持 BLE 5.0，当前固件未启用 |
|---|
四、云端通信
| 协议 | MQTT over WebSocket Secure（WSS），带 TLS 加密 |
|---|
| 接入地址 | wss://iot.snapwhere.app/mqtt |
|---|
| 投递等级 | QoS 1（至少一次），等待 PUBACK，8 秒超时用同一批重发 |
|---|
| 离线感知 | MQTT 遗嘱消息（LWT），断线即刻标记离线 |
|---|
| 心跳 | 30 秒一次，携带在线状态、信号强度、缓冲水位、过滤配置等 |
|---|
| 批次上限 | 每批 ≤ 40 行或 ≤ 2200 字节，同一时刻仅一批在途 |
|---|
| 行编号 | 逐行 uint32 序号，服务端按（设备号, 序号）去重，可重复发 |
|---|
五、缓冲与可靠性
| 内存缓冲 | ring，开机按可用堆动态分配 8–32 KB；实测本机 8192 B ≈ 100 行 |
|---|
| flash 缓冲 | spill，上限 64 KB（16 × 4 KB）≈ 790 行，默认关闭，掉电保持 |
|---|
| 溢出策略 | 内存满则丢最旧保最新；云端离线时才转写 flash，连上后自动回灌补传 |
|---|
| 回灌节奏 | 每轮最多搬 8 行，且要求内存缓冲留有余量，实时数据始终优先 |
|---|
| 完整性判据 | seq 跳号检测，后台可列出缺行区间、行数与时间 |
|---|
| 降载手段 | 设备侧过滤（级别 / 关键字 / 采样）、一键暂停上行 |
|---|
缓冲按行数计算，能撑多久完全取决于日志速率：满速 boot log（数千行/秒）不足 1 秒，10 行/秒约 90 秒，1 行/秒约 15 分钟。它的定位是覆盖一次断线重连 —— 需要长时间离线留档，请用第六节的 TF 卡。
六、TF 卡离线记录
| 记录模式 | 三档可选：关 / 仅断网时 / 始终写；后台「更多 → TF 卡离线日志」或串口 #SD 0|1|2 切换，掉电保持 |
|---|
| 写入内容 | 经过设备侧过滤之前的完整原始行（云端只为通过过滤的行付流量，卡上留全档），带行首时间戳与级别字符 |
|---|
| 落盘节奏 | 2 KB 缓冲，写满或静默 1.5 秒即刷盘，避免频繁小写缩短卡寿命 |
|---|
| 文件组织 | /snaplog/0001.log 顺序编号；单文件满 4 MB 自动切下一个，最多 48 个（约 190 MB） |
|---|
| 内容导出 | 后台「历史查询 → TF 文件导出」：像打开文件夹一样列出卡上文件、勾选下载（单文件纯文本 / 多文件 zip）。写卡开关关闭也能浏览和导出 —— 关的是「写」，不是「读」；导出结束后卡自动卸回未挂载状态 |
|---|
| 导出限制 | 一次 ≤ 8 个文件、合计 ≤ 16 MB；文件名须 NNNN.log / NNNN.done；同一台设备同时仅一个导出任务；设备必须在线 |
|---|
| 导出速率 | 实测约 2.5~3 KB/s（24 KB ≈ 9 秒、67 KB ≈ 24 秒）；单次取文件超时 90 秒，建议单文件 ≤ 200 KB。更大的档请拔卡读或用串口 #SDGET |
|---|
| 补传 | 已取消。卡上的档不进日志库、不占额度，只在「TF 文件导出」里直接下载 —— 灌回云端要占上行流量与配额，还会挤掉实时日志 |
|---|
| 卡拔出 / 未插 | 不影响抓取与上云；后台与串口报 sd_ok:false 与原因，可热插拔后重试挂载 |
|---|
| 卡与屏的关系 | TF 与 LCD 共用 SPI2 总线，本版固件默认不初始化屏幕，把总线与 60 KB 帧缓冲全部让给写卡 |
|---|
卡必须格式化为 FAT32。exFAT / NTFS 的卡会挂载失败（@SD|MOUNT_FAIL）—— 32 GB 以内的卡在 Windows 下默认格式即 FAT32，64 GB 及以上需用工具转成 FAT32。
七、后台服务规格（默认值，均可调整）
| 每日上行流量 | 100 MB / 账户（名下所有设备合计），单设备上限同为 100 MB |
|---|
| 每月上行流量 | 20 GB / 账户 |
|---|
| 日志保留 | 40 MB 或 7 天，先到者为准（滚动覆盖最旧的） |
|---|
| 存储配额 | 300 MB / 账户 |
|---|
| 显示主题 | 实时页两种看法：日志流（解析展示，按级别着色）/ 嵌入式调试模式（xterm 终端，忠实透传字节）；两者底色一致 |
|---|
| 在线判定 | 30 秒心跳 + MQTT 遗嘱消息（LWT）；拔电 / 断网通常 1~2 秒内标记离线，页面收到状态推送后即时刷新 |
|---|
| 设备数上限 | 20 台 / 账户 |
|---|
| 绑定方式 | 4 位认领码（已剔除 O/0、I/1 等易混字符） |
|---|
| 分享 | 免登录只读链接，可随时收回 |
|---|
八、物理与环境
| 模块尺寸 | 22.52 × 18 mm |
|---|
| 芯片工作温度 | −40 ~ +85 °C |
|---|
| 整机尺寸 / 重量 | 待补（按最终外壳填写） |
|---|
| 整机工作温度 | 待补（按整机实测填写） |
|---|
| 防护等级 | 待补 |
|---|
| 认证 | 待补（CE / FCC / RoHS 等，视出货地区） |
|---|
九、接口与命令
| 本地网页 | 实时日志、发命令、改波特率、Wi-Fi 配置、串口抓包、TF 卡设置、OTA |
|---|
| 串口控制台 | #HELP 查看全部；常用：#STATUS 状态、#UART 波特率、#WIFI 配网、#LOG 上行开关、#FILTER 过滤、#SPILL 落盘、#SD TF 落档、#SDLIST 列卡上文件、#SDGET <nnnn.log> 串口导出、#SDCLEAR YES 清空卡、#LCD 屏幕开关、#REBOOT 重启 |
|---|
| 云端下发 | 波特率、过滤规则、上行开关、落盘开关、TF 落档模式、TF 文件列表 / 取文件、重启；全部经 MQTT 下行 |
|---|