Skip to content

blueye.sdk.motion

motion

Classes:

  • Motion –

    Control the motion of the drone, and set automatic control modes

Motion 

Motion(parent_drone)

Control the motion of the drone, and set automatic control modes

Motion can be set one degree of freedom at a time by using the 4 motion setters (set_surge, set_sway, set_heave and set_yaw) or for all 4 degrees of freedom in one go through the send_thruster_setpoint method.

Methods:

Attributes:

Source code in blueye/sdk/motion.py 
18
19
20
21
22
def __init__(self, parent_drone):
    self._parent_drone = parent_drone
    self.thruster_lock = threading.Lock()
    self._current_thruster_setpoints = {"surge": 0, "sway": 0, "heave": 0, "yaw": 0}
    self._current_boost_setpoints = {"slow": 0, "boost": 0}

current_thruster_setpoints property writable 

current_thruster_setpoints

Deprecated, use get_current_thruster_setpoints instead.

enable_auto_altitude 

enable_auto_altitude(enable: bool)

Enable or disable the auto altitude control mode

When auto altitude is active, the drone will attempt to maintain its current altitude above the seabed. Input for the heave direction to the thruster_setpoint function specifies a speed set point instead of a force set point. A control loop on the drone will then attempt to maintain the wanted speed in the heave direction as long as auto altitude is active.

Parameters:

  • enable (bool) –

    Activate auto altitude mode if true, de-activate if false. If the drone does not have a valid altitude reading this command will be ignored.

Source code in blueye/sdk/motion.py 
296
297
298
299
300
301
302
303
304
305
306
307
308
def enable_auto_altitude(self, enable: bool):
    """Enable or disable the auto altitude control mode

    When auto altitude is active, the drone will attempt to maintain its current altitude above
    the seabed. Input for the heave direction to the thruster_setpoint function specifies a
    speed set point instead of a force set point. A control loop on the drone will then attempt
    to maintain the wanted speed in the heave direction as long as auto altitude is active.

    Args:
        enable (bool): Activate auto altitude mode if true, de-activate if false. If the drone
                       does not have a valid altitude reading this command will be ignored.
    """
    self._parent_drone._ctrl_client.set_auto_altitude_state(enable)

enable_auto_depth 

enable_auto_depth(enable: bool)

Enable or disable the auto depth control mode

When auto depth is active, input for the heave direction to the thruster_setpoint function specifies a speed set point instead of a force set point. A control loop on the drone will then attempt to maintain the wanted speed in the heave direction as long as auto depth is active.

Parameters:

  • enable (bool) –

    Activate auto depth mode if true, de-activate if false.

Source code in blueye/sdk/motion.py 
230
231
232
233
234
235
236
237
238
239
240
241
def enable_auto_depth(self, enable: bool):
    """Enable or disable the auto depth control mode

    When auto depth is active, input for the heave direction to the thruster_setpoint function
    specifies a speed set point instead of a force set point. A control loop on the drone will
    then attempt to maintain the wanted speed in the heave direction as long as auto depth is
    active.

    Args:
        enable (bool): Activate auto depth mode if true, de-activate if false.
    """
    self._parent_drone._ctrl_client.set_auto_depth_state(enable)

enable_auto_heading 

enable_auto_heading(enable: bool)

Enable or disable the auto heading control mode

When auto heading is active, input for the yaw direction to the thruster_setpoint function specifies a angular speed set point instead of a moment set point. A control loop on the drone will then attempt to maintain the wanted angular velocity in the yaw direction as long as auto heading is active.

Parameters:

  • enable (bool) –

    Activate auto heading mode if true, de-activate if false.

Source code in blueye/sdk/motion.py 
263
264
265
266
267
268
269
270
271
272
273
274
def enable_auto_heading(self, enable: bool):
    """Enable or disable the auto heading control mode

    When auto heading is active, input for the yaw direction to the thruster_setpoint function
    specifies a angular speed set point instead of a moment set point. A control loop on the
    drone will then attempt to maintain the wanted angular velocity in the yaw direction as
    long as auto heading is active.

    Args:
        enable (bool): Activate auto heading mode if true, de-activate if false.
    """
    self._parent_drone._ctrl_client.set_auto_heading_state(enable)

