OneroGripper API · 用户手册

OneRobotics 独立夹爪的预编译 SDK 与 Python 安装包。本手册作为总入口，负责说明仓库布局、三种语言接口关系和最常用控制流程；完整签名、安装细节和更多诊断信息请跳转到各语言子 README。

• c/README.md - 纯 C ABI 包，适合 C 工程或 FFI
• c++/README.md - C++ SDK，namespace onero_gripper_api
• python/README.md - Python 包，import onerogripper
• demo/README.md - Python / C / C++ 三语言最小控制示例

版本：1.1.0 · 支持平台：Linux x86_64 / Linux arm64 / Linux riscv64 / Windows x86_64 · C 标准：C11+ · C++ 标准：C++17+ · Python：3.12

---

一、仓库布局

OneroGripper_API_for_Users/
├── README.md
├── c/
│   ├── include/onero_gripper_c.h
│   ├── linux/{linux-x86_64,linux-arm64,linux-riscv64}/libonerogripper.so
│   ├── windows/windows-x86_64/{onerogripper.dll,onerogripper.lib}
│   └── README.md
├── c++/
│   ├── include/{onero_gripper.h,onero_define.h}
│   ├── linux/{linux-x86_64,linux-arm64,linux-riscv64}/libonerogripper.so
│   ├── windows/windows-x86_64/{onerogripper.dll,onerogripper.lib}
│   └── README.md
├── python/
│   ├── conda_channel/
│   ├── wheels/linux-riscv64/onerogripper-*.whl
│   └── README.md
└── demo/
    ├── demo.py
    ├── demo.c
    ├── demo.cpp
    ├── CMakeLists.txt
    └── README.md

c/ 与 c++/ 是两个分发面：二进制库相同，公开头不同。Python 包安装后提供 onerogripper 扩展模块。

---

二、接口入口

语言	入口	说明
Python	onerogripper.OneroGripper(device)	快速原型和脚本控制
C	onerogripper_create(device) / onerogripper_*	纯 C ABI，适合嵌入和 FFI
C++	onero_gripper_api::OneroGripper	RAII 封装，额外提供触觉读取和中断控制

三层都使用同一个底层夹爪会话。串口设备是独占资源，同一设备同一时刻只能被一个进程打开。

如果夹爪与 OneroArm 机械臂共用同一根 CAN-转串口线，不要在同进程里再创建独立 OneroGripper 会话；请使用机械臂 SDK 的 OneroArm(..., with_gripper=true)，由机械臂实例统一持有总线会话。

---

三、单位与返回值

项	约定
device	Linux 如 "/dev/ttyACM0"，Windows 如 "COM3"
位置 position / percent	夹爪开合百分比，0..100
速度 velocity	百分比/s
力 force / torque	N，命令和反馈按内部上限钳位到约 ±40 N
move_position 默认规划参数	max_vel=100.0，max_acc=250.0，max_jerk=1000.0

常用 int 返回码：

值	含义
0	成功
-1	参数非法、句柄无效或会话未就绪
-4	串口 / 总线写失败或状态刷新失败
-6	运动被 request_stop() 中断（C++ / Python）

---

四、最小控制流程

三种语言的基本顺序一致：

open device -> valid -> enable -> move_position -> status -> force_control -> disable -> close

Python 示例：

import onerogripper as g

grip = g.OneroGripper("/dev/ttyACM0")
assert grip.valid(), "failed to open gripper"

grip.enable()
grip.move_position(80.0)

s = grip.status()
print(f"pos={s.position:.1f}% force={s.force:.2f}N")

grip.force_control(20.0)
grip.disable()

可运行的 Python / C / C++ 示例见 demo/。

---

五、安装与编译入口

Python：

conda create -n onerogripper python=3.12 -y
conda activate onerogripper
conda install -c conda-forge -c ./python/conda_channel/linux onerogripper -y
python -c "import onerogripper; print(onerogripper.__file__)"

RISC-V（linux-riscv64）不走 conda channel，改用随包 wheel： python -m pip install --no-deps ./python/wheels/linux-riscv64/onerogripper-*.whl， 详见 python/README.md 第 2.2 节。

C / C++ demo：

cd demo
cmake -S . -B build -G Ninja
cmake --build build
./build/gripper_demo_c /dev/ttyACM0
./build/gripper_demo_cpp /dev/ttyACM0

更多平台差异、Windows 命令和常见错误处理请看各语言子 README。