blueye.sdk.guestport - Blueye SDK

Skip to content

# blueye.sdk.guestport

## `` guestport

Classes:

- `GenericServo` –

  Represents a servo connected to a guest port on the Blueye drone.

- `Gripper` –

  Represents a gripper connected to a guest port on the Blueye drone.

- `GuestPortCamera` –

  Represents a camera connected to a guest port on the Blueye drone.

- `GuestPortLight` –

  Represents a light connected to a guest port on the Blueye drone.

- `Laser` –

  Represents a laser connected to a guest port on the Blueye drone.

- `Peripheral` –

  Represents a peripheral device connected to a guest port on the Blueye drone.

- `SkidServo` –

  Represents the servo on the skid (typically used for multibeams)

Functions:

- `device_to_peripheral` –

  Convert a device to its corresponding peripheral class.

### `` GenericServo

    GenericServo(
        parent_drone: Drone,
        port_number: GuestPortNumber,
        device: GuestPortDevice,
    )

Represents a servo connected to a guest port on the Blueye drone.

Parameters:

- `parent_drone` (`Drone`) –

  The parent drone instance.

- `port_number` (`GuestPortNumber`) –

  The guest port number.

- `device` (`GuestPortDevice`) –

  The guest port device.

Methods:

- `get_angle` –

  Get the current angle of the servo.

- `set_angle` –

  Set the angle of the servo.

Source code in `blueye/sdk/guestport.py`

    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    def __init__(
        self, parent_drone: "Drone", port_number: bp.GuestPortNumber, device: bp.GuestPortDevice
    ):
        """Initialize the Servo class.

        Args:
            parent_drone (Drone): The parent drone instance.
            port_number (bp.GuestPortNumber): The guest port number.
            device (bp.GuestPortDevice): The guest port device.
        """

        self.max_angle = 90
        self.min_angle = -90
        Peripheral.__init__(self, parent_drone, port_number, device)

#### `` get_angle

    get_angle() -> float | None

Get the current angle of the servo.

Returns:

- `float | None` –

  The current angle of the servo in degrees. None if telemetry is not available.

Source code in `blueye/sdk/guestport.py`

    251
    252
    253
    254
    255
    256
    257
    258
    259
    260
    261
    def get_angle(self) -> float | None:
        """Get the current angle of the servo.

        Returns:
            The current angle of the servo in degrees. None if telemetry is not available.
        """
        telemetry_msg = self.parent_drone.telemetry.get(bp.GenericServoTel)
        if telemetry_msg is None:
            return None
        else:
            return telemetry_msg.servo.value

#### `` set_angle

    set_angle(angle: float) -> None

Set the angle of the servo.

Parameters:

- `angle` (`float`) –

  The angle to set for the servo (-90 to 90 degrees).

Raises:

- `ValueError` –

  If the angle is not within the allowed range.

Source code in `blueye/sdk/guestport.py`

    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    def set_angle(self, angle: float) -> None:
        """Set the angle of the servo.

        Args:
            angle (float): The angle to set for the servo (-90 to 90 degrees).

        Raises:
            ValueError: If the angle is not within the allowed range.
        """
        if angle < self.min_angle or angle > self.max_angle:
            raise ValueError(
                f"Angle must be between {self.min_angle} and {self.max_angle} degrees."
            )
        self.parent_drone._ctrl_client.set_generic_servo_angle(angle, self.port_number)

### `` Gripper

    Gripper(
        parent_drone: Drone,
        port_number: GuestPortNumber,
        device: GuestPortDevice,
    )

Represents a gripper connected to a guest port on the Blueye drone.

Parameters:

- `parent_drone` (`Drone`) –

  The parent drone instance.

- `port_number` (`GuestPortNumber`) –

  The guest port number.

- `device` (`GuestPortDevice`) –

  The guest port device.

Attributes:

- `grip_velocity` (`float`) –

  Get or set the current grip velocity of the Gripper.

- `rotation_velocity` (`float`) –

  Get or set the current rotation velocity of the Gripper.

Source code in `blueye/sdk/guestport.py`

    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    def __init__(
        self, parent_drone: "Drone", port_number: bp.GuestPortNumber, device: bp.GuestPortDevice
    ):
        """Initialize the Gripper class.

        Args:
            parent_drone (Drone): The parent drone instance.
            port_number (bp.GuestPortNumber): The guest port number.
            device (bp.GuestPortDevice): The guest port device.
        """
        Peripheral.__init__(self, parent_drone, port_number, device)
        self._grip_velocity = 0
        self._rotation_velocity = 0

#### `` grip_velocity `property` `writable`

    grip_velocity: float

