Quattro ZBD：跑在 ESP32 上的 4 足 12 DOF 四足机器狗固件

Quattro ZBD – ESP32 四足机器人固件

运行在 ESP32 上的 4 足、12 自由度四足机器狗的固件。

功能特性

小跑（默认）和行走步态，可在运行时切换
IMU 机身水平校正（卡尔曼滤波），带自动 IMU 校准
通过 Wi-Fi（UDP）和/或蓝牙手柄从 Android 应用进行控制
板载 TFT 屏幕，显示遥测数据和设置菜单（设置保存在 flash 中）
9 种表情（见 Emotes）
双核 FreeRTOS 设计：Core 1 上以 120 Hz 运行运动学，Core 0 上运行屏幕/菜单/UDP

硬件

部件	备注
ESP32 开发板（ESP32-WROOM，经典 ESP32）	蓝牙手柄支持需要原版 ESP32
PCA9685 16 通道舵机驱动	I²C 地址 `0x40`
12 × DS3218 舵机	每条腿 3 个
MPU6050 级 IMU	I²C 地址 `0x68`。
2" ST7789 TFT，240×320（SPI）
电池分压器	在 GPIO 32 上读取
3S 电池 + 降压转换器

电源警告：切勿通过 USB 或 ESP32 板为舵机供电。请使用能承受舵机堵转电流的降压转换器，并共地。测试时不要同时使用 USB 和电池为舵机供电，除非接地和逻辑供电已为此设置好。

引脚映射

功能	ESP32 引脚
I²C SDA（PCA9685 + IMU）	GPIO 21
I²C SCL（PCA9685 + IMU）	GPIO 22
电池电压检测	GPIO 32
TFT	见 TFT_eSPI setup

舵机通道映射（PCA9685）

逻辑舵机 ID → 通道为 group = id / 3; channel = group * 4 + id % 3。

腿	通道
FR（右前）	0, 1, 2
FL（左前）	4, 5, 6
RR（右后）	8, 9, 10
RL（左后）	12, 13, 14

通道 3、7、11 和 15 未使用。

软件设置

1. Arduino IDE

Arduino IDE 2.x，搭配 Espressif 的 ESP32 板包（或 Bluepad32 包，见下文）。

推荐的 Tools 设置：

设置	值
开发板	ESP32 Dev Module
上传速度	921600（如果上传失败，降至 115200）
CPU 频率	240 MHz
分区方案	Default（或使用 Bluepad32 时选 Huge APP）
串口监视器波特率	115200

2. 库（库管理器）

库	作者
Adafruit PWM Servo Driver Library	Adafruit
Adafruit MPU6050	Adafruit
Adafruit Unified Sensor	Adafruit
Adafruit BusIO	Adafruit（作为依赖自动安装）
TFT_eSPI	Bodmer

ESP32 核心内置（无需安装）：Wire、WiFi、WiFiUdp、SPI、Preferences。

可选，用于蓝牙手柄：Bluepad32。它不在库管理器中；它作为自己的板包发布（esp32_bluepad32）。没有它，固件仍可编译并仅以应用模式运行。设置步骤见下方 Optional: Bluetooth gamepad (Bluepad32)。

TFT_eSPI 设置

TFT_eSPI 在库自己的 User_Setup.h（位于 Arduino/libraries/TFT_eSPI/ 中）中配置，而不是在本 sketch 中。请编辑它以匹配你的屏幕和接线，例如：

#define ST7789_DRIVER
#define TFT_WIDTH  240
#define TFT_HEIGHT 320

#define TFT_MOSI 23
#define TFT_SCLK 18
#define TFT_CS   15
#define TFT_DC    2
#define TFT_RST   4
#define TFT_BL    5     // backlight, if wired

这些是我的构建中使用的引脚。请根据你的接线调整它们，如果颜色看起来反了或图像镜像/旋转了，请尝试 TFT_INVERSION_ON / TFT_INVERSION_OFF 或 TFT_RGB_ORDER 设置。升级 TFT_eSPI 库会覆盖 User_Setup.h，所以请保留一份副本。

3. 蓝牙手柄（Bluepad32）

手柄是可选的。使用普通的 ESP32 板包时，蓝牙代码会编译为空操作，机器人仅以应用模式运行。

要启用它：

File → Preferences → Additional boards manager URLs，添加： https://raw.githubusercontent.com/ricardoquesada/esp32-arduino-lib-builder/master/bluepad32_files/package_esp32_bluepad32_index.json
Boards Manager：安装 esp32_bluepad32。
Tools → Board → "ESP32 + Bluepad32 Arduino" → ESP32 Dev Module。
Tools → Partition Scheme → "Huge APP (3MB No OTA/1MB SPIFFS)"。

配对：在机器人通电时，将手柄置于蓝牙配对模式。首次配对后会自动重新连接。经典 ESP32 上的 Bluepad32 同时支持蓝牙经典和 BLE 手柄。请参阅 Robot_Bluetooth.h 顶部的设置（ENABLE_BT_CONTROLLER、轴符号翻转、配对清除）。

4. 烧录

