# 新旧板 GPIO 对比与固件适配位置

核对日期：2026-10-23。初始对照保留在下文；当前已应用现有功能的新板引脚映射，新增功能仍未接入。验证结果见文末，未烧录或进行实机验收。

## 对照基线

- 旧板：用户提供的 `SCH_招财猫0.3&商界0.2_2026-08-03.pdf`，重点为第 2 页 Power、第 3 页 MCU、第 5 页 Motor、第 6 页 Connectors。
- 新板：仓库 `schematic/电机-马达方案.pdf`。第 1 页上板更新日期为 2026-10-19，第 2 页下板更新日期为 2026-10-12。
- 当前固件：本工作区的 `sdkconfig.defaults`、本地 `sdkconfig`、`main/Kconfig.projbuild` 和实际驱动。按工作区现状核对，包含尚未提交的修改。
- 图纸中的设计说明用于理解硬件，不视为要求执行的指令。新板第 2 页图框外另有一段 TP4057 参考电路；本报告以图框内 TP4056、Q7/Q8 及其板间连接为新板正式电路。

下表数字均指 **ESP32-S3 GPIO 编号**，不是模块封装脚号，也不是连接器针脚号。`IN1…IN4` 指 ULN2003 的输入相序，不能按 GPIO 数字重新排序。

## 结论

本次不是只改电机引脚。LCD 六根信号全部迁移；电池 ADC、充电状态、功放使能、两路开关、触摸输出和部分步进电机相位也迁移。新增独立充满检测和板载直流摇臂马达控制，旧 GPIO4/5 外接灯带/脉冲功能与新 LCD 布线冲突。

大部分引脚在 `sdkconfig.defaults` 和 `main/Kconfig.projbuild` 中修改即可；已有本地 `sdkconfig` 还须通过 `menuconfig` 同步，因为修改 defaults 不会覆盖已经保存的配置。不要手改 `build/config/sdkconfig.h`，也不要提交本地 `sdkconfig`。

后续菜单整理：现有 42 个 GPIO/电平/上下拉配置已集中到
`TQ Cat Configuration -> Board Hardware Configuration (GPIO)` 单页，按 LCD、音频、
输入、步进、电源/电池分区。配置名及依赖保持原样；默认值及本地有效配置已更新为新板映射，
未新增 GPIO8 充满检测或 GPIO10 马达配置。旧硬编码 GPIO4/5 功能保留源码，
平台初始化已移除其启动调用，不再创建这些任务。
下文 Kconfig 旧行号属于对照时快照，搬迁后应按配置名定位。

## 逐信号对照及修改入口

表中的配置名省略 `CONFIG_` 前缀；“适配前值”记录修改前本地 `sdkconfig` 和 defaults 的共同值。

