Pinion — pi Agent 终端固件

ESP32-P4 掌上设备（720×720 MIPI-DSI 触摸屏）的单一用途固件：开机直接进入 pi-c Agent 对话界面（main/display/screen/pi_screen/）， 通过 DeepSeek API 进行流式对话。没有菜单、没有其他 App —— UI 只有这一个屏。

除了对话，模型还能自己画界面：ui_render 工具让 LLM 吐一份声明式 UI 描述， 设备把它求解成布局、渲染为原生 LVGL 网格卡片，并可绑定实时数据（行情、媒体、 传感器）——设计说明见 docs/AI_TO_UI.md。

本仓库源自 xiaozhi-esp32 的 fork，xiaozhi 业务层已整体删除，硬件能力收敛为可复用 组件 components/metalio_hal/。该重构的权威记录（as-built API、旧→新映射、 能力验收矩阵、资产清理清单）见 docs/EXTRACTION.md。

硬件

部件	说明
主控	ESP32-P4（双核 RISC-V 480 MHz，32 MB Flash，32 MB PSRAM）
屏幕	3.95″ 720×720 MIPI-DSI（NV3051F / FL7707N 面板，运行时探测），GT911 触摸
Wi-Fi	ESP32-C5 协处理器，ESP-Hosted SDIO
4G	NT26 模组（UART eth-modem），网络类型存 NVS "network"/"type"（0=WiFi，1=4G，默认 4G）
音频	蓝牙音频编解码芯片（UART AT 控制）+ I2S 16 kHz 全双工 codec
电源	BQ27220 电量计、无线充电、TCA9555 IO 扩展（电源键/电源轨）

构建与烧录

source ./.idf-env.sh                  # 激活项目本地 ESP-IDF v5.5.4（见下）
idf.py build                          # sdkconfig 已预调好；绝不要运行 idf.py set-target
idf.py -p /dev/ttyACM0 flash monitor  # P4 口 = "USB JTAG/serial debug unit"；Ctrl+] 退出 monitor

• 项目本地 ESP-IDF：.esp-idf/ 与 .idf-env.sh 均不入库。fresh clone 后：
  1. git clone --branch v5.5.4 --depth 1 --recursive --shallow-submodules https://github.com/espressif/esp-idf.git .esp-idf （必须 v5.5.4：managed 依赖 uart-uhci 需要 idf >=5.5.2 的 UHCI driver）；
  2. cd .esp-idf && ./install.sh esp32p4；
  3. 参照 CLAUDE.md 的 "Build / flash" 一节写 .idf-env.sh（导出 IDF_PATH、 IDF_TOOLS_PATH、IDF_PYTHON_ENV_PATH 后 source export.sh）。
• pi-c 依赖：以预编译静态库随仓交付（components/pi_c_prebuilt/，私有上游、 不 vendor 源码）。它是 components/ 下的普通本地组件，无需在 main/idf_component.yml 声明，也不需要把 pi-c 源码仓 clone 到旁边。上游更新后用 components/pi_c_prebuilt/pack_pi_c.sh 重新打包。
• 设备会枚举出四个串口，只对 USB JTAG/serial debug unit 烧录 P4 固件；其余三个 （CH340K = 蓝牙音频芯片，log/at = NT26 4G 模组）属于独立子系统，不要烧。
• sdkconfig 不入库；sdkconfig.defaults 携带全部承重配置（PSRAM/DSI/压缩字体/ ESP-Hosted 引脚等），细节与禁忌见 CLAUDE.md。

首次配置（扫码进设备后台，不改代码不重烧）

固件里不打包任何密钥，克隆后直接 idf.py build 即可。密钥在设备上填、存 NVS：

1. 新设备开机，待机页会显示一张引导卡。没连过 WiFi 就点「开始配网」（设备重启进热点， 扫码连热点后打开 http://192.168.4.1 填 WiFi）。
2. 连上 WiFi 后引导卡显示后台地址二维码，手机扫码（或浏览器打开该地址）。
3. 在「配置」页填两组值，点「保存并重启」：
   • 大模型 — API Key + 模型 ID（都必填，如 deepseek-v4-flash）；Base URL 可选 （默认 https://api.deepseek.com，任何兼容 OpenAI Completions 的端点都行）。想换 供应商或精确控制模型参数，展开「高级」粘一整份 pi-c 格式的 models JSON，它会完全 覆盖上面三项。
   • 语音（火山引擎） — App Key + Access Key。需开通流式语音识别大模型（resource volc.seedasr.sauc.duration）与双向流式语音合成（seed-tts-2.0）；缺这两项只影响 按住说话与朗读，对话仍可用。资源名与音色以宏硬编码在 components/volc_speech/src/ 顶部，换产品改宏即可，详见 docs/VOLC_SPEECH.md。

配置后随时可从快捷面板（PWR_KEY 长按或状态栏下拉）的「后台」重新进入，那页同时管理 SD 卡音乐文件。后台只在 WiFi 下可用（4G 是运营商 NAT，手机连不进设备），10 分钟无请求自停。

模拟器同理：PI_SIM_ADMIN=1 ./sim/build/pi_sim 后开 http://127.0.0.1:8080 配置，值落在 pi_sim_settings.ini 的 cfg.* 键。

代码结构

• main/ — 仅 UI：main.cc（启动链：NVS → mhal::Init() → 加载 pi_screen → mhal::network::StartAsync() → mhal::sysmon::Start()）、 display/screen/pi_screen/（对话 UI + agent 任务）、display/screen/screen_util.*、 3 个压缩 pi 字体。
• components/metalio_hal/ — 硬件库，公共门面头在 include/metalio_hal/： hal.h（一站式初始化）、display.h、backlight.h、network.h（Wi-Fi/4G 双网）、 bluetooth.h、audio.h、power.h、sysmon.h，另有直通头 IOExpander.hpp、 settings.h、audio_codec.h。每个 API 的签名与调用示例见 docs/EXTRACTION.md §2。 lib 不引用任何 UI/业务代码，向上仅通过注册回调通知。

许可

MIT，见 LICENSE。上游致谢（按血缘由近及远）： MetalioClaw4 ← xiaozhi-esp32。