Bl616 Lowpower Io Guide

When to Use

客户涉及 BL616/BL618 低功耗 IO 唤醒的以下场景：1) 引导：客户不知道如何分配唤醒引脚、选择触发方式或配置外部电路。2) 校验：客户已填唤醒配置表（xlsx）或已口头描述配置，需要核对。3) 诊断：客户遇到故障（唤醒不生效、睡眠电流偏大、入睡即醒、唤醒来源不明）。4) 生成：客户需要标准唤醒配置模板。边界：不替代 BL616/618 参考手册；与 IO 唤醒无关的低功耗问题不归本技能处理。

Procedure

1. 入口分流：判断客户处于引导（未设计）、校验（有配置）、诊断（有故障）或生成（要模板）四种状态之一。
2. 校验模式：获取 xlsx 路径或问答信息，运行引擎 python3 engine.py check -i （或 check -j ），逐条解读 🔴/🟡/🟢 报告，给出证据要求清单与结论摘要。
3. 引导模式：按问题清单采集（芯片/封装、功耗模式、是否外接 32K 晶振〔默认是，占用 GPIO16/17〕、唤醒源类型、信号电平与保持时间、组内其他引脚用途），按引脚分配决策表输出建议（具体 GPIO 号+触发方式+外部电路+睡眠前电平）。
4. 诊断模式：按现象分支（不生效/电流大/入睡即醒/来源不明）运行排查树，输出检查项与证据要求。
5. 模板生成：python3 engine.py generate -o [--chip BL618] [--package QFN56]，把标准模板发给客户填写。模板引脚表带分组可视化（左侧合并单元格的触发组/IE·PU/PD 组标签、可折叠行分组、冻结窗格）和底部填写说明，客户无需事先了解分组约束即可填写。
6. 所有模式结束时，报告必须包含：违规/建议清单（分级）、证据要求清单（电流/波形/日志）、一句话结论与下一步动作。

Pitfalls

• ACOMP 比较阈值固定为内部 1.65V（NuttX bl_lp_set_acomp 硬编码），客户不可配置；信号必须跨越 1.65V 才能触发 ACOMP 唤醒。
• ACOMP 候选引脚（2/3/10/12/13/14/20，BL618 加 19）在唤醒位图中自动提拔前 2 个编号最小者，其余候选脚按 PDS_IO 下降沿唤醒——客户常误解这一点。
• 高电平唤醒时睡眠前已是高电平【不会】立即唤醒；只有上升沿唤醒要求睡眠前必须为低电平。
• GPIO0~15 组睡眠时驱动默认内部下拉（g_lp_wake_pds_cfg.io_0_15_res=PULL_DOWN），该组外部上拉引脚会与内部下拉形成反向冲突漏电。
• 组内有唤醒脚时整组 IE=1（GPIO015、GPIO2034 各自整组），组内所有引脚睡眠时都必须有确定电平。
• 正常模式 GPIO 中断配置与睡眠唤醒是两套独立机制；本 SDK 睡眠唤醒固定为下降沿，配置上升沿/高电平/双边沿需要改驱动（green 提示并说明方法）。
• HBN 模式 IO 唤醒在 SDK 中处于开发中状态，客户拿到的版本可能不支持：先确认客户 SDK 版本，再给结论。
• BL616 QFN40 未引出引脚（49/18/19/2326/31~34）默认按新封装（内部打线接地）处理：配置内部上拉会形成对地通路损坏芯片（🔴 严重）；NuttX 没有禁止这种配置的保护，必须靠检查拦截。
• BL616 QFN40 只有 GPIO03/1017/2022/2730 共 19 个引脚可用。
• GPIO16/17 复用 XTAL32K：当前项目低功耗模组（BL616/BL618）默认外接 32K 晶振（模板默认填"是"，未填写也按"是"处理），GPIO16/17 不能用作唤醒源；仅确认模组确实未外接 32K 晶振时才可释放这两个引脚。
• GPIO2 是 BOOT 引脚，建议 1MΩ 接地保证启动可靠性。
• 唤醒信号时序：PDS_IO/AON_IO 电平保持 ≥100us，ACOMP ≥50us，识别具体引脚需保持 ≥2ms。

内联参考：事实速查

运行引擎和解释报告时使用本表。技能自包含，不依赖任何 SDK 仓库。

引脚集合（已确认）

分组约束

SDK 默认行为

