# AILO_Drive_Peeko

**Repository Path**: chging/ailo_drive_peeko

## Basic Information

- **Project Name**: AILO_Drive_Peeko
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Peeko ESP32-S3 动画与传感器固件

基于 ESP-IDF 5.5，在独立工程中移植桌面 `xiaoda/xiaoda_device` 的显示传输、动画播放器、备用表情绘制以及完整动画包。无联网、语音唤醒或云端依赖。

## 当前实现

- **33 个原始动画全部保留**，动画索引和校验值见 `docs/animation-manifest.json`。串口 `demo` 可逐个播放，`clips` 列出全部名称，`clip angry` 等命令可单独播放，`auto` 恢复传感器联动。
- **开机动画播完整段再切换**：boot 片段按一次性播放，结束由播放器的片段完成事件判定（实测 7.42 s），不再用固定 3.5 s 超时截断。20 s 上限只用于兜底（事件丢失或动画包缺失），串口输入 `clip`/`demo` 可以提前打断。
- **串口诊断命令**：`help` 全部列出。`status` 健康行、`pins` 引脚表、`mon [秒]` 每秒 5 次输出加速度/角速度/倾角/lux/双麦 RMS 和音乐判定中间量、`clips`/`clip NAME`/`demo`/`auto` 动画控制、`bright N|auto` 背光、`gain DB` 临时改麦克风增益、`calib` 把当前姿态设为正放、`sim still|move|shake|tilt|music|off` 无传感器时模拟状态、`i2cfind [all]` 搜索 I2C 实际引脚、`i2cid` 列出并识别总线上的器件、`i2creg 地址 [寄存器] [个数]` 读寄存器。开机时配置的 SDA/SCL 无应答会自动执行一次 `i2cfind`。
- **圆屏 GC9A01 / 方屏 ST7789，均为 240×240 SPI 模块**。通过构建配置选择控制器；ST7789 可配置方向、颜色顺序和偏移。其他分辨率及 QSPI/RGB 屏不在当前已实现范围内。
- **OPT3001**：自动检查 0x44–0x47 地址及 TI 制造商/器件 ID；自动量程、800 ms 连续采样；读取就绪和溢出检查；对数亮度映射、死区、渐变 PWM；数据陈旧保持当前亮度并重新初始化。
- **BMI270**：集成 Bosch 官方驱动及初始化固件，自动检查 0x68/0x69；50 Hz 加速度和陀螺仪采样；运动去抖和保持时间；静止→neutral，移动→happy，摇晃→shocked，倾斜→looking。**正放姿态由设备自己学习**：上电后第一个静止姿态即为“正放”，倾斜是相对该姿态偏离约 37°；换了摆放位置后静置约 25 s 会自动跟随，`calib` 可立即重新校准。不再假设 Z 轴朝上，任意安装角度都适用。
- **ES7210**：使用 Espressif codec 驱动，双 ADC、16 kHz / 16 bit 标准立体声 I2S，提供 MCLK，回读接口模式，启动后设置增益；持续处理两个麦克风，不启用 WakeNet/唤醒。地址在 0x40–0x43 内自动查找；麦克风 ADC 必须成对为 1+2（数据在 SDOUT1）或 3+4（数据在 SDOUT2），否则拒绝启动。
- **音乐律动**：检测短时能量、频谱分布及节奏周期；音乐模式优先于运动表情，播放 excited 并叠加 8 段频谱，节拍使表情轻微跳动。连续判定后进入，连续约 3 秒不满足后退出。声音不上传。能量门限用包络（快起慢落约 1 秒），使节拍之间的间隙不被当作静音；节奏周期用平滑后的起音包络自相关（55–190 BPM），避免 32 ms 帧与节拍不整除造成的抖动。

音乐判定是本地信号特征算法，不是已经过真实语料验证的音乐/人声分类模型。合成音频测试不能证明真实音乐识别率；无明显节奏的音乐可能漏判，有节奏的人声或敲击可能误判，必须用实际双麦克风和目标环境校准。

## 接线配置（方案，尚待与实际硬件核对）

检测到的 COM7 芯片是 ESP32-S3（ESP32-S3-DevKitC-1 类开发板，N16R8：8 MB Octal PSRAM、16 MB Quad Flash）。下面的 GPIO 是固件默认值，全部可在 `menuconfig → Peeko ESP32-S3 hardware` 中修改；它们不代表已经确认的现有接线。所有模块共地，全部用开发板 **3V3** 供电，信号电平 3.3 V；不要接 5V。

