handsdk 1.0.0

手部控制模块 - 支持多种手部类型的统一控制接口

Hand Control Module (总览)

一个统一的灵巧手控制模块，支持多种灵巧手类型的控制接口，包括PantheonHand灵巧手和GaiaHand灵巧手。提供高级抽象接口和底层控制功能，适用于机器人研究、教育和工业应用。

详细文档：各手型详细说明请参阅 docs/ 目录：

• Hand Control Module (PantheonHand) - PantheonHand 详细文档
• Hand Control Module (GaiaHand) - GaiaHand 详细文档

📋 目录

• 功能特性
• 支持的手部类型
• 快速开始
• 安装
• 基本使用
• API文档
• 示例代码
• 架构设计
• 故障排除
• 贡献指南
• 许可证

✨ 功能特性

🔧 核心功能

• 统一接口: 提供标准化的手部控制接口，支持多种手部类型
• 多手部支持: 支持单手、双手和混合模式
• 实时控制: 支持实时关节角度控制和位置控制
• 手势执行: 内置多种预设手势，支持自定义手势
• 运动学计算: 提供正逆运动学计算功能
• 状态监控: 实时监控电机状态和手部状态

🚀 高级功能

• 异步通信: 支持异步电机状态查询，提高响应速度
• 广播控制: 支持单点控制和广播控制模式
• 平滑运动: 支持关节平滑过渡和轨迹规划
• 紧急停止: 提供紧急停止功能，确保安全
• 自动检测: 自动检测串口设备和CAN设备
• 错误处理: 完善的错误处理和恢复机制

🛠️ 开发友好

• 类型提示: 完整的Python类型提示支持
• 详细文档: 提供详细的API文档和使用示例
• 日志系统: 完善的日志记录和调试功能
• 单元测试: 包含完整的单元测试套件
• 跨平台: 支持Windows、Linux和macOS

🤖 支持的灵巧手

PantheonHand

• 通信方式: CAN总线通信
• 控制精度: 高精度位置和力矩控制
• 自由度: 可配置自由度
• 应用场景: 工业应用、协作机器人、研究平台

GaiaHand

• 通信方式: 串口通信 (RS232/RS485)

• 控制精度: 高精度位置控制

• 自由度:

  • GaiaHand: 15个自由度 (5个手指 × 3个关节)
  • Gaia16Hand: 16个自由度 (拇指4关节 + 其他手指各3关节)

• 应用场景: 精细操作、抓取任务、手势展示，触觉导纳

🚀 快速开始

环境要求

• Python 3.7+ (建议Python3.12)
• CAN驱动 (PantheonHand)
• 串口驱动 (GaiaHand)
• conda 或 pip (推荐使用 conda 进行环境管理)
• Git (用于克隆仓库)

克隆仓库

# 克隆仓库
git clone https://gitee.com/stellarrobot/handsdk.git

环境与依赖

# 创建新的 conda 环境（Python 3.12）
conda create -n handsdk python=3.12

# 激活环境
conda activate handsdk

# 安装基础依赖
pip install pyserial==3.5 numpy==2.4.2 typing-extensions==4.15.0 scipy==1.17.1
# 或者使用requirements.txt
cd handsdk  # 确保在handsdk文件夹下
pip install -r requirements.txt

安装模块

# 确保在handsdk文件夹下，上一步如果已经进入，此步可以忽略
cd handsdk

# 开发模式安装
pip install -e .
# 或者直接安装
pip install .

运行示例

PantheonHand示例

# Windows
python example\pantheonhand_example.py

# Linux / macOS
python example/pantheonhand_example.py

GaiaHand示例

# Windows
python example\gaiahand_example.py

# Linux / macOS
python example/gaiahand_example.py

Linux系统环境配置

USB_CANFD权限设置

因Linux系统下将涉及到usb底层驱动的调用，运行时，一定要加sudo获取权限运行，否则USB设备没有权限操作。 现提供一种USB权限设置，配置后，可以不加权限运行。下面创建一个新的 udev 规则。名称取为：99-myusb.rules

# 新建 udev 规则
sudo nano /etc/udev/rules.d/99-myusb.rules

注意：
1、 数字 99 最好不要改动，否则可能设置失败
2、 要加 sudo

在99-myusb.rules中，添加下面的内容

##
ACTION=="add",SUBSYSTEMS=="usb", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="0053", 
GROUP="users", MODE="0777"

USB_CAN权限设置

