ekko/LPT26x-HSF-4MB-Hilink_14.2.0.308_20250411

Files

ekko.bao 53ba39e35d 优化开关与渐变的无缝衔接，消除‘先黑一下再变亮’突变

问题：关灯渐变进行中途点击开灯，会出现先熄灭再从0渐变的突变。

方案（A+B+C）：
A. ‘开灯’打断‘关灯渐变’时，沿用当前渐变中的即时亮度作为起点，反向渐变到目标（不再强制从0起步）。
B. 渐变任务收尾保护：关灯渐变完成前若已被开灯抢占，跳过PWM关断收尾，避免黑场。
C. 取消逻辑加固：取消当前渐变时清除 is_fading/is_closing_fade/fade_completed，避免旧渐变回调误关灯。

实现点：
- set_light：记录 was_closing_fade 与当前即时亮度；开灯时根据 was_closing_fade 决定起点（即时亮度或0）。
- fade_task：在关灯完成分支检查 g_device_control.on，已被开灯抢占则不关断，交由开灯渐变接管。
- cancel_current_light_fade：补充状态清理，防止回调残留。

验证：亮→关（渐变中）→开、末尾抢占、快速连点关/开、单色↔双色切换夹杂开关，均无‘黑一下’突变。

2025-11-17 07:27:44 +08:00

16 KiB

Raw Blame History

调试模式（Wi‑Fi Console + HTTP OTA）需求与设计说明

文档版本：v1.1
更新时间：2025-10-26
适用机型/平台：WS63（LiteOS/Harmony 适配），本仓库版本 SR_Light_Hilink_14.2.1.312_20250714
文档目的：沉淀“仅 Wi‑Fi、按需开启”的远程 Debug 能力（TCP Console + HTTP OTA），在不影响现网业务下，实现快速问题定位与在线升级。本文给出明确的需求、行为规格、接口契约、资源预算、测试与风控。

1. 背景与目标

设备组装后无物理串口；现场需要远程获取日志与执行命令，并可在线推送固件进行升级。现有工程具备 SOC_LOG、DIAG、UPG 能力，本文在不改动业务使用打印宏与模块的前提下，定义一套“仅 Wi‑Fi、调试模式下启用”的远程调试与 OTA 方案。

目标：

纯 Wi‑Fi：仅用 TCP Console 与 HTTP OTA，不使用 BLE/USB/AP/mDNS。
调试模式准入：仅当扫描到 SSID=EK_HF_DEBUG 时进入；平时不暴露任何端口与广播。
类串口体验：双向交互（收发），支持历史日志回溯与实时回显。
OTA 直装：写入并校验通过后立即安装（可重启）。
低侵入：常态仅维护内存日志环形缓冲；调试行为可在高负载期延后；禁止 AP 模式。

不做：

不开启 UDP syslog；不做 mDNS/DNS‑SD；不引入 HTTPS/TLS 与口令认证。

2. 术语与缩写

Debug 模式：本文所述仅在现场触发后短时开放的“调试窗口”。
TCP Console：类串口的 TCP 字节流服务。
HTTP OTA：通过 HTTP 推送固件包分片并安装。
Ring Buffer：内存日志环形缓冲，常态写入，调试时可读取。

3. 需求清单（用户决策映射）

仅启用 TCP Console 与 HTTP OTA；UDP 日志不启用，且所有 Debug 功能只在 Debug 模式开启时可用。
常态始终维护日志 Ring Buffer（仅内存，不外发），用于 Debug 时回溯。
不做服务发现（mDNS/DNS‑SD）。
唯一入口＝扫描到 SSID EK_HF_DEBUG：
- 若设备当前“未连接任何 Wi‑Fi”（STA 未关联），则直接连接该热点（开放式，无密码），以确保与调试主机处于同一网段后进入 Debug 模式。
- 若设备已连接 Wi‑Fi，则不切换网络，仅把“扫描命中”视作触发信号而进入 Debug 模式，避免打断云业务。
- 禁止开启 AP 模式。
不需要共享口令、不做 SSID 校验后缀，入口完全开放（按风险提示执行）。
多设备场景：进入 Debug 模式后，设备以 UDP 广播帧周期发布自身识别信息（复用 HiLink 设备信息字段）以便工具端筛选目标设备。
Debug 窗口：若进入后的 5 分钟内“从未有主机连接”（Console 或 OTA 任一）则退出 Debug 模式并关闭端口与广播。
端口由本方案指定（见 §6）。
不启用 IP 白名单/黑名单。
背景扫描允许在“高流量周期”暂停/延后。

4. 总体架构与模块

组件划分（逻辑）：