### 总览

| 接口 | 信号 | 默认 GPIO |
|---|---|---:|
| 共享 I2C（OPT3001 + BMI270 + ES7210 控制） | SDA / SCL | 17 / 18 |
| LCD SPI | SCLK / MOSI / CS | 12 / 11 / 10 |
| LCD | DC / RESET / BLK(PWM) | 9 / 14 / 13 |
| ES7210 I2S | MCLK / BCLK / LRCK / SDOUT→DIN | 4 / 5 / 6 / 7 |

### OPT3001 光照模块 → ESP32-S3

常见的 5 脚模块（VCC / GND / SCL / SDA / INT，ADDR 已在板上固定，通常接 GND 对应 0x44）：

| 模块引脚 | 接到 | 说明 |
|---|---|---|
| VCC | **3V3，不要接 5V** | OPT3001 的 VDD 绝对最大额定值是 4 V，推荐 1.6–3.6 V。板上若没有稳压器（SOT-23 三脚件），接 5V 会直接损坏芯片 |
| GND | GND | 必须与开发板共地 |
| SCL | GPIO18 | 与 BMI270、ES7210 并联 |
| SDA | GPIO17 | 同上 |
| INT | 不接 | 固件轮询转换完成标志，不使用中断 |

模块没有 ADDR 引脚时地址由板上固定，固件会遍历 0x44–0x47 并校验 TI 厂商 ID（0x5449）和器件 ID（0x3001），所以地址不需要配置。

### BMI270 六轴模块 → ESP32-S3

| BMI270 模块引脚 | 接到 | 说明 |
|---|---|---|
| VCC / VIN / VDD | 3V3 | VDD 1.71–3.6 V，VDDIO 1.2–3.6 V；若模块有 VDDIO 单独引脚也接 3V3 |
| GND | GND | 共地 |
| SCL / SCK | GPIO18 | I2C 时钟 |
| SDA / SDI | GPIO17 | I2C 数据 |
| CS | 3V3（或模块默认上拉） | **必须为高电平**才是 I2C 模式；接 GND 会变成 SPI，固件找不到设备 |
| SDO / SA0 | GND 或 3V3 | GND→0x68，3V3→0x69；固件两个地址都会尝试 |
| INT1 / INT2 | 不接 | 固件 50 Hz 轮询数据就绪 |
| SCX / SDX / OCS | 不接 | 这是 BMI270 的辅助传感器总线，不是主机 I2C |

安装方向：默认按 Z 轴向上（芯片面朝天）判断“正放”；倾斜判定是 `az/|a| < 0.55`（约倾斜 57° 以上）。装反或侧装时把模块转到芯片面向上即可，不需要改固件。

### ES7210 双麦克风板 → ESP32-S3

| ES7210 板引脚 | 接到 | 说明 |
|---|---|---|
| 3V3 / VCC | 3V3 | 麦克风板电流小，直接取自开发板 3V3 |
| GND | GND | 共地 |
| SDA | GPIO17 | 与两个传感器共用 I2C |
| SCL | GPIO18 | 同上 |
| MCLK | GPIO4 | 固件输出 4.096 MHz（256×16 kHz） |
| SCLK / BCLK | GPIO5 | 位时钟，固件为主机 |
| LRCK / WS | GPIO6 | 帧时钟 |
| SDOUT1 / DOUT | GPIO7 | 麦克风数据；两颗麦接 MIC1/MIC2 时用 SDOUT1，接 MIC3/MIC4 时用 SDOUT2 并把 menuconfig 的 ADC 改为 3/4 |
| AD0 / AD1 | 默认 | 决定 0x40–0x43，固件自动查找 |

自制麦克风板（BOM：ES7210 + 2×MSM381A3729H9BPC + 8P FPC）没有丝印时，8 根 FPC 线按上表信号对照原理图确认，必须与 `pins` 命令打印的引脚一致。

### LCD（圆屏 GC9A01 / 方屏 ST7789，均 240×240 SPI）

