ESP32-S3 API 参考

本文引用的文件

• ai_cloud.py

• ATGM336H_5N.py

• max30102.py

• xgo.py

• lv_utils.py

• xunfei.py

• espnow.py

• hrcalc.py

产品概述

本参考聚焦于 ESP32-S3 产品线（掌控板3.0、乐动掌控2.0等）的专属API，重点覆盖新增模块与能力：AI云端交互、GNSS定位（北斗/GPS）、心率血氧传感、机器狗控制、LVGL事件循环工具，以及与ESP32版API的差异要点。文档面向K12创客教育场景，帮助开发者快速理解各模块职责、调用方式与注意事项。

核心业务流程

• AI语音识别与问答流程（百度语音+文心大模型）

  • 录音文件转Base64并请求百度语音识别接口，返回文本；再调用文心对话接口获取回答。

  • 关键节点：鉴权token获取、音频文件读取、HTTP POST请求、JSON解析。

• GNSS定位数据读取与解析流程（ATGM336H）

  • UART读取原始NMEA帧，过滤RMC与BDGSA段，解析时间、经纬度、速度、日期及卫星信息。

  • 关键节点：串口缓冲、ASCII解码容错、字段截取与校验、数据有效性标志。

• 心率血氧测量流程（MAX30102 + hrcalc）

  • I2C初始化设备，周期性读取FIFO红/红外光值，使用算法计算HR与SpO2，输出有效结果或错误码。

  • 关键节点：寄存器配置、FIFO采样、峰值检测、比值计算与阈值判定。

• 机器狗控制流程（XGO）

  • 通过串口协议发送指令控制移动、姿态、动作、舵机角度、电池与固件信息等。

  • 关键节点：命令封装与校验、参数范围映射、响应解包与超时处理。

• LVGL事件循环流程

  • 基于定时器或uasyncio驱动LVGL tick与任务处理，支持同步/异步刷新回调。

  • 关键节点：lv.init、tick_inc、task_handler、异常捕获与自动停止。

sequenceDiagram
participant App as "应用"
participant AI as "AI云端模块"
participant HTTP as "网络请求"
App->>AI : 调用 get_text(录音文件)
AI->>HTTP : 获取访问令牌
HTTP-->>AI : 返回 token
AI->>HTTP : POST 语音识别接口
HTTP-->>AI : 返回识别结果
App->>AI : 调用 get_answer(文本)
AI->>HTTP : POST 文心对话接口
HTTP-->>AI : 返回回答文本
AI-->>App : 返回最终答案

图表来源

• ai_cloud.py:18-24

• ai_cloud.py:69-92

• ai_cloud.py:94-122

章节来源

• ai_cloud.py:18-24

• ai_cloud.py:69-92

• ai_cloud.py:94-122

功能模块清单

• AI云端模块（ai_cloud.py）

  • 职责：提供语音识别与文心问答的便捷接口，封装鉴权、HTTP请求与JSON解析。

  • 用户价值：简化云端AI集成，降低网络与协议复杂度。

  • 验收要点：token获取成功、识别结果正确、问答返回合理文本；异常时打印错误并抛出提示。

• GNSS定位模块（ATGM336H_5N.py）

  • 职责：UART读取NMEA数据，解析RMC与BDGSA，输出时间、经纬度、速度与日期。

  • 用户价值：为位置服务、轨迹记录、导航类项目提供基础定位能力。

  • 验收要点：能稳定读取RMC/BDGSA，解析出有效坐标与UTC时间，具备无效数据处理逻辑。

• 心率血氧模块（max30102.py + hrcalc.py）

  • 职责：I2C驱动MAX30102，采集PPG信号，计算心率与血氧浓度。

  • 用户价值：健康类项目的基础生理指标采集。

  • 验收要点：设备可扫描到，FIFO数据可读，HR/SpO2在合理范围内且带有效性标识。

• 机器狗控制模块（xgo.py）

  • 职责：通过串口协议控制XGO机器狗的运动、姿态、动作、舵机、电池与固件信息。

  • 用户价值：机器人教学与竞赛的核心控制库。

  • 验收要点：指令发送与响应校验通过，参数范围限制生效，读回数据准确。

• LVGL事件循环工具（lv_utils.py）

  • 职责：提供LVGL定时刷新与任务调度，支持同步/异步模式与异常处理。

  • 用户价值：统一GUI刷新机制，避免阻塞与内存分配问题。

  • 验收要点：lv.init后tick正常推进，task_handler执行，异常被捕获并安全停止。

