From f74c67bcd9c6ca885735925a128cb0e79f76a024 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20Folles=C3=B8?= Date: Thu, 8 Oct 2026 19:50:32 +0200 Subject: [PATCH 1/3] Add gripper diagnostics and identity telemetry GripperDiagnosticsTel reports the health of each device of a gripper every few seconds: supply voltage, the temperature, humidity and pressure in its housing, motor current and the hardware status flags a Reach Robotics device raises, over-pressure and over-humidity of a leaking housing among them. A value a device does not report is NaN. GripperInfoTel reports what a gripper is, as the GuestPortDeviceID of its connector, and its serial number, model number and firmware version, every minute. Both carry the guest port of the gripper, so that two grippers can be told apart. Co-Authored-By: Claude Opus 5.5 --- protobuf_definitions/message_formats.proto | 55 ++++++++++++++++++++++ protobuf_definitions/telemetry.proto | 10 ++++ 2 files changed, 65 insertions(+) diff --git a/protobuf_definitions/message_formats.proto b/protobuf_definitions/message_formats.proto index d3bb1b4b..ae43e5f7 100644 --- a/protobuf_definitions/message_formats.proto +++ b/protobuf_definitions/message_formats.proto @@ -320,6 +320,61 @@ message Gripper { ManipulatorPose moving_to = 8; // Named pose the arm is moving towards, if any. } +// Hardware status flags a device of a gripper raises about itself, named as a Reach Robotics device names them. +message GripperHardwareStatus { + bool flash_failed_read = 1; // Reading the device's flash memory failed. + bool over_humidity = 2; // Humidity in the housing is too high: water may have got in. + bool over_temperature = 3; // The housing is too hot. + bool comms_serial_error = 4; // Error on the serial line. + bool comms_crc_error = 5; // A packet failed its checksum. + bool motor_driver_fault = 6; // The motor driver reports a fault. + bool encoder_position_error = 7; // The position encoder reads an invalid position. + bool encoder_not_detected = 8; // The position encoder is not detected. + bool device_axis_conflict = 9; // Another device has the same axis. + bool motor_not_connected = 10; // The motor is not connected. + bool motor_over_current = 11; // The motor draws too much current. + bool input_encoder_position_error = 12; // The input encoder reads an invalid position. + bool device_id_conflict = 13; // Another device has the same ID. + bool over_pressure = 14; // Pressure in the housing is too high: the seal may have failed. + bool motor_driver_over_current_and_under_voltage = 15; // Over current or under voltage in the motor driver. + bool motor_driver_over_temperature = 16; // The motor driver is too hot. + bool joint_service_due = 17; // The device is due for service. + bool encoder_fault = 18; // The position encoder reports a fault. + bool low_supply_voltage = 19; // The supply voltage is too low. + bool position_report_not_received = 20; // A position report the device waits for has not arrived. +} + +// Health of one device of a gripper: a joint, or a device of its own. +// +// A value the device did not report is NaN. +message GripperDeviceDiagnostics { + uint32 device_id = 1; // Address of the device on the gripper's bus. On a Reach Robotics arm, 1 is the jaws. + float supply_voltage = 2; // Supply voltage (V). + float temperature = 3; // Temperature in the housing (°C). + float humidity = 4; // Relative humidity in the housing (%). + float internal_pressure = 5; // Pressure in the housing (bar). It holds a partial vacuum: a rise can mean a leak. + float current = 6; // Motor current (A). + // Flags the device reported, and those it raised since the last report. Not set if it reported none. + GripperHardwareStatus hardware_status = 7; +} + +// Identity of a gripper: what it is, and what it reports of itself. +// +// A value the gripper does not report is empty. +message GripperInfo { + GuestPortNumber guest_port_number = 1; // Guest port the gripper is on. + GuestPortDeviceID device_id = 2; // What the gripper is, as its guest-port connector names it. + string serial_number = 3; // Serial number of the gripper, such as 5854. + string model_number = 4; // Model number of the gripper, such as 5001 for a Reach Alpha 5 (RA-5001). + string software_version = 5; // Firmware version of the gripper, such as 5.2.0. +} + +// Health of a gripper and its devices, for diagnostics. +message GripperDiagnostics { + repeated GripperDeviceDiagnostics devices = 1; // One for each device of the gripper that answered. + GuestPortNumber guest_port_number = 2; // Guest port the gripper is on. +} + // Information about a remote client. message ClientInfo { string type = 1; // The type of client (such as Blueye App, Observer App, SDK, etc). diff --git a/protobuf_definitions/telemetry.proto b/protobuf_definitions/telemetry.proto index d51326d7..5467e677 100644 --- a/protobuf_definitions/telemetry.proto +++ b/protobuf_definitions/telemetry.proto @@ -273,6 +273,16 @@ message GripperTel { Gripper gripper = 1; // Gripper state. } +// Identity of a gripper, published every minute for each connected gripper. +message GripperInfoTel { + GripperInfo gripper_info = 1; // Gripper identity. +} + +// Health of a gripper, published every few seconds for each connected gripper that reports it. +message GripperDiagnosticsTel { + GripperDiagnostics gripper_diagnostics = 1; // Gripper diagnostics. +} + // GuestPort current readings. message GuestPortCurrentTel { GuestPortCurrent current = 1; // Guest port current readings. From 7da12012ce7608e2105127195c05956601d3714b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20Folles=C3=B8?= Date: Fri, 9 Oct 2026 11:46:38 +0200 Subject: [PATCH 2/3] Name the gripper diagnostics fields as the protocol does A device of a gripper is known by its address on the gripper's bus, as device_id means a GuestPortDeviceID everywhere else in the protocol, GripperInfo included. GripperInfo reports a firmware_version, and the Reach-only flags are ReachHardwareStatus. The comments now say the housing pressure is absolute, when the hardware status is left out, and what GetTelemetryReq returns with more than one gripper. Co-Authored-By: Claude Opus 5.5 --- protobuf_definitions/message_formats.proto | 18 ++++++++++-------- protobuf_definitions/telemetry.proto | 2 ++ 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/protobuf_definitions/message_formats.proto b/protobuf_definitions/message_formats.proto index ae43e5f7..26077885 100644 --- a/protobuf_definitions/message_formats.proto +++ b/protobuf_definitions/message_formats.proto @@ -320,8 +320,9 @@ message Gripper { ManipulatorPose moving_to = 8; // Named pose the arm is moving towards, if any. } -// Hardware status flags a device of a gripper raises about itself, named as a Reach Robotics device names them. -message GripperHardwareStatus { +// Hardware status flags a device of a Reach Robotics gripper raises about itself, named as Reach names them. +// A gripper of another make would need flags of its own. +message ReachHardwareStatus { bool flash_failed_read = 1; // Reading the device's flash memory failed. bool over_humidity = 2; // Humidity in the housing is too high: water may have got in. bool over_temperature = 3; // The housing is too hot. @@ -348,14 +349,15 @@ message GripperHardwareStatus { // // A value the device did not report is NaN. message GripperDeviceDiagnostics { - uint32 device_id = 1; // Address of the device on the gripper's bus. On a Reach Robotics arm, 1 is the jaws. + uint32 address = 1; // Address of the device on the gripper's bus. On a Reach Robotics arm, 1 is the jaws. float supply_voltage = 2; // Supply voltage (V). float temperature = 3; // Temperature in the housing (°C). float humidity = 4; // Relative humidity in the housing (%). - float internal_pressure = 5; // Pressure in the housing (bar). It holds a partial vacuum: a rise can mean a leak. + float internal_pressure = 5; // Absolute pressure in the housing (bar), a partial vacuum: a rise can mean a leak. float current = 6; // Motor current (A). - // Flags the device reported, and those it raised since the last report. Not set if it reported none. - GripperHardwareStatus hardware_status = 7; + // Flags the device reported, and those it raised since the last report. + // Not set if the device sent no hardware status. + ReachHardwareStatus hardware_status = 7; } // Identity of a gripper: what it is, and what it reports of itself. @@ -365,8 +367,8 @@ message GripperInfo { GuestPortNumber guest_port_number = 1; // Guest port the gripper is on. GuestPortDeviceID device_id = 2; // What the gripper is, as its guest-port connector names it. string serial_number = 3; // Serial number of the gripper, such as 5854. - string model_number = 4; // Model number of the gripper, such as 5001 for a Reach Alpha 5 (RA-5001). - string software_version = 5; // Firmware version of the gripper, such as 5.2.0. + string model_number = 4; // Model number of the gripper, such as 5001 for a Reach Alpha 5 or 2130 for a Reach Alpha 2. + string firmware_version = 5; // Firmware version of the gripper, such as 5.2.0. } // Health of a gripper and its devices, for diagnostics. diff --git a/protobuf_definitions/telemetry.proto b/protobuf_definitions/telemetry.proto index 5467e677..f693a6db 100644 --- a/protobuf_definitions/telemetry.proto +++ b/protobuf_definitions/telemetry.proto @@ -274,11 +274,13 @@ message GripperTel { } // Identity of a gripper, published every minute for each connected gripper. +// With several grippers, GetTelemetryReq returns the one that published last: its guest port tells which. message GripperInfoTel { GripperInfo gripper_info = 1; // Gripper identity. } // Health of a gripper, published every few seconds for each connected gripper that reports it. +// With several grippers, GetTelemetryReq returns the one that published last: its guest port tells which. message GripperDiagnosticsTel { GripperDiagnostics gripper_diagnostics = 1; // Gripper diagnostics. } From f33f30e73c2b52b92e26f0326e46f2d9411b54b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20Folles=C3=B8?= Date: Fri, 9 Oct 2026 12:17:02 +0200 Subject: [PATCH 3/3] Mark unreported gripper diagnostics with validity bools A value a device of a gripper did not report was NaN, a convention no other message has, and one that does not survive a JSON round trip in the TypeScript package. Each value now has an is_*_valid bool, as GnssStatus does, and is 0 when not reported. Co-Authored-By: Claude Opus 5.5 --- protobuf_definitions/message_formats.proto | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/protobuf_definitions/message_formats.proto b/protobuf_definitions/message_formats.proto index 26077885..05c06df6 100644 --- a/protobuf_definitions/message_formats.proto +++ b/protobuf_definitions/message_formats.proto @@ -347,14 +347,19 @@ message ReachHardwareStatus { // Health of one device of a gripper: a joint, or a device of its own. // -// A value the device did not report is NaN. +// A value the device did not report is 0, with its is_*_valid false. message GripperDeviceDiagnostics { uint32 address = 1; // Address of the device on the gripper's bus. On a Reach Robotics arm, 1 is the jaws. float supply_voltage = 2; // Supply voltage (V). + bool is_supply_voltage_valid = 8; // True when the device reported its supply voltage. float temperature = 3; // Temperature in the housing (°C). + bool is_temperature_valid = 9; // True when the device reported the temperature in its housing. float humidity = 4; // Relative humidity in the housing (%). + bool is_humidity_valid = 10; // True when the device reported the humidity in its housing. float internal_pressure = 5; // Absolute pressure in the housing (bar), a partial vacuum: a rise can mean a leak. + bool is_internal_pressure_valid = 11; // True when the device reported the pressure in its housing. float current = 6; // Motor current (A). + bool is_current_valid = 12; // True when the device reported its motor current. // Flags the device reported, and those it raised since the last report. // Not set if the device sent no hardware status. ReachHardwareStatus hardware_status = 7;