Metadata-Version: 2.3
Name: pydamiao
Version: 0.1.4
Summary: An unofficial Damiao motor control library, developed based on the official SDK. 一个非官方的达妙电机控制库, 基于官方sdk二次开发
Author: DBinK
Author-email: DBinK <DBinKv1@Gmail.com>
Requires-Dist: numpy>=2.0.1
Requires-Dist: pyserial>=3.5
Requires-Python: >=3.10
Project-URL: Repository, https://github.com/DBinK/pydamiao
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://github.com/user-attachments/assets/04fbae2c-53e7-46ee-bb77-a79b0d9d8597" style="width: 40%; height: auto;">
</p>

<p align="center">
  <a href="https://zread.ai/DBinK/pydamiao" target="_blank"><img src="https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff" alt="zread"/></a>

  <!-- PyPI -->
  <a href="https://pypi.org/project/pydamiao/">
    <img src="https://img.shields.io/pypi/v/pydamiao?color=blue&label=PyPI&logo=pypi&logoColor=white" />
  </a>

  <!-- License -->
  <a href="https://github.com/DBinK/pydamiao/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/DBinK/pydamiao?color=blue" />
  </a>

  <!-- CI -->
  <a href="https://github.com/DBinK/pydamiao/actions">
    <img src="https://img.shields.io/github/actions/workflow/status/DBinK/pydamiao/test_and_publish.yml?branch=main&logo=githubactions&logoColor=white" />
  </a>


  <!-- Last Commit -->
  <a href="https://github.com/DBinK/pydamiao/commits/main">
    <img src="https://img.shields.io/github/last-commit/DBinK/pydamiao" />
  </a>

  <!-- Stars -->
  <a href="https://github.com/DBinK/pydamiao">
    <img src="https://img.shields.io/github/stars/DBinK/pydamiao?style=social" />
  </a>

</p>

<div align="center">
  <!-- Keep these links. Translations will automatically update with the README. -->
  <a href="https://www.zdoc.app/DBinK/pydamiao?lang=en">English</a> | 
  <a href="https://www.zdoc.app/DBinK/pydamiao?lang=ja">日本語</a> | 
  <a href="https://www.zdoc.app/DBinK/pydamiao?lang=de">Deutsch</a> | 
  <a href="https://www.zdoc.app/DBinK/pydamiao?lang=es">Español</a> | 
  <a href="https://www.zdoc.app/DBinK/pydamiao?lang=fr">français</a> | 
  <a href="https://www.zdoc.app/DBinK/pydamiao?lang=ko">한국어</a> | 
  <a href="https://www.zdoc.app/DBinK/pydamiao?lang=pt">Português</a> | 
  <a href="https://www.zdoc.app/DBinK/pydamiao?lang=ru">Русский</a>
</div>

# pydamiao

一个非官方的达妙电机 Python 库。

`pydamiao` 基于官方 SDK 的工作流做了更 Pythonic 的封装, 使其开发体验更好。`pydamiao` 提供串口通信、电机管理、参数读写和常见控制模式的高层接口，适合快速集成到自己的项目中。


## 基本特性

- 包含完整的类型注解, 为开发者提供舒适的开发体验。
- 可能会失败的接口, 使用类似 Rust 的 `Result` 返回格式, 显式处理错误, 避免大量 `None` 判断
- 提供 `Motor` 和 `MotorManager` 等高层接口
- 支持 `MIT`、`VEL`、`POS_VEL`、`POS_FORCE` 等常见控制模式
- 同时支持单电机和多电机场景


## 开发者体验 (DX) 升级

本项目从达妙官方提供的 [单文件脚本](https://github.com/cmjang/DM_Control_Python/blob/main/DM_CAN.py) 重构为现代化的 Python 库，在易用性和可维护性上进行了全方位升级：

* **极速环境构建**：全面采用 `uv` 管理项目依赖与虚拟环境，提升开发与部署效率。
* **现代类型推导**：基于 Python 3.10+，全面覆盖核心 API 的原生类型注解，大幅提升 IDE 代码提示与静态检查体验。
* **模块化代码解耦**：将巨石架构拆分为 `bus`、`protocol`、`motor` 等独立模块，并封装了底层硬编码的字节位移操作，显著降低源码阅读与二次开发门槛。


## 安装

从 [PyPI](https://pypi.org/project/pydamiao/) 安装
```bash
uv pip install pydamiao 
```
或
```bash
pip install pydamiao 
```

从源码安装：

```bash
git clone https://github.com/DBinK/pydamiao.git
cd pydamiao
pip install -e .
```

## 快速开始

```python
import math
import time

from pydamiao import Motor, MotorManager, ControlMode, MotorType, MotorReg, SerialBus

# 初始化所有对象
bus = SerialBus("COM3", baudrate=921600, timeout=0.01)
manager = MotorManager(bus)

motor1 = Motor(bus, MotorType.DM4310, 0x06, 0x12)
motor2 = Motor(bus, MotorType.DM4310, 0x05, 0x12)

# 注册电机到管理器
manager.register(motor1)
manager.register(motor2)

# 统一控制电机
manager.clean_error_all()
manager.disable_all()
manager.set_mode_all(ControlMode.MIT)

# 查看电机参数
for id, motor in manager.motors.items():
    print(f"电机 ID {id}:")
    print("CTRL_MODE:", motor.read_param(MotorReg.CTRL_MODE).value)
    print("MST_ID:", motor.read_param(MotorReg.MST_ID).value)

# 单独控制电机
if not motor1.set_mode(ControlMode.POS_VEL).is_ok:
    print("motor1 切换到 POS_VEL 失败")

if not motor2.set_mode(ControlMode.VEL).is_ok:
    print("motor2 切换到 VEL 失败")

# 运动测试
for _ in range(1000):
    q = math.sin(time.time())
    motor1.set_pos_vel(q * 8, 3)
    motor2.set_velocity(8 * q)
    time.sleep(0.001)

# 程序结束前, 记得失能所有电机 (虽然有自动失能兜底, 但是推荐养成好习惯)
manager.disable_all()
bus.close()
```

## API 概览

- `SerialBus`：共享串口通信总线
- `Motor`：单个电机的高层控制对象
- `MotorManager`：同一总线上的多电机管理器
- `ControlMode`、`MotorType`、`MotorReg`：协议相关枚举和辅助类型

## 使用文档 和 示例

文档正在补充中... 

可先查看 [Zread](https://zread.ai/DBinK/pydamiao) 生成的说明文档

或先查看示例 [`examples`](./examples) 目录, 包含了本库几乎全部用法:

- [`base.py`](./examples/base.py): 基础用法, 包含常用 API 的使用
- [`motor_single.py`](./examples/motor_single.py): 单电机控制
- [`motor_muitl.py`](./examples/motor_muitl.py): 多电机控制
- [`calibration.py`](./examples/calibration.py): 零点校准 (多电机)
- [`read_reg.py`](./examples/read_reg.py): 读取电机寄存器中的值

## 项目状态

项目仍在持续迭代中，正式稳定版本发布前 API 可能会继续调整。

## 许可证

MIT，详见 [`LICENSE`](./LICENSE)。
