Woan Gripper SDK — 用户安装指南

版本: v1.0.0 | 平台: Linux (x86_64) / Windows
维护: OneRobotics 团队

目录结构

woan_gripper_for_user/
├── README.md                       ← 本文件
├── conda_package/                  ← Python 接口 conda 包
│   ├── linux-64/                   
│   │   ├── ruckig-*.conda
│   │   └── woangripper_api_py-*.conda
│   ├── win-64/                     
│   │   ├── ruckig-*.conda
│   │   └── woangripper_api_py-*.conda
│   └── noarch/
│       └── woangripper-*.conda     ← 元包：一条命令安装全部
├── cpp_sdk/                        ← C++ 接口开发包
│   ├── linux/                    
│   └── win/                       
├── install_conda_package.sh        ← 一键安装脚本 (Linux)
└── install_conda_package.ps1       ← 一键安装脚本 (Windows)

一、Python 接口安装 (推荐)

前置条件

Miniforge 或 Mambaforge 已安装

方法 A — 一键脚本 (conda 包)

Linux:

cd woan_gripper_for_user
bash install_conda_package.sh

Windows (PowerShell):

cd woan_gripper_for_user
.\install_conda_package.ps1

脚本会自动创建名为 woan_gripper 的 conda 环境，索引本地 channel，并安装 woangripper 元包（自动拉取第三方库 + woangripper_api_py）。

方法 B — 手动安装

Linux / Windows (命令相同):

# 创建环境
conda create -n woan_gripper python=3.12 -y
conda activate woan_gripper
conda install -y conda-index -c conda-forge
# 建立本地 channel 索引
python -m conda_index ./conda_package
# 安装 woangripper 元包
conda install woangripper \
  -c "file://$PWD/conda_package" \
  -c conda-forge \
  -y

验证安装

conda activate woan_gripper
python -c "import woangripper_api_py; print('安装成功')"

二、C++ 接口安装

1. SDK 目录结构

目录结构（以 Linux 为例）：

cpp_sdk/linux/
├── include/woan/        ← 头文件
│   ├── gripper_control.h
│   ├── motor_control.h
│   ├── serial_port.h
│   └── slcan.h
├── lib/                 ← 库文件 (Linux: .so, Windows: .lib/.dll)
└── share/               ← 其他资源（如有）

2. 在你的项目中使用

CMakeLists.txt (Linux):

cmake_minimum_required(VERSION 3.15)
project(my_app)
set(CMAKE_CXX_STANDARD 17)

set(GRIPPER_SDK "${CMAKE_SOURCE_DIR}/woan_gripper_for_user/cpp_sdk/linux")
include_directories(${GRIPPER_SDK}/include)
link_directories(${GRIPPER_SDK}/lib)

add_executable(my_app main.cpp)
target_link_libraries(my_app gripper_control_lib)

CMakeLists.txt (Windows): 将上述 linux 改为 win 即可。

编译 & 运行 (Linux):

mkdir build && cd build
cmake ..
make
export LD_LIBRARY_PATH=../cpp_sdk/linux/lib:$LD_LIBRARY_PATH
./my_app

三、Python 接口说明

以下文档基于 woangripper_api_py.GripperControl 封装接口，覆盖常用控制流程中的核心方法。

1) `GripperControl()`

功能介绍

创建夹爪控制器对象，后续所有初始化、控制与状态查询均通过该对象完成。

函数原型

g = gripper.GripperControl()

参数

无

返回值

GripperControl：夹爪控制对象实例。

示例

import woangripper_api_py as gripper
g = gripper.GripperControl()

2) `initialize(device, motor_type="canable")`

功能介绍

建立与夹爪硬件的通信连接并完成底层控制器初始化，是执行任何运动或力控指令前的必要步骤。

函数原型

ok: bool = g.initialize(device: str, motor_type: str = "canable")

参数

device (str)：串口设备路径（如 Linux 下 /dev/ttyACM0）。
motor_type (str)：协议类型，当前支持 canable。

返回值

bool：True 表示初始化成功，False 表示初始化失败（如设备不可达或参数不匹配）。

示例

if not g.initialize("/dev/ttyACM0", "canable"):
    raise RuntimeError("夹爪初始化失败，请检查设备连接与端口权限")

3) `enable_motors()`

功能介绍

使能夹爪电机驱动，允许设备接受位置控制、力控制和抓取控制指令。

函数原型

g.enable_motors() -> None

参数

无

返回值

None

示例

g.enable_motors()

4) `set_position(position)`