DebugManager（状态机）
- 维护状态 Closed/Debug、计时器、端口启停与广播调度。
WifiScanner（被动扫描或等效）
- 周期扫描，命中 SSID 触发 Debug；在高负载时延后。
TcpConsoleServer（2323/tcp）
- 行缓冲命令模式 + RAW 透传模式；与 DIAG 虚拟 shell 对接；镜像实时日志。
HttpOtaServer（8070/tcp）
- prepare/chunk/commit/status 路由；调用 UPG uapi；commit 通过即安装。
LogRingBuffer（内存环形，常态写入）
- 通过 DIAG 通道 TX hook 或用户打印注册接口镜像日志到环形缓冲；Debug 时提供 tail/dump 出口。
UdpAnnouncer（37501/udp 广播，仅 Debug）
- 发布设备识别信息（did/model/sn/ip/fw 等）。
LoadMonitor（高负载守门）
- 采样 CPU/LWIP 队列/吞吐量，给扫描与广播提供延后/降频依据。

5. 状态机与时序

状态：

Closed（默认）：
- TcpConsole/HttpOta/Announcer 均关闭；Ring Buffer 持续写入。
- WifiScanner 以固定周期被动扫描 SSID。
Debug（触发进入）：
- 立即开启 2323/tcp 与 8070/tcp，并启动 37501/udp 广播。
- 启动“5 分钟首联计时器”。若 5 分钟内从未有主机建立 Console 或 OTA 连接，则自动回到 Closed。
- 一旦出现首个连接，首联计时器停止；Debug 模式默认保持，直至手工 debug off 或设备重启（可选：实现“断开后闲置 5 分钟退出”的拓展策略，默认关闭）。

触发（唯一）：

WifiScanner 扫描结果出现 SSID = EK_HF_DEBUG：
- 若未联网：尝试连接该 SSID（无密码），DHCP 成功后进入 Debug。
- 若已联网：不切换，仅作为信号进入 Debug。

扫描策略：

周期：默认 120 s/次；优先采用被动扫描。目标是整个扫描总时长 ≤1.5 s；具体信道驻留时长受驱动能力限制，可按平台实际尽量控制。
高负载抑制：CPU>60% 或 LWIP 队列>80% 或近 10 s 吞吐>阈值 → 跳过本轮并记录；连续跳过 3 次后强制进行“快速扫描”（仅当前信道与相邻）。若无法直接获取上述指标，可退化为基于 I/O 速率与任务执行时长的启发式延后/降频。

6. 端口与协议

TCP Console：2323/tcp
- 单连接优先。并发连接时：保持首个连接为“前台会话”，后续连接返回“忙碌”并断开。
- 编码：UTF‑8；行终止 CR/LF；单行上限 512 字节（可配）。
- 模式：默认命令模式；支持 raw on/off 切换透传模式（不解析 CR/LF）。
- 历史日志：提供 log tail N / log dump S 指令（见 §7）。
HTTP OTA：8070/tcp
- POST /ota/prepare Content‑Type: application/json
  - 入参：{"length": <uint32>, "sha256": "<可选hex>"}
  - 行为：调用 uapi_upg_prepare()；返回 200/错误码。
- PUT /ota/chunk?offset=<uint32> Content‑Type: application/octet-stream
  - 要求 4 字节对齐；offset + len <= length。
  - 行为：uapi_upg_write_package_sync(offset, buf, len)；返回 200/错误码。
- POST /ota/commit
  - 行为：uapi_upg_verify_file() → 成功则 uapi_upg_request_upgrade(reset=true) 立刻安装并重启；返回 200（可能随即断开）。
- GET /ota/status
  - 返回：{"status":"NONE|UPDATING|SUCC|FAIL", "progress":<0-100 可选>}。
    - status 源自 uapi_upg_get_status() 的聚合状态。
    - 若编译开启并注册 uapi_upg_register_progress_callback()，则返回 progress；否则仅返回状态。

设备广播（仅 Debug）：37501/udp（广播地址/子网广播）

间隔：进入 Debug 后前 10 秒每秒 1 次；之后每 30 秒 1 次，直至 Debug 结束。

载荷（JSON 示例）：

{"t":"ekhf.debug.presence.v1","pid":"<productId>","did":"<deviceId>","model":"<model>",
 "sn":"<sn>","mac":"<xx:xx:xx:xx:xx:xx>","ip":"<a.b.c.d>","fw":"<version>",
 "uptime":12345,"ports":{"console":2323,"ota":8070},"window_sec_left":270}

实现备注：

Console/HTTP 服务需基于 lwIP socket/netconn 自行实现最小可用服务器（单连接 Console、最小路由 HTTP）。
端口共存与冲突：若系统中已启用如 hfnet_start_assis(ASSIS_PORT) 等服务，需确保与 2323/8070 端口不冲突；必要时在 Debug 模式启用时暂时关闭或改口。