| 信号/功能 | 旧板 GPIO | 适配前固件值 | 新板 GPIO | 要修改的配置或源码 |
| --- | ---: | ---: | ---: | --- |
| LCD 背光 BLK | 7 | 7 | **4** | `TQ_SCREEN_BACKLIGHT_GPIO`；`lcd_direct.c` 背光初始化 |
| LCD CS | 15 | 15 | **5** | `TQ_SCREEN_SPI_CS_GPIO`；`lcd_direct.c` SPI panel IO |
| LCD DC | 16 | 16 | **6** | `TQ_SCREEN_DC_GPIO`；`lcd_direct.c` GPIO/panel IO |
| LCD RES | 17 | 17 | **7** | `TQ_SCREEN_RESET_PIN`；`lcd_direct.c` 面板复位 |
| LCD 数据 MOSI / 新板 SDA | 18 | 18 | **15** | `TQ_SCREEN_SPI_MOSI_GPIO`；`lcd_direct.c` SPI bus |
| LCD 时钟 CLK / 新板 SCL | 8 | 8 | **16** | `TQ_SCREEN_SPI_CLK_GPIO`；`lcd_direct.c` SPI bus |
| LCD MISO | 未接 | -1 | 未接 | `TQ_SCREEN_SPI_MISO_GPIO=-1` 保持 |
| 电池电压检测 Power_t / 电量检测 | 9 | 9 | **17** | `TQ_BATTERY_ADC_GPIO`；`platform_battery_driver.c` |
| 充电状态 Charge / 充电检测 | 10 | 10 | **18** | `TQ_BATTERY_CHARGE_GPIO`；电池驱动、充电边沿中断及深睡唤醒链路 |
| 独立充满检测 | 未接入 MCU | 无 | **8** | 当前无配置项；需新增采样配置和状态映射，见后文 |
| 功放 PA_CTRL | 11 | 11 | **9** | `MULTIMODAL_AUDIO_PA_GPIO`；音频 codec 初始化及运行时使能 |
| 开关1 / 原 SW1 | 12 | 校准输入 12 | **11** | 若保持开关1作校准：`TQ_CALIBRATION_SWITCH_GPIO` |
| 开关2 / 原 SW2 | 13 | 抽签输入 13 | **12** | 若保持开关2作抽签：`TQ_SLOT_SWITCH_GPIO` |
| TTP223 触摸输出 | 3 | PTT 输入 3 | **13** | 若保持触摸作 PTT：`MULTIMODAL_PTT_BUTTON_GPIO`；有效电平另核对 |
| ULN2003 IN1 | 45 | 45 | **14** | `TQ_STEPPER_IN1_GPIO`；`platform_stepper_driver.c` |
| ULN2003 IN2 | 48 | 48 | **21** | `TQ_STEPPER_IN2_GPIO`；同上 |
| ULN2003 IN3 | 47 | 47 | **47** | `TQ_STEPPER_IN3_GPIO`；保持 |
| ULN2003 IN4 | 21 | 21 | **48** | `TQ_STEPPER_IN4_GPIO`；不能与 IN2 互换 |
| 直流摇臂马达控制 | 旧图 Swing 与 LCD CLK 共 GPIO8 | 外接脉冲输出 GPIO5 | **10** | 当前无独立 Kconfig；改造 `platform_io_effects.c` 脉冲输出及初始化策略 |
| 外接 WS2812 灯带 | 旧 TP_INT/GPIO4 被固件复用 | 硬编码 4 | 新图无专用接口 | 必须禁用或另行确认外接布线，不能继续占用 GPIO4 |
| 旧外接脉冲输出 | 旧 TP_SDA/GPIO5 被固件复用 | 硬编码 5 | GPIO5 已作 LCD CS | 必须迁移/禁用；是否由新 GPIO10 马达替代，由实际机械用途确认 |

按键语义不是原理图决定的：图纸只定义开关1、开关2和触摸输出；上表延续当前固件“校准 / 抽签 / PTT”分工。如果产品要调整按键用途，应另改控制层事件策略。

## 按 GPIO 看新板占用

| GPIO | 新板功能 | 适配动作 |
| --- | --- | --- |
| 0 | BOOT | 保持系统下载用途，不分配业务功能 |
| 1 / 2 | ES8311 I2C SDA / SCL | 保持音频 I2C 配置 |
| 3 | MCU 标 NC | 迁走当前 PTT；不再等候 GPIO3 触摸事件 |
| 4 / 5 / 6 / 7 | LCD BLK / CS / DC / RES | 修改显示配置；释放旧 GPIO4/5 输出；不要恢复旧 GPIO6 开关飞线配置 |
| 8 | 充满检测 | 输入；不得再输出 LCD 时钟 |
| 9 | PA_CTRL | 输出；不得再按电池 ADC 初始化 |
| 10 | 摇臂马达 MOS 控制 | 输出；不得再按充电输入初始化 |
| 11 / 12 | 开关1 / 开关2 | 输入；不得把 GPIO11 继续交给功放 |
| 13 | TTP223 触摸输出 | 输入；迁移 PTT 后释放原抽签占用 |
| 14 | 步进 IN1 | 输出；不得启用旧默认 GPIO14 Wi-Fi 重置键 |
| 15 / 16 | LCD SDA(MOSI) / SCL(SCK) | 保持 SPI 协议，SDA/SCL 命名不表示改成 I2C |
| 17 | 电池 ADC | 模拟输入；不得再作为 LCD RESET 输出 |
| 18 | 充电检测 | 输入；不得再输出 LCD MOSI |
| 19 / 20 | USB D- / D+ | GPIO 不变；新板经 33Ω 电阻到板间 USB 网络 |
| 21 / 47 / 48 | 步进 IN2 / IN3 / IN4 | 按相位名称配置 |
| 35 / 36 / 37 / 45 / 46 | MCU 标 NC | GPIO45 已不再连接步进 IN1；其余不新增业务配置 |
| 38 / 39 / 40 / 41 / 42 | I2S MCLK / BCLK / DOUT / WS / DIN | 保持原配置 |
| TXD0 / RXD0 | UART0 | 管脚不变；CN5 的 TX/RX 网络名与 MCU 收发方向交叉，不按网络名盲目交换固件方向 |