功能介绍

直接下发目标开合度，用于快速将夹爪定位到指定位置。

函数原型

g.set_position(position: float) -> None

参数

position (float)：目标开合度百分比，常用范围 0~100。

返回值

None

示例

g.set_position(50.0)  # 快速设置到 50% 开合度

5) `move_p(target_pos, max_vel=100.0, max_acc=250.0, max_jerk=1000.0)`

功能介绍

基于轨迹约束执行平滑位置运动，在保证运动连续性的同时移动到目标开合度。

函数原型

g.move_p(
    target_pos: float,
    max_vel: float = 100.0,
    max_acc: float = 250.0,
    max_jerk: float = 1000.0
) -> None

参数

target_pos (float)：目标开合度百分比（常用 0~100）。
max_vel (float, 可选)：轨迹最大速度限制。
max_acc (float, 可选)：轨迹最大加速度限制。
max_jerk (float, 可选)：轨迹最大加加速度（jerk）限制。

返回值

None

示例

g.move_p(50.0)  # 默认动态参数平滑移动
g.move_p(80.0, max_vel=60.0, max_acc=200.0, max_jerk=800.0)

6) `smart_grasp(grip_force, max_vel=100.0, max_acc=250.0, max_jerk=250.0)`

功能介绍

执行智能抓取流程：闭合接近目标物体，在接触后建立并维持设定抓取力。

函数原型

ok: bool = g.smart_grasp(
    grip_force: float,
    max_vel: float = 100.0,
    max_acc: float = 250.0,
    max_jerk: float = 250.0
)

参数

grip_force (float)：目标抓取力（常用单位 N）。
max_vel (float, 可选)：接近阶段速度上限。
max_acc (float, 可选)：接近阶段加速度上限。
max_jerk (float, 可选)：接近阶段 jerk 上限。

返回值

bool：True 表示抓取流程成功执行，False 表示未达到预期抓取结果。

示例

ok = g.smart_grasp(30.0, max_vel=50.0)
if not ok:
    print("未成功建立稳定抓取，请调整抓取力或接近速度")

7) `force_control(torque)`

功能介绍

发送一次力控指令，适用于高频外部控制循环中的单步控制。

函数原型

g.force_control(torque: float) -> None

参数

torque (float)：单次力控/力矩控制指令值（业务侧通常按抓取力目标传入）。

返回值

None

示例

g.force_control(20.0)  # 发送单帧力控制指令

8) `force_control_loop(torque, duration_sec)`

功能介绍

在给定时间内持续输出力控目标，便于实现短时恒力夹持。

函数原型

g.force_control_loop(torque: float, duration_sec: float) -> None

参数

torque (float)：持续输出的力控/力矩目标值。
duration_sec (float)：持续时间（秒）。

返回值

None

示例

g.force_control_loop(20.0, 3.0)  # 持续 3 秒输出力控制指令

9) `get_gripper_status()`

功能介绍

读取夹爪当前状态快照，用于监控位置、速度和受力反馈。

函数原型

status: gripper.GripperStatus = g.get_gripper_status()

参数

无

返回值

GripperStatus：状态对象，包含：
- position (float)：当前位置（开合度）
- velocity (float)：当前速度
- force (float)：当前受力/输出力

示例

status = g.get_gripper_status()
print(f"位置={status.position:.2f}, 速度={status.velocity:.2f}, 力={status.force:.2f}")

10) `disable_motors()`

功能介绍

关闭电机使能并停止主动驱动，通常用于任务结束或安全停机。

函数原型

g.disable_motors() -> None

参数

无

返回值

None

示例

g.disable_motors()

四、C++ 接口说明

以下仅保留与 Python 文档对应的核心接口，重点给出函数雏形与参数类型定义。

1) `GripperControl()`

gripper_api::GripperControl g;

2) `initialize(const std::string& device, const std::string& motor_type = "canable")`

bool initialize(const std::string& device,
                const std::string& motor_type = "canable");

device：设备路径（如 /dev/ttyACM0）
motor_type：电机/协议类型（如 canable 或 develop）

3) `enableMotors()`

void enableMotors();

4) `set_position(float position)`

void set_position(float position);

position：目标开合度（百分比）

5) `move_p(float target_pos, float max_vel = 100.0f, float max_acc = 250.0f, float max_jerk = 1000.0f)`

void move_p(float target_pos,
            float max_vel = 100.0f,
            float max_acc = 250.0f,
            float max_jerk = 1000.0f);