Get or set the current grip velocity of the Gripper.

Parameters:

- `value` (`float`) –

  The new grip velocity to set. Must be a float between -1.0 and 1.0.

Returns:

- `float` –

  The current grip velocity of the Gripper.

Raises:

- `ValueError` –

  If the grip velocity is not between -1.0 and 1.0.

#### `` rotation_velocity `property` `writable`

    rotation_velocity: float

Get or set the current rotation velocity of the Gripper.

Parameters:

- `value` (`float`) –

  The new rotation velocity to set. Must be a float between -1.0 and 1.0.

Returns:

- `float` –

  The current rotation velocity of the Gripper.

Raises:

- `ValueError` –

  If the rotation velocity is not between -1.0 and 1.0.

### `` GuestPortCamera

    GuestPortCamera(
        parent_drone: Drone,
        port_number: GuestPortNumber,
        device: GuestPortDevice,
    )

Represents a camera connected to a guest port on the Blueye drone.

Parameters:

- `parent_drone` (`Drone`) –

  The parent drone instance.

- `port_number` (`GuestPortNumber`) –

  The guest port number.

- `device` (`GuestPortDevice`) –

  The guest port device.

Methods:

- `take_picture` –

  Take a still picture and store it locally on the drone.

Attributes:

- `bitrate` (`int`) –

  Set or get the video stream bitrate.

- `bitrate_still_picture` (`int`) –

  Set or get the bitrate for the still picture stream.

- `exposure` (`int`) –

  Set or get the camera exposure.

- `framerate` (`int`) –

  Set or get the camera frame rate.

- `hue` (`int`) –

  Set or get the camera hue.

- `is_recording` (`Optional[bool]`) –

  Get or set the camera recording state.

- `record_time` (`Optional[int]`) –

  Get the duration of the current camera recording.

- `recording_resolution` (`Resolution`) –

  Set or get the camera recording resolution.

- `resolution` (`int`) –

  Set or get the camera resolution.

- `stream_resolution` (`Resolution`) –

  Set or get the camera stream resolution.

- `whitebalance` (`int`) –

  Set or get the camera white balance.

Source code in `blueye/sdk/guestport.py`

    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    def __init__(
        self, parent_drone: "Drone", port_number: bp.GuestPortNumber, device: bp.GuestPortDevice
    ):
        """Initialize the GuestPortCamera class.

        Args:
            parent_drone (Drone): The parent drone instance.
            port_number (bp.GuestPortNumber): The guest port number.
            device (bp.GuestPortDevice): The guest port device.
        """
        Camera.__init__(self, parent_drone, is_guestport_camera=True)
        Peripheral.__init__(self, parent_drone, port_number, device)

#### `` bitrate `property` `writable`

    bitrate: int

Set or get the video stream bitrate.

Parameters:

- `bitrate` (`int`) –

  Set the video stream bitrate in bits, valid values are in range (1 000 000 .. 16 000 000).

Returns:

- `int` –

  The H264 video stream bitrate.

#### `` bitrate_still_picture `property` `writable`

    bitrate_still_picture: int

Set or get the bitrate for the still picture stream.

Parameters:

- `bitrate` (`int`) –

  Set the still picture stream bitrate in bits, valid values are in range (1 000 000 .. 300 000 000). Default value is 100 000 000.

Returns:

- `int` –

  The still picture stream bitrate.

#### `` exposure `property` `writable`

    exposure: int

Set or get the camera exposure.

Parameters:

- `exposure` (`int`) –

  Set the camera exposure time. Unit is thousandths of a second, ie. 5 = 5s/1000. Valid values are in the range (1 .. 5000) or -1 for auto exposure.

Returns:

- `int` –

  The camera exposure.

#### `` framerate `property` `writable`

    framerate: int

Set or get the camera frame rate.

Parameters:

- `framerate` (`int`) –

  Set the camera frame rate in frames per second. Valid values are 25 or 30.

Returns:

- `int` –

  The camera frame rate.

#### `` hue `property` `writable`

    hue: int

Set or get the camera hue.

Parameters:

- `hue` (`int`) –

  Set the camera hue. Valid values are in the range (-40..40).

Returns:

- `int` –

  The camera hue.

#### `` is_recording `property` `writable`

    is_recording: Optional[bool]

Get or set the camera recording state.

Parameters:

- `start_recording` (`bool`) –

  Set to True to start a recording, set to False to stop the current recording.

Returns:

- `Optional[bool]` –

  True if the camera is currently recording, False if not. Returns None if the SDK hasn't received a RecordState telemetry message.

Warns:

- `RuntimeWarning` –

  If no recording state telemetry data is received.

#### `` record_time `property`

    record_time: Optional[int]

Get the duration of the current camera recording.

Returns:

- `Optional[int]` –

  The length in seconds of the current recording, -1 if the camera is not currently recording. Returns None if the SDK hasn't received a RecordState telemetry message.

#### `` recording_resolution `property` `writable`

    recording_resolution: Resolution

Set or get the camera recording resolution.

For drones running Blunux version < 4.4.1 this is the same as the `resolution` property.

Returns:

- `Resolution` –

  The camera recording resolution.

#### `` resolution `property` `writable`

    resolution: int

Set or get the camera resolution.

Parameters:

- `resolution` (`int`) –

  Set the camera in vertical pixels. Valid values are 720 or 1080.

Returns:

- `int` –

  The camera resolution.

#### `` stream_resolution `property` `writable`

    stream_resolution: Resolution

Set or get the camera stream resolution.

For drones running blunux version < 4.4.1 this is the same as the `resolution` property.

Parameters:

- `resolution` (`Resolution`) –

  Set the camera stream resolution.

Raises:

- `ValueError` –

  If the resolution is not a valid `blueye.protocol.Resolution` type

Returns:

- `Resolution` –

  The camera stream resolution

#### `` whitebalance `property` `writable`

    whitebalance: int

Set or get the camera white balance.

Parameters:

- `white_balance` (`int`) –

  Set the camera white balance. Valid values are in the range (2800..9300) or -1 for auto white balance.

Returns:

- `int` –

  The camera white balance.

#### `` take_picture

    take_picture()

Take a still picture and store it locally on the drone.

These pictures can be downloaded with the Blueye App, or by any WebDAV compatible client.

Source code in `blueye/sdk/camera.py`

    1070
    1071
    1072
    1073
    1074
    1075
    def take_picture(self):
        """Take a still picture and store it locally on the drone.

        These pictures can be downloaded with the Blueye App, or by any WebDAV compatible client.
        """
        self._parent_drone._ctrl_client.take_still_picture()

### `` GuestPortLight

    GuestPortLight(
        parent_drone: Drone,
        port_number: GuestPortNumber,
        device: GuestPortDevice,
    )

Represents a light connected to a guest port on the Blueye drone.

Parameters:

- `parent_drone` (`Drone`) –

  The parent drone instance.

- `port_number` (`GuestPortNumber`) –

  The guest port number.

- `device` (`GuestPortDevice`) –

  The guest port device.

Methods:

- `get_intensity` –

  Get the intensity of the guest port light.

- `set_intensity` –

  Set the intensity of the guest port light.

Source code in `blueye/sdk/guestport.py`

    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    def __init__(
        self, parent_drone: "Drone", port_number: bp.GuestPortNumber, device: bp.GuestPortDevice
    ):
        """Initialize the GuestPortLight class.

        Args:
            parent_drone (Drone): The parent drone instance.
            port_number (bp.GuestPortNumber): The guest port number.
            device (bp.GuestPortDevice): The guest port device.
        """
        Peripheral.__init__(self, parent_drone, port_number, device)

#### `` get_intensity

    get_intensity() -> Optional[float]

Get the intensity of the guest port light.

Returns:

- `Optional[float]` –

  The intensity of the light (0..1).

Source code in `blueye/sdk/guestport.py`

    93
    94
    95
    96
    97
    98
    99
    def get_intensity(self) -> Optional[float]:
        """Get the intensity of the guest port light.

        Returns:
            The intensity of the light (0..1).
        """
        return self.parent_drone.telemetry.get(bp.GuestPortLightsTel).lights.value

#### `` set_intensity

    set_intensity(intensity: float)

Set the intensity of the guest port light.

Parameters:

- `intensity` (`float`) –

  The intensity of the light (0..1).

Source code in `blueye/sdk/guestport.py`

    85
    86
    87
    88
    89
    90
    91
    def set_intensity(self, intensity: float):
        """Set the intensity of the guest port light.

        Args:
            intensity (float): The intensity of the light (0..1).
        """
        self.parent_drone._ctrl_client.set_guest_port_lights(intensity)

### `` Laser

    Laser(
        parent_drone: Drone,
        port_number: GuestPortNumber,
        device: GuestPortDevice,
    )

Represents a laser connected to a guest port on the Blueye drone.

Parameters:

- `parent_drone` (`Drone`) –

  The parent drone instance.

- `port_number` (`GuestPortNumber`) –

  The guest port number.

- `device` (`GuestPortDevice`) –

  The guest port device.

Methods:

- `get_intensity` –

  Get the current intensity of the laser.