| 屏模块引脚 | 接到 | 说明 |
|---|---|---|
| VCC | 3V3 | |
| GND | GND | |
| SCL / CLK | GPIO12 | SPI 时钟（不是 I2C） |
| SDA / DIN / MOSI | GPIO11 | SPI 数据 |
| RES / RST | GPIO14 | 复位 |
| DC | GPIO9 | 数据/命令 |
| CS | GPIO10 | 模块无 CS 引脚时把 menuconfig 的 CS 设为 -1 |
| BLK / BL | GPIO13 | 背光 PWM，由 OPT3001 调光控制 |

圆屏用根目录 `sdkconfig`（GC9A01，SPI 模式 0），方屏用 `sdkconfig.square`（ST7789，SPI 模式 3，可配置偏移/镜像/颜色顺序）；接错屏型会显示花屏或黑屏。

### 关于上拉与地址冲突

大多数 OPT3001/BMI270/ES7210 模块自带 4.7–10 kΩ 上拉，固件同时启用内部弱上拉；如果三块板都没有上拉，在 SDA、SCL 各加一只 4.7 kΩ 到 3V3。三种器件地址段（0x44–0x47、0x68/0x69、0x40–0x43）互不重叠，可以直接并联。上电后串口会打印 `I2C ACK 0x..`，没有任何应答时固件会自动运行 `i2cfind` 并报告在哪对引脚上发现了设备。

不要占用的 GPIO：0/3/45/46（启动配置）、19/20（USB）、26–37（Flash/PSRAM）、43/44（串口日志）。ES7210 默认地址 0x40、ADC1/ADC2、24 dB；当前支持两 ADC 标准 I2S，不把其他工程的四槽 TDM 顺序直接当作双麦克风顺序。

## 编译

已包含当前用到的本地组件，依赖版本随源代码固定。工具脚本使用本机 `C:\Espressif\frameworks\esp-idf-v5.5.1`。

```powershell
.\tools\idf.ps1 -B build-round build
.\tools\idf.ps1 -B build-square -D 'SDKCONFIG=sdkconfig.square' -D 'SDKCONFIG_DEFAULTS=sdkconfig.defaults;sdkconfig.square.defaults' build
```

圆屏使用根目录 `sdkconfig`，方屏使用 `sdkconfig.square`；更新默认配置不会覆盖已存在配置中的设置。两种配置需要分别核对引脚。

确认接线和控制器后，选对应目录烧写（会写入完整动画分区）：

```powershell
.\tools\idf.ps1 -B build-round -p COM7 -b 460800 flash
.\tools\idf.ps1 -B build-square -D 'SDKCONFIG=sdkconfig.square' -p COM7 -b 460800 flash
```

串口 115200。`status` 输出光照 lux/PWM、运动状态、左右声道 RMS、音乐置信度、动画数及堆内存。`lcd=1` 表示显示软件初始化成功，SPI 屏没有读回时不能证明屏幕已显示正确。

## 验证

```powershell
cmd /c tools\test.cmd
python tools/check_assets.py
```

测试使用与固件相同的 C 算法，覆盖亮度边界/平滑/无效读数、运动去抖/恢复、静音/白噪声/单音/DC/拍手拒绝、合成节奏识别、反相双声道及音乐退出。编译日志和测试结果位于 `docs/`。

### 2026-09-22 传感器接入后的实机结果（COM7）

- I2C 总线上实际应答三个器件：**0x41 ES7210 双麦 ADC**（固件自动找到，配置值 0x40 不必改）、**0x69 BMI270**（chip id 0x24）、**0x18 ES8311 音频 DAC**（本固件不使用）。
- **OPT3001 没有出现在总线上**：0x44–0x47 全部无应答，`i2cid` 只列出上面三个地址。由于同一条 SDA/SCL 上的 ES7210 和 BMI270 工作正常，总线本身没有问题，问题在光照模块自身的供电或连线。健康行会一直是 `light=0 lux=-1.00`，背光保持开机亮度，不做自动调光。
- **BMI270 已实测**：开发板倾斜安装（重力读数 +0.41,-0.82,+0.39 g），学习正放姿态后稳定报 `state=0`（静止），移动时切到 happy；`mon` 中倾角相对正放为 0°。修复前它会永久判定为“倾斜”并卡在 looking 动画。
- **ES7210 双麦已实测**：两路 RMS 同步跟随环境声，安静时约 0.0005，说话/敲击时上升到 0.01–0.02。
- **音乐律动已用真实声学链路验证，并修掉了一个误判缺陷**：
  - 播放 120 BPM 测试曲（`tools/make_music_wav.py` 生成，经 PC 音箱）时，麦克风处 RMS 只有 0.003–0.007（约 −45 dBFS）的低声压，节奏自相关 0.5–0.6，`music=1` 置信度 0.95 以上，屏幕切到 excited 并显示频谱条；曲子结束后约 3 秒退出。最近一次完整回合：进入后连续保持 24 秒，随曲终退出。
  - 首次改进后做 90 秒安静房间对照时发现**误判**：RMS 仅 0.0009（等于本底噪声）也会报 `music=1`。原因是起音包络的缓慢漂移会在所有滞后上产生高自相关。现已在自相关前减去 1 秒滑动均值去除漂移，安静房间的节奏相关度从 0.5–0.84 降到 0.12–0.19；重测 75 秒无任何误判，同时音乐仍能正常识别。
  - 能量门限改用包络（快起、约 0.6 秒慢落）并要求高于本底噪声 3 倍，计数器在静音时按 4/帧快速回落，避免一次响声让判定窗口开着几十秒。
  - 低声压下进入判定需要十几秒；正常听歌音量、设备离音源近时会快得多。人声误判率仍需你用自己的声音实测（播放中用 `mon` 观察 `beat=` 和 `music=`）。
