# Bl616 Lowpower Io Guide

> BL616/BL618 低功耗 IO 唤醒（GPIO wakeup）设计引导、配置校验与故障诊断：客户不知道怎么分配唤醒引脚/选触发方式、唤醒配置需核对（xlsx 或口头描述）、唤醒不生效、睡眠电流偏大、误唤醒、ACOMP 唤醒困惑、HBN IO 唤醒，或需要标准唤醒配置模板时使用。

- Skill: `bouffalolab/bl616-lowpower-io-guide` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add bouffalolab/bl616-lowpower-io-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bouffalolab/bl616-lowpower-io-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: bouffalolab (https://skillmd.com/u/bouffalolab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bouffalolab/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 <xlsx>（或 check -j <json>），逐条解读 🔴/🟡/🟢 报告，给出证据要求清单与结论摘要。
3. 引导模式：按问题清单采集（芯片/封装、功耗模式、是否外接 32K 晶振〔默认是，占用 GPIO16/17〕、唤醒源类型、信号电平与保持时间、组内其他引脚用途），按引脚分配决策表输出建议（具体 GPIO 号+触发方式+外部电路+睡眠前电平）。
4. 诊断模式：按现象分支（不生效/电流大/入睡即醒/来源不明）运行排查树，输出检查项与证据要求。
5. 模板生成：python3 engine.py generate -o <path> [--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（GPIO0~15、GPIO20~34 各自整组），组内所有引脚睡眠时都必须有确定电平。
- 正常模式 GPIO 中断配置与睡眠唤醒是两套独立机制；本 SDK 睡眠唤醒固定为下降沿，配置上升沿/高电平/双边沿需要改驱动（green 提示并说明方法）。
- HBN 模式 IO 唤醒在 SDK 中处于开发中状态，客户拿到的版本可能不支持：先确认客户 SDK 版本，再给结论。
- BL616 QFN40 未引出引脚（4~9/18/19/23~26/31~34）默认按新封装（内部打线接地）处理：配置内部上拉会形成对地通路损坏芯片（🔴 严重）；NuttX 没有禁止这种配置的保护，必须靠检查拦截。
- BL616 QFN40 只有 GPIO0~3/10~17/20~22/27~30 共 19 个引脚可用。
- GPIO16/17 复用 XTAL32K：当前项目低功耗模组（BL616/BL618）默认外接 32K 晶振（模板默认填"是"，未填写也按"是"处理），GPIO16/17 不能用作唤醒源；仅确认模组确实未外接 32K 晶振时才可释放这两个引脚。
- GPIO2 是 BOOT 引脚，建议 1MΩ 接地保证启动可靠性。
- 唤醒信号时序：PDS_IO/AON_IO 电平保持 ≥100us，ACOMP ≥50us，识别具体引脚需保持 ≥2ms。

## 内联参考：事实速查

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

### 引脚集合（已确认）

| 集合 | 引脚 | 说明 |
|---|---|---|
| AON_IO | 16~19 | 独立 IE/PU/PD；完整触发；唯一支持 HBN IO 唤醒的类型 |
| PDS_IO | 0~15、20~34 | 仅 PDS 模式；仅下降沿/上升沿/高电平 |
| ACOMP 候选 | 2/3/10/12/13/14/20（BL618 加 19） | 最多 2 路；阈值固定 1.65V |
| XTAL32K | 16/17 | 使用外部 32K 晶振时不可用；当前项目低功耗模组默认外接 |
| BOOT | 2 | 建议 1MΩ 接地 |
| QFN40 未引出 | 4~9/18/19/23~26/31~34 | BL616 可用引脚仅 0~3/10~17/20~22/27~30 |

### 分组约束

| 类型 | 分组 | 说明 |
|---|---|---|
| 触发分组 | 0-7 / 8-15 / 16-19 / 20-27 / 28-34 | 同组共享触发方式 |
| IE/PU/PD 大组 | 0-15 / 20-34 | 整组统一；组内有唤醒脚时整组 IE=1 |

### SDK 默认行为

| 项目 | 行为 |
|---|---|
| 睡眠唤醒触发 | 全部分组硬编码下降沿（含 AON_IO、ACOMP） |
| ACOMP 提拔 | 唤醒位图中编号最小的 2 个候选脚自动配置为 ACOMP 唤醒，其余退化 PDS_IO 下降沿 |
| GPIO0~15 组电阻 | 睡眠时默认内部下拉 |
| HBN IO 唤醒 | SDK 开发中，客户版本可能不支持；当前仅 RTC 唤醒 |
| 正常模式中断 | 与睡眠唤醒是两套独立机制 |

### 时序与电平

| 唤醒源 | 电平保持 |
|---|---|
| PDS_IO / AON_IO | ≥100us |
| ACOMP | ≥50us |
| 识别具体引脚 | ≥2ms |

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

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

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

| 需求 | 建议 |
|---|---|
| 数字信号唤醒（按键/传感器/UART RX） | PDS_IO 优先，下降沿；确认睡眠前电平与触发方式匹配 |
| 模拟信号唤醒 | ACOMP 候选脚（≤2 路），信号必须跨越 1.65V，保持 ≥50us |
| 电平唤醒/双边沿 | AON_IO（16~19）芯片支持；本 SDK 默认下降沿，需改驱动 |
| HBN 模式 | 先确认客户 SDK 版本（IO 唤醒开发中） |

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

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

| 现象 | 检查项 | 证据要求 |
|---|---|---|
| 唤醒不生效 | 唤醒使能是否配置；触发方式是否非下降沿（需改驱动）；睡眠前电平是否满足；时序是否 ≥100us/50us；ACOMP 是否跨 1.65V；引脚是否未引出/被占用 | 唤醒波形（标注保持时间）、`<<<--- [R]:` 日志 |
| 睡眠电流偏大 | IE=1 悬空引脚（整组连带）；GPIO0~15 组外部上拉与默认内部下拉反向；未引出引脚内部上拉（烧芯片）；ADC 模拟输入未隔离 | 睡眠电流实测值（uA）、分状态电流 |
| 入睡即醒 | 上升沿唤醒且睡眠前高电平；信号毛刺；保持时间不足 | 睡眠前后波形 |
| 唤醒来源不明 | ACOMP 引脚识别（acomp cfg 日志）；保持 ≥2ms | `acomp cfg: %d %d`、`[R]:` 日志 |

## 内联参考：引擎与输入

```bash
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：

```json
{
  "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 验证）。