enable_station_keeping 

enable_station_keeping(enable: bool)

Enable or disable the station keeping control mode

When station keeping is active, the drone will attempt to maintain its current position and orientation in the water as long as the mode is active.

Parameters:

  • enable (bool) –

    Activate station keeping mode if true, de-activate if false.

Source code in blueye/sdk/motion.py 
328
329
330
331
332
333
334
335
336
337
def enable_station_keeping(self, enable: bool):
    """Enable or disable the station keeping control mode

    When station keeping is active, the drone will attempt to maintain its current position
    and orientation in the water as long as the mode is active.

    Args:
        enable (bool): Activate station keeping mode if true, de-activate if false.
    """
    self._parent_drone._ctrl_client.set_station_keeping_state(enable)

enable_weather_vaning 

enable_weather_vaning(enable: bool)

Enable or disable the weather vaning control mode

When weather vaning is active, the drone will attempt to maintain its current position in the water and orient itself parallel to the current.

Parameters:

  • enable (bool) –

    Activate weather vaning mode if true, de-activate if false. If the drone does not have a valid altitude reading this command will be ignored.

Source code in blueye/sdk/motion.py 
359
360
361
362
363
364
365
366
367
368
369
def enable_weather_vaning(self, enable: bool):
    """Enable or disable the weather vaning control mode

    When weather vaning is active, the drone will attempt to maintain its current position
    in the water and orient itself parallel to the current.

    Args:
        enable (bool): Activate weather vaning mode if true, de-activate if false. If the drone
                       does not have a valid altitude reading this command will be ignored.
    """
    self._parent_drone._ctrl_client.set_weather_vaning_state(enable)

get_boost 

get_boost() -> float

Get the boost gain

Returns:

  • float –

    The current boost gain, range from 0 to 1.

Source code in blueye/sdk/motion.py 
172
173
174
175
176
177
178
def get_boost(self) -> float:
    """Get the boost gain

    Returns:
        The current boost gain, range from 0 to 1.
    """
    return self._current_boost_setpoints["boost"]

get_current_thruster_setpoints 

get_current_thruster_setpoints()

Returns the current setpoints for the thrusters

We maintain this state in the SDK since the drone expects to receive all of the setpoints at once.

For setting the setpoints you should use the dedicated setters/functions for that, trying to set them directly will raise an AttributeError.

Source code in blueye/sdk/motion.py 
24
25
26
27
28
29
30
31
32
33
34
def get_current_thruster_setpoints(self):
    """Returns the current setpoints for the thrusters

    We maintain this state in the SDK since the drone expects to receive all of the setpoints at
    once.

    For setting the setpoints you should use the dedicated setters/functions for that, trying
    to set them directly will raise an AttributeError.
    """

    return self._current_thruster_setpoints

get_heave 

get_heave() -> float

Get the force reference for the heave direction

Returns:

  • float –

    Force set point in the heave direction in range <-1, 1>.

Source code in blueye/sdk/motion.py 
102
103
104
105
106
107
108
def get_heave(self) -> float:
    """Get the force reference for the heave direction

    Returns:
        Force set point in the heave direction in range <-1, 1>.
    """
    return self._current_thruster_setpoints["heave"]

get_slow 

get_slow() -> float

Get the "slow gain" (inverse of boost)

Returns:

  • float –

    The current slow gain, range from 0 to 1.

Source code in blueye/sdk/motion.py 
192
193
194
195
196
197
198
def get_slow(self) -> float:
    """Get the "slow gain" (inverse of boost)

    Returns:
        The current slow gain, range from 0 to 1.
    """
    return self._current_boost_setpoints["slow"]

get_surge 

get_surge() -> float

Get the force reference for the surge direction

Returns:

  • float –

    Force set point in the surge direction in range <-1, 1>.

Source code in blueye/sdk/motion.py 
60
61
62
63
64
65
66
def get_surge(self) -> float:
    """Get the force reference for the surge direction

    Returns:
        Force set point in the surge direction in range <-1, 1>.
    """
    return self._current_thruster_setpoints["surge"]