参考：https://manual.zlg.cn/web/#/55/2282

增加文件：/etc/udev/rules.d/50-usbcan.rules，

sudo nano /etc/udev/rules.d/50-usbcan.rules

50-usbcan.rules内容如下：

SUBSYSTEMS=="usb",ATTRS{idVendor}=="0471",ATTRS{idProduct}=="1200", GROUP="users", MODE="0666"

重新加载udev规则后插拔设备即可应用新权限：

sudo udevadm control --reload

📖 基本使用

1. 创建手部实例

from hand import create_hand, HandType, HandSide

# 创建Pantheon手部实例
pantheon_hand = create_hand(
    hand_type=HandType.PANTHEON,
    hand_side=HandSide.RIGHT,
    can_config={
        'dev_type': 41,  # USB-CAN
        'channel': 0,
        'arbitration_bitrate': 500000
    }
)

# 创建Gaia灵巧手实例
gaia_hand = create_hand(
    hand_type=HandType.GAIA,
    hand_side=HandSide.RIGHT,
    port="COM3",
    baudrate=230400
)

2. 连接和基本控制

# 连接手部
if gaia_hand.connect():
    print("手部连接成功")
    
    # 使能所有电机
    gaia_hand.enable_all_motors(True)
    
    # 设置关节角度
    from hand import FingerType, JointType
    gaia_hand.set_joint_angle(FingerType.INDEX, JointType.JOINT_1, 45.0)
    
    # 执行手势
    from hand import GestureType
    gaia_hand.perform_gesture(GestureType.FIST)
    
    # 断开连接
    gaia_hand.disconnect()

3. 高级控制功能

# 使用move_joints_pos进行批量控制
positions = {
    6: [1, 1, 1, 0.5]  # 手部1，食指关节1，角度0.5弧度
}
gaia_hand.move_joints_pos(positions, speed=0.8)

# 运动学计算
x, y = gaia_hand.forward_kinematics(FingerType.INDEX)
print(f"食指末端位置: ({x:.3f}, {y:.3f})")

# 逆运动学
target_x, target_y = 0.1, 0.05  # 目标位置(米)
joint_angles = gaia_hand.inverse_kinematics(FingerType.INDEX, target_x, target_y)

📚 API文档

MkDocs 依赖安装、构建与本地预览等操作说明见 tools/README.md。

核心类

Hand (抽象基类)

手部控制的抽象基类，定义了标准接口。

主要方法:

• connect(): 连接手部硬件
• disconnect(): 断开连接
• is_connected(): 检查连接状态
• set_joint_angle(): 设置关节角度
• get_joint_angle(): 获取关节角度
• perform_gesture(): 执行手势
• emergency_stop(): 紧急停止

GaiaHandAdapter

Gaia灵巧手的适配器类。

特殊功能:

• 串口通信管理
• 15自由度控制
• 高精度位置控制
• 实时状态监控

PantheonHandAdapter

Pantheon手部的适配器类。

特殊功能:

• CAN总线通信
• 可配置自由度
• 力矩控制
• 工业级稳定性

枚举类型

HandType

class HandType(Enum):
    GAIA = "gaia"        # Gaia灵巧手
    PANTHEON = "pantheon" # Pantheon手部

HandSide

class HandSide(Enum):
    RIGHT = "right"   # 右手
    LEFT = "left"     # 左手
    DOUBLE = "double" # 双手

FingerType

class FingerType(Enum):
    THUMB = "拇指"    # 拇指
    INDEX = "食指"    # 食指
    MIDDLE = "中指"   # 中指
    RING = "无名指"   # 无名指
    LITTLE = "小指"   # 小指

JointType

class JointType(Enum):
    JOINT_1 = "关节1"  # 第一关节
    JOINT_2 = "关节2"  # 第二关节
    JOINT_3 = "关节3"  # 第三关节

GestureType

class GestureType(Enum):
    FIST = "握拳"           # 握拳
    OPEN = "张开"          # 张开
    POINT = "指向"         # 指向
    VICTORY = "胜利"       # 胜利手势
    OK = "OK"             # OK手势
    THUMB_UP = "点赞"      # 点赞

工具函数

串口工具

from hand import get_available_ports, auto_detect_gaia_ports

# 获取可用串口
ports = get_available_ports()

# 自动检测Gaia手部串口
gaia_ports = auto_detect_gaia_ports()

💡 示例代码

基础示例

查看 example/ 目录中的完整示例：