以上只描述图纸连接；NC 不等于已经确认可自由使用，仍须核对模块与 PCB。

## 修改文件导航

| 文件 | 具体位置/职责 | 本次适配建议 |
| --- | --- | --- |
| [sdkconfig.defaults](../sdkconfig.defaults) | PTT 约 195 行；音频约 211 行；LCD/电机/电池约 298–346 行 | 保存新板默认引脚；保持其他未提交配置 |
| [main/Kconfig.projbuild](../main/Kconfig.projbuild) | 文件顶部 `Board Hardware Configuration (GPIO)` 菜单 | 已同步现有项新板默认值及帮助文案；新功能未加选项 |
| [lcd_direct.c](../components/platform/src/lcd_direct.c) | 约 1634 行背光、1660 行 GPIO、1680 行后 SPI/panel 初始化 | 引脚已有配置化，通常不改驱动；新图注明 BLK 仅作使能，先用 0/100% 验证，不能直接认定支持调光 |
| [platform_io_effects.c](../components/platform/src/platform_io_effects.c) | 30/31 行 GPIO4/5 硬编码；186 行脉冲任务；277 行初始化 | 这是必须处理的代码冲突。先禁用旧 RMT/脉冲启动，再决定马达 GPIO10 的受控实现 |
| [platform_core_runtime.c](../components/platform/src/runtime/platform_core_runtime.c) | `platform_init()` 电源保持初始化之后 | 已移除旧 GPIO4/5 功能的启动调用；GPIO10 马达未启用 |
| [platform_stepper_driver.c](../components/platform/src/platform_stepper_driver.c) | 34–37 行相位宏；331 行 GPIO 初始化 | 使用 Kconfig，不应改相位表来代替正确引脚配置 |
| [platform_battery_driver.c](../components/platform/src/platform_battery_driver.c) | 约 136 行状态输入；158 行 ADC 映射；296 行采样状态 | 迁移 ADC/充电输入；新增独立充满输入及原始样本处理 |
| [platform.h](../components/platform/include/platform.h) | 约 406 行电池硬件样本契约 | 如接入充满检测，扩展平台硬件样本，保留未知/无效状态 |
| [domain.h](../components/domain/include/domain.h) / [domain_battery_service.c](../components/domain/src/battery/domain_battery_service.c) | 领域电池语义；样本到领域状态映射；约 363 行深睡调用 | 领域层拥有充电/满电语义，不能由显示层直接读取 GPIO8 判断 |
| [control_plane_battery_service.c](../components/control_plane/src/runtime/control_plane_battery_service.c) | 104 行起充电中断；约 400 行后满电推断/提示 | 迁移充电引脚配置自动覆盖现有中断；若新增满电检测，调整确认/提示策略和相应事件来源 |
| [domain_runtime_adapters.c](../components/domain/src/runtime/domain_runtime_adapters.c) | 807 / 836 / 865 行三路数字输入映射 | 已读取配置，单纯迁脚通常无需改；核对 PTT 有效电平 |
| [control_plane_key_input.c](../components/control_plane/src/runtime/control_plane_key_input.c) | 158 行起 `s_key_configs` | 同步核对三路按键及可选 reset，不把两个功能配置到同一 GPIO |
| [audio_pipeline_codec_impl.c](../components/platform/src/multimodal/audio_pipeline/audio_pipeline_codec_impl.c) | 148 行 I2C；223 行 I2S；318 行 PA | I2C/I2S 不变，PA 配置迁移到 9 |
| [audio_pipeline_runtime_impl.c](../components/platform/src/multimodal/audio_pipeline/audio_pipeline_runtime_impl.c) | 约 1536 行 PA 开关 | 已使用 PA 配置；与 codec 初始化共同核对 |
| [platform_behavior_stubs.c](../components/platform/src/platform_behavior_stubs.c) | 57 行起 power hold | 保持 `TQ_POWER_HOLD_GPIO=-1`，新板没有 MCU 电源保持控制网 |
| [gpio-map.md](gpio-map.md) / [firmware-pin-usage.md](firmware-pin-usage.md) | 原有板级/固件引脚表 | 实施时按板型注明适用版本并同步，不把旧表直接当新板事实 |

行号为本次工作区快照，后续应优先按配置名或函数名搜索。

