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:

GenericServo 

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

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

Parameters:

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:

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:

Methods:

  • take_picture –

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

Attributes:

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 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:

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:

Methods:

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:

Methods:

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:

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:

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:

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