Metadata-Version: 2.4
Name: robodyno-debugger
Version: 1.0.0
Summary: Robodyno 设备调试器（Web UI）
Author-email: awei <awei@163.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/awei/robodyno-debugger
Project-URL: Repository, https://github.com/awei/robodyno-debugger
Keywords: robodyno,can,debugger,robotics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask<4,>=2.3
Requires-Dist: waitress>=2.1
Requires-Dist: robodyno>=1.7.3
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Robodyno Debugger

Robodyno 设备的 Web 调试器 —— 一个基于 Flask 的轻量级设备管理平台，通过浏览器即可扫描、监控和控制 CAN 总线上的所有 Robodyno 设备。

![Python](https://img.shields.io/badge/Python-3.8%2B-blue)
![Robodyno](https://img.shields.io/badge/Robodyno-1.7.3%2B-blue)
![Flask](https://img.shields.io/badge/Flask-2.3%2B-green)
![Waitress](https://img.shields.io/badge/Waitress-2.1%2B-green)
![License](https://img.shields.io/badge/License-Apache%202.0-yellow)

---

## 功能特性

- 🔍 **自动设备扫描** —— SSE 流式推送，设备逐个实时显示
- 🔌 **CAN 总线管理** —— 支持 can0 ~ can3 通道，可切换波特率（1M / 500K / 250K）
- 🎛️ **多设备类型支持** —— 覆盖 Robodyno 全系列组件（电机 / 夹持器 / 传感器 / 控制器）
- 📊 **实时数据监控** —— 电压、温度、位置、速度、力矩、距离、姿态、错误状态
- 📈 **动态曲线绘制** —— Chart.js 实时图表（陀螺仪 / 加速度 / 欧拉角 / 距离 / 位置 / 速度 / 力矩）
- ⚙️ **参数在线配置** —— PID、限速、限流、控制模式在线切换
- 🖱️ **数值任意控制** —— 滑条实时拖动，数值徽章双击可精确输入
- 🔧 **设备管理** —— 在线修改设备 ID，一键校准、清错、回零
- 💾 **本地保存设置** —— 单位 / 步长等偏好保存在浏览器

---

## 支持的设备

| 设备类型 | 型号 | 状态 |
|---|---|---|
| 行星减速电机 | `ROBODYNO_PRO_*` | ✅ |
| 直线运动模组 | 复用行星电机驱动 | ✅ |
| 灵足减速电机 | `THIRD_PARTY_CYBERGEAR` | ✅ |
| 双指夹持器（新）| `MINI_REDUCER` | ✅ |
| 双指夹持器（旧）| `MINI_P100` | ✅ |
| 步进电机控制器 | `STEPPER_DRIVER` | ✅ |
| 传送带驱动器 | 复用步进驱动 | ✅ |
| IMU 传感器 | `IMU_SENSOR` | ✅ |
| 超声波传感器 | `ULTRASONIC_SENSOR` | ✅ |
| 磁导航传感器 | `MAGNETIC_SENSOR` | ✅ |
| PWM 气动控制器 | `D_VAC01` | ✅ |
| PWM 舵机控制器 | `D_VAC01` | ✅ |
| LED 控制器 | `LED_DRIVER` | ✅ |

---

## 安装

### 从 PyPI（推荐）

```bash
pip install robodyno-debugger
```

---

## 系统要求

- **Python** ≥ 3.8
- **CAN 总线驱动**：
  - Linux：`socketcan`（内核自带）
  - Windows：`candle` 等
- **robodyno 库**：能正常识别 CAN 设备（它依赖 `python-can` 库来与 CAN 硬件通信）

### Linux 配置 CAN（示例）

```bash
# 设置 can0 波特率为 1M
sudo ip link set can0 up type can bitrate 1000000

# 验证
ip -details link show can0
```

### Windows 配置 CAN

安装对应 USB-CAN 适配器的驱动，确保在设备管理器中能识别。

---

## 快速开始

### 1. 启动服务

- 在 `终端(PowerShell\CMD)` 中输入

```bash
robodyno-debugger
```

输出：

```
Robodyno Debugger 启动中...
  访问地址: http://localhost:5000
  监听: 0.0.0.0:5000
  线程数: 8
  按 Ctrl+C 停止
```

### 2. 打开浏览器

访问 `http://localhost:5000`（或局域网 IP `http://192.168.x.x:5000`）。

### 3. 连接 CAN 总线

点击右下角 ⚙️ 齿轮按钮：

- 选择通道（`can0` / `can1` / `can2` / `can3`）
- 选择波特率（`1000000` / `500000` / `250000`）
- 点击「连接」

连接成功后设备会自动扫描并逐个显示。

### 4. 进入设备页面

点击 **任意设备** 卡片进入对应控制页面。

---

## 命令行参数

```bash
robodyno-debugger [OPTIONS]

Options:
  --host TEXT     监听地址（默认 0.0.0.0）
  --port INTEGER  监听端口（默认 5000）
  --threads INT   工作线程数（默认 8）
  --help          显示帮助
```

### 示例

```bash
# 指定端口
robodyno-debugger --port 8080

# 只监听本地
robodyno-debugger --host 127.0.0.1

# 增加线程数（并发更多请求）
robodyno-debugger --threads 16
```

---

## 界面说明

### 首页 —— 设备列表

- **顶部**：连接状态徽章（已连接 / 未连接）
- **卡片**：按 ID 排序，逐个流式加载，带淡入动画
- **右下角按钮**：
  - ⓘ 系统信息（版本、IP、运行时长、CAN 状态）
  - ⚙️ CAN 总线设置（连接 / 断开）

### 二级页面 —— 设备控制

- **左侧**：控制区（滑条、按钮、模式切换）
- **右侧**：实时数据（电压、温度、位置、速度、力矩、PID 等）
- **底部**：实时曲线（Chart.js）
- **右下角**：设备信息 / 设置

**双击蓝色数值徽章**可以精确输入目标值。

---

## 常见问题

### Q1：无法连接 CAN

**Linux**：
```bash
sudo ip link set can0 up type can bitrate 1000000
```

**Windows**：检查 USB-CAN 适配器驱动是否安装。
- 驱动装好后，`robodyno` 库会自动通过 `python-can` 访问设备。

### Q2：扫描超时

- 检查 CAN 总线物理连接
- 逐个上电设备排查故障节点

### Q3：页面打开但无法识别设备

- 点击右下角 ⚙️ 检查 CAN 状态是否"已连接"
- 未连接时页面不会扫描

### Q4：`robodyno-debugger` 命令找不到

Windows 上 pip 的 Scripts 目录可能不在 PATH。备选运行方式：

```bash
python -m robodyno_debugger
```

或把提示的目录加到 PATH：

```powershell
# 比如提示的是 C:\Users\xxx\AppData\Local\Programs\Python\Python312\Scripts
setx PATH "%PATH%;C:\Users\xxx\AppData\Local\Programs\Python\Python312\Scripts"
```

### Q5：端口被占用

```bash
robodyno-debugger --port 8080
```

或查找占用进程：

```bash
# Linux / Mac
lsof -i :5000

# Windows
netstat -ano | findstr :5000
```

### Q6：如何让局域网其他机器访问

默认 `--host 0.0.0.0`，直接访问本机 IP 即可：

```
http://192.168.1.100:5000
```

如果无法访问，检查防火墙：
- **Linux**：`sudo ufw allow 5000`
- **Windows**：控制面板 → Windows Defender 防火墙 → 允许应用通过防火墙 → 添加 Python

---

## 技术栈

- **后端**：Flask、`python-can`（CAN 总线抽象库）、`robodyno`（设备控制库）
- **前端**：Bootstrap 5、Font Awesome 6、Chart.js
- **通信**：CAN 总线、Server-Sent Events（SSE）
- **并发**：Flask `threaded=True` + `threading.Lock` 串行化 CAN 访问

---

## 相关资源

- [Robodyno 官方文档](http://101.42.250.169/1.7.3/)
- [robodyno Python 库](https://github.com/robodyno/robodyno)

---

## License

Apache License 2.0

---

## 更新日志

### v1.0.0

**设备支持**

- 行星减速电机（`ROBODYNO_PRO_*`）
- 直线运动模组（复用行星电机驱动）
- 灵足减速电机（`THIRD_PARTY_CYBERGEAR`）
- 双指夹持器（`MINI_REDUCER`）
- 旧版双指夹持器（`MINI_P100`，固件 <1.0，独立控制页面）
- 步进电机控制器（`STEPPER_DRIVER`）
- 传送带驱动器（复用步进驱动，支持 rad ↔ m 单位换算）
- IMU 传感器（`IMU_SENSOR`，四元数 / 欧拉角 / 陀螺仪 / 加速度）
- 超声波传感器（`ULTRASONIC_SENSOR`，支持 cm / m 切换）
- 磁导航传感器（`MAGNETIC_SENSOR`，16 位检测点阵显示）
- PWM 控制器（`D_VAC01`，气动执行器 / 舵机控制）
- LED 控制器（`LED_DRIVER`，常亮 / 闪烁 / 呼吸 / 跑马）

**CAN 总线管理**

- 支持 can0 ~ can3 通道
- 波特率在线切换（1M / 500K / 250K）

**设备扫描**

- SSE 流式推送，设备逐个实时显示
- 支持自动刷新（10 秒倒计时）与手动刷新

**实时监控与曲线**

- 位置、速度、力矩、电压、温度、错误状态
- 姿态（四元数 / 欧拉角 / 陀螺仪 / 加速度）、距离
- Chart.js 实时曲线，可切换显示数据集

**控制与配置**

- 滑条实时拖动，数值徽章双击精确输入
- 控制模式在线切换（位置 / 速度 / 力矩 / MIT 等）
- PID、速度上限、电流上限在线读写
- 零点设置、电机校准、错误清除、回零
- 设备 ID 在线修改并保存到闪存

**本地偏好**

- 单位 / 步长 / 最大行程等设置保存在浏览器
- 每个设备页面独立配置，互不干扰