- 麦克风增益默认从 24 dB 提高到 30 dB；`gain DB` 可以在不重新烧写的情况下临时调整。

### 2026-09-21 COM7 实机结果

- 圆屏与方屏两个固件都已烧写到 COM7 的 ESP32-S3 并启动：分区表正确，动画包挂载 33 个动画，`demo` 模式连续运行 31 分钟、切换 374 次覆盖全部 33 个动画均返回 ESP_OK，渲染 35400 帧无复位、无错误，帧统计约 33 ms/帧（渲染 10 ms + SPI 传输 23 ms，40 MHz），内部堆 168 KB、PSRAM 7950 KB 稳定，总空闲堆 8.28 MB 前后一致；`sim music` / `sim shake` / `sim tilt` / `bright` 命令按预期切换动画和背光 PWM。日志见 `docs/monitor-round-*.log`、`docs/monitor-square-1.log`、`docs/soak-round-demo.log`。
- 开发板上**没有连接任何 I2C 设备和 ES7210**：配置引脚（SDA 17 / SCL 18）无应答，`i2cfind all` 遍历全部空闲引脚对也没有设备应答，ES7210 0x40–0x43 无应答。因此 OPT3001 调光、BMI270 运动切换和双麦克风音乐识别只通过了主机端算法测试，尚未在实机验证。
- 屏幕没有读回通道，`lcd=1` 只说明 SPI 初始化和 DMA 传输成功，屏幕实际显示需要人工确认；不清楚当前接的是圆屏还是方屏时，先用 `bright 100` 观察背光是否点亮。

实机验收仍需：两种屏分别显示全部动画；遮光/补光验证亮度平滑变化；移动/摇晃/倾斜验证切换；分别刺激两个麦克风验证声道；播放音乐、人声和环境噪声测量误判与退出；运行至少 30 分钟观察稳定性；断开/重连传感器确认恢复。不能用编译成功代替上述验收。

接好传感器后的最短验收流程：上电看串口是否出现 `I2C ACK 0x44/0x68/0x40` 等地址（没有则看 `i2cfind` 报告的引脚对并改 `menuconfig`）；`status` 中 `light=1 lux=...`、`imu=1`、`mic=1 rms=...` 均非零；用手遮住 OPT3001 看 `pwm` 平滑下降；摇晃看 `motion=2` 并切到 shocked；靠近音箱播放有节奏的音乐约 3 秒看 `music=1` 并出现频谱条。

## 来源

- Xiaoda 本地源码基线 `d89dd36a35a2b30c0cb54e6c2be834a3bc59c3f0`，复制时包含本地工作区实际版本；原项目保持未修改。
- Bosch BMI270 SensorAPI `41129fcfe39c583ee5462d79195741945d51c1fe`：https://github.com/boschsensortec/BMI270_SensorAPI
- TI OPT3001 数据手册：https://www.ti.com/lit/gpn/OPT3001
- Espressif ES7210 驱动：https://github.com/espressif/esp-audio-dev/tree/main/esp_codec_dev/device/es7210 （工程复用本机 ESP-ADF 组件副本）。
- 各第三方组件保留其许可证；根目录保留 Xiaoda 的 Apache-2.0 许可证。