7. 日志 Ring Buffer（常态写入，仅 Debug 可读）

源：通过 DIAG 通道 TX hook 或用户打印注册接口，对 SOC_LOG 与 osal_printk/print_str 输出进行镜像，写入环形缓冲（生产者无阻塞拷贝）。
容量：建议 128 KB（可调 128–512 KB）。
条目：时间戳（ms）、等级、模块、线程/CPU 与文本；按行存储，超过行长进行切分。
读取（Console 指令）：
- log tail <N>：输出最近 N 行；
- log dump <S>：输出最近 S 秒内日志；
- log level <ERR|WARN|INFO|DBG>：调节“实时镜像到 Console”的等级（不影响 ring 的写入）。
限速：Console 推送上限 100 KB/s（可配）。

8. 资源与负载策略

扫描预算：≤1.5 s/120 s；高负载时延后；连续跳过 3 次后进行快速扫描。
Console 与 OTA：非阻塞 socket；后台任务优先级低于业务任务；拥塞时降速/丢弃输出，不反压业务。
广播预算：仅 Debug 模式广播；高负载时自动将间隔提升至 60 s。
负载指标退化：若无法采集 CPU%/LWIP 队列等指标，允许使用基于 I/O 速率和任务运行时长的启发式降频/延后策略。

9. 安全与合规

入口完全开放（按照用户要求）：
- 无密码 SSID；Console/HTTP 无鉴权；无 IP 白名单/黑名单。
- 风险：同网段任何人可在 Debug 窗口内接入；因此 Debug 模式仅在现场触发、短时使用，且 5 分钟内无人接入即退出。
数据：OTA 包整体仍由 UPG 在本地执行完整性校验（头/整包/镜像哈希与签名链，具体以现有 UPG 配置为准）。

10. 配置项（默认值）

项目	键名（建议）	默认
扫描周期	`DBG_SCAN_PERIOD_S`	120
信道驻留	`DBG_SCAN_DWELL_MS`	100
高负载 CPU 阈值	`DBG_CPU_BUSY_PCT`	60
高负载 LWIP 队列阈值	`DBG_LWIP_Q_BUSY_PCT`	80
Console 端口	`DBG_CONSOLE_PORT`	2323
OTA 端口	`DBG_OTA_PORT`	8070
广播端口	`DBG_BROADCAST_PORT`	37501
Ring 容量（KB）	`DBG_RING_KB`	128
Console 实时流上限（KB/s）	`DBG_CONSOLE_RATE_KBPS`	100
首联超时（s）	`DBG_FIRST_CONN_TIMEOUT_S`	300

注：以上均为实现时的可配置参数，本文档不强制其持久化方式（编译宏 / NV）。

11. 与现有代码的对接点（不改变业务调用）