• 讯飞语音模块（xunfei.py）

  • 职责：基于WebSocket实现语音识别（IAT）与语音合成（TTS），含鉴权签名。

  • 用户价值：在线语音能力扩展，适合语音交互项目。

  • 验收要点：WebSocket连接建立成功，音频流分段发送，识别结果拼接正确，TTS音频下载完成。

• ESP-NOW通信模块（espnow.py）

  • 职责：封装底层ESPNowBase，提供无连接短报文收发与迭代接收。

  • 用户价值：低功耗、低延迟的局域网通信方案。

  • 验收要点：发送与接收字节流正确，超时处理合理，迭代器模式可用。

章节来源

• ai_cloud.py:18-24

• ai_cloud.py:69-92

• ai_cloud.py:94-122

• ATGM336H_5N.py:29-165

• ATGM336H_5N.py:198-388

• max30102.py:39-168

• hrcalc.py:13-105

• xgo.py:123-787

• lv_utils.py:43-142

• xunfei.py:65-229

• espnow.py:6-41

数据与状态

• AI云端模块

  • 输入：录音文件路径、文本内容；配置：API_KEY/SECRET_KEY。

  • 输出：识别文本、问答回答；状态：token缓存、请求头设置。

  • 边界：网络可达性、云端限流与鉴权失败需重试或降级。

• GNSS定位模块

  • 输入：UART原始NMEA帧；状态：是否解码、是否解析、数据有效性标志。

  • 输出：UTC时间、经纬度（度分格式与十进制）、速度（节与km/h）、日期、卫星PRN列表。

  • 边界：非ASCII字符容错、RMC/BDGSA缺失时的空值处理。

• 心率血氧模块

  • 输入：I2C FIFO红/红外光值序列；状态：设备初始化、测量进行中。

  • 输出：HR（bpm）、SpO2（%）及有效性；内部状态：ir_D/red_D均值。

  • 边界：采样时长约30秒，异常时返回None或错误码。

• 机器狗控制模块

  • 输入：运动方向/步数、姿态角度、动作ID、舵机角度、电池查询等。

  • 输出：固件版本、电池电量、IMU角度（roll/pitch/yaw）、舵机角度。

  • 状态：协议帧解析状态机、超时与校验失败处理。

• LVGL事件循环

  • 输入：频率、定时器ID、刷新回调、异常处理器。

  • 输出：LVGL任务处理、UI刷新；状态：运行中/已停止、嵌套计数。

  • 边界：缺少uasyncio时仅支持同步模式；异常时自动deinit。

• 讯飞语音模块

  • 输入：音频文件或文本；状态：WebSocket连接、消息帧状态（首帧/中间帧/末帧）。

  • 输出：识别结果字符串、TTS音频文件。

  • 边界：鉴权签名生成、RTC时间获取、网络稳定性。

• ESP-NOW模块

  • 输入：目标地址、数据长度、格式；状态：接收缓冲区、迭代器状态。

  • 输出：字节流或浮点数（可选格式化）；状态：超时与空结果。

  • 边界：MAX_DATA_LEN限制、字节序转换。

章节来源

• ai_cloud.py:18-24

• ai_cloud.py:69-92

• ai_cloud.py:94-122

• ATGM336H_5N.py:29-165

• ATGM336H_5N.py:198-388

• max30102.py:39-168

• hrcalc.py:13-105

• xgo.py:123-787

• lv_utils.py:43-142

• xunfei.py:65-229

• espnow.py:6-41

关键约束与边界

• 网络与云端依赖

  • AI云端与讯飞语音均依赖WiFi与互联网，需确保网络连通与鉴权配置正确；云端限流或故障时应做重试与降级策略。

• 硬件资源与引脚

  • GNSS使用UART（默认UART1，TX/RX可配），注意引脚冲突；MAX30102使用I2C，需确认设备地址与总线空闲。

  • XGO通过串口通信，注意波特率与协议帧校验；LVGL事件循环占用定时器或协程资源。

• 数据有效性与容错

  • GNSS数据需检查RMC有效性标志，缺失时返回占位值；心率血氧测量需要稳定接触与足够采样时长。

  • LVGL事件循环在异常时自动停止，避免死锁；ESP-NOW接收有超时与空结果处理。

• 性能与实时性

  • 心率血氧测量约30秒，期间应避免阻塞其他任务；LVGL刷新频率建议根据屏幕与任务负载调整。

  • XGO指令发送间隔与最小时间参数影响运动平滑性，需按实际硬件调优。

章节来源

• ai_cloud.py:69-92

• xunfei.py:65-229

• ATGM336H_5N.py:29-165

• max30102.py:133-168

• xgo.py:610-688

• lv_utils.py:43-142

• espnow.py:14-41