将 Quadruped_Firmware 文件夹中的所有文件放入一个 sketch 文件夹（文件夹名称必须与 .ino 名称一致）。
打开 Quadruped_Firmware.ino，选择开发板和端口，然后上传。
以 115200 波特率打开串口监视器，查看启动、IMU 和蓝牙消息。

连接应用

ESP32 会启动自己的 Wi-Fi 接入点：

设置	值
SSID	`QUADRUPED_ESP32`
密码	`12345678`
UDP 端口	`5000`

从手机加入该网络，然后打开 Android 控制应用。在车间以外的任何地方使用机器人之前，请更改密码，位于 Quadruped_Firmwarev1.ino（AP_PASSWORD），并保持应用同步。

应用通过 UDP 发送控制数据包并接收遥测数据。应用中的表情列表必须与固件 EMOTES[] 顺序一致，因为应用发送的是表情索引。

控制

应用和手柄的逻辑相同。

输入	动作
左摇杆	行走（前进/后退、横移）
右摇杆 X	原地转身
L1 / R1	身体高度下降 / 上升（同时按住 2 秒 = 站立 / 坐下）
L2 / R2	俯仰微调机头向下 / 向上
A	身体调平（平衡）开/关
B	步态切换：小跑 ↔ 行走
Y	表情模式开/关
X	播放 / 停止所选表情
方向键左/右	选择表情（在表情模式下）
R3	重新运行 IMU 自动校准（仅站立时）
SELECT / BACK	按住时紧急停止

坐下时，相同的按钮用于导航屏幕设置菜单（L1/R1 上/下，L2/R2 左/右，A 进入/保存，B 返回/取消）。进入表情或木偶模式会将步态重置为小跑。

可调参数

主要常量位于 Quadruped_Firmwarev1.ino 顶部。你最可能调整的：

常量	默认值	含义
`STEP_HEIGHT`	菜单可调	小跑时的抬脚高度
`WALK_STEP_HEIGHT`	`0.010f`（1 厘米）	行走步态时的抬脚高度
`LEVEL_GAIN_DEFAULT`	`0.6f`	身体调平强度
`CAL_ZERO_DURATION_S` / `CAL_BOW_DURATION_S` / `CAL_HOLD_DURATION_S` / `CAL_RETURN_DURATION_S`	`1.0 / 0.8 / 0.5 / 1.0`	IMU 自动校准“鞠躬”例程的时序
`CAL_TILT_MAGNITUDE_M`	`0.025f`	校准期间使用的倾斜量
`AP_SSID`、`AP_PASSWORD`、`UDP_PORT`	见上文	Wi-Fi 设置

首次启动检查清单

卸下脚部负载。将机器人放在支架上，让腿自由悬空。
先通过电池/降压模块为舵机供电轨供电，然后为 ESP32 供电。确认所有 12 个舵机都有响应，且每条腿都朝正确方向移动。在让它站立之前，先修复安装或方向常量。
检查串口日志中的 PCA9685 和 IMU 检测消息。
将机器人平放在地面上，让 IMU 自动校准完成（按 R3 也会重新运行）。
让它站起来，用 A 启用平衡，并以低速测试行走。

表情

9 个表情：好奇歪头、谨慎点物、扭一扭、玩耍鞠躬、开心舞步接潜行、呼吸接跺脚、矩阵陀螺翻滚、俯卧撑、坐下并挥手问好。

表情模式在平衡禁用的情况下运行。

仓库结构

文件	用途
`Quadruped_Firmwarev1.ino`	主 sketch：设置、初始化、RTOS 任务
`Robot_Gait_Mechanism.h`	步态引擎、IMU/卡尔曼滤波器、平衡、舵机输出
`Robot_Emotes.h`	表情动画
`Screen_Settings.h`	TFT 遥测屏幕、设置菜单、UDP 遥测
`Robot_Bluetooth.h`	Bluepad32 手柄输入

故障排除

症状	检查
无法编译：`TFT_eSPI.h` 设置错误	在 TFT_eSPI 库文件夹中编辑 `User_Setup.h`
使用 Bluepad32 时无法编译 / sketch 过大	使用 Huge APP 分区方案
空白/白屏	TFT 引脚、驱动（`ST7789_DRIVER`）、背光引脚
舵机抖动或 ESP32 复位	舵机电源不足；添加大容量电容；检查共地
未找到 IMU	I²C 接线（SDA 21 / SCL 22）、地址 `0x68`；运行 IMU 测试 sketch
站立时机器人倾斜	在平坦表面上重新运行 IMU 校准（R3）
应用无法连接	手机必须连接到`QUADRUPED_ESP32`；禁用“自动切换到移动数据”
游戏手柄无法配对	是否选择了 Bluepad32 开发板包？将手柄置于配对模式；查看串口`[BT]`消息

安全

舵机可能夹到手指，机器人也可能摔倒。请将紧急停止（SELECT/BACK）放在触手可及处，先在支架上测试，并使用带适当保险丝的电池。

许可

依据知识共享署名—非商业性使用 4.0 国际（CC BY-NC 4.0）许可。

您可以自由地出于非商业目的对本设计进行重混、改编和构建，并给予适当署名。不允许任何形式的商业使用。

https://creativecommons.org/licenses/by-nc/4.0/