• gaia_hand_usage_example.py: Gaia手部使用示例
• motor_usage_example.py: 底层电机控制示例
• move_joints_pos.py: 关节位置控制示例

快速示例

# 简单的手部控制示例
from hand import create_hand, HandType, HandSide, FingerType, JointType, GestureType

def simple_hand_control():
    # 创建手部实例
    hand = create_hand(HandType.GAIA, HandSide.RIGHT, port="COM3")
    
    try:
        # 连接手部
        if hand.connect():
            print("手部连接成功")
            
            # 使能电机
            hand.enable_all_motors(True)
            
            # 执行一系列动作
            hand.perform_gesture(GestureType.OPEN)
            time.sleep(1)
            
            hand.perform_gesture(GestureType.FIST)
            time.sleep(1)
            
            hand.perform_gesture(GestureType.POINT)
            time.sleep(1)
            
            print("动作执行完成")
        else:
            print("手部连接失败")
            
    except Exception as e:
        print(f"发生错误: {e}")
    finally:
        hand.disconnect()

if __name__ == "__main__":
    simple_hand_control()

🏗️ 架构设计

模块结构

hand/
├── hand/
│   ├── __init__.py          # 模块入口
│   ├── core.py              # 核心抽象类和适配器
│   ├── gaiahand/            # Gaia手部实现
│   │   ├── gaia_hand.py     # Gaia手部适配器
│   │   ├── motor.py         # 电机控制
│   │   └── hand_mappings.py # 映射关系
│   ├── pantheonhand/        # Pantheon手部实现
│   │   ├── pantheon_hand.py # Pantheon手部适配器
│   │   └── can_utils/       # CAN通信工具
│   └── utils/               # 工具函数
│       └── serial_utils.py  # 串口工具
├── example/                 # 示例代码
├── docs/                    # 文档
├── tests/                   # 测试代码
└── setup.py                 # 安装配置

设计模式

1. 工厂模式: 使用create_hand()工厂函数创建手部实例
2. 适配器模式: 通过适配器类统一不同手部类型的接口
3. 策略模式: 支持不同的通信策略（串口/CAN）
4. 观察者模式: 状态变化通知机制

通信协议

串口协议 (GaiaHand)

• 波特率: 230400
• 数据位: 8
• 停止位: 1
• 校验位: 无

CAN协议 (PantheonHand)

• 波特率: 500000
• 设备类型: USB-CAN/PCI-CAN
• 通道数: 可配置

🔧 故障排除

常见问题

1. 连接失败

症状: 无法连接到手部硬件 解决方案:

• 检查串口号是否正确
• 确认硬件连接正常
• 检查驱动是否安装
• 验证波特率设置

2. 通信超时

症状: 命令执行超时 解决方案:

• 检查通信线路质量
• 降低波特率
• 增加超时时间
• 检查硬件状态

3. 电机不响应

症状: 电机不执行命令 解决方案:

• 检查电机使能状态
• 验证关节角度范围
• 检查电源供应
• 查看错误日志

4. 位置控制异常

症状: 位置控制不准确 解决方案:

• 执行手部回零操作
• 检查编码器状态
• 验证运动学参数
• 校准关节角度

调试方法

1. 启用详细日志:

import logging
logging.basicConfig(level=logging.DEBUG)

2. 使用串口调试工具:

from hand import get_available_ports
ports = get_available_ports()
print(f"可用串口: {ports}")

3. 检查硬件状态:

status = hand.get_motor_status()
print(f"电机状态: {status}")

🤝 贡献指南

我们欢迎社区贡献！请遵循以下步骤：

开发环境设置

# 克隆仓库
git clone https://gitee.com/stellarrobot/handsdk.git
cd handsdk

# 安装开发依赖
pip install -e .[dev]

# 运行测试
pytest tests/

代码规范

• 遵循PEP 8代码风格
• 添加类型提示
• 编写单元测试
• 更新文档

提交规范

• 使用清晰的提交信息
• 包含测试用例
• 更新相关文档

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

📞 联系我们

• 项目主页: https://gitee.com/stellarrobot/handsdk
• 问题反馈: https://gitee.com/stellarrobot/handsdk/issues
• 邮箱: [e-mail]
• 文档: https://hand-control.readthedocs.io/

🙏 致谢

感谢所有为这个项目做出贡献的开发者和用户！

---

注意: 使用本模块时请确保在安全环境下进行测试，并遵循相关的安全操作规程。