17 KiB
新旧板 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 | PTT 约 195 行；音频约 211 行；LCD/电机/电池约 298–346 行 | 保存新板默认引脚；保持其他未提交配置 |
| main/Kconfig.projbuild | 文件顶部 Board Hardware Configuration (GPIO) 菜单 |
已同步现有项新板默认值及帮助文案；新功能未加选项 |
| lcd_direct.c | 约 1634 行背光、1660 行 GPIO、1680 行后 SPI/panel 初始化 | 引脚已有配置化，通常不改驱动；新图注明 BLK 仅作使能，先用 0/100% 验证，不能直接认定支持调光 |
| platform_io_effects.c | 30/31 行 GPIO4/5 硬编码；186 行脉冲任务；277 行初始化 | 这是必须处理的代码冲突。先禁用旧 RMT/脉冲启动，再决定马达 GPIO10 的受控实现 |
| platform_core_runtime.c | platform_init() 电源保持初始化之后 |
已移除旧 GPIO4/5 功能的启动调用；GPIO10 马达未启用 |
| platform_stepper_driver.c | 34–37 行相位宏；331 行 GPIO 初始化 | 使用 Kconfig，不应改相位表来代替正确引脚配置 |
| platform_battery_driver.c | 约 136 行状态输入；158 行 ADC 映射；296 行采样状态 | 迁移 ADC/充电输入；新增独立充满输入及原始样本处理 |
| platform.h | 约 406 行电池硬件样本契约 | 如接入充满检测，扩展平台硬件样本，保留未知/无效状态 |
| domain.h / domain_battery_service.c | 领域电池语义；样本到领域状态映射；约 363 行深睡调用 | 领域层拥有充电/满电语义，不能由显示层直接读取 GPIO8 判断 |
| control_plane_battery_service.c | 104 行起充电中断；约 400 行后满电推断/提示 | 迁移充电引脚配置自动覆盖现有中断；若新增满电检测，调整确认/提示策略和相应事件来源 |
| domain_runtime_adapters.c | 807 / 836 / 865 行三路数字输入映射 | 已读取配置，单纯迁脚通常无需改；核对 PTT 有效电平 |
| control_plane_key_input.c | 158 行起 s_key_configs |
同步核对三路按键及可选 reset，不把两个功能配置到同一 GPIO |
| audio_pipeline_codec_impl.c | 148 行 I2C；223 行 I2S；318 行 PA | I2C/I2S 不变，PA 配置迁移到 9 |
| audio_pipeline_runtime_impl.c | 约 1536 行 PA 开关 | 已使用 PA 配置；与 codec 初始化共同核对 |
| platform_behavior_stubs.c | 57 行起 power hold | 保持 TQ_POWER_HOLD_GPIO=-1，新板没有 MCU 电源保持控制网 |
| gpio-map.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 功能未接入。
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 保持。
实施顺序与验证边界
- 先在新板配置下禁用旧 GPIO4/5 任务，保持马达默认关闭；必要时首次调试暂时关闭开机转盘校准。
- 同步 defaults、Kconfig 和本地有效配置，核对 GPIO8/17/18 全部为输入用途、GPIO9 为 PA、GPIO14 无 reset 冲突。
- 验证 LCD、音频、开关1/2及触摸有效电平，再分别验证步进相序和摇臂马达，最后启用开机校准。
- 测量 ADC 与 VBAT、充电/充满两路真值表，验证拔插充电、满电提示、低电量及深睡唤醒。
- 实施后执行 ESP-IDF 5.5.4 构建；修改显示配置/机制后执行仓库列出的五个显示回归脚本，并按实际变更补充检查。检查联网、语音与电机同时运行时的稳定性。
- 同步 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 负载下采样、充电/唤醒、步进方向及显示并行稳定性。