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` 文件。