target_pos：目标开合度（百分比）
max_vel：最大速度
max_acc：最大加速度
max_jerk：最大 jerk

6) `smart_grasp(double grip_force, float max_vel = 100.0f, float max_acc = 250.0f, float max_jerk = 250.0f)`

bool smart_grasp(double grip_force,
                 float max_vel = 100.0f,
                 float max_acc = 250.0f,
                 float max_jerk = 250.0f);

grip_force：抓取力目标
max_vel：接近阶段最大速度
max_acc：接近阶段最大加速度
max_jerk：接近阶段最大 jerk

7) `force_control(double torque)`

void force_control(double torque);

torque：单次力控/力矩指令

8) `force_control_loop(double torque, double duration_sec)`

void force_control_loop(double torque, double duration_sec);

torque：持续力控/力矩目标
duration_sec：持续时间（秒）

9) `get_gripper_status()`

GripperControl::GripperStatus get_gripper_status();

返回结构体定义：

struct GripperStatus {
    float position;
    float velocity;
    float force;
};

10) `disableMotors()`

void disableMotors();

五、常见问题

问题	解决方法
打开端口失败	`ls /dev/ttyACM*` 确认设备号，改用正确的设备路径
`import` 报错找不到 `.so`	确认在正确的 conda 环境中：`conda activate woan_gripper`
C++ 运行时找不到库	`export LD_LIBRARY_PATH=cpp_sdk/linux/lib:$LD_LIBRARY_PATH`（Linux）；Windows 需将 dll 加入 PATH
权限不足	`sudo chmod 666 /dev/ttyACM0` 或把用户加入 `dialout` 组
conda install 找不到依赖	确认 CI 产物 `conda-packages-*` 完整解压到 `conda_package/`（含 linux-64/ 或 win-64/、noarch/）且执行过索引

许可证

MIT License — OneRobotics 团队

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
conda_package		conda_package
cpp_sdk		cpp_sdk
.gitignore		.gitignore
README.md		README.md
install_conda_package.ps1		install_conda_package.ps1
install_conda_package.sh		install_conda_package.sh

Folders and files

Latest commit

History

Repository files navigation

Woan Gripper SDK — 用户安装指南

目录结构

一、Python 接口安装 (推荐)

前置条件

方法 A — 一键脚本 (conda 包)

方法 B — 手动安装

验证安装

二、C++ 接口安装

1. SDK 目录结构

2. 在你的项目中使用

三、Python 接口说明

1) GripperControl()

2) initialize(device, motor_type="canable")

3) enable_motors()

4) set_position(position)

5) move_p(target_pos, max_vel=100.0, max_acc=250.0, max_jerk=1000.0)

6) smart_grasp(grip_force, max_vel=100.0, max_acc=250.0, max_jerk=250.0)

7) force_control(torque)

8) force_control_loop(torque, duration_sec)

9) get_gripper_status()

10) disable_motors()

四、C++ 接口说明

1) GripperControl()

2) initialize(const std::string& device, const std::string& motor_type = "canable")

3) enableMotors()

4) set_position(float position)

5) move_p(float target_pos, float max_vel = 100.0f, float max_acc = 250.0f, float max_jerk = 1000.0f)

6) smart_grasp(double grip_force, float max_vel = 100.0f, float max_acc = 250.0f, float max_jerk = 250.0f)

7) force_control(double torque)

8) force_control_loop(double torque, double duration_sec)

9) get_gripper_status()

10) disableMotors()

五、常见问题

许可证

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1) `GripperControl()`

2) `initialize(device, motor_type="canable")`

3) `enable_motors()`

4) `set_position(position)`

5) `move_p(target_pos, max_vel=100.0, max_acc=250.0, max_jerk=1000.0)`

6) `smart_grasp(grip_force, max_vel=100.0, max_acc=250.0, max_jerk=250.0)`

7) `force_control(torque)`

8) `force_control_loop(torque, duration_sec)`

9) `get_gripper_status()`

10) `disable_motors()`

1) `GripperControl()`

2) `initialize(const std::string& device, const std::string& motor_type = "canable")`

3) `enableMotors()`

4) `set_position(float position)`

5) `move_p(float target_pos, float max_vel = 100.0f, float max_acc = 250.0f, float max_jerk = 1000.0f)`

6) `smart_grasp(double grip_force, float max_vel = 100.0f, float max_acc = 250.0f, float max_jerk = 250.0f)`

7) `force_control(double torque)`

8) `force_control_loop(double torque, double duration_sec)`

9) `get_gripper_status()`

10) `disableMotors()`

Packages