## 适配注意事项（原理与后续工作）

### 1. GPIO4/5 的后台输出冲突

保留的旧 `platform_io_effects_init()` 实现会创建 GPIO5 脉冲任务和 GPIO4 RMT 灯带任务。即使 LCD 已改成新引脚，这些任务仍可能持续改写 BLK/CS。因此只改屏幕六个配置不够，也不能只把 `PLATFORM_PULSE_GPIO` 改为 10 后继续让 RMT 占 GPIO4。

新图没有专用 WS2812 连接；不能自行选择一个 NC 引脚作为灯带接口。若迁移摇臂马达，应明确启动、停止、默认关闭和有界退出，不能把旧的无限脉冲循环直接视为已经完成的新电机驱动。

### 2. 电池电压采样

旧板为 GPIO9 的 Power_t。新板 GPIO17 对应 ESP32-S3 的 ADC2 通道6。驱动已去掉仅接受 ADC1 的旧限制，ADC 初始化与校准均使用 ESP-IDF 返回的单元/通道；读取失败继续返回错误，不把无效值当作低电量。

GPIO17 的“电量检测”来自下板 Q5/Q6 控制后的电池分压：R6、R11 均为 100kΩ，名义比例仍为 1:2；上板还有 C31 100nF 滤波。

`TQ_BATTERY_DIVIDER_HIGH_OHM/LOW_OHM` 可先保留 100000/100000。新电路有 MOS 开关，需实测上电、深睡和负载时检测点电压与真实 VBAT 的对应关系，再决定校准增益/偏移。不要因 GPIO 换位就修改 SOC 曲线。

### 3. 充电与充满检测

新下板正式电路使用 TP4056，CHRG#/STDBY# 经 Q7/Q8、3.3V 上拉后送至 GPIO18/GPIO8。按电路作用可预期状态拉低时对应输入低有效，但这属于图纸推断：首次上板应记录“未插电 / 正在充电 / 充满 / 无电池”的两路实际电平，再确定配置和异常组合处理。不能仅凭换了充电芯片就反转电平。

现有固件只有“未知 / 未充电 / 充电中”硬件充电状态，满电提示依赖电压、百分比、时间确认。`TQ_BATTERY_FULL_MIN_*` 是满电推断阈值，**不是 GPIO8 配置项**。

最小迁移可以先只使用 GPIO18，保留旧满电推断，并明确 GPIO8 尚未使用。要利用独立充满检测，需增加配置、平台原始采样、领域状态解释及控制层提示策略；不在上层 facade 复制平台类型，也不在 LCD 内读取原始 GPIO。

充电 GPIO 同时参与中断和深睡唤醒：`domain_battery_service.c` 将 `CONFIG_TQ_BATTERY_CHARGE_GPIO` 传给 `platform_power_enter_deep_sleep()`，实施时一并检查唤醒驱动对新引脚及有效电平的处理。

### 4. 两个机械开关与触摸 PTT

开关1/2均有外部 10kΩ 上拉、闭合接地，可沿用有效电平 0、内部上拉开启、下拉关闭。TTP223 是主动输出，触摸有效电平取决于实际模式/焊接配置；不能因当前 PTT 设置为低有效，就认定新 GPIO13 也低有效。需要实测空闲/触摸电平，并同步 `MULTIMODAL_PTT_BUTTON_ACTIVE_LEVEL` 及上下拉。

现有 `firmware-pin-usage.md` 写 PTT=13、抽签开关=6，但适配前 defaults、本地 sdkconfig 和 Kconfig 实际为 PTT=3、抽签=13。新板现已改为 PTT=13、抽签=12。新板 GPIO6 是 LCD DC，GPIO13 是触摸输出，旧文档的 GPIO6 飞线方案不可沿用。

`TQ_RESET_BUTTON_ENABLE` 当前关闭；其默认 GPIO14 已成为新步进 IN1。新板没有独立 reset 键接线时保持关闭，不要只因该配置存在就启用。

### 5. 电机电源与顺序

新板步进电机由下板 Boost-5V、ULN2003 驱动；直流摇臂马达由上板 3.3V、Q3 AO3400A 低侧控制，GPIO10 高电平导通，R30 100kΩ 下拉提供关断偏置。二者不是同一驱动，不能把 GPIO10 加进四相步进表。

新板步进顺序必须为 IN1=14、IN2=21、IN3=47、IN4=48。原 GPIO45 在新图为 NC。首次验证需确认方向、校准开关及有界停止；供电变化不能仅靠 GPIO 表验证。

