四足机器人控制面板（Balance）

基于 Gradio 的 Web UI，封装了 BalanceController、LegsController 与 IMU 驱动，实现串口自动打开、日志记录、实时电机使能/失能、位置与速度控制、扭矩读取以及后台平衡循环。

目录

• 项目简介
• 环境要求
• 快速安装
• 运行方式
• 主要功能
• 代码结构概览
• 使用说明
• 常见问题与故障排查
• 许可证

项目简介

本项目提供一个面向四足机器人的控制面板，使用 Gradio 构建网页 UI，能够在浏览器中直接操控机器人。核心逻辑封装在 BalanceController（位于 balance.py）中，内部调用 LegsController（Legs_controller.py）完成电机的初始化、使能/失能、扭矩读取和位置控制；同时通过 dm_imu 包的 DmImu 实现 IMU 数据获取并驱动平衡算法。

注意：若硬件未连接，BalanceController 与 LegsController 会捕获异常并创建 dummy 对象，保证脚本仍可运行而不会崩溃。

环境要求

• 操作系统：Linux（POSIX 串口）或 Windows（使用对应的串口驱动）
• Python：>=3.8
• 依赖库（已在 pyproject.toml 中声明）
  • gradio<6.0
  • pyserial>=3.5
  • numpy<2.0
  • pybind11>=2.10（用于编译 C++ IMU 驱动）
• 硬件
  • 4×腿部电机（DM4340）+ 4×轮子电机（DMH6215）
  • IMU（通过 dm_imu 包的 DmImu）

快速安装

# 克隆仓库
git clone https://github.com/ydy0615/balance.git
cd balance

# 创建并激活虚拟环境（推荐）
python -m venv venv
.\venv\Scripts\activate   # Windows
source venv/bin/activate  # Linux/macOS

# 安装 Python 依赖
pip install -r requirements.txt   # 若没有此文件，可手动安装
pip install gradio pyserial numpy pybind11

# 编译 C++ IMU 驱动（需要 cmake、gcc/clang）
mkdir build && cd build
cmake .. && cmake --build .
cd ..

若只想运行 UI 而不编译 C++ 部分，可跳过最后的编译步骤，dm_imu 包会在运行时尝试加载已编译的 .so/.dll，若不存在则使用 Python 伪实现（仅用于调试）。

运行方式

python main.py

启动后会在终端显示类似信息：

Running on http://0.0.0.0:7860/

在浏览器打开该地址即可看到 四足机器人控制面板。

主要功能

功能	对应后端函数	UI 控件	说明
自动打开串口	open_port	-	程序启动时即尝试实例化 BalanceController 并打开串口
电机使能	enable_all	“✅ 使能全部” 按钮	使能四条腿电机 + 四个轮子电机
电机失能	disable_all	“❌ 失能全部” 按钮	失能所有电机
启动平衡控制	start_balance	“▶️ 启动平衡控制” 按钮	检查电机是否已使能，随后在守护线程中运行 run_balance_loop
位置控制	set_position	四个滑块 + “📍 设置位置” 按钮	通过 control_legs_pos 设置四条腿的位置（00.85）与速度比例（0.11.0）
扭矩读取	get_torque	“🔍 读取扭矩” 按钮	调用 controller.get_legs_torque()，返回四条腿的扭矩值
实时日志	refresh_log	“刷新日志” 按钮 + 文本框	读取 ui.log（写入位置 LOG_PATH = "ui.log"）并显示在 UI 中
日志写入	log（内部）	-	所有关键操作均通过 log(msg) 同时写入文件并打印到控制台，便于调试

代码结构概览

balance/
│
├─ main.py               # Gradio UI 与业务入口
├─ balance.py            # BalanceController（平衡算法、线程管理）
├─ Legs_controller.py    # LegsController（电机底层控制）
├─ dm_imu/               # C++ IMU 驱动（pybind11 包装）
│   ├─ src/
│   │   ├─ imu_driver.cpp
│   │   └─ bsp_crc.cpp
│   └─ __init__.py
├─ pyproject.toml        # 项目元信息与依赖声明
├─ README.md             # 本文档
└─ ... (其他辅助脚本、测试文件)

使用说明

1. 检查硬件：确保机器人电机控制板和 IMU 已正确连接，串口设备路径与 BalanceController.__init__ 中的默认值相符（/dev/dm-u2can、/dev/dm-imu）。若使用不同路径，请在 main.py 或 balance.py 中自行修改。
2. 启动 UI：运行 python main.py，打开浏览器访问 http://<本机IP>:7860。
3. 日志查看：点击 “刷新日志” 可实时读取 ui.log。若日志文件不存在，首次点击会自动创建。
4. 电机使能：先点击 “✅ 使能全部”，随后才能使用位置或扭矩功能。
5. 位置调节：调节四个滑块后点击 “📍 设置位置”，下方的 “位置设置结果” 框会显示返回信息。
6. 扭矩读取：点击 “🔍 读取扭矩”，右侧文本框会显示四条腿当前扭矩（N/m），若读取失败则显示 “错误”。
7. 启动平衡：在电机已使能后点击 “▶️ 启动平衡控制”。后台线程会不断读取 IMU 数据并根据偏置调节腿部位置。若出现异常，日志中会记录详细信息。

常见问题与故障排查

问题	可能原因	解决方案
UI 无法打开	未安装 gradio 或端口被占用	pip install gradio，或更换 server_port 参数
串口打开失败	设备路径错误、权限不足或硬件未连接	检查 BalanceController.__init__ 中的 leg_port 与 imu_port，在 Linux 上使用 sudo chmod a+rw /dev/ttyUSB*
日志不刷新	ui.log 未生成或文件被锁定	确认 log() 已被调用；手动删除 ui.log 让程序重新创建
电机不使能	LegsController 初始化异常	查看终端输出的 “初始化 LegsController 失败” 信息；确保 u2can 包已正确安装且串口可用
平衡控制未启动	motors_enabled 为 False（未使能）	必须先点击 “✅ 使能全部”，然后再点击 “▶️ 启动平衡控制”
读取扭矩返回 “错误”	controller.get_legs_torque() 抛异常	检查 LegsController.get_legs_torque 是否成功刷新电机状态，确保电机已连接
IMU 数据异常	IMU 未启动或波特率不匹配	确认 BalanceController.__init__ 中的 imu_port 与 imu_baud 与实际硬件匹配；若硬件缺失，程序会使用 DummyImu（返回零姿态）

许可证

本项目采用 MIT 许可证。详情请参见根目录下的 LICENSE 文件。