get_sway 

get_sway() -> float

Get the force reference for the sway direction

Returns:

  • float –

    Force set point in the sway direction in range <-1, 1>.

Source code in blueye/sdk/motion.py 
81
82
83
84
85
86
87
def get_sway(self) -> float:
    """Get the force reference for the sway direction

    Returns:
        Force set point in the sway direction in range <-1, 1>.
    """
    return self._current_thruster_setpoints["sway"]

get_yaw 

get_yaw() -> float

Get the moment reference for the yaw direction

Returns:

  • float –

    Moment set point in the yaw direction in range <-1, 1>.

Source code in blueye/sdk/motion.py 
123
124
125
126
127
128
129
def get_yaw(self) -> float:
    """Get the moment reference for the yaw direction

    Returns:
        Moment set point in the yaw direction in range <-1, 1>.
    """
    return self._current_thruster_setpoints["yaw"]

is_auto_altitude_active 

is_auto_altitude_active() -> Optional[bool]

Get the state of the auto altitude control mode

When auto altitude is active, the drone will attempt to maintain its current altitude above the seabed. Input for the heave direction to the thruster_setpoint function specifies a speed set point instead of a force set point. A control loop on the drone will then attempt to maintain the wanted speed in the heave direction as long as auto altitude is active.

Returns:

  • Optional[bool] –

    Auto altitude state (bool): True if auto altitude is active, false if not. None if no telemetry message has been received.

Source code in blueye/sdk/motion.py 
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
def is_auto_altitude_active(self) -> Optional[bool]:
    """Get the state of the auto altitude control mode

    When auto altitude is active, the drone will attempt to maintain its current altitude above
    the seabed. Input for the heave direction to the thruster_setpoint function specifies a
    speed set point instead of a force set point. A control loop on the drone will then attempt
    to maintain the wanted speed in the heave direction as long as auto altitude is active.

    Returns:
        Auto altitude state (bool): True if auto altitude is active, false if not. None if no
        telemetry message has been received.
    """
    control_mode_tel = self._parent_drone.telemetry.get(blueye.protocol.ControlModeTel)
    if control_mode_tel is None:
        return None
    else:
        return control_mode_tel.state.auto_altitude

is_auto_depth_active 

is_auto_depth_active() -> Optional[bool]

Get the state of the auto depth control mode

When auto depth is active, input for the heave direction to the thruster_setpoint function specifies a speed set point instead of a force set point. A control loop on the drone will then attempt to maintain the wanted speed in the heave direction as long as auto depth is active.

Returns:

  • Optional[bool] –

    Auto depth state (bool): True if auto depth is active, false if not. None if no telemetry message has been received.

Source code in blueye/sdk/motion.py 
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
def is_auto_depth_active(self) -> Optional[bool]:
    """Get the state of the auto depth control mode

    When auto depth is active, input for the heave direction to the thruster_setpoint function
    specifies a speed set point instead of a force set point. A control loop on the drone will
    then attempt to maintain the wanted speed in the heave direction as long as auto depth is
    active.

    Returns:
        Auto depth state (bool): True if auto depth is active, false if not. None if no
        telemetry message has been received.
    """
    control_mode_tel = self._parent_drone.telemetry.get(blueye.protocol.ControlModeTel)
    if control_mode_tel is None:
        return None
    else:
        return control_mode_tel.state.auto_depth

is_auto_heading_active 

is_auto_heading_active() -> Optional[bool]

Get the state of the auto heading control mode

When auto heading is active, input for the yaw direction to the thruster_setpoint function specifies a angular speed set point instead of a moment set point. A control loop on the drone will then attempt to maintain the wanted angular velocity in the yaw direction as long as auto heading is active.

Returns:

  • Optional[bool] –

    Auto heading state (bool): True if auto heading mode is active, false if not. None if no telemetry message has been received.

