小智 ESP32 接入 EDA-Super-Bear 机器熊：从分区表配置到 MCP 动作控制全解析
【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32
EDA-Super-Bear（机器熊）是立创 EDA 课程项目中的双足舵机机器人，在本仓库中它作为一块独立的 ESP32-S3 开发板被完整接入 xiaozhi-esp32 语音助手固件，通过 MCP（Model Context Protocol）工具集实现"语音指令 → 机器人动作"的闭环。本文以该板卡的 README 文档 为骨架，结合仓库内的 config.h、eda_super_bear.cc、eda_super_bear_controller.cc 与 eda_super_bear_movements.cc 等源码，完整讲解该板卡的硬件引脚、编译分区配置、MCP 工具注册机制与底层步态运动学原理，读完即可独立完成烧录与二次开发。
一、板卡概览：一台能"听懂人话"的双足机器熊
EDA-Super-Bear 是立创 EDA 课程项目（Smart Internet 系列）的机器熊，结构上属于经典的 Otto 类双足机器人：两条腿各由大腿（leg）与脚掌（foot）两个舵机驱动，可选配左右手舵机。在本仓库中，它被封装为一块标准的 xiaozhi-esp32 开发板，目标芯片为ESP32-S3，由 config.json 声明：
{ "manufacturer": "lceda-course-examples", "type": "eda-super-bear", "target": "esp32s3", "builds": [ { "name": "eda-super-bear", "sdkconfig_append": [ "CONFIG_PARTITION_TABLE_CUSTOM_FILENAME=\"partitions/v1/16m.csv\"" ] } ] }其板级接入入口在 eda_super_bear.cc：EdaSuperBear类继承自WifiBoard，通过DECLARE_BOARD(EdaSuperBear)注册到固件框架。它的角色定位很特别：
- 无物理显示屏：
InitializeDisplay()中直接使用NoDisplay，开机日志会打印"使用NoDisplay (无物理显示屏)"； - 语音不经过本机扬声器：音频编解码使用
NoAudioCodecSimplex，麦克风采集的音频照常上传云端，但音频输出走云端 TTS 后由用户侧设备播放； - 动作全部交给 MCP 工具：构造函数末尾调用
InitializeEdaSuperBearController()，注册一套完整的self.edarobot.*MCP 工具，大模型根据对话语义直接调用这些工具驱动舵机。
从源码结构看，该板卡的"交互界面"不是屏幕而是身体语言——机器人通过行走、转身、跳跃、挥手等动作对用户做出反馈。
二、硬件引脚配置详解
板卡的硬件映射全部集中在 config.h，包括 6 路舵机、I2S 音频与按键：
#define RIGHT_LEG_PIN GPIO_NUM_11 #define RIGHT_FOOT_PIN GPIO_NUM_14 #define LEFT_LEG_PIN GPIO_NUM_13 #define LEFT_FOOT_PIN GPIO_NUM_12 #define LEFT_HAND_PIN GPIO_NUM_21 #define RIGHT_HAND_PIN GPIO_NUM_10 #define AUDIO_INPUT_SAMPLE_RATE 16000 #define AUDIO_OUTPUT_SAMPLE_RATE 24000 #define AUDIO_I2S_METHOD_SIMPLEX #define AUDIO_I2S_MIC_GPIO_WS GPIO_NUM_40 #define AUDIO_I2S_MIC_GPIO_SCK GPIO_NUM_39 #define AUDIO_I2S_MIC_GPIO_DIN GPIO_NUM_41 #define AUDIO_I2S_SPK_GPIO_DOUT GPIO_NUM_47 #define AUDIO_I2S_SPK_GPIO_BCLK GPIO_NUM_48 #define AUDIO_I2S_SPK_GPIO_LRCK GPIO_NUM_45 #define TOUCH_BUTTON_GPIO GPIO_NUM_14 #define BOOT_BUTTON_GPIO GPIO_NUM_38 #define EDA_SUPER_BEAR_VERSION "1.0.0"要点说明：
| 类别 | 引脚 | 用途 |
|---|---|---|
| 舵机 | GPIO 13 / 11 | 左 / 右大腿（leg） |
| 舵机 | GPIO 12 / 14 | 左 / 右脚掌（foot） |
| 舵机 | GPIO 21 / 10 | 左 / 右手（hand，可选） |
| 音频输入 | GPIO 39 / 40 / 41 | I2S 麦克风 SCK / WS / DIN，16 kHz 采样 |
| 音频输出 | GPIO 48 / 45 / 47 | I2S 扬声器 BCLK / LRCK / DOUT，24 kHz 采样 |
| 按键 | GPIO 38 | BOOT 键，用于配网与对话开关 |
在 eda_super_bear.cc 中，BOOT 按键被复用为交互入口：设备处于kDeviceStateStarting状态时单击进入 Wi-Fi 配网模式，否则单击切换对话状态（app.ToggleChatState()）。手部舵机是可选项——eda_super_bear_movements.h 中Init()的left_hand/right_hand参数默认值为-1，控制器会根据LEFT_HAND_PIN != -1 && RIGHT_HAND_PIN != -1判断是否启用全部手部动作，因此无手版机器熊也能正常编译运行。
三、编译配置：按模组 Flash 容量选择分区表
这是原 README 的核心实操内容：Flash 大小需按 ESP32-S3 模组实际容量调整分区表。README 给出的示例是模组 Flash 为 8MB 时，在 ESP-IDF 的 menuconfig 中进行如下配置：
Partition Table ---> Partition Table (Custom partition table CSV) ---> (partitions/v2/8m.csv) Custom partition CSV file即把分区表指定为仓库根目录下的 partitions/v2/8m.csv。该文件的内容如下：
# ESP-IDF Partition Table # Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x4000, otadata, data, ota, 0xd000, 0x2000, phy_init, data, phy, 0xf000, 0x1000, ota_0, app, ota_0, 0x20000, 0x2f0000, ota_1, app, ota_1, , 0x2f0000, assets, data, spiffs, 0x600000, 2M它采用双 OTA 分区（ota_0/ota_1各约 3MB），并预留 2MB 的assetsSPIFFS 分区存放语音提示等资源。这里需要留意两处细节：
- 默认值与 README 示例的差异：仓库的 config.json 在
sdkconfig_append中默认写入的是partitions/v1/16m.csv（面向 16MB 模组）。因此如果手头模组 Flash 不足 16MB（例如 8MB 的常见 ESP32-S3 模组），就必须按 README 的指引通过 menuconfig 手工切换分区表，否则固件烧录或 OTA 会出现空间不足问题。 - 分区表可选范围：仓库在 partitions/v2 目录下提供
4m.csv、8m.csv、16m.csv、32m.csv以及 ESP32-C3 专用的16m_c3.csv，在 v1 目录下还保留了4m.csv、8m.csv、16m.csv、32m.csv及带自定义唤醒词/回声消除（16m_custom_wakeword.csv、16m_echoear.csv）的变体，可按模组实际 Flash 容量与功能需求选择。
编译时，main/CMakeLists.txt 中通过CONFIG_BOARD_TYPE_EDA_SUPER_BEAR将BOARD_DIR指向lceda-course-examples/eda-super-bear，固件构建系统据此自动纳入该板卡的源码与配置。
四、MCP 工具集：大模型如何指挥机器熊
EDA-Super-Bear 接入的核心亮点是MCP 工具注册机制。控制器 eda_super_bear_controller.cc 在构造时调用RegisterMcpTools()，通过McpServer::GetInstance().AddTool(...)向 MCP Server 注册 17 个动作枚举与 10 余个工具，云端大模型（LLM）在对话中按需调用这些工具，实现"说一句话，机器人动一下"。
4.1 动作分类与 MCP 工具清单
动作在内部以枚举ActionType编号（1~17），控制器通过 FreeRTOS 队列（容量 10 条）串行投递执行，避免多个动作互相抢占舵机：
| 枚举 | 编号 | MCP 工具 | 关键参数（默认值/范围） | 说明 |
|---|---|---|---|---|
| ACTION_WALK | 1 | self.edarobot.walk_forward | steps=3(1-100), speed=1000(500-1500), arm_swing=50(0-170), direction=1(-1后退/1前进) | 前进/后退行走 |
| ACTION_TURN | 2 | self.edarobot.turn_left | steps=3, speed=1000, arm_swing=50, direction=1(1左转/-1右转) | 原地转身 |
| ACTION_JUMP | 3 | self.edarobot.jump | steps=1(1-100), speed=1000 | 跳跃 |
| ACTION_SWING | 4 | self.edarobot.swing | steps=3, speed=1000, amount=30(0-170) | 左右摇摆 |
| ACTION_MOONWALK | 5 | self.edarobot.moonwalk | steps=3, speed=1000, direction=1, amount=25 | 太空步 |
| ACTION_BEND | 6 | self.edarobot.bend | steps=1, speed=1000, direction=1 | 左右侧弯 |
| ACTION_SHAKE_LEG | 7 | self.edarobot.shake_leg | steps=1, speed=1000, direction=1(1左腿/-1右腿) | 摇腿 |
| ACTION_UPDOWN | 8 | self.edarobot.updown | steps=3, speed=1000, amount=20 | 上下起伏 |
| ACTION_TIPTOE_SWING | 9 | 无独立工具（由控制器内部可达） | steps, speed, amount | 踮脚摇摆 |
| ACTION_JITTER | 10 | 无独立工具 | steps, speed, amount | 抖动 |
| ACTION_ASCENDING_TURN | 11 | 无独立工具 | steps, speed, amount | 上升转身 |
| ACTION_CRUSAITO | 12 | 无独立工具 | steps, speed, amount, direction | 太空步+行走混合 |
| ACTION_FLAPPING | 13 | 无独立工具 | steps, speed, amount, direction | 扑翼动作 |
| ACTION_HANDS_UP | 14 | self.edarobot.hands_up | speed=1000, direction=1(1左手/-1右手/0双手) | 举手 |
| ACTION_HANDS_DOWN | 15 | self.edarobot.hands_down | speed=1000, direction=1 | 放手 |
| ACTION_HAND_WAVE | 16 | self.edarobot.hand_wave | speed=1000, direction=1 | 挥手 |
| ACTION_HOME | 17 | 复位（stop 工具内部调用） | direction=1 | 回到站立姿态 |
注：部分动作枚举（如 TiptoeSwing、Jitter、AscendingTurn、Crusaito、Flapping）已具备底层运动函数，但当前仅注册了面向对话的常用工具子集，开发者可在RegisterMcpTools()中按同样模式补充暴露。手部动作（14~16）仅在has_hands_为真时注册，无手版调用会被QueueAction()拦截并打印"尝试执行手部动作，但机器人没有配置手部舵机"。
速度参数的语义需要特别注意：数值越小动作越快（500 最快、1500 最慢），因为它直接对应EdaRobot运动函数中的period（周期，单位毫秒）。
4.2 工具参数描述如何"喂"给大模型
AddTool的参数描述是 MCP 与 LLM 交互的关键。以 walk_forward 为例，工具描述字符串完整给出了每个参数的语义与范围：
mcp_server.AddTool("self.edarobot.walk_forward", "行走。steps: 行走步数(1-100); speed: 行走速度(500-1500，数值越小越快); " "direction: 行走方向(-1=后退, 1=前进); arm_swing: 手臂摆动幅度(0-170度)", PropertyList({Property("steps", kPropertyTypeInteger, 3, 1, 100), Property("speed", kPropertyTypeInteger, 1000, 500, 1500), Property("arm_swing", kPropertyTypeInteger, 50, 0, 170), Property("direction", kPropertyTypeInteger, 1, -1, 1)}), this -> ReturnValue { ... });Property的五个参数依次为：名称、类型（kPropertyTypeInteger/kPropertyTypeString）、默认值、最小值、最大值。这样大模型既能看到自然语言说明，又能拿到结构化的数值约束，从而生成合法调用。
4.3 状态查询与电池工具
除运动工具外，控制器还注册了 4 个系统级工具：
self.edarobot.stop：立即停止——删除动作任务、清空队列并回到站立姿态；self.edarobot.set_trim：校准单个舵机，见下文第五节；self.edarobot.get_trims：查询全部舵机微调值；self.edarobot.get_status：返回moving或idle；self.battery.get_level：通过Board::GetInstance().GetBatteryLevel()返回{"level":xx,"charging":true/false}。
动作执行的底层是ActionTask任务（栈 3KB、优先级configMAX_PRIORITIES - 1）：循环从队列取参数，先AttachServos()挂载舵机，按switch(action_type)分派到EdaRobot的运动函数；除ACTION_HOME外，每个动作结束后自动调用Home()复位，保证机器人始终回到稳定站姿。
五、运动学底层：Oscillator 正弦振荡器与步态合成
机器熊的"舞步"并非逐帧硬编码，而是建立在正弦振荡器模型之上，这一思路源自 Otto 系列机器人（oscillator.h 标注了 Obijuan 2011 的原始实现与 txp666 的 ESP32 移植）。
5.1 振荡器模型
每个舵机由一个Oscillator实例驱动，其输出角度由四个参数决定：
A（amplitude）：振幅，单位度；O（offset）：偏移，单位度；T（period）：周期，单位毫秒；Ph（phase0）：初始相位，单位弧度（DEG2RAD宏转换）。
EdaRobot::OscillateServos()将每个舵机的 A/O/T/Ph 设置好后，在period * cycle时间内每 5ms 调用一次servo_[i].Refresh()刷新所有舵机角度。Execute()则按steps拆分为整数个完整周期加一个尾周期执行。
舵机角度输出还经过两个保护机制（见 oscillator.h）：PWM 脉宽限制在 500~2500 微秒（对应 -90°~+90°），以及默认 240°/秒 的角速度限制器（SERVO_LIMIT_DEFAULT），防止舵机瞬间大幅跳变损坏齿轮。
5.2 步态即相位差组合
以最常用的Walk为例（eda_super_bear_movements.cc），腿部四个舵机的振荡参数为：
int A[SERVO_COUNT] = {30, 30, 30, 30, 0, 0}; // 大腿、脚掌振幅 30° int O[SERVO_COUNT] = {0, 0, 5, -5, ...}; // 脚掌轻微偏置，模拟踮脚 double phase_diff[SERVO_COUNT] = {0, 0, DEG2RAD(dir * -90), DEG2RAD(dir * -90), 0, 0};行走的关键在于：大腿与脚掌相位差 90°——dir=1时脚掌相位为 -90°，dir=-1时变为 +90°，从而决定前进还是后退。转向Turn则把一侧大腿振幅置 0、另一侧置 30°，利用左右步幅差走出弧线。
手部摆动（arm_swing > 0且装有手部舵机时）也遵循真实步态的相位关系：
- 行走时左手与右腿同相、右手与左腿同相（交叉摆臂）；
- 转向时左手与左腿同相、右手与右腿同相（增强转向效果）。
类似地，Moonwalker（太空步）利用两脚 60° 相位差形成"蠕虫式"行波，Jitter让双腿 180° 反相抖动，AscendingTurn叠加腿脚同幅反相实现边升边转——每个动作本质上都是(振幅, 偏移, 周期, 相位差)四元组的组合，理解这一点后，开发者可以轻松在EdaRobot中组合出新动作。
六、舵机姿态校准：set_trim 与 NVS 持久化
机器熊使用廉价舵机，装配误差会导致站姿歪斜，因此控制器提供了基于 MCP 的在线校准能力。校准值存储在 NVS 命名空间edarobot_trims中（通过项目封装的 Settings 读写），LoadTrimsFromNVS()在启动时加载并调用edarobot_.SetTrims(...)生效。
校准流程（全部通过语音对话完成）：
- 让大模型调用
self.edarobot.get_trims查看当前微调值（返回 JSON，如{"left_leg":0,...,"right_hand":0}）； - 调用
self.edarobot.set_trim，指定servo_type（left_leg/right_leg/left_foot/right_foot/left_hand/right_hand）和trim_value（-50~50 度）； - 工具内部更新对应微调值、写入 NVS 永久保存，并以一次跳跃（
ACTION_JUMP）作为动作反馈，同时返回类似"舵机 left_leg 微调设置为 5 度，已永久保存"的文本供大模型向用户播报。
实现细节上，SetTrims只对手部舵机存在时（has_hands_）应用手部微调；若对无手版调用left_hand/right_hand校准，会返回"错误：机器人没有配置手部舵机"。舵机 0°~180° 的脉宽映射、微调叠加都在 oscillator.cc 的AngleToCompare与SetTrim中完成。
七、总结
EDA-Super-Bear 板卡展示了 xiaozhi-esp32 框架的"万能外设"扩展思路：一个没有屏幕、甚至不需要本机发声的双足机器人，通过继承WifiBoard+ 注册 MCP 工具，即可无缝接入语音对话链路，让大模型直接"操控"硬件。三个层面的知识可以沉淀复用：
- 接入层面：仿照 eda_super_bear.cc 继承
WifiBoard并DECLARE_BOARD，在 main/CMakeLists.txt 增加CONFIG_BOARD_TYPE_*分支； - 编译层面：务必按模组 Flash 容量在 menuconfig 中切换分区表（默认 16MB，8MB 模组用 partitions/v2/8m.csv）；
- 控制层面：复用
RegisterMcpTools()的AddTool模式为任意外设注册工具，底层动作复用EdaRobot+Oscillator的正弦步态引擎，配合set_trim在线校准即可快速完成整机联调。
【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
)
)