时序与电平

上升沿唤醒要求睡眠前为低电平（否则入睡即醒）。高电平唤醒无此限制（睡眠前已是高电平不会立即唤醒）。

内联参考：引导模式决策表

1. 先确定封装可用引脚（QFN56 全可用；QFN40 仅 19 个，见上表）。
2. 避开：XTAL32K（16/17，当前项目低功耗模组默认外接 32K 晶振，按已占用处理）、BOOT（2，需 1MΩ 接地处理）、外设已占用引脚。
3. 按唤醒需求分配：

4. 定外部电路：优先外部电阻钳位电平，不依赖内部 PU/PD（分组共享易漏电）。
5. 输出建议后回灌 check 验证，确认无 🔴 违规。

内联参考：诊断模式排查树

内联参考：引擎与输入

python3 engine.py generate -o 模板.xlsx [--chip BL618] [--package QFN56]
python3 engine.py check -i 已填表.xlsx
python3 engine.py check -j data.json

• generate：生成标准模板（基本信息 + BL618_QFN56/BL616_QFN40 两张引脚表）。引脚表贴近原版模板、打开即直观：黄色表头；左侧两列合并单元格分组标签（触发组 0-7/8-15/16-19/20-27/28-34·PDSIO/AONIO、IE/PU/PD 组 0-15/20-34〔16-19 AON 标独立〕）；GPIO 列带功能注释（ADC/ACOMP/XTAL32K/Boot），XTAL32K 行红标；首行 GPIO0 预填按键唤醒示例（可修改/删除）；触发组可折叠行分组；冻结窗格（表头+组标签固定）；字段列数据有效性下拉；底部填写说明。
• check：输出分级报告。退出码：0=无红无黄，1=有黄，2=有红。
• JSON 输入（问答降级路径）schema：

{
  "basic": {"chip": "BL618", "package": "QFN56", "pmode": "PDS",
            "xtal32k": "是", "symptom": "唤醒不生效", "current_ua": "120"},
  "pins":  [{"gpio": 0, "use": true, "func": "普通IO", "wake": true,
             "trig": "下降沿", "ext": "外部上拉", "int_res": "无",
             "level": "高", "note": ""}]
}

枚举值：func ∈ 普通IO/唤醒/ADC/ACOMP/UART/SPI/I2C/XTAL32K/BOOT/悬空；trig ∈ 下降沿/上升沿/高电平/低电平/双边沿/无；ext ∈ 外部上拉/外部下拉/内部上拉/内部下拉/悬空/外设钳位/模拟信号/空；int_res ∈ 上拉/下拉/无；level ∈ 高/低/不确定/不适用；pmode ∈ PDS/HBN；symptom ∈ 无/唤醒不生效/睡眠电流偏大/误唤醒/唤醒来源不明。

报告格式

报告按以下结构输出（引擎生成 markdown，agent 负责向客户解释与补充）：

1. 基本信息：回显客户填写项。
2. 🔴 严重问题：必然导致不唤醒、漏电或损坏（每项含引脚/问题/原因/措施）。
3. 🟡 警告：大概率出问题，需客户确认。
4. 🟢 提示：建议项（时序、改驱动、1.65V 等）。
5. 证据要求：按问题推导（电流实测/波形/日志）。
6. 结论摘要：一句话结论 + 下一步动作。

Verification

1. python3 engine.py generate -o /tmp/tpl.xlsx 生成成功，检查基本信息与两张引脚表的表头、数据有效性下拉；引脚表确认 freeze_panes="C2"、GPIO 列带注释且 XTAL32K 行红标、首行 GPIO0 示例、触发组/IE·PU/PD 组标签的合并单元格与触发组行分组（outline_level=1）、底部填写说明。
2. 用 check -i 回读新生成模板（仅示例行）应解析正常且无红无黄；填 GPIO16 为唤醒源后应命中 R2（XTAL32K 冲突）。
3. 构造故意违规的样例表（未引出引脚、上升沿+睡眠前高电平、ACOMP 超 2 个、组内悬空、HBN 配唤醒、XTAL32K 冲突、未引出内部上拉），运行 check，每条规则按预期命中且级别正确。
4. 问答降级路径：构造等价 JSON 输入运行 check -j，输出与 xlsx 路径一致。
5. 引导模式：按决策表给出的引脚分配建议不违反任何 🔴 规则（可回灌 check 验证）。