- `set_intensity` –

  Set the intensity of the laser.

Source code in `blueye/sdk/guestport.py`

    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    def __init__(
        self, parent_drone: "Drone", port_number: bp.GuestPortNumber, device: bp.GuestPortDevice
    ):
        """Initialize the Laser class.

        Args:
            parent_drone (Drone): The parent drone instance.
            port_number (bp.GuestPortNumber): The guest port number.
            device (bp.GuestPortDevice): The guest port device.
        """
        Peripheral.__init__(self, parent_drone, port_number, device)

#### `` get_intensity

    get_intensity() -> Optional[float]

Get the current intensity of the laser.

Returns:

- `Optional[float]` –

  The current intensity of the laser.

Source code in `blueye/sdk/guestport.py`

    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    def get_intensity(self) -> Optional[float]:
        """Get the current intensity of the laser.

        Returns:
            The current intensity of the laser.
        """
        telemetry_msg = self.parent_drone.telemetry.get(bp.LaserTel)
        if telemetry_msg is None:
            return None
        else:
            return telemetry_msg.laser.value

#### `` set_intensity

    set_intensity(intensity: float)

Set the intensity of the laser.

If the laser does not support dimming but only on and off, a value of 0 turns the laser off, and any value above 0 turns the laser on.

Parameters:

- `intensity` (`float`) –

  The intensity of the laser (0..1).

Raises:

- `ValueError` –

  If the intensity is not between 0 and 1.

Source code in `blueye/sdk/guestport.py`

    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    def set_intensity(self, intensity: float):
        """Set the intensity of the laser.

        If the laser does not support dimming but only on and off, a value of 0 turns the laser off,
        and any value above 0 turns the laser on.

        Args:
            intensity (float): The intensity of the laser (0..1).

        Raises:
            ValueError: If the intensity is not between 0 and 1.
        """
        if intensity < 0 or intensity > 1:
            raise ValueError("Laser intensity must be between 0 and 1.")
        self.parent_drone._ctrl_client.set_laser_intensity(intensity)

### `` Peripheral

    Peripheral(
        parent_drone: Drone,
        port_number: GuestPortNumber,
        device: GuestPortDevice,
    )

Represents a peripheral device connected to a guest port on the Blueye drone.

Parameters:

- `parent_drone` (`Drone`) –

  The parent drone instance.

- `port_number` (`GuestPortNumber`) –

  The guest port number.

- `device` (`GuestPortDevice`) –

  The guest port device.

Source code in `blueye/sdk/guestport.py`

    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    def __init__(
        self, parent_drone: "Drone", port_number: bp.GuestPortNumber, device: bp.GuestPortDevice
    ):
        """Initialize the Peripheral class.

        Args:
            parent_drone (Drone): The parent drone instance.
            port_number (bp.GuestPortNumber): The guest port number.
            device (bp.GuestPortDevice): The guest port device.
        """
        self.parent_drone = parent_drone
        self.port_number: bp.GuestPortNumber = port_number
        self.name: str = device.name
        self.manufacturer: str = device.manufacturer
        self.serial_number: str = device.serial_number
        self.depth_rating: float = device.depth_rating
        self.required_blunux_version: str = device.required_blunux_version
        self.device_id: bp.GuestPortDeviceID = device.device_id
        if self.required_blunux_version != "":
            if version.parse(self.required_blunux_version) > version.parse(
                parent_drone.software_version_short
            ):
                logger.warning(
                    f"Peripheral {self.name} requires Blunux version "
                    f"{self.required_blunux_version}, but the drone is running "
                    f"{parent_drone.software_version_short}"
                )

### `` SkidServo

    SkidServo(
        parent_drone: Drone,
        port_number: GuestPortNumber,
        device: GuestPortDevice,
    )

Represents the servo on the skid (typically used for multibeams)

Parameters:

- `parent_drone` (`Drone`) –

  The parent drone instance.

- `port_number` (`GuestPortNumber`) –

  The guest port number.

- `device` (`GuestPortDevice`) –

  The guest port device.

Methods:

- `get_angle` –

  Get the current angle of the skid servo.

- `set_angle` –

  Set the angle of the skid servo.

Source code in `blueye/sdk/guestport.py`

    269
    270
    271
    272
    273
    274
    275
    276
    277
    278
    279
    280
    281
    def __init__(
        self, parent_drone: "Drone", port_number: bp.GuestPortNumber, device: bp.GuestPortDevice
    ):
        """Initialize the SkidServo class.

        Args:
            parent_drone (Drone): The parent drone instance.
            port_number (bp.GuestPortNumber): The guest port number.
            device (bp.GuestPortDevice): The guest port device.
        """
        self.max_angle = 28
        self.min_angle = -28
        Peripheral.__init__(self, parent_drone, port_number, device)

