Add gripper interface

blueye/sdk/connection.py

@@ -212,6 +212,12 @@ def take_still_picture(self):
         msg = blueye.protocol.TakePictureCtrl()
         self._messages_to_send.put(msg)
 
+    def set_gripper_velocities(self, grip: float, rotation: float):
+        msg = blueye.protocol.GripperCtrl(
+            gripper_velocities={"grip_velocity": grip, "rotate_velocity": rotation}
+        )
+        self._messages_to_send.put(msg)
+
 
 class ReqRepClient(threading.Thread):
     def __init__(self, parent_drone: "blueye.sdk.Drone", context: zmq.Context = None):

blueye/sdk/drone.py

@@ -16,7 +16,13 @@
 from .camera import Camera
 from .connection import CtrlClient, ReqRepClient, TelemetryClient, WatchdogPublisher
 from .constants import WaterDensities
-from .guestport import GuestPortCamera, GuestPortLight, Peripheral, device_to_peripheral
+from .guestport import (
+    Gripper,
+    GuestPortCamera,
+    GuestPortLight,
+    Peripheral,
+    device_to_peripheral,
+)
 from .logs import LegacyLogs, Logs
 from .motion import Motion
 
@@ -256,6 +262,8 @@ def _create_peripherals_from_drone_info(self, gp_info: blueye.protocol.GuestPort
                     self.external_light = peripheral
                 elif isinstance(peripheral, GuestPortCamera):
                     self.external_camera = peripheral
+                elif isinstance(peripheral, Gripper):
+                    self.gripper = peripheral
 
     def connect(
         self,

blueye/sdk/guestport.py

@@ -56,6 +56,80 @@ def get_intensity(self) -> Optional[float]:
         return self.parent_drone.telemetry.get(bp.GuestPortLightsTel).lights.value
 
 
+class Gripper(Peripheral):
+    def __init__(
+        self, parent_drone: "Drone", port_number: bp.GuestPortNumber, device: bp.GuestPortDevice
+    ):
+        """
+        Initializes a new Gripper object.
+
+        *Arguments*:
+
+        * parent_drone (Drone): The parent Drone object that this Gripper is attached to.
+        * port_number (GuestPortNumber): The guest port number that this Gripper is attached to.
+        * device (GuestPortDevice): The guest port device that this Gripper is attached to.
+        """
+        Peripheral.__init__(self, parent_drone, port_number, device)
+        self._grip_velocity = 0
+        self._rotation_velocity = 0
+
+    @property
+    def grip_velocity(self) -> float:
+        """
+        Gets or sets the current grip velocity of the Gripper.
+
+        When used as a getter, returns the current grip velocity of the Gripper.
+
+        When used as a setter, sets the grip velocity of the Gripper to the specified value.
+
+        *Arguments*:
+
+        * value (float): The new grip velocity to set. Must be a float between -1.0 and 1.0.
+
+        *Returns*:
+
+        * grip_velocity (float): The current grip velocity of the Gripper.
+        """
+        return self._grip_velocity
+
+    @grip_velocity.setter
+    def grip_velocity(self, value: float):
+        if value < -1.0 or value > 1.0:
+            raise ValueError("Grip velocity must be between -1.0 and 1.0.")
+        self._grip_velocity = value
+        self.parent_drone._ctrl_client.set_gripper_velocities(
+            self._grip_velocity, self._rotation_velocity
+        )
+
+    @property
+    def rotation_velocity(self) -> float:
+        """
+        Gets or sets the current rotation velocity of the Gripper.
+
+        When used as a getter, returns the current rotation velocity of the Gripper.
+
+        When used as a setter, sets the rotation velocity of the Gripper to the specified value.
+
+        *Arguments*:
+
+        * value (float): The new rotation velocity to set. Must be a float between -1.0 and 1.0.
+
+        *Returns*:
+
+        * rotation_velocity (float): The current rotation velocity of the Gripper.
+        """
+        return self._rotation_velocity
+
+    @rotation_velocity.setter
+    def rotation_velocity(self, value: float):
+        if value < -1.0 or value > 1.0:
+            raise ValueError("Rotation velocity must be between -1.0 and 1.0.")
+        self._rotation_velocity = value
+        self.parent_drone._ctrl_client.set_gripper_velocities(
+            self._grip_velocity, self._rotation_velocity
+        )
+
+
 def device_to_peripheral(
     parent_drone: "Drone", port_number: bp.GuestPortNumber, device: bp.GuestPortDevice
 ) -> Peripheral:
@@ -68,6 +142,13 @@ def device_to_peripheral(
         or device.device_id == bp.GuestPortDeviceID.GUEST_PORT_DEVICE_ID_BLUE_ROBOTICS_LUMEN
     ):
         peripheral = GuestPortLight(parent_drone, port_number, device)
+    elif (
+        device.device_id == bp.GuestPortDeviceID.GUEST_PORT_DEVICE_ID_BLUE_ROBOTICS_NEWTON
+        or device.device_id
+        == bp.GuestPortDeviceID.GUEST_PORT_DEVICE_ID_BLUE_ROBOTICS_DETACHABLE_NEWTON
+        or device.device_id == bp.GuestPortDeviceID.GUEST_PORT_DEVICE_ID_BLUEPRINT_LAB_REACH_ALPHA
+    ):
+        peripheral = Gripper(parent_drone, port_number, device)
     else:
         peripheral = Peripheral(parent_drone, port_number, device)
     return peripheral

docs/peripherals.md

@@ -0,0 +1,51 @@
+# Peripherals
+
+The `Drone` class maintains a list of peripherals that are attached to the drone. These peripherals can include cameras, grippers, and other devices that can be controlled using the drone's API.
+
+To list the peripherals that are currently attached to the drone, you can check the `peripherals` attribute of the `Drone` class. This attribute is a list of [`Peripheral`](reference/blueye/sdk/guestport.md#peripheral) objects.
+
+The SDK will also create attributes for supported peripherals to simplify access.
+
+## External camera
+If the drone has a camera attached, the `Drone` class will have an `external_camera` attribute that is a [`GuestPortCamera`](reference/blueye/sdk/guestport.md#guestportcamera) object. This object can be used to control the camera.
+
+```python
+# Capture an image from the external camera
+drone.external_camera.take_picture()
+
+# Set bitrate for external camera to 2 Mbps
+drone.external_camera.bitrate = 2_000_000
+
+# Start recording video from the external camera
+drone.external_camera.is_recording = True
+```
+
+## External light
+If the drone has an external light attached, the `Drone` class will have an `external_light` attribute that is a [`GuestPortLight`](reference/blueye/sdk/guestport.md#guestportlight) object. This object can be used to control the light.
+
+```python
+# Get the current intensity of the external light
+intensity: float = drone.external_light.get_intensity()
+
+# Set the intensity of the external light to 0.5
+drone.external_light.set_intensity(0.5)
+```
+
+## Gripper
+If the drone has a gripper attached, the `Drone` class will have a `gripper` attribute that is a [`Gripper`](reference/blueye/sdk/guestport.md#gripper) object. This object can be used to control the grip and rotation of the gripper.
+
+If the connected gripper does not support rotation, the `rotation_velocity` property will be ignored.
+
+```python
+# Open the gripper
+drone.gripper.grip_velocity = 1.0
+
+# Close the gripper
+drone.gripper.grip_velocity = -1.0
+
+# Rotate the gripper clockwise
+drone.gripper.rotation_velocity = 1.0
+
+# Rotate the gripper counterclockwise
+drone.gripper.rotation_velocity = -1.0
+```

mkdocs.yml

@@ -67,6 +67,7 @@ nav:
       - "Legacy log file format": "logs/legacy-log-file-format.md"
   - "Configure drone parameters": "configuration.md"
   - "Subscribing to a telemetry message": "telemetry-callback.md"
+  - "Peripherals": "peripherals.md"
   - "Updating from v1 to v2": "migrating-to-v2.md"
   - "Protobuf protocol": "protobuf-protocol.md"
   - "HTTP API": "http-api.html"