docs: 补充核心分层中文注释

2026-09-29 18:18:44 +08:00
parent a77471a7b1
commit 9fd01bb61b
81 changed files with 1189 additions and 112 deletions
@@ -9,6 +9,11 @@
 extern "C" {
 #endif

+/*
+ * LCD 直接驱动的内部接口。
+ * 面板初始化、渲染任务及 SPI 访问均由本模块独占；platform facade 只做参数透传，
+ * 不复制驱动状态。停止接口采用有界等待，presentation 请求在返回前完成深拷贝。
+ */
 esp_err_t lcd_direct_init_device(void);
 esp_err_t lcd_direct_set_backlight_brightness(uint8_t brightness_percent);
 void lcd_direct_start_render_loop(void);
@@ -7,14 +7,17 @@
 extern "C" {
 #endif

+/* RGB565 图片描述符，实际像素由渲染任务根据路径加载和解码。 */
 typedef struct {
    const char *path;
 } lcd_direct_image_t;

+/* 图标描述符与普通帧分离，便于在主画面之上进行状态叠加。 */
 typedef struct {
    const char *path;
 } lcd_direct_icon_t;

+/* 默认图标序列携带绘制坐标，返回的数组由静态资源表持有。 */
 typedef struct {
    uint16_t icon_id;
    uint16_t x;
@@ -26,6 +29,7 @@ typedef struct {
 #define LCD_DIRECT_ICON_CHARGING 5U
 #define LCD_DIRECT_ICON_LOW_BATTERY 6U

+/* 查找函数返回只读静态描述符；目录、序号或图标不存在时返回 NULL。 */
 const lcd_direct_image_t *lcd_direct_default_image(void);
 const lcd_direct_image_t *lcd_direct_asset_frame(const char *asset_dir, uint8_t frame_index);
 const lcd_direct_icon_t *lcd_direct_icon(uint16_t icon_id);
@@ -10,7 +10,9 @@
 extern "C" {
 #endif

+/* 上行回调接收已经编码的 Opus 包；返回错误会被采集任务记录并按策略处理。 */
 typedef esp_err_t (*multimodal_audio_uplink_cb_t)(const uint8_t *data, size_t len, void *ctx);
+/* PCM 观察者运行在采集任务上下文，必须有界且不可阻塞。 */
 typedef void (*multimodal_audio_pcm_observer_t)(const int16_t *pcm,
                                               size_t samples,
                                               uint32_t sample_rate_hz,
@@ -23,6 +25,7 @@ typedef enum {
    MULTIMODAL_AUDIO_DOWNSTREAM_PLAYBACK_STALLED,
 } multimodal_audio_downstream_playback_event_type_t;

+/* generation 将开始、完成、停止或卡顿事件绑定到唯一一次下行响应。 */
 typedef struct {
    multimodal_audio_downstream_playback_event_type_t type;
    uint32_t playback_generation;
@@ -35,6 +38,7 @@ typedef void (*multimodal_audio_downstream_playback_callback_t)(
 esp_err_t multimodal_audio_init(void);
 void multimodal_audio_deinit(void);

+/* 上行和下行工作任务共享 codec/I2S 资源，但生命周期和停止请求彼此独立。 */
 esp_err_t multimodal_audio_start_uplink(multimodal_audio_uplink_cb_t cb, void *cb_ctx);
 esp_err_t multimodal_audio_stop_uplink(int timeout_ms);
 bool multimodal_audio_is_uplink_running(void);
@@ -48,6 +52,7 @@ esp_err_t multimodal_audio_unregister_pcm_observer(
        void *observer_ctx,
        int timeout_ms);

+/* 下行响应先 begin 建代、持续送入 Opus 包，最后 finish 标记服务端数据结束。 */
 esp_err_t multimodal_audio_handle_downstream_opus(const uint8_t *data, size_t len);
 esp_err_t multimodal_audio_begin_downstream_response(uint32_t *out_playback_generation);
 esp_err_t multimodal_audio_finish_downstream_response(void);
@@ -9,6 +9,7 @@
 extern "C" {
 #endif

+/* 仅描述 WebSocket 传输事件，不携带 domain 层的业务会话语义。 */
 typedef enum {
    MULTIMODAL_WS_EVENT_CONNECTED = 0,
    MULTIMODAL_WS_EVENT_DISCONNECTED,
@@ -17,6 +18,7 @@ typedef enum {
    MULTIMODAL_WS_EVENT_BINARY_MESSAGE,
 } multimodal_ws_event_type_t;

+/* data 指针只在事件回调期间有效，需要异步处理时必须复制。 */
 typedef struct {
    multimodal_ws_event_type_t type;
    const uint8_t *data;
@@ -26,6 +28,7 @@ typedef struct {
 typedef void (*multimodal_ws_event_callback_t)(const multimodal_ws_event_t *event,
                                               void *user_data);

+/* start 复制鉴权信息和回调；stop 负责回收 client、队列及全部工作任务。 */
 esp_err_t multimodal_ws_start(const char *bearer_token,
                              const char *workspace_id,
                              multimodal_ws_event_callback_t cb,
@@ -33,6 +36,7 @@ esp_err_t multimodal_ws_start(const char *bearer_token,
 esp_err_t multimodal_ws_stop(int timeout_ms);
 bool multimodal_ws_is_connected(void);

+/* 普通文本允许内部重试；realtime 接口使用更短锁等待和发送超时以保护实时性。 */
 esp_err_t multimodal_ws_send_text(const char *label, const char *text);
 esp_err_t multimodal_ws_send_text_realtime(const char *label, const char *text);
 esp_err_t multimodal_ws_send_binary_realtime(const uint8_t *data, size_t len);
@@ -2,6 +2,10 @@

 #include <stdint.h>

+/*
+ * 高负载来源使用独立引用计数：同一来源允许嵌套 begin/end，只有全部结束后
+ * 才进入冷却窗口。该状态用于标记采样质量，不直接计算电量百分比。
+ */
 typedef enum {
    PLATFORM_BATTERY_LOAD_AUDIO = 0,
    PLATFORM_BATTERY_LOAD_STEPPER,
@@ -10,13 +10,16 @@
 #include "esp_err.h"
 #include "platform.h"

+/* platform facade 以下的板级驱动入口，不允许被上层组件直接包含。 */
 esp_err_t platform_stepper_driver_init(void);
+/* 旋转调用同步占有运动互斥锁，返回时不会残留后台运动。 */
 esp_err_t platform_stepper_driver_rotate_angle_with_accel(float angle,
                                                          int target_delay_us,
                                                          int timeout_ms);
 esp_err_t platform_stepper_driver_release_hold(int timeout_ms);
 void platform_stepper_driver_power_off(void);
 void platform_power_hold_init(void);
+/* 初始化板级灯带和脉冲输出任务；重复调用由实现保证幂等。 */
 esp_err_t platform_io_effects_init(void);
 esp_err_t platform_digital_input_driver_configure(const platform_digital_input_config_t *config);
 bool platform_digital_input_driver_is_active(const platform_digital_input_config_t *config);
@@ -6,6 +6,10 @@
 extern "C" {
 #endif

+/*
+ * 更新“保持唤醒”状态。true 阻止电源保持 GPIO 进入关断态，false 允许恢复
+ * 低功耗状态；调用方不应直接操作对应 GPIO。
+ */
 void power_manager_set_keep_awake(bool keep_awake);

 #ifdef __cplusplus
@@ -6,6 +6,10 @@
 extern "C" {
 #endif

+/*
+ * 同步播放 LittleFS 中的 Opus 提示音。函数负责分帧、下行播放会话和完成等待，
+ * 返回时文件句柄已关闭；路径解析和播放超时均在实现内处理。
+ */
 esp_err_t voice_prompt_play_file(const char *path);

 #ifdef __cplusplus
@@ -8,6 +8,11 @@
 extern "C" {
 #endif

+/*
+ * Wi-Fi 门户内部契约：封装第三方 wifi-manager、凭据优先级和连接等待。
+ * 所有连接 API 都在调用者给定的超时内结束，返回后不启动隐藏的破坏性重试。
+ * 行为钩子只用于唤醒保持和提示音，具体连接策略仍由 control_plane 拥有。
+ */
 typedef struct {
    void (*set_keep_awake)(bool keep_awake);
    esp_err_t (*play_prompt_file)(const char *path);