Source code in blueye/sdk/motion.py 
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
def is_auto_heading_active(self) -> Optional[bool]:
    """Get the state of the auto heading control mode

    When auto heading is active, input for the yaw direction to the thruster_setpoint function
    specifies a angular speed set point instead of a moment set point. A control loop on the
    drone will then attempt to maintain the wanted angular velocity in the yaw direction as
    long as auto heading is active.

    Returns:
        Auto heading state (bool): True if auto heading mode is active, false if not. None if no
        telemetry message has been received.
    """
    control_mode_tel = self._parent_drone.telemetry.get(blueye.protocol.ControlModeTel)
    if control_mode_tel is None:
        return None
    else:
        return control_mode_tel.state.auto_heading

is_station_keeping_active 

is_station_keeping_active() -> Optional[bool]

Get the state of the station keeping control mode

When station keeping is active, the drone will attempt to maintain its current position and orientation in the water as long as the mode is active.

Returns:

  • Optional[bool] –

    Station keeping state (bool): True if station keeping mode is active, false if not. None if no telemetry message has been received.

Source code in blueye/sdk/motion.py 
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
def is_station_keeping_active(self) -> Optional[bool]:
    """Get the state of the station keeping control mode

    When station keeping is active, the drone will attempt to maintain its current position
    and orientation in the water as long as the mode is active.

    Returns:
        Station keeping state (bool): True if station keeping mode is active, false if not. None
        if no telemetry message has been received.
    """
    control_mode_tel = self._parent_drone.telemetry.get(blueye.protocol.ControlModeTel)
    if control_mode_tel is None:
        return None
    else:
        return control_mode_tel.state.station_keeping

is_weather_vaning_active 

is_weather_vaning_active() -> Optional[bool]

Get the state of the weather vaning control mode

When weather vaning is active, the drone will attempt to maintain its current position in the water and orient itself parallel to the current.

Returns:

  • Optional[bool] –

    Weather vaning state (bool): True if weather vaning mode is active, false if not. None if no telemetry message has been received.

Source code in blueye/sdk/motion.py 
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
def is_weather_vaning_active(self) -> Optional[bool]:
    """Get the state of the weather vaning control mode

    When weather vaning is active, the drone will attempt to maintain its current position
    in the water and orient itself parallel to the current.

    Returns:
        Weather vaning state (bool): True if weather vaning mode is active, false if not. None
        if no telemetry message has been received.
    """
    control_mode_tel = self._parent_drone.telemetry.get(blueye.protocol.ControlModeTel)
    if control_mode_tel is None:
        return None
    else:
        return control_mode_tel.state.weather_vaning

send_thruster_setpoint 

send_thruster_setpoint(surge, sway, heave, yaw)

Control the thrusters of the drone

Set reference values between -1 and 1 for each controllable degree of freedom on the drone. The reference values are mapped linearly to a thruster force, a set point of -1 correspons to maximum negative force and a set point of 1 corresponds to maximum positive force. For the yaw direction the reference is a moment not a force, as the yaw direction is rotational not translational.

Arguments:

  • surge (float): Force set point in the surge direction in range <-1, 1>, a positive set point makes the drone move forward
  • sway (float): Force set point in the sway direction in range <-1, 1>, a positive set point makes the drone move to the right
  • heave (float): Force set point in the heave direction in range <-1, 1>, a positive set point makes the drone move down.
  • yaw (float): Moment set point in the yaw direction in range <-1, 1>, a positive set point makes the drone rotate clockwise.
Source code in blueye/sdk/motion.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def send_thruster_setpoint(self, surge, sway, heave, yaw):
    """Control the thrusters of the drone

    Set reference values between -1 and 1 for each controllable degree of freedom on the drone.
    The reference values are mapped linearly to a thruster force, a set point of -1 correspons
    to maximum negative force and a set point of 1 corresponds to maximum positive force. For
    the yaw direction the reference is a moment not a force, as the yaw direction is rotational
    not translational.


    Arguments:

    * **surge** (float): Force set point in the surge direction in range <-1, 1>,
                         a positive set point makes the drone move forward
    * **sway** (float): Force set point in the sway direction in range <-1, 1>,
                         a positive set point makes the drone move to the right
    * **heave** (float): Force set point in the heave direction in range <-1, 1>,
                         a positive set point makes the drone move down.
    * **yaw** (float): Moment set point in the yaw direction in range <-1, 1>,
                         a positive set point makes the drone rotate clockwise.
    """
    with self.thruster_lock:
        self._current_thruster_setpoints["surge"] = surge
        self._current_thruster_setpoints["sway"] = sway
        self._current_thruster_setpoints["heave"] = heave
        self._current_thruster_setpoints["yaw"] = yaw
        self._send_motion_input_message()