前置依赖与初始化：
- Kconfig：启用升级模块（MIDDLEWARE_SUPPORT_UPDATE=y）。
- 启动阶段调用 ws63_upg_init() 完成 uapi_upg_init() 初始化（见 middleware/chips/ws63/update/common/upg_common_porting.c）。
- Console/HTTP 服务需新增（基于 lwIP socket/netconn）。
Console 入站命令执行：
- 入口：diag_debug_cmd_proc(uint8_t *data, uint32_t len)
- 参考：middleware/chips/ws63/dfx/dfx_system_init.c 中 cmd_shell_proc() 用法。
日志输出镜像与 Ring 写入：
- 通过 DIAG 通道 TX hook 做 tee：先走原 UART 输出，再写入 Ring Buffer；或使用平台暴露的用户打印注册入口实现镜像；
- 保持原 UART 输出不变，同时镜像一份至 Console 与 Ring Buffer。
OTA 调用序列（HTTP 路由对应）：
- prepare → uapi_upg_prepare(upg_prepare_info_t*)；
- chunk → uapi_upg_write_package_sync(offset, buf, len)；
- commit → uapi_upg_verify_file() → uapi_upg_request_upgrade(reset=true)（立即安装与重启）；
- status → uapi_upg_get_status()；
- 参考：middleware/utils/update/storage/upg_storage.c、middleware/utils/update/common/upg_verify.c、middleware/utils/update/local_update/upg_process.c。
Wifi 扫描/连接：
- 复用现有 Wi‑Fi 管理接口（参照 application/samples/wifi/* 示例）实现被动扫描（或等效）与条件连接；不得影响现有 STA 工作。
端口共存：
- 若使用 hfnet_start_assis(ASSIS_PORT) 等调试服务，需在 Debug 模式启用时避免与 2323/8070 端口冲突（可在进入 Debug 时停止该服务或调整端口）。

12. 错误码与返回（建议）

Console：

BUSY（已占用，拒绝并断开）
ERR_BAD_CMD / ERR_ARGS / ERR_TOO_LONG

HTTP OTA：

400 ERR_INVALID_ARGS（length/offset/对齐错误）
409 ERR_STATE（未 prepare 先 chunk；重复 commit 等）
413 ERR_TOO_LARGE（包长超出 FOTA 区）
416 ERR_RANGE（offset 越界）
422 ERR_VERIFY_FAILED（校验失败）
500 ERR_INTERNAL

13. 典型交互示例

Console：

$ nc <dev-ip> 2323
> help\r\n
< ...（回显各命令）
> log tail 200\r\n
< 最近200行历史日志...
> raw on\r\n  （进入透传）

OTA：

# 1) 准备
curl -sS -X POST http://<dev-ip>:8070/ota/prepare \
  -H 'Content-Type: application/json' -d '{"length": 1048576}'

# 2) 分片写入（举例 4KB 步进）
offset=0; while read -r -d '' -n 4096 chunk; do \
  curl -sS -X PUT "http://<dev-ip>:8070/ota/chunk?offset=${offset}" \
       --data-binary @<(printf "%s" "$chunk"); \
  offset=$((offset+4096)); done < <(dd if=fw.bin bs=4096 status=none)

# 3) 提交并安装（设备可能立即断开并重启）
curl -sS -X POST http://<dev-ip>:8070/ota/commit

广播（工具侧监听）：

tcpdump -n -vv -s0 udp port 37501

14. 测试计划（验收标准）

触发：

未联网→现场开启 EK_HF_DEBUG 热点：设备自动连接并进入 Debug；5 分钟内无连接则退出。
已联网→现场开启同名热点：设备不切换，仅进入 Debug；5 分钟内无连接则退出。

Console：

命令回显正常；log tail 200、log dump 60 正确输出；raw on 8KB 循环透传校验正确；并发第二连接被拒绝。

OTA：

prepare→chunk→commit 正常；commit 后立即安装/重启；重启后版本信息与日志中可见升级结果；错误 offset/越界/校验失败分别返回 400/416/422。
GET /ota/status：在未初始化/未 prepare/写入中/完成/失败各阶段返回符合 NONE|UPDATING|SUCC|FAIL 映射；启用进度回调时返回合理 progress。

稳定性：

高负载下扫描延后生效；广播间隔自动增大；Console/OTA 不阻塞业务（无明显时延抖动）。

端口与并发：

与 ASSIS_PORT 等服务共存/冲突验证；Console 并发连接第二路返回 BUSY 并断开。

限速：

Console 实时推送限速 100KB/s 验证（长流量压测下不反压业务）。

回归：

Debug 退出后端口与广播确实关闭；常态 Ring Buffer 持续工作且占用符合预算。

15. 风险与缓解

开放式入口风险：同网段内任意主机可接入 Debug。缓解：仅在现场触发；5 分钟无人连即退出；记录接入来源到 Ring；可后续加“口令开关”。
扫描扰动：被动扫描+高负载抑制；扫描时间受限；必要时频率可进一步降低。
OTA 失败风险：UPG 既有校验链与回退策略（AB/整包/差分由现配置决定）；失败保留当前运行分区。

16. 交付与实施建议（不改变业务逻辑）

开发任务拆解（建议）：

DebugManager/LoadMonitor/状态机与计时器骨架。
WifiScanner：被动扫描与条件连接；高负载抑制策略。
TcpConsoleServer（需新增）：基于 lwIP 单连接、行缓冲/RAW 模式、命令桥接、实时日志镜像、历史日志指令。
HttpOtaServer（需新增）：最小路由 /ota/prepare|chunk|commit|status 与 UPG uapi 串接、错误码与进度上报。
LogRingBuffer：通过 DIAG TX hook/用户打印注册入口做日志 tee；读口；限速。
UdpAnnouncer：JSON 载荷、节流与停止逻辑。
集成与测试：按 §14 验收标准逐项打勾。

端口冲突处理：

若存在既有调试/辅助服务占用端口，进入 Debug 模式时进行协调（停服或改口），退出时恢复。

17. 变更记录

2025-10-26：v1.1 调整为可落地实现版本：
- 明确 Console/HTTP 需基于 lwIP 实现；新增端口冲突与共存说明。
- 日志镜像改为 DIAG TX hook/用户打印注册入口；Ring 默认容量建议为 128KB。
- GET /ota/status 状态与进度对齐 uapi_upg_get_status 与进度回调。
- 扫描策略放宽为目标约束，并提供负载指标不可用时的启发式退化方案。
2025-10-26：初版（按“纯 Wi‑Fi + SSID 触发 + 无认证 + 5 分钟首联退出 + 无 AP/mDNS/UDP syslog”的决策输出）。

16 KiB Raw Blame History Unescape Escape