ydy0615
7c3d18ffcb
- Updated import in `balance.py` from `dm_imu_pkg` to the correct `dm_imu` package. - Introduced `quick_test()` function as a convenient debugging entry point, moving the previous script execution logic into this callable. - Modified `__main__` block to display a UI usage message instead of directly running the balance loop. - Revised `dm_imu.egg-info/PKG-INFO` to reflect the new Gradio‑based control panel documentation and project description.
136 lines
7.2 KiB
Plaintext
136 lines
7.2 KiB
Plaintext
Metadata-Version: 2.4
|
||
Name: dm_imu
|
||
Version: 0.1.0
|
||
Summary: Balance project with pybind11 IMU driver
|
||
Author: allenyuan
|
||
Author-email: allenyuan <allenyuan410@gmail.com>
|
||
License-Expression: MIT
|
||
Classifier: Programming Language :: Python :: 3
|
||
Classifier: Operating System :: OS Independent
|
||
Requires-Python: >=3.8
|
||
Description-Content-Type: text/markdown
|
||
License-File: LICENSE
|
||
Requires-Dist: pybind11>=2.10
|
||
Requires-Dist: numpy<2.0
|
||
Requires-Dist: pyserial>=3.5
|
||
Requires-Dist: gradio<6.0
|
||
Dynamic: author
|
||
Dynamic: license-file
|
||
Dynamic: requires-python
|
||
|
||
# 四足机器人控制面板（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`）
|
||
|
||
## 快速安装
|
||
```bash
|
||
# 克隆仓库
|
||
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 伪实现（仅用于调试）。
|
||
|
||
## 运行方式
|
||
```bash
|
||
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` 设置四条腿的位置（0~0.85）与速度比例（0.1~1.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` 文件。
|