Grippers

Grippers are mechanical devices that can be integrated with an unmanned vehicle to grip (hold) and release payloads.

PX4 allows grippers to be triggered automatically in Payload Delivery Missions or manually using a Joystick.

High-load gripper example

:::note A gripper can instead be configured as a generic RC or MAVLink actuator. A generic actuator cannot be used with a joystick or in payload missions, but it can be used with an RC Controller. :::

Supported Grippers

There are many different gripper mechanisms ("jaws", "fingers", "electromagnets") and interfaces (PWM, CAN, MAVLink, and so on).

PX4 supports grippers that have simple triggers to hold and release, and that use the following interfaces (see linked documents for details):

• PWM Servo Gripper - Grippers connected to autopilot PWM outputs
• MAVLink Gripper (Untested) - Grippers that support the MAV_CMD_DO_GRIPPER MAVLink command.

Using a Gripper

For information on using a gripper in missions see Payload Delivery Missions.

You can manually trigger a gripper manually from a Joystick button if you've mapped gripper open and gripper close buttons in the QGC Joystick Configuration. Note that if you press the Grab button while the gripper is opening, it will automatically abort releasing behavior and go to the closed position, effectively cancelling the release command. If you do this in a mission while the release is actually happening, then the delivery will be cancelled.

Manually triggering a gripper from an RC Control switch is not supported.

MAVLink applications, such as ground stations, can also control the gripper using the MAV_CMD_DO_GRIPPER MAVLink command.

PX4 Configuration

Package Delivery Configuration

PX4 gripper support is tied to the package delivery feature, which must be enabled and configured in order to be able to use a gripper.

1. Set PD_GRIPPER_EN parameter to 1 (reboot required after change).
2. Set PD_GRIPPER_TYPE to match your gripper. For example, set to Servo for a Servo Gripper.

Gripper Actuator Mapping

Grippers that are connected directly to a flight controller, such as PWM servo grippers, must be mapped to specific outputs during Actuator Configuration.

This is done by assigning the Gripper function to the to the output port where the gripper is connected. For example, the image below assigns Gripper to the PWM AUX5 output.

Gripper output mapping

Additional information about actuator mapping is provided in the gripper-specific documentation. For example, see Gripper Servo > Actuator Mapping.

Enable Pre-ARM Mode

Typically you will want to enable the pre-arming mode. This mode keeps the motors disabled but allows the gripper to be opened and closed for attaching the payload (avoiding potential danger from spinning propellers).

1. Set COM_PREARM_MODE to Always.

Gripper Actuation Timeout

It is important for package delivery that the gripper has time to release before progressing to subsequent waypoints. For grippers that do not provide sensor-based feedback of their state, which is most of them, a configurable timeout is used to signal when the gripper should have opened or closed.

To set the actuation timeout:

1. Measure the time taken for the gripper to open and time to close, and note the longer of these two times.

   There are two easy ways to open and close the gripper. While the drone is on a bench and the propellers are removed:

   • Run the payload_deliverer test in the QGC MAVLink Shell:

     > payload_deliverer gripper_test

     :::note If you get an error message like "[payload_deliverer] not running", repeat the setup procedures above. You might also run the payload_deliverer start command in the Nuttx shell. :::

   • Use the Joystick to trigger gripper open and close actions.
2. Set PD_GRIPPER_TO to whichever of the gripper open and close time is larger.

Mission Delivery Timeout

When running a Payload Delivery Mission it is important that the mission is not halted in the case where the gripper does not report that it has opened (or closed). This might happen if a gripper feedback sensor was damaged or UORB dropped the gripper actuator timout message.

:::note Gripper state feedback from a sensor is not actually supported yet, but it may be in future. :::

The mission-delivery timout provides an additional safeguard, continuing the mission if the gripper's successful actuation acknowledgement is not received.

To set the timeout:

1. Set MIS_PD_TO to a value greater than the gripper actuation timeout.

QGC Joystick Configuration

QGroundControl Joystick configuration allows you to map gripper actions to Joystick buttons, after which you will be open and close the gripper manually.

To map joystick buttons in QGroundControl:

1. Open the menu: QGC Logo (upper-left) > Vehicle Setup > Joystick > Button Assignment tab.

   

   Gripper action mapping
2. Select Gripper Open and Gripper Close actions for your desired joystick buttons, as shown above.

You can test the actions by clicking on the mapped buttons and checking for gripper movement. If the gripper doesn't move as expected check the package delivery configuration and actuator mapping are set up properly.