706 lines
20 KiB
Markdown
706 lines
20 KiB
Markdown
# TQ Cat 固件整体架构与运行工作流
|
||
|
||
本文档基于 `feature/st7789p3-new-board` 分支的代码，面向项目接手、问题定位和后续重构。内容以实际函数调用关系为准。
|
||
|
||
## 1. 系统定位
|
||
|
||
项目运行在 ESP32-S3 上，主要负责：
|
||
|
||
- ST7789P3 LCD 表情播放；
|
||
- ES8311 音频采集与播放；
|
||
- Opus 编解码与 WebSocket 多模态对话；
|
||
- TTP223 PTT、SW1、SW2 按键处理；
|
||
- ULN2003 步进电机和转盘校准；
|
||
- Wi-Fi 连接、重连和配置热点；
|
||
- 设备身份、JWT 和会话令牌；
|
||
- 用户出生资料、每日运势和财富方向；
|
||
- NVS、应用内嵌素材、模型分区和工厂 CLI。
|
||
|
||
## 2. 分层架构
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
Main["main / app_main"]
|
||
App["app_composition<br/>启动顺序与应用装配"]
|
||
CP["control_plane<br/>策略、状态机、任务、重试"]
|
||
Domain["domain<br/>方向、校准、运势、表情语义"]
|
||
Platform["platform<br/>GPIO、LCD、音频、网络、存储"]
|
||
HW["ESP32-S3 新板硬件"]
|
||
|
||
Main --> App --> CP --> Domain --> Platform --> HW
|
||
```
|
||
|
||
各层职责：
|
||
|
||
| 层 | 主要职责 | 典型内容 |
|
||
| --- | --- | --- |
|
||
| `main` | 固件入口 | 只调用 composition 入口 |
|
||
| `app_composition` | 决定启动顺序 | 存储、音频、LCD、校准、联网、workers |
|
||
| `control_plane` | 产品策略和生命周期 | Wi-Fi、PTT、多模态、任务、重试、异常恢复 |
|
||
| `domain` | 业务语义和状态 | 方向、角度、校准、运势、LCD 表情映射 |
|
||
| `platform` | 硬件与传输原语 | GPIO、I2S、I2C、SPI、WebSocket、NVS、HTTP |
|
||
|
||
## 3. 启动总流程
|
||
|
||
入口：
|
||
|
||
```text
|
||
app_main()
|
||
└── app_composition_start_default_runtime()
|
||
└── app_composition_run_plan_a_boot_sequence()
|
||
```
|
||
|
||
主要文件：
|
||
|
||
- `main/main.c`
|
||
- `components/app_composition/src/runtime/app_composition_default_runtime.c`
|
||
|
||
启动阶段：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Entry["app_main"]
|
||
Storage["准备 NVS / 文件系统"]
|
||
Audio["初始化音频并播放开机音"]
|
||
LCD["初始化 LCD 和渲染任务"]
|
||
Core["初始化 platform / domain"]
|
||
Expression["请求默认 LCD 表情"]
|
||
Calibration["执行转盘原点校准"]
|
||
WiFi["连接 Wi-Fi 或启动配置 AP"]
|
||
Workers["启动运行时 workers"]
|
||
|
||
Entry --> Storage --> Audio --> LCD --> Core --> Expression --> Calibration --> WiFi --> Workers
|
||
```
|
||
|
||
### 3.1 存储初始化
|
||
|
||
```text
|
||
control_plane_prepare_runtime_storage()
|
||
└── domain_runtime_prepare_storage()
|
||
└── platform_prepare_storage()
|
||
├── nvs_flash_init()
|
||
├── 必要时 nvs_flash_erase()
|
||
├── 再次 nvs_flash_init()
|
||
└── platform_log_nvs_stats()
|
||
```
|
||
|
||
默认 NVS namespace 包括 `wifi`、`ota`、`auth`、`auth_key` 和 `fortune`。
|
||
|
||
### 3.2 音频与开机音
|
||
|
||
```text
|
||
control_plane_play_boot_sound(timeout)
|
||
├── domain_runtime_multimodal_audio_init()
|
||
│ └── platform_multimodal_audio_init()
|
||
│ └── multimodal_audio_init()
|
||
└── domain_runtime_behavior_play_prompt_file(path)
|
||
```
|
||
|
||
`multimodal_audio_init()` 的主要步骤：
|
||
|
||
```text
|
||
fill_codec_sample_info()
|
||
→ audio_init_heap_guard_passed()
|
||
→ init_opus_codec()
|
||
→ init_i2c_bus()
|
||
→ init_i2s_bus()
|
||
→ create_codec_path()
|
||
→ open_codec_device()
|
||
→ apply_codec_default_controls()
|
||
→ ensure_uplink_worker_tasks()
|
||
→ ensure_downstream_playback_task()
|
||
```
|
||
|
||
开机音失败只记录 warning，不会终止启动。
|
||
|
||
### 3.3 LCD 初始化
|
||
|
||
```text
|
||
control_plane_init_lcd_device()
|
||
└── domain_runtime_init_lcd_device()
|
||
└── platform_init_lcd_device()
|
||
└── lcd_direct_init_device()
|
||
├── lcd_direct_gpio_init()
|
||
└── lcd_direct_panel_init()
|
||
```
|
||
|
||
渲染任务：
|
||
|
||
```text
|
||
control_plane_start_lcd_render_worker()
|
||
└── control_plane_lcd_render_loop_task()
|
||
└── control_plane_start_lcd_render_loop()
|
||
└── domain_runtime_start_lcd_render_loop()
|
||
└── platform_start_lcd_render_loop()
|
||
└── lcd_direct_start_render_loop()
|
||
```
|
||
|
||
### 3.4 platform/domain 初始化
|
||
|
||
```text
|
||
control_plane_init()
|
||
├── domain_direction_default_axis_config()
|
||
├── domain_direction_default_calibration()
|
||
└── domain_init(axis_config, calibration)
|
||
├── domain_runtime_platform_init()
|
||
│ └── platform_init()
|
||
│ ├── platform_power_hold_init()
|
||
│ ├── platform_io_effects_init()
|
||
│ ├── platform_stepper_driver_init()
|
||
│ └── platform_stepper_driver_power_off()
|
||
├── 初始化方向状态
|
||
└── domain_calibration_store_set()
|
||
```
|
||
|
||
注意：启动日志将 power hold 描述为已提前拉起，但实际 `platform_power_hold_init()` 位于 `platform_init()` 中。新板应真机验证 GPIO9 拉高时机是否足够早。
|
||
|
||
## 4. 新板关键 GPIO
|
||
|
||
| 功能 | GPIO | 电气语义 |
|
||
| --- | ---: | --- |
|
||
| Power Hold | 9 | 高有效 |
|
||
| LCD CLK | 8 | SPI clock |
|
||
| LCD MOSI | 18 | SPI data |
|
||
| LCD CS | 15 | 低有效 |
|
||
| LCD DC | 16 | 数据/命令 |
|
||
| LCD RESET | 17 | 低有效 reset |
|
||
| LCD Backlight | 7 | 高有效 |
|
||
| TTP223 / PTT | 3 | 高有效，无内部上下拉 |
|
||
| SW1 校准开关 | 12 | 低有效，上拉 |
|
||
| SW2 功能开关 | 13 | 低有效，上拉 |
|
||
| Stepper IN1/2/3/4 | 45/48/47/21 | ULN2003 相线 |
|
||
| Audio PA | 11 | 功放使能 |
|
||
| ES8311 I2C SDA/SCL | 1/2 | codec 控制 |
|
||
| I2S MCLK/BCLK/DOUT/WS/DIN | 38/39/40/41/42 | 音频数据 |
|
||
|
||
## 5. 转盘校准与旋转
|
||
|
||
启动校准调用链：
|
||
|
||
```text
|
||
control_plane_calibrate()
|
||
└── control_plane_calibrate_with_timeout()
|
||
└── control_plane_direction_calibrate_internal()
|
||
└── domain_calibrate_with_timeout()
|
||
```
|
||
|
||
`domain_calibrate_with_timeout()`：
|
||
|
||
```text
|
||
锁定方向状态
|
||
→ prepare_calibration_switch()
|
||
→ 检查 SW1 是否已有效
|
||
→ 循环执行 calibration_rotate_and_track()
|
||
→ calibration_settle()
|
||
→ 再次读取 SW1
|
||
→ 触发后 calibration_return_from_limit()
|
||
→ domain_set_current_angle(home_angle)
|
||
→ domain_runtime_stepper_power_off()
|
||
```
|
||
|
||
底层旋转：
|
||
|
||
```text
|
||
domain_runtime_stepper_rotate_angle_with_accel_timeout()
|
||
└── platform_stepper_rotate_angle_with_accel_timeout()
|
||
└── platform_stepper_driver_rotate_angle_with_accel()
|
||
└── rotate_with_accel()
|
||
├── calculate_motion_segments()
|
||
├── stepper_advance_phase()
|
||
└── precise_delay_us()
|
||
```
|
||
|
||
绝对角度旋转：
|
||
|
||
```text
|
||
control_plane_rotate_to_angle()
|
||
└── domain_rotate_to_angle_with_timeout()
|
||
├── domain_angle_normalize()
|
||
├── domain_angle_shortest_rotation()
|
||
├── 执行电机旋转
|
||
└── 更新 s_current_angle
|
||
```
|
||
|
||
## 6. Wi-Fi 启动与恢复
|
||
|
||
启动入口：
|
||
|
||
```text
|
||
control_plane_bootstrap_connectivity(seed_ssid, seed_password, timeout, "TQ-CAT")
|
||
```
|
||
|
||
调用链：
|
||
|
||
```text
|
||
control_plane_register_wifi_behavior_hooks()
|
||
→ domain_runtime_wifi_portal_init_defaults()
|
||
→ wifi_portal_init_defaults()
|
||
→ 检查已保存凭据
|
||
→ control_plane_connect_sta_with_feedback()
|
||
→ 最多三次 STA 连接
|
||
→ 成功则播放提示音
|
||
→ 失败则按错误类型保留或清除凭据
|
||
→ 必要时启动 TQ-CAT 配置 AP
|
||
```
|
||
|
||
运行时由 `control_plane_wifi_state_task()` 负责：
|
||
|
||
- 检测 Wi-Fi 断开；
|
||
- 等待短暂 disconnect grace；
|
||
- 停止多模态 client 和用户配置 server；
|
||
- 请求断网表情；
|
||
- 按指数退避重连；
|
||
- 重连后恢复 idle 表情、WebSocket 和配置 server；
|
||
- 同时驱动 PTT 状态机。
|
||
|
||
## 7. 运行时任务拓扑
|
||
|
||
入口：
|
||
|
||
```text
|
||
control_plane_start_runtime_workers()
|
||
```
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
Start["control_plane_start_runtime_workers"]
|
||
Model["cp_model_cmd<br/>模型设备命令"]
|
||
WiFi["cp_wifi_state<br/>Wi-Fi、WS、PTT"]
|
||
LCD["cp_lcd_render<br/>LCD 启动"]
|
||
Events["cp_system_event<br/>事件分发"]
|
||
Keys["cp_key_input<br/>GPIO 与消抖"]
|
||
Fortune["cp_fortune<br/>每日运势"]
|
||
Monitor["cp_task_monitor<br/>可选诊断"]
|
||
|
||
Start --> Model
|
||
Start --> WiFi
|
||
Start --> LCD
|
||
Start --> Events
|
||
Start --> Keys
|
||
Start --> Fortune
|
||
Start --> Monitor
|
||
```
|
||
|
||
`control_plane_schedule_websocket_wait_task()` 当前只设置 `s_ws_start_requested = true`，实际 WebSocket 启动由 `cp_wifi_state` 执行。
|
||
|
||
## 8. 按键和系统事件
|
||
|
||
按键中断链路：
|
||
|
||
```text
|
||
GPIO edge
|
||
→ control_plane_key_gpio_isr_handler()
|
||
→ xQueueSendFromISR(s_gpio_irq_queue)
|
||
→ control_plane_key_input_task()
|
||
→ control_plane_process_key_timers()
|
||
→ control_plane_handle_debounced_transition()
|
||
→ control_plane_emit_key_event()
|
||
→ control_plane_post_system_event()
|
||
→ control_plane_system_event_task()
|
||
→ control_plane_dispatch_system_event()
|
||
→ control_plane_dispatch_key_event()
|
||
```
|
||
|
||
事件包括：
|
||
|
||
- `PRESSED`；
|
||
- `RELEASED`；
|
||
- `SHORT_PRESS`；
|
||
- `LONG_PRESS_START`；
|
||
- `LONG_PRESS_RELEASE`；
|
||
- `DOUBLE_CLICK`。
|
||
|
||
行为映射：
|
||
|
||
| 输入 | 行为 |
|
||
| --- | --- |
|
||
| PTT 短按 | `control_plane_set_ptt_active(true)` |
|
||
| PTT 在服务端回复时按下 | `control_plane_multimodal_send_request_to_speak()` |
|
||
| PTT 双击 | 请求 `DOMAIN_EXPRESSION_MUYU` |
|
||
| SW2 单击 | 请求 `DOMAIN_EXPRESSION_CHOUQIAN` |
|
||
| SW2 双击 | 请求 `DOMAIN_EXPRESSION_WUXING` |
|
||
|
||
## 9. PTT 状态机
|
||
|
||
状态：
|
||
|
||
```text
|
||
IDLE
|
||
WAIT_WIFI
|
||
WAIT_WS
|
||
WAIT_START_SENT
|
||
WAIT_LISTENING
|
||
WAIT_SPEECH_STARTED
|
||
STREAMING
|
||
TEARDOWN_LOCAL
|
||
TEARDOWN_REMOTE
|
||
DENIED
|
||
```
|
||
|
||
状态机由 `control_plane_drive_ptt_state_machine()` 在 `cp_wifi_state` 中周期驱动：
|
||
|
||
```text
|
||
无 Wi-Fi → WAIT_WIFI
|
||
无 WebSocket → WAIT_WS
|
||
无 active task → WAIT_START_SENT
|
||
服务端未 Listening → WAIT_LISTENING
|
||
未发送 SendSpeech → WAIT_SPEECH_STARTED
|
||
uplink 已运行 → STREAMING
|
||
释放/超时 → TEARDOWN_LOCAL → TEARDOWN_REMOTE → IDLE
|
||
```
|
||
|
||
每次推进调用 `control_plane_multimodal_handle_ptt_press_step()`，根据当前会话状态选择：
|
||
|
||
- `control_plane_multimodal_send_start()`；
|
||
- `control_plane_multimodal_send_request_to_speak()`；
|
||
- `control_plane_multimodal_send_speech_start()`；
|
||
- `control_plane_multimodal_start_uplink()`。
|
||
|
||
## 10. 设备认证和 WebSocket
|
||
|
||
启动链：
|
||
|
||
```text
|
||
cp_wifi_state
|
||
→ control_plane_try_start_multimodal_from_state_machine()
|
||
→ control_plane_start_multimodal_client()
|
||
→ control_plane_multimodal_start()
|
||
```
|
||
|
||
`control_plane_start_multimodal_client()`：
|
||
|
||
```text
|
||
control_plane_prepare_for_multimodal_start()
|
||
→ 注册 event callback
|
||
→ 注册 downstream audio callback
|
||
→ 创建 mm_watchdog
|
||
→ control_plane_multimodal_start()
|
||
```
|
||
|
||
认证链：
|
||
|
||
```text
|
||
control_plane_multimodal_auth_fetch()
|
||
├── resolve_device_identity()
|
||
├── control_plane_multimodal_device_auth_ensure()
|
||
│ ├── control_plane_multimodal_device_auth_init()
|
||
│ ├── 检查已有 JWT 和 scope
|
||
│ └── refresh_jwt_internal()
|
||
├── control_plane_multimodal_device_auth_copy_jwt()
|
||
├── HTTP POST token endpoint
|
||
├── 401/403 时 invalidate JWT 并重试
|
||
└── parse_token_response()
|
||
```
|
||
|
||
WebSocket 链：
|
||
|
||
```text
|
||
domain_runtime_multimodal_transport_start()
|
||
└── platform_multimodal_transport_start()
|
||
└── multimodal_ws_start()
|
||
├── 停止旧 client
|
||
├── 构造 Authorization 和 Workspace headers
|
||
├── 创建 send mutex
|
||
├── create_worker_pipeline()
|
||
└── start_websocket_client_with_fallback()
|
||
```
|
||
|
||
## 11. 一次完整语音会话
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户/PTT
|
||
participant CP as Control Plane
|
||
participant Session as Session Service
|
||
participant Audio as Audio Pipeline
|
||
participant WS as WebSocket
|
||
participant Server as 服务端
|
||
|
||
User->>CP: 短按
|
||
CP->>Session: send_start()
|
||
Session->>WS: run-task / Start
|
||
Server-->>Session: DialogStateChanged(Listening)
|
||
CP->>Session: send_speech_start()
|
||
CP->>Audio: start_uplink()
|
||
Audio->>WS: Opus binary frames
|
||
Server-->>Session: SpeechEnded / RespondingStarted
|
||
Session->>Audio: stop uplink / begin response
|
||
Server-->>Audio: Opus binary frames
|
||
Audio-->>User: 扬声器播放
|
||
Server-->>Session: RespondingEnded
|
||
Audio-->>Session: playback completed
|
||
Session->>WS: LocalRespondingEnded
|
||
```
|
||
|
||
### 11.1 Start
|
||
|
||
```text
|
||
control_plane_multimodal_send_start()
|
||
→ 生成 task UUID
|
||
→ 构造 run-task / Start JSON
|
||
→ 设置 upstream/downstream Opus 参数
|
||
→ domain_runtime_multimodal_transport_send_text()
|
||
→ 保存 s_task_id
|
||
```
|
||
|
||
### 11.2 开始采集和上行
|
||
|
||
```text
|
||
control_plane_multimodal_send_speech_start()
|
||
→ send_directive("continue-task", "SendSpeech")
|
||
→ control_plane_multimodal_start_uplink()
|
||
→ domain_runtime_multimodal_audio_start_uplink()
|
||
→ multimodal_audio_start_uplink()
|
||
```
|
||
|
||
实时音频：
|
||
|
||
```text
|
||
I2S capture task
|
||
→ PCM 整理
|
||
→ Opus encode
|
||
→ uplink send queue
|
||
→ uplink_send_task
|
||
→ control_plane_audio_uplink_send_cb()
|
||
→ control_plane_multimodal_send_audio_realtime()
|
||
→ multimodal_ws_send_binary_realtime()
|
||
```
|
||
|
||
### 11.3 下行播放
|
||
|
||
```text
|
||
WebSocket binary frame
|
||
→ transport_event_bridge()
|
||
→ control_plane_downstream_audio_bridge()
|
||
→ control_plane_multimodal_play_downstream_audio()
|
||
→ multimodal_audio_handle_downstream_opus()
|
||
→ downstream playback queue
|
||
→ Opus decode
|
||
→ I2S / ES8311 播放
|
||
```
|
||
|
||
服务端 `RespondingEnded` 和本地播放完成都满足后，才发送 `LocalRespondingEnded`。
|
||
|
||
## 12. 服务端事件解析
|
||
|
||
所有文本帧进入 `process_text_json()`，主要处理：
|
||
|
||
- `task-failed`；
|
||
- `task-started`；
|
||
- `DialogStateChanged`；
|
||
- `RequestAccepted`；
|
||
- `RespondingStarted`；
|
||
- `RespondingContent`；
|
||
- `RespondingEnded`；
|
||
- `SpeechStarted`；
|
||
- `SpeechContent`；
|
||
- `SpeechEnded`；
|
||
- `Stopped`；
|
||
- `Error`。
|
||
|
||
回复文本还会进入：
|
||
|
||
```text
|
||
notify_responding_text()
|
||
→ control_plane_responding_text_bridge()
|
||
→ control_plane_extract_model_command()
|
||
→ control_plane_on_model_command()
|
||
→ model command queue
|
||
→ control_plane_model_command_task()
|
||
```
|
||
|
||
设备命令包括方向、校准动作和抽签。
|
||
|
||
## 13. LCD 表情工作流
|
||
|
||
```text
|
||
domain_runtime_request_expression()
|
||
├── domain_resolve_expression_platform_request()
|
||
└── platform_lcd_request_presentation()
|
||
└── lcd_direct_request_presentation()
|
||
```
|
||
|
||
domain 负责把业务语义映射成 platform 播放请求：
|
||
|
||
```text
|
||
IDLE
|
||
SERVER_ERROR
|
||
WIFI_DISCONNECTED
|
||
WEALTH_SPIN
|
||
WEALTH_DIRECTION
|
||
MUYU
|
||
CHOUQIAN
|
||
WUXING
|
||
```
|
||
|
||
platform 只处理：
|
||
|
||
- asset directory；
|
||
- frame index；
|
||
- frame interval；
|
||
- priority；
|
||
- interrupt policy；
|
||
- repeat count；
|
||
- return-to-idle。
|
||
|
||
渲染循环：
|
||
|
||
```text
|
||
lcd_direct_take_pending()
|
||
→ lcd_direct_play_asset_sequence() 或 lcd_direct_play_step_sequence()
|
||
→ lcd_direct_signal_completion()
|
||
→ 无 pending 时播放 basic idle face
|
||
```
|
||
|
||
## 14. 财富方向与运势
|
||
|
||
财富方向动作：
|
||
|
||
```text
|
||
control_plane_apply_wealth_direction()
|
||
├── domain_runtime_preheat_expression(reveal)
|
||
├── 阻塞播放 WEALTH_SPIN
|
||
├── 请求 WEALTH_DIRECTION reveal
|
||
├── 记录 start_angle
|
||
├── 旋转固定角度
|
||
├── 延时
|
||
└── 返回 start_angle
|
||
```
|
||
|
||
当前 `direction_index` 主要选择 LCD 方向资源，电机仍执行固定角度转出再返回，并非直接旋转到方向目录的绝对角度。
|
||
|
||
每日运势 worker：
|
||
|
||
```text
|
||
control_plane_daily_fortune_task()
|
||
├── 等待 birth profile
|
||
├── 等待 Wi-Fi
|
||
├── control_plane_wait_for_synced_time()
|
||
├── 等待 WebSocket TLS 握手稳定
|
||
├── 计算本地日期
|
||
├── control_plane_fortune_fetch()
|
||
├── domain_fortune_result_store_set()
|
||
└── control_plane_apply_wealth_direction()
|
||
```
|
||
|
||
运势 HTTPS 与 WebSocket TLS 握手被有意串行化，以避免内部 DMA RAM 不足。
|
||
|
||
## 15. 局域网用户配置
|
||
|
||
联网后 `control_plane_wifi_state_task()` 启动用户配置 server：
|
||
|
||
```text
|
||
control_plane_ensure_user_config_server()
|
||
└── domain_user_config_server_start()
|
||
└── platform_lan_http_server_start()
|
||
```
|
||
|
||
路由：
|
||
|
||
| 方法 | 路径 | 处理函数 |
|
||
| --- | --- | --- |
|
||
| GET | `/` | `handle_index()` |
|
||
| GET | `/api/profile` | `handle_get_profile()` |
|
||
| POST | `/api/profile` | `handle_post_profile()` |
|
||
| GET | `/api/fortune` | `handle_get_fortune()` |
|
||
|
||
资料更新后：
|
||
|
||
```text
|
||
domain_birth_profile_store_set()
|
||
→ birth profile observer
|
||
→ control_plane_request_fortune_refresh()
|
||
→ 唤醒 cp_fortune
|
||
```
|
||
|
||
## 16. Watchdog 和异常恢复
|
||
|
||
`multimodal_watchdog_task()` 每秒检查：
|
||
|
||
- WebSocket 是否连接；
|
||
- 是否存在 active task；
|
||
- heartbeat 是否到期；
|
||
- 是否长时间没有下行；
|
||
- transport 是否空闲超过 30 秒。
|
||
|
||
处理：
|
||
|
||
```text
|
||
heartbeat 到期
|
||
→ control_plane_multimodal_send_heartbeat()
|
||
|
||
无下行超时
|
||
→ control_plane_multimodal_send_stop("NoResponseTimeout")
|
||
→ stop uplink
|
||
|
||
transport 空闲 30 秒
|
||
→ control_plane_multimodal_stop()
|
||
```
|
||
|
||
WebSocket 断开或错误时，会停止 uplink，并由 `cp_wifi_state` 安排后续重连。
|
||
|
||
## 17. 停止流程
|
||
|
||
```text
|
||
control_plane_stop_runtime_workers()
|
||
├── 设置 runtime stop flag
|
||
├── 停止用户配置 server
|
||
├── 注销模型命令和 profile observer
|
||
├── 停止 key task 和 system event task
|
||
├── 停止 LCD render loop
|
||
├── bounded wait 各 worker
|
||
├── 必要时强制删除 task
|
||
├── 删除 model command queue
|
||
└── control_plane_stop_multimodal_client()
|
||
├── stop_watchdog_task()
|
||
└── control_plane_multimodal_stop()
|
||
├── stop uplink
|
||
├── 停止本地 responding worker
|
||
├── 注销 callbacks
|
||
├── transport_stop(2000)
|
||
└── reset_session_state_locked()
|
||
```
|
||
|
||
## 18. 调试索引
|
||
|
||
遇到问题时先判断属于哪个状态机：
|
||
|
||
1. `control_plane_wifi_state_task()`：Wi-Fi、WebSocket 启动、PTT；
|
||
2. multimodal session：task、Listening、Speech、Responding；
|
||
3. audio pipeline：capture、send queue、decode、playback。
|
||
|
||
推荐排查路径：
|
||
|
||
| 现象 | 优先检查 |
|
||
| --- | --- |
|
||
| 上电后掉电 | GPIO9、`platform_power_hold_init()` 调用时机 |
|
||
| LCD 无显示 | GPIO、`lcd_direct_init_device()`、背光和 SPI |
|
||
| 电机不动 | `platform_stepper_driver_init()`、相序、限位状态 |
|
||
| 开机校准超时 | GPIO12、有效电平、最大 sweep、旋转方向 |
|
||
| PTT 无反应 | ISR queue、消抖、system event、PTT state |
|
||
| 有按键但没录音 | Listening、SendSpeech、audio init、uplink task |
|
||
| 有录音但服务端收不到 | Opus queue、uplink callback、WS binary send |
|
||
| 服务端回复但没声音 | binary callback、decode queue、I2S、PA GPIO11 |
|
||
| 第二轮对话失败 | `s_task_id`、Listening、speech flags、playback completion |
|
||
| 断网不恢复 | `cp_wifi_state`、saved credentials、backoff、WS start request |
|
||
|
||
## 19. 关键源码入口
|
||
|
||
- `main/main.c`
|
||
- `components/app_composition/src/runtime/app_composition_default_runtime.c`
|
||
- `components/control_plane/src/runtime/control_plane_runtime_workers.c`
|
||
- `components/control_plane/src/runtime/control_plane_connectivity_runtime.c`
|
||
- `components/control_plane/src/runtime/control_plane_key_input.c`
|
||
- `components/control_plane/src/runtime/control_plane_system_events.c`
|
||
- `components/control_plane/src/multimodal/control_plane_multimodal_runtime.c`
|
||
- `components/control_plane/src/multimodal/control_plane_multimodal_session_service.c`
|
||
- `components/control_plane/src/multimodal/control_plane_multimodal_auth_service.c`
|
||
- `components/control_plane/src/multimodal/control_plane_multimodal_device_auth.c`
|
||
- `components/domain/src/direction/domain_direction_service.c`
|
||
- `components/domain/src/calibration/domain_calibration_service.c`
|
||
- `components/domain/src/runtime/domain_runtime_adapters.c`
|
||
- `components/platform/src/multimodal/audio_pipeline/audio_pipeline_runtime_impl.c`
|
||
- `components/platform/src/multimodal/transport_ws/transport_ws_runtime_impl.c`
|
||
- `components/platform/src/lcd_direct.c`
|
||
- `components/platform/src/platform_stepper_driver.c`
|