Grippers C++ SDK 1.0.0

Grippers C++ SDK 1.0.0

First stable release of the C++ SDK for Robotiq adaptive grippers over Modbus RTU. From here the API follows semantic versioning: what the README and the public headers describe breaks only on a major release.

The 2F-85, 2F-140 and Hand-E share one Modbus register map, so the SDK speaks to all of them and nothing in it is model-specific. Hardware validation to date is on a 2F-85.

Hosted builds need CMake ≥ 3.16, a C++17 compiler and libserialport (the latter only for the default serial transport). The core also builds freestanding — see Embedded and RTOS targets.

Driving a gripper

• One object to drive a gripper. Constructing Gripper opens the serial link, reads the gripper status (it fails when nothing answers), seeds the command image from the gripper's own state echoes — so connecting never disturbs a running gripper — and starts exchanging.
• Typed whole-block command and status API. setCommand() / getCommand() / getStatus() exchange complete GripperCommand / GripperStatus blocks with named fields (positionRequest, speed, ...), accessors for the packed action/status bytes, and the raw bytes through data(). Reads are whole snapshots, so consecutive fields never come from different exchange cycles.
• Background exchange cycle, one FC 0x17 transaction per period. A single read/write-multiple-registers transaction carries command and status together (~4 ms median at 115200 baud). Rate set by connectionFrequency — default 100 Hz, up to ~200 Hz, 0 free-runs. Application accessors touch the process image only and never block on the bus.
• Published register map. Block byte layout and status bit masks in Robotiq/gripper/register_map.hpp, Modbus register addresses in Robotiq/detail/modbus_constants.hpp, both mirroring the instruction manual; typed decoding of the gripper and controller fault nibbles (FaultStatus, GripperFault, ControllerFault, severity).
• Bring your own logging. Inject a Logger implementation; StderrLogger (optionally named, to tell library lines from application lines) and NullLogger ship with it. No logging framework imposed on the consumer.

Runs without hardware

makeFakeGripper() returns a Gripper driving a fake device instead of a serial port — the real typed blocks, exchange cycle, process image and procedures above a deliberately minimal device — for bring-up, demos and CI. No motion profile, travel time, object detection or fault injection. GRIPPERS_BUILD_FAKE=OFF leaves it out of the library.

Embedded and RTOS targets

The core — Gripper and its exchange loop — compiles for freestanding targets (arm-none-eabi, e.g. Cortex-M). Everything OS-flavored is injectable:

• GRIPPERS_HOSTED=OFF drops the std::thread-backed Platform (makeDefaultPlatform()) and the stderr default logger. Supply a Platform — four members over your RTOS's primitives — to Gripper's platform-taking constructor. ports/threadx/threadx_platform.hpp is a working reference port (Azure RTOS ThreadX, exchange-task stack size and priority as constructor arguments).
• GRIPPERS_BUILD_DEFAULT_SERIAL=OFF drops the libserialport-backed DefaultSerial and the dependency; inject your own Serial, e.g. a UART transport. Hosted builds can do the same to reach a transport libserialport does not cover.
• detail::GripperModbusClient is the no-thread layer — one Modbus transaction per call — so a single-threaded superloop schedules the exchange itself. The simplest path for small MCUs: no RTOS, no Platform.

Hosted platforms

Linux, macOS and Windows (MSYS2/UCRT64; MSVC not supported because libserialport ships no MSVC package). libserialport transport, nanoMODBUS protocol layer. On Linux the FTDI latency_timer is set to 1 ms automatically when permissions allow — the 16 ms kernel default triples Modbus latency. Known ceilings: ~60 Hz on the default macOS FTDI driver, and Windows timer quantization (~15.6 ms) below ~16 ms periods.

Packaging and quality

• Consumed as find_package(grippers) or add_subdirectory(sdk_cpp), linking Robotiq::grippers. A consumer that re-exports the SDK's headers as part of its own API links Robotiq::grippers_objects instead and absorbs every object without whole-archive linker flags — which is what keeps CMake 3.22 consumers (ROS 2 Humble) building. Both forms carry identical usage requirements and are position-independent.
• BSD-3-Clause license (portions derived from PickNik's ros2_robotiq_gripper, notices preserved).
• Hardware-free unit test suite, with CI on Linux, macOS and Windows, plus an arm-none-eabi freestanding compile, a ThreadX link test on Cortex-M55, a hosted-pieces-off CMake build, clang-format and coverage jobs.
• README with a worked example (sdk_cpp/examples/move_gripper.cpp).

Not in this release

No exchange-cycle sync primitive yet — a control loop wanting to run in step with the exchange polls the process image — and no human-readable dump of the command and status blocks. Both are additive, so they land in a 1.x minor release.