Add Reach Alpha 5 device id and manipulator arm messages

[follesoe]

Adds what the drone needs for the Reach Robotics Reach Alpha 5, a five-function manipulator.

Device id

GUEST_PORT_DEVICE_ID_REACH_ROBOTICS_REACH_ALPHA_5 = 52, next to the Outland MP-200 (#310).

Manipulator arm

• GripperCtrl keeps gripper_velocities at field 1 and gains:
  • oneof arm_input:
    • CartesianManipulatorInput: x forward, y right, z down, in the drone body frame.
    • CylindricalManipulatorInput: radial out from the base axis, vertical down along it, azimuth clockwise seen from above.
    • KnownPoseManipulatorInput: a ManipulatorPose (stowed or deployed) and a velocity (0..1) along the drone's path to it. Hold-to-run: the arm moves only while the velocity is above zero, and resumes from wherever it stopped.
    • Cartesian and cylindrical values are normalized to -1..1 and scaled by the drone to its configured maximum speeds. The chosen input says how the command is read, so there is no separate mode to disagree with it.
  • speed_modifier (-1..1): negative is slower, positive faster, 0 the drone's default speed. Scales arm_input only, not gripper_velocities.
  • Each command stands until the next one, as clients send on change: the arm stops on a command without arm input, or when the client watchdog lapses. Existing clients keep working unchanged.
• GripperTel { Gripper }: how the last arm input was read (ManipulatorControlMode), joint positions, end position in the drone body frame (m), flags for a joint at its limit, a collision, jaws holding something and a joint fault, and the pose being moved towards.

Joint control stays a desk and service tool and is not in the protocol. Maximum speeds, grip current, where the arm sits on the hull and its obstacles stay in the drone's configuration.

The driver side (libblunux) follows in its own PR; nothing uses the new messages yet.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟢 Approval recommended

The protocol additions are consistent, documented, and compatible with existing generation workflows.

Review effort: Balanced
Findings: None

What changed in this PR

Adds protocol support for the Reach Robotics Reach Alpha 5 manipulator.

Changes:

• Adds device ID 52.
• Defines velocity, pose, and telemetry schemas.
• Adds manipulator control and telemetry messages.

File	Description
protobuf_definitions/​message_formats.proto	Defines manipulator data types and device ID.
protobuf_definitions/​control.proto	Adds velocity and named-pose commands.
protobuf_definitions/​telemetry.proto	Adds manipulator state telemetry.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[johannesschrimpf]

I’d prefer extending GripperCtrl with arm input instead of introducing a separate ManipulatorCtrl. This keeps one command path and avoids arbitration between legacy gripper commands and manipulator commands.

Preserve gripper_velocities at field 1 and use a oneof for the arm input:

message GripperCtrl {
  GripperVelocities gripper_velocities = 1;

  oneof arm_input {
    CartesianManipulatorInput cartesian = 2;
    CylindricalManipulatorInput cylindrical = 3;
  }

  float speed_modifier = 4;
}

The Cartesian input would contain x, y, z; the cylindrical input would contain radial, vertical, azimuth. Document the reference frames, positive directions, and normalized ranges for each.

This also removes the need for a separate control-mode field: the selected input determines how to interpret the command, and the two cannot disagree. Telemetry could still report the active mode if useful.

These names avoid overloading surge to mean radial extension, which is no longer forward relative to the drone once the arm swings sideways. Existing clients can continue sending their current commands; absent arm input should mean no arm movement, with consistent stop/watchdog behavior.

[follesoe]

Thanks, agreed. This is now one command path (20de6fb, 96d7b41):

• GripperCtrl keeps gripper_velocities at 1, adds the arm_input oneof (CartesianManipulatorInput x/y/z in the drone body frame; CylindricalManipulatorInput radial/vertical/azimuth about the arm's base axis) and speed_modifier at 4. Frames, positive directions and ranges are documented; speed_modifier scales arm_input only, not gripper_velocities.
• ManipulatorCtrl and the mode field are gone; ManipulatorControlMode remains only in telemetry, to report how the last arm input was read.
• Without arm input the arm doesn't move, and it stops when the commands stop.
• ManipulatorPoseCtrl: a pose move runs to the end by itself; a GripperCtrl with a nonzero arm_input or a lapse of the client watchdog cancels it, gripper and rotation velocities do not.
• The telemetry end_position is in the drone body frame, the same axes as the cartesian input.

[johannesschrimpf]

Thanks, this addresses my review: extending GripperCtrl gives us one command path, and the oneof makes the coordinate mode explicit without a separate mode field. The field names and documented frames are clearer.

Could we clarify the stop behavior during a named-pose move? GripperCtrl says that without arm input the arm does not move, but ManipulatorPoseCtrl says the pose continues unless interrupted by nonzero arm input or watchdog expiry.

I’d document that absent/zero arm input means no manual movement and does not cancel a pose. We should also define how a client explicitly cancels a pose without requesting movement or letting its watchdog expire—for example, whether ManipulatorPoseCtrl with MANIPULATOR_POSE_UNSPECIFIED cancels the current move.

[follesoe]

Good catch. We resolved it by removing the one-shot pose move altogether (08b3f6d), so there's no conflict left to document.

Moving to a known pose is now an explicit, hold-to-run action, and a third case of arm_input:

message KnownPoseManipulatorInput {
  ManipulatorPose pose = 1;
  float velocity = 2; // Speed along the path (0.0..1.0): 0 holds the arm where it is.
}

oneof arm_input {
  CartesianManipulatorInput cartesian = 2;
  CylindricalManipulatorInput cylindrical = 3;
  KnownPoseManipulatorInput known_pose = 5;
}

• The arm moves towards the pose only while the latest GripperCtrl carries known_pose with a velocity above zero. The drone chooses the path; for the Reach Alpha 5 it lifts to upright, swings the base, then lowers, with the joints arriving together.
• It stops where it is when the velocity goes to 0, when a command carries another arm input or none, or when the client watchdog lapses. There's no separate cancel: releasing the control is the cancel, and resuming continues from wherever the arm stopped.
• So "without arm input the arm does not move" holds for poses too, and ManipulatorPoseCtrl is gone.
• The GripperCtrl comment now matches how the app sends it, on change: each command stands until the next one, and the arm stops on a command without arm input or when the client watchdog lapses.
• ManipulatorControlMode gains KNOWN_POSE, and ManipulatorTel.moving_to reports the pose being approached.

The idea is that moving the arm into a pose is never something that happens on its own: in the app it maps to holding a control (on a pad, the right stick pushed forward in a pose mode), and letting go stops the arm.

[Copilot]

Copilot review overview

🟢 Approval recommended

The additive protobuf changes are coherent, documented, and preserve existing wire compatibility.

Review effort: Balanced
Findings: None