{"id":51011661,"url":"https://github.com/ioai-tech/io_gripper_sdk","last_synced_at":"2026-06-21T03:30:48.474Z","repository":{"id":362411647,"uuid":"1244140276","full_name":"ioai-tech/io_gripper_sdk","owner":"ioai-tech","description":"SDK for IO-AI gripper hardware","archived":false,"fork":false,"pushed_at":"2026-06-12T02:38:12.000Z","size":1970,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-12T04:17:12.158Z","etag":null,"topics":["cpp","gripper","robotics"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ioai-tech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-20T02:07:50.000Z","updated_at":"2026-06-12T02:38:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ioai-tech/io_gripper_sdk","commit_stats":null,"previous_names":["ioai-tech/io_gripper_sdk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ioai-tech/io_gripper_sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioai-tech%2Fio_gripper_sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioai-tech%2Fio_gripper_sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioai-tech%2Fio_gripper_sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioai-tech%2Fio_gripper_sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ioai-tech","download_url":"https://codeload.github.com/ioai-tech/io_gripper_sdk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioai-tech%2Fio_gripper_sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34593128,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","gripper","robotics"],"created_at":"2026-06-21T03:30:44.955Z","updated_at":"2026-06-21T03:30:48.465Z","avatar_url":"https://github.com/ioai-tech.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IO Gripper SDK\n\n飞特机械夹爪 C++ SDK 文档\n\n**日期**: 2026.6.4  \n**作者**: fpy\n\n## 概述\n\nIO Gripper SDK 是一个基于 SCServo 协议的机械夹爪驱动库，提供完整的夹爪控制、状态读取和高级功能接口，同时支持相机图像捕获功能。\n\n## 主要功能\n\n- **连接管理**: 支持串口连接、断开和设备扫描\n- **力控制**: 扭矩使能、力限制设置\n- **位置控制**: 支持原始脉冲值和弧度制控制\n- **速度控制**: 支持多种速度设置方式\n- **状态监测**: 实时读取位置、速度、电流、温度等参数\n- **同步控制**: 支持多舵机同步动作\n- **标定功能**: 自动标定最大/最小开口宽度\n- **轮询机制**: 后台轮询更新状态\n- **故障处理**: 紧急停止、故障清除\n- **相机功能**: USB 相机图像捕获、JPEG 压缩、设备枚举\n\n## 核心类和结构体\n\n### DeviceProfile\n设备配置文件，包含波特率、协议版本、夹爪宽度范围和相机参数等。\n\n### GripperState\n实时状态结构体，包含位置、速度、电流、温度、错误码等信息。\n\n### GripperCommand\n控制命令结构体，支持宽度、归一化开口、速度、力矩等参数。\n\n### GripperDriver\n主驱动类，提供所有夹爪控制和查询接口。\n\n### GripperCamera\n相机驱动类，提供图像捕获功能，查询相机支持的设置。\n\n### GripperCompressedImage\n压缩图像结构体，包含时间戳、分辨率、格式和 JPEG 数据。\n\n### CameraInfo\n相机信息结构体，包含设备路径、USB 端口、VID/PID 和序列号。\n\n### CameraSettings\n相机设置结构体，包含宽度、高度和帧率。\n\n### find_port\n设备查找类，提供 USB 设备枚举和路径转换功能。\n\n## 配置文件使用指南\n\n### 配置文件位置\n\n配置文件位于 `gripper_config.yaml`，在初始化驱动时加载。\n\n### 配置文件结构\n\n#### 1. DeviceProfile（设备配置）\n\n##### device_info - 设备信息\n```yaml\ndevice_info:\n  model_name: Feetech_DeviceProfile      # 设备型号名称\n  port: /dev/serial/by-id/usb-1a86_USB_Serial-if00-port0        # 串口设备路径\n  servo_id: 1                             # 默认舵机 ID\n  recommended_baudrate: 128000            # 推荐波特率（bps）\n```\n\n**修改建议**:\n- `port`: 上面的port大概率不用修改。\n- `servo_id`: 自己的舵机id\n- `recommended_baudrate`: 常用值115200, 128000\n\n##### capabilities - 功能特性\n```yaml\ncapabilities:\n  supports_sync_write: true       # 是否支持同步写入\n  supports_sync_read: false       # 是否支持同步读取\n  supports_present_current: true  # 是否支持电流读取\n```\n\n**说明**: 根据实际硬件能力配置，一般无需修改。\n\n##### safety_limits - 安全限制\n```yaml\nsafety_limits:\n  min_voltage_v: 4.5              # 最低工作电压（伏特）\n  max_voltage_v: 25.4             # 最高工作电压（伏特）\n  max_temperature_c: 70.0         # 最高工作温度（摄氏度）\n  max_servo_velocity: 3000        # 最大舵机速度阈值\n  start_power: 8                  # 最小启动力（0-255）\n  release_torque_on_disconnect: true  # 3次通信失败后是否泄力\n```\n\n**修改建议**:\n- 根据实际工作环境调整温度和电压限制以及速度上限\n- `start_power`: 默认为8,值越大会抖动\n- `release_torque_on_disconnect`: 为 `true` 或者 `false` \n\n##### calibration - 标定参数\n```yaml\ncalibration:\n  calib_max_position_raw: 2742    # 基准最大位置原始值（脉冲数）\n  calib_min_position_raw: 2293    # 基准最小位置原始值（脉冲数）\n  calib_max_width_mm: 100.0       # 基准最大开口宽度（毫米）\n  calib_min_width_mm: 0.0         # 基准最小开口宽度（毫米）\n```\n\n**修改建议**:\n- 首次使用运行 `calibrate()` 自动获取calib_max_position_raw，calib_min_position_raw并写入配置文件。\n    注：写入后不能随意修改\n- calib_max_width_mm，calib_min_width_mm需要物理测量实际开口宽度\n- 这些参数用于位置到宽度的线性映射\n\n##### camera - 相机参数\n```yaml\ncamera:\n  width: 640                      # 相机分辨率宽度（像素）\n  height: 480                     # 相机分辨率高度（像素）\n  fps: 25.0                       # 帧率（帧/秒）\n  jpeg_quality: 80                # JPEG 压缩质量（0-100）\n  camera_serial: \"G2026061\"       # 相机序列号（用于设备持久化）\n```\n\n**修改建议**:\n- `width/height`: 根据相机能力调整，常用值：640x480, 1280x720\n- `fps`: 帧率，常用值：15, 25, 30\n- `jpeg_quality`: 图像质量，值越高质量越好，文件越大\n- `camera_serial`: 相机序列号，用于设备拔插后重新定位\n\n#### 2. gripper（夹爪语义控制参数）\n\n```yaml\ngripper:\n  use_width_normalized:\n    use_width_mm: true            # 是否使用毫米单位宽度控制\n    use_normalized_opening: false # 是否使用归一化开口值（0-1）\n    width_mm: 80.0                # 默认控制宽度（毫米）\n    normalized_opening: 0.1       # 默认开口比例（0 闭合, 1 全开）\n    max_effort: 0.15              # 最大夹爪力（0-1）\n    speed: 0.5                    # 夹爪运动速度（0-1）\n```\n\n**修改建议**:\n- `use_width_mm`: `true` 使用宽度控制，`false` 则不使用该方式控制\n- `use_normalized_opening`: `true` 使用归一化控制，`false` 则不使用该方式控制\n- `max_effort`: 根据产品需求调整 输入范围0 - 1 ，最大表示1000\n- `speed`: 运动速度，输入范围0 - 1 最大为之前设置的最大速度\n\n### 加载配置文件示例\n\n```cpp\n#include \"io_gripper.hpp\"\n\nint main() {\n    // 方式1: 使用配置文件初始化\n    io::gripper::GripperDriver driver(\n        \"/dev/serial/by-id/usb-1a86_USB_Serial-if00-port0 \",\n        std::nullopt,\n        \"build/gripper_config.yaml\"  // 指定配置文件  相对路径\n    );\n    \n    // 方式2: 程序中动态创建配置，确保基准最大位置原始值以及基准最小位置原始值准确\n    io::gripper::DeviceProfile profile;\n    profile.model_name = \"Feetech_DeviceProfile\";\n    profile.servo_id = 1;\n    profile.recommended_baudrate = 128000;\n    profile.max_voltage_V = 25.4;\n    profile.min_voltage_V = 4.5;\n    profile.calib_max_position_raw: 2742 \n    profile.calib_min_position_raw: 2293\n    profile.calib_max_width_mm = 100.0;\n    profile.calib_min_width_mm = 0.0;\n    \n    // 设置相机参数\n    profile.width = 640;\n    profile.height = 480;\n    profile.fps = 30.0;\n    profile.jpeg_quality = 80;\n    \n    io::gripper::GripperDriver driver(\n        \"/dev/serial/by-id/usb-1a86_USB_Serial-if00-port0 \",\n        profile\n    );\n    \n    if (driver.connect()) {\n        // 使用驱动...\n    }\n    \n    return 0;\n}\n```\n\n## 使用示例\n\n### 夹爪控制示例 参考main.cpp\n\n```cpp\n// 创建驱动实例\nio::gripper::GripperDriver driver(\"/dev/ttyUSB0\");\n\n// 连接设备\nif (driver.connect()) {\n    // 扫描设备 ID\n    auto ids = driver.scanIds();\n    \n    // 初始化\n    driver.initialize(ids);\n    \n    // 启用扭矩\n    driver.enableTorque(ids[0]);\n    \n    // 控制夹爪\n    io::gripper::GripperCommand cmd;\n    cmd.use_width_mm = true;\n    cmd.width_mm = 50.0;\n    cmd.max_effort = 1.0;\n    driver.commandGripper(cmd);\n    \n    // 读取状态\n    auto state = driver.readState(ids[0]);\n    \n    // 断开连接\n    driver.disconnect();\n}\n```\n\n### 相机使用示例  参考main1.cpp\n\n```cpp\n// 创建相机对象\nio::gripper::GripperCamera camera(\"/dev/video0\");\n\n// 或者使用 DeviceProfile 配置\nio::gripper::DeviceProfile profile;\nprofile.width = 1280;\nprofile.height = 720;\nprofile.fps = 30.0;\nio::gripper::GripperCamera camera_with_profile(\"/dev/video0\", profile);\n\n// 打开相机（可选，捕获时会自动打开）\ncamera.open();\n\n// 捕获图像\nio::gripper::GripperCompressedImage image;\nif (camera.captureCompressedImage(image)) {\n    std::cout \u003c\u003c \"图像大小: \" \u003c\u003c image.data.size() \u003c\u003c \" bytes\" \u003c\u003c std::endl;\n    std::cout \u003c\u003c \"分辨率: \" \u003c\u003c image.width \u003c\u003c \"x\" \u003c\u003c image.height \u003c\u003c std::endl;\n    \n    // 保存图像到文件\n    std::ofstream file(\"image.jpg\", std::ios::binary);\n    file.write(reinterpret_cast\u003cconst char*\u003e(image.data.data()), image.data.size());\n}\n\n// 关闭相机\ncamera.close();\n```\n\n### USB 设备枚举示例\n\n```cpp\n// 枚举所有 USB 相机\nio::gripper::find_port port_finder;\nstd::vector\u003cio::gripper::CameraInfo\u003e cameras = port_finder.get_usb_cameras_info();\n\nfor (const auto\u0026 cam : cameras) {\n    std::cout \u003c\u003c \"设备: \" \u003c\u003c cam.device \u003c\u003c std::endl;\n    std::cout \u003c\u003c \"  USB端口: \" \u003c\u003c cam.usb_port \u003c\u003c std::endl;\n    std::cout \u003c\u003c \"  序列号: \" \u003c\u003c cam.serial \u003c\u003c std::endl;\n}\n\n// 通过序列号查找设备路径（解决热插拔问题）\nstd::string video_path = port_finder.find_video_by_camera_serial(\"G2026061\");\nstd::cout \u003c\u003c \"找到设备: \" \u003c\u003c video_path \u003c\u003c std::endl;\n```\n\n## API 参考\n\n### 连接控制\n- `bool connect()` - 连接设备\n- `void disconnect()` - 断开连接\n\n### 设备管理\n- `bool ping(uint8_t servo_id)` - ping 设备是否在线\n- `std::vector\u003cuint8_t\u003e scanIds(uint8_t start, uint8_t end)` - 扫描设备，检查哪些id在线\n- `bool initialize(const std::vector\u003cuint8_t\u003e \u0026servo_ids)` - 初始化\n\n### 扭矩控制\n- `bool enableTorque(uint8_t servo_id)` - 启用扭矩\n- `bool disableTorque(uint8_t servo_id)` - 禁用扭矩\n\n### 运动控制\n- `bool commandPosition()` - 位置控制\n- `bool commandVelocity()` - 速度控制\n- `bool commandGripper()` - 夹爪语义控制\n- `bool syncMove()` - 同步移动\n\n### 状态查询\n- `GripperState readState(uint8_t servo_id)` - 读取单个状态\n- `std::vector\u003cGripperState\u003e readGroupState()` - 读取多个状态\n- `GripperState getCachedState()` - 获取缓存的状态\n\n### 高级功能\n- `void startPolling()` - 启动后台轮询\n- `void stopPolling()` - 停止轮询\n- `bool calibrate()` - 标定\n- `bool clearFault()` - 清除故障\n- `void emergencyStop()` - 紧急停止\n\n### 相机功能\n- `bool GripperCamera::open()` - 打开相机\n- `void GripperCamera::close()` - 关闭相机\n- `bool GripperCamera::isOpened()` - 检查相机是否打开\n- `bool GripperCamera::captureCompressedImage(GripperCompressedImage\u0026)` - 捕获压缩图像\n- `CameraSettings GripperCamera::getCameraSettings(const std::string\u0026)` - 获取相机设置\n\n### USB 设备枚举\n- `std::vector\u003cCameraInfo\u003e find_port::get_usb_cameras_info()` - 获取所有相机信息\n- `std::string find_port::find_video_by_camera_serial(const std::string\u0026)` - 通过序列号找设备\n- `std::string find_port::get_video_id_path(const std::string\u0026)` - 获取物理插槽路径\n- `std::string find_port::find_video_by_id_path(const std::string\u0026)` - 通过物理插槽找设备\n\n## 常见问题\n\n**Q: 如何找到正确的串口？**  \nA: 使用命令 `ls /dev/ttyUSB*` 或 `ls /dev/serial/by-id/` 查看\n\n**Q: 出现：启动失败: bad file: gripper_config.yaml**  \nA: 找不到配置文件，确保路径正确\n\n**Q: 如何调整夹爪力度？**  \nA: 修改配置文件中的 `max_effort` 或通过 `setEffortLimit()` API 动态调整\n\n**Q: 相机设备路径变化怎么办？**  \nA: 使用 `find_port` 类的 `find_video_by_camera_serial()` 或 `find_video_by_id_path()` 方法，通过序列号或物理插槽定位设备\n\n**Q: 如何设置相机分辨率？**  \nA: 修改配置文件中的 `camera.width` 和 `camera.height`，或在 `DeviceProfile` 中设置相应字段\n\n## 编译依赖\n\n- Linux系统 根镜像为Ubuntu22.04\n\n- 系统库安装 yaml-cpp：执行 sudo apt-get install libyaml-cpp-dev。\n\n- 安装：sudo apt install libopencv-dev\n\n- 安装：sudo apt install libudev-dev\n\n- 编译器：支持 C++17 或更高版本。\n\n- 头文件：请确保将本 SDK 提供的 include/ 目录加入到项目的包含路径中。\n\n- 库链接：在编译时链接 libio_gripper.so。\n\n## 版本历史\n\n### v1.1 (2026.6.4)\n- 新增相机图像捕获功能\n- 新增 `GripperCamera` 类\n- 新增 `find_port` 类，支持 USB 设备枚举和路径持久化\n- 添加 `GripperCompressedImage`、`CameraInfo`、`CameraSettings` 结构体\n- 在 `DeviceProfile` 中添加相机参数\n\n### v1.0 (2026.4.15)\n- 初始版本\n- 支持夹爪基本控制功能","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fioai-tech%2Fio_gripper_sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fioai-tech%2Fio_gripper_sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fioai-tech%2Fio_gripper_sdk/lists"}