RIG-TARS（塔斯）二次开发指南

本章面向开发者，拆解 RIG-TARS 的底层技术细节——硬件架构、固件框架、MCP 工具扩展与编译烧录流程。读完之后，你可以让这台桌面机器人按自己的想法继续生长。

系统架构

RIG-TARS 采用高度集成的单芯片架构：感知、步态控制、界面渲染与语音交互全部由一颗 ESP32-S3 独立完成，无需协处理器。固件基于 RIG-Omni 开源项目构建，结构模型、固件代码与组装资料均已开放，适合用于学习机器人运动控制、大模型与多模态交互、物联网通信等技术。

硬件抽象层

主控核心：ESP32-S3（Xtensa 双核 32 位处理器，主频 240 MHz），2.4 GHz Wi-Fi + BLE 5.0，板载 PSRAM。
运动总线（UART · XGO 协议）：3 台 SCS009 总线舵机通过 TX / RX 串行总线控制（GPIO46 / GPIO38），支持 ID 寻址与位置、速度、负载状态回读。
显示链路（SPI）：2.4 英寸 ST7789V2 面板（320 × 240 横屏），40 MHz 像素时钟，16 行分段 DMA 刷新——按实际写入量申请缓冲，不占用整屏内存。
视觉与触摸：DVP 摄像头采集图像；触摸模块为数字输出传感器（GPIO3，低电平有效），用于短触互动与长按休眠。
音频系统（I2S 直连）：数字麦克风拾音 + 3514 腔体喇叭放音，无硬件编解码芯片，音频链路直接在 I2S 上完成。
姿态感知（I2C）：QMI8658C 六轴 IMU（SDA GPIO14 / SCL GPIO48），提供实时姿态解算与动态平衡数据。

软件框架

RIG-Omni 采用「一份共用核心、各形态独立扩展」的模块化架构：语音 AI、界面渲染、MCP 远程控制等能力由公共层提供；机器人形态相关的逻辑——步态、界面风格、唤醒词与音效——收拢在板型目录 main/boards/tars/ 中。MCP（Model Context Protocol）控制协议以结构化指令流对外开放，配合断线重连机制保障控制的实时性与可靠性。

分层架构

层级	组件	位置
应用层	语音 AI · 终端风界面 · MCP 服务 · 摄像头工具	main/
板型抽象	IMU · 按键 · BLE · 电池 · 摄像头等共享驱动	main/boards/common/
机器人逻辑	板级初始化 · 步态生成 · 终端 UI · 蓝牙遥控	main/boards/tars/
平台层	Wi-Fi · 蓝牙 · SPI · I2C · I2S · UART · GPIO	ESP-IDF v5.5.2+

关键模块

tars_board.cc：TarsBoard 板级类——UART、SPI 屏幕、摄像头、按键的初始化，以及全部 TARS 专属 MCP 工具的注册。
tars_display.cc：终端风 UI 渲染——FLIGHT LOG 日志流、STATUS 状态面板与人格参数 footer 的绘制与刷新。
xgo.cc：SCS009 舵机驱动层——零位管理（Flash 持久化）、位置与负载状态回读、非阻塞串口发送与堵转检测。
xgo_action.cc：步态生成层——前进 / 后退 / 转向的余弦步态、限时运动与速度限幅。
ble_remote_control.cc：蓝牙遥控模式——BLE 连接与遥控指令解析。
mcp_server.cc / device_state_machine.cc：公共核心——MCP 工具服务（含 self.camera.* 通用工具）与设备状态机。
ota.cc / settings.cc：公共核心——云端 OTA 升级与 NVS 设置持久化。

核心代码解析

1. MCP 工具注册（tars_board.cc）

每个能力通过 AddTool 注册为一个云端大模型可调用的「工具」：工具名、自然语言描述、参数定义与执行回调。其中的描述会随请求提交给模型，由它判断何时调用——这是「说话就能控制」的关键一环。

mcp_server.AddTool("self.tars.forward",
    "TARS 前进或后退。speed 为运动幅度(0-60，正值前进，负值后退，0 停下)，"
    "time 为持续时间(毫秒)，time=0 时持续运动直到再次调用并设 speed=0。"
    "步态频率 1.5Hz。适用于用户说'前进''往前走''后退''过来'等。",
    PropertyList({
        Property("speed", kPropertyTypeInteger, -60, 60),
        Property("time", kPropertyTypeInteger, 0, 10000),
    }),
    [this](const PropertyList& properties) -> ReturnValue {
        int speed = properties["speed"].value<int>();
        int time = properties["time"].value<int>();
        ESP_LOGI(TAG, "MCP forward speed=%d time=%d", speed, time);
        tars_set_forward(speed, time);
        return true;
    });

2. 余弦步态生成（xgo_action.cc）

步态在舵机控制循环中周期性更新：相位按 1.5 Hz 推进，cos 分量驱动一号关节前后摆动，sin 分量驱动另外两路关节交替起落。前进、后退、转向三种模式根据运动幅值自动切换，幅值越大步幅越大；带时长参数的运动到期后会自动停下。