#### `` get_angle

    get_angle() -> float | None

Get the current angle of the skid servo.

Returns:

- `float | None` –

  The current angle of the skid servo in degrees. None if telemetry is not available.

Source code in `blueye/sdk/guestport.py`

    298
    299
    300
    301
    302
    303
    304
    305
    306
    307
    308
    def get_angle(self) -> float | None:
        """Get the current angle of the skid servo.

        Returns:
            The current angle of the skid servo in degrees. None if telemetry is not available.
        """
        telemetry_msg = self.parent_drone.telemetry.get(bp.MultibeamServoTel)
        if telemetry_msg is None:
            return None
        else:
            return telemetry_msg.servo.angle

#### `` set_angle

    set_angle(angle: float) -> None

Set the angle of the skid servo.

Parameters:

- `angle` (`float`) –

  The angle to set for the servo (-28 to 28 degrees).

Raises:

- `ValueError` –

  If the angle is not within the allowed range.

Source code in `blueye/sdk/guestport.py`

    283
    284
    285
    286
    287
    288
    289
    290
    291
    292
    293
    294
    295
    296
    def set_angle(self, angle: float) -> None:
        """Set the angle of the skid servo.

        Args:
            angle (float): The angle to set for the servo (-28 to 28 degrees).

        Raises:
            ValueError: If the angle is not within the allowed range.
        """
        if angle < self.min_angle or angle > self.max_angle:
            raise ValueError(
                f"Angle must be between {self.min_angle} and {self.max_angle} degrees."
            )
        self.parent_drone._ctrl_client.set_multibeam_servo_angle(angle)

### `` device_to_peripheral

    device_to_peripheral(
        parent_drone: Drone,
        port_number: GuestPortNumber,
        device: GuestPortDevice,
    ) -> Peripheral

Convert a device to its corresponding peripheral class.

Parameters:

- `parent_drone` (`Drone`) –

  The parent drone instance.

- `port_number` (`GuestPortNumber`) –

  The guest port number.

- `device` (`GuestPortDevice`) –

  The guest port device.

Returns:

- `Peripheral` –

  The corresponding peripheral class instance.

Source code in `blueye/sdk/guestport.py`

    311
    312
    313
    314
    315
    316
    317
    318
    319
    320
    321
    322
    323
    324
    325
    326
    327
    328
    329
    330
    331
    332
    333
    334
    335
    336
    337
    338
    339
    340
    341
    342
    343
    344
    345
    346
    347
    348
    349
    350
    351
    def device_to_peripheral(
        parent_drone: "Drone", port_number: bp.GuestPortNumber, device: bp.GuestPortDevice
    ) -> Peripheral:
        """Convert a device to its corresponding peripheral class.

        Args:
            parent_drone (Drone): The parent drone instance.
            port_number (bp.GuestPortNumber): The guest port number.
            device (bp.GuestPortDevice): The guest port device.

        Returns:
            The corresponding peripheral class instance.
        """
        logger.debug(f"Found a {device.name} at port {port_number}")
        if device.device_id == bp.GuestPortDeviceID.GUEST_PORT_DEVICE_ID_BLUEYE_CAM:
            peripheral = GuestPortCamera(parent_drone, port_number, device)
        elif (
            device.device_id == bp.GuestPortDeviceID.GUEST_PORT_DEVICE_ID_BLUEYE_LIGHT
            or device.device_id == bp.GuestPortDeviceID.GUEST_PORT_DEVICE_ID_BLUEYE_LIGHT_PAIR
            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)
        elif (
            device.device_id == bp.GuestPortDeviceID.GUEST_PORT_DEVICE_ID_LASER_TOOLS_SEA_BEAM
            or device.device_id == bp.GuestPortDeviceID.GUEST_PORT_DEVICE_ID_SPOT_X_LASER_SCALERS
        ):
            peripheral = Laser(parent_drone, port_number, device)
        elif device.device_id == bp.GuestPortDeviceID.GUEST_PORT_DEVICE_ID_BLUEYE_GENERIC_SERVO:
            peripheral = GenericServo(parent_drone, port_number, device)
        elif device.device_id == bp.GuestPortDeviceID.GUEST_PORT_DEVICE_ID_BLUEYE_MULTIBEAM_SERVO:
            peripheral = SkidServo(parent_drone, port_number, device)
        else:
            peripheral = Peripheral(parent_drone, port_number, device)
        return peripheral