set_boost 

set_boost(boost_gain: float)

Set the boost gain

Parameters:

  • boost_gain (float) –

    Range from 0 to 1.

Source code in blueye/sdk/motion.py 
180
181
182
183
184
185
186
187
188
def set_boost(self, boost_gain: float):
    """Set the boost gain

    Args:
        boost_gain (float): Range from 0 to 1.
    """
    with self.thruster_lock:
        self._current_boost_setpoints["boost"] = boost_gain
        self._send_motion_input_message()

set_heave 

set_heave(heave_value: float)

Set force reference for the heave direction

Parameters:

  • heave_value (float) –

    Force set point in the heave direction in range <-1, 1>, a positive set point makes the drone move downwards.

Source code in blueye/sdk/motion.py 
110
111
112
113
114
115
116
117
118
119
def set_heave(self, heave_value: float):
    """Set force reference for the heave direction

    Args:
        heave_value (float): Force set point in the heave direction in range <-1, 1>,
                             a positive set point makes the drone move downwards.
    """
    with self.thruster_lock:
        self._current_thruster_setpoints["heave"] = heave_value
        self._send_motion_input_message()

set_slow 

set_slow(slow_gain: float)

Set the "slow gain" (inverse of boost)

Parameters:

  • slow_gain (float) –

    Range from 0 to 1.

Source code in blueye/sdk/motion.py 
200
201
202
203
204
205
206
207
208
def set_slow(self, slow_gain: float):
    """Set the "slow gain" (inverse of boost)

    Args:
        slow_gain (float): Range from 0 to 1.
    """
    with self.thruster_lock:
        self._current_boost_setpoints["slow"] = slow_gain
        self._send_motion_input_message()

set_surge 

set_surge(surge_value: float)

Set force reference for the surge direction

Parameters:

  • surge_value (float) –

    Force set point in the surge direction in range <-1, 1>, a positive set point makes the drone move forward.

Source code in blueye/sdk/motion.py 
68
69
70
71
72
73
74
75
76
77
def set_surge(self, surge_value: float):
    """Set force reference for the surge direction

    Args:
        surge_value (float): Force set point in the surge direction in range <-1, 1>,
                             a positive set point makes the drone move forward.
    """
    with self.thruster_lock:
        self._current_thruster_setpoints["surge"] = surge_value
        self._send_motion_input_message()

set_sway 

set_sway(sway_value: float)

Set force reference for the sway direction

Parameters:

  • sway_value (float) –

    Force set point in the sway direction in range <-1, 1>, a positive set point makes the drone move to the right.

Source code in blueye/sdk/motion.py 
89
90
91
92
93
94
95
96
97
98
def set_sway(self, sway_value: float):
    """Set force reference for the sway direction

    Args:
        sway_value (float): Force set point in the sway direction in range <-1, 1>,
                            a positive set point makes the drone move to the right.
    """
    with self.thruster_lock:
        self._current_thruster_setpoints["sway"] = sway_value
        self._send_motion_input_message()

set_yaw 

set_yaw(yaw_value: float)

Set moment reference for the yaw direction

Parameters:

  • yaw_value (float) –

    Moment set point in the yaw direction in range <-1, 1>, a positive set point makes the drone rotate clockwise.

Source code in blueye/sdk/motion.py 
131
132
133
134
135
136
137
138
139
140
def set_yaw(self, yaw_value: float):
    """Set moment reference for the yaw direction

    Args:
        yaw_value (float): Moment set point in the yaw direction in range <-1, 1>,
                           a positive set point makes the drone rotate clockwise.
    """
    with self.thruster_lock:
        self._current_thruster_setpoints["yaw"] = yaw_value
        self._send_motion_input_message()