void tars_gait_update() {
    // 限时运动到期后自动停下
    if (gait_until_us > 0 && esp_timer_get_time() >= gait_until_us) {
        vx = 0.0f;
        vyaw = 0.0f;
        gait_until_us = 0;
    }

    float t = (now - gait_t0_us) / 1000000.0f;
    float phase = TARS_GAIT_FREQ_HZ * t * 2.0f * (float)PI;
    float c = cosf(phase);   // 主柱摆动分量
    float s = sinf(phase);   // 侧柱交替分量

    if (fabsf(amp_yaw) >= fabsf(amp_x)) {
        // 转向模式：幅值为正左转，为负右转
        float scale = fabsf(amp_yaw) / 30.0f;
        pos[0] = c * 40.0f * scale;
        pos[1] = s * amp_yaw;
        pos[2] = -s * amp_yaw;
    } else if (amp_x > 0.0f) {
        // 前进模式
        float scale = amp_x / 40.0f;
        pos[0] = c * 55.0f * scale;
        pos[1] = s * (-amp_x);
        pos[2] = s * (-amp_x);
    } else {
        // 后退模式
        float speed = -amp_x;
        float scale = speed / 40.0f;
        pos[0] = c * 50.0f * scale;
        pos[1] = s * speed;
        pos[2] = s * speed;
    }

    WritePos(pos);
}

3. 堵转检测与保护（xgo.h / xgo.cc）

固件对每台舵机回读位置与负载。当位置误差与负载同时超过阈值并连续确认 3 次、且距上次触发已超过冷却窗口时，判定为堵转——保护回调立即接管，自动卸力冷却，避免舵机长时间憋劲。

#define STALL_POS_THRESHOLD   100    // 位置误差阈值
#define STALL_TOR_THRESHOLD   100    // 负载阈值
#define STALL_DEBOUNCE_COUNT  3      // 连续确认次数
#define STALL_COOLDOWN_MS     1000   // 触发后冷却窗口（毫秒）

编译与烧录

环境要求

硬件：RIG-TARS 整机（RIG-Board0722 主控板）与 Type-C 数据线。
工具链：ESP-IDF v5.5.2 或更高版本（含 Xtensa-ESP32-S3-ELF 编译器）。
其他：Python 3.8+（构建脚本），USB 串口工具（连接 UART0 烧录与查看日志）。

编译与烧录步骤

# 1. 获取固件源码
git clone https://github.com/Xgorobot/RIG-Omni.git
cd RIG-Omni

# 2. 激活 ESP-IDF 环境（Linux / macOS 示例）
. $HOME/esp/esp-idf/export.sh
#    Windows 用户请在 ESP-IDF 命令行环境中直接执行以下步骤

# 3. 选择目标芯片与板型
idf.py set-target esp32s3
idf.py menuconfig
#    → RIG-Omni → Board Type → RIG-TARS
#    → RIG-Omni → Firmware Region → Domestic (China) / Overseas

# 4. 编译
idf.py build

# 5. 烧录并查看串口日志（端口号按实际情况填写）
idf.py -p COM3 flash monitor

固件区域（国内 / 海外）

RIG-Omni 支持从同一代码库构建国内与海外两个版本。在 menuconfig 中切换区域后，OTA 地址、默认语言、唤醒词与配网二维码会自动联动：

配置项	国内版（Domestic）	海外版（Overseas）
OTA 地址	xl-api.xgorobot.com	xl-api.luwudynamics.ai
默认语言	zh_CN	en_US
唤醒词	自定义唤醒词（小陆同学）	自定义唤醒词 + 内置「Hey Kira」
配网动画	国内版二维码	海外版二维码

发布打包

编译完成后，可运行打包脚本生成发布包——含固件、bootloader、分区表、资源文件与 manifest.json，输出到 bin/ 目录：

python tools/gen_bin_package.py

扩展开发

注册新的 MCP 工具

想让塔斯学会一个新技能，先为它注册一个工具：在 TarsBoard 的工具初始化代码中追加 AddTool 调用，填入工具名、描述、参数范围与执行逻辑，重新编译烧录即可。云端模型会自动把用户的话匹配到新工具上。

mcp_server.AddTool("self.tars.custom_action",
    "用一句话描述这个工具的用途与大模型的调用时机",
    PropertyList({
        Property("duration", kPropertyTypeInteger, 0, 10000),
    }),
    [this](const PropertyList& properties) -> ReturnValue {
        int duration = properties["duration"].value<int>();
        // 在这里执行你的自定义动作
        return true;
    });

自定义开机音效

把 .ogg 音效文件放进板型目录 main/boards/tars/，编译时会自动发现并嵌入固件，无需手动配置。
开机音效文件名为 tars_startup.ogg；建议使用 Opus 编码、单声道、16 kHz 采样。
请使用原创或已获授权的音效素材；可用 FFmpeg 完成转码：

ffmpeg -i source.wav -t 4.5 -ac 1 -ar 16000 -c:a libopus -b:a 24k main/boards/tars/tars_startup.ogg

创建自定义板型

快速方式：运行 python tools/create_board.py，按向导提示创建新板型——自动生成全部必要文件并在构建系统中完成注册。
手动方式：在 main/boards/ 下新建板型目录，编写板级与电机逻辑代码，并在 Kconfig 与 CMakeLists 中完成注册。
板型专属资源：表情动画（emoji/）、界面布局（320_240/）、唤醒词模型（wakenet/）与音效文件（*.ogg）均随板型目录独立存放。

资源下载与开发环境

固件开源仓库（GitHub）：Xgorobot/RIG-Omni——开源 ESP32-S3 多形态机器人固件。
结构模型与装配资料：RIG-TARS 全链路复刻指南（含 BOM、3D 打印工程与总装参考）。
开发环境清单：ESP-IDF v5.5.2+ · Python 3.8+ · Xtensa-ESP32-S3-ELF 工具链 · USB 转串口调试工具。

二次开发