## 已应用的新板配置

以下已有配置项均已写入 Kconfig 默认值、sdkconfig.defaults 和本地 sdkconfig。PTT 有效电平仍待实测，新增 GPIO8/10 功能未接入。

```ini
CONFIG_TQ_SCREEN_BACKLIGHT_GPIO=4
CONFIG_TQ_SCREEN_SPI_CS_GPIO=5
CONFIG_TQ_SCREEN_DC_GPIO=6
CONFIG_TQ_SCREEN_RESET_PIN=7
CONFIG_TQ_SCREEN_SPI_MOSI_GPIO=15
CONFIG_TQ_SCREEN_SPI_CLK_GPIO=16
CONFIG_TQ_SCREEN_SPI_MISO_GPIO=-1

CONFIG_TQ_BATTERY_ADC_GPIO=17
CONFIG_TQ_BATTERY_CHARGE_GPIO=18
CONFIG_MULTIMODAL_AUDIO_PA_GPIO=9
CONFIG_TQ_POWER_HOLD_GPIO=-1

CONFIG_TQ_CALIBRATION_SWITCH_GPIO=11
CONFIG_TQ_SLOT_SWITCH_GPIO=12
CONFIG_MULTIMODAL_PTT_BUTTON_GPIO=13
# CONFIG_TQ_RESET_BUTTON_ENABLE is not set

CONFIG_TQ_STEPPER_IN1_GPIO=14
CONFIG_TQ_STEPPER_IN2_GPIO=21
CONFIG_TQ_STEPPER_IN3_GPIO=47
CONFIG_TQ_STEPPER_IN4_GPIO=48
```

平台初始化已停止调用旧 GPIO4/5 输出模块；GPIO8 满电和 GPIO10 马达没有新增配置项。音频 SDA=1、SCL=2、MCLK=38、BCLK=39、DOUT=40、WS=41、DIN=42 保持。

## 实施顺序与验证边界

1. 先在新板配置下禁用旧 GPIO4/5 任务，保持马达默认关闭；必要时首次调试暂时关闭开机转盘校准。
2. 同步 defaults、Kconfig 和本地有效配置，核对 GPIO8/17/18 全部为输入用途、GPIO9 为 PA、GPIO14 无 reset 冲突。
3. 验证 LCD、音频、开关1/2及触摸有效电平，再分别验证步进相序和摇臂马达，最后启用开机校准。
4. 测量 ADC 与 VBAT、充电/充满两路真值表，验证拔插充电、满电提示、低电量及深睡唤醒。
5. 实施后执行 ESP-IDF 5.5.4 构建；修改显示配置/机制后执行仓库列出的五个显示回归脚本，并按实际变更补充检查。检查联网、语音与电机同时运行时的稳定性。
6. 同步 GPIO 两份说明和受影响的中文开发指南；保留旧板版本信息。涉及新增跨层状态时遵守现有电池契约所有权，不在 composition 添加硬件策略。

本次证据层级：两份 PDF 文本提取及关键连线视觉核对、工作区配置和源码静态核对。新板配置的构建与回归记录见下方；没有设备验证结果。

### 2026-10-23 重新切换新板后的验证记录

本次在保留 VAD 重复 PTT 修复和 kikivok.com 域名迁移的基础上重新应用；以下主机测试与构建均已重新执行。

- 现有 27 个 GPIO/PIN 选项数量未变；Kconfig 默认值、sdkconfig.defaults、本地 sdkconfig 一致，已启用的 GPIO 无重复，GPIO8/10 未分配新功能。
- 主机：五个显示回归脚本全部通过，包括脚本自带 profiling 开/关分支；`tools/test_battery_adc_init.py` 通过实际 C 初始化函数的 ADC2/ADC1 单元和通道传递、重复初始化、锁失败、通道/校准失败释放与重试。
- 构建：ESP-IDF 5.5.4 新板有效配置构建通过；应用镜像 3,154,064 B。首次受沙箱 sysctl 权限限制，放宽本地构建权限后完成；未修改工具链或组件管理器。
- 未增加运行时任务、像素/音频缓存或 DMA 缓冲；旧 GPIO4/5 输出任务不再创建。未烧录，尚未确认触摸电平、ADC2 在 Wi-Fi 负载下采样、充电/唤醒、步进方向及显示并行稳定性。