brian.motors.Motor

MotorWaitOptimismLevel
- WAIT_UNTIL_CORRECT_TYPE
- WAIT_UNTIL_FULLY_READY
Motor

MotorWaitOptimismLevel class objects

class MotorWaitOptimismLevel(Enum)

Optimism level for wait_until_ready() calls.

WAIT_UNTIL_CORRECT_TYPE: Wait only until the motor type is confirmed correct. Use this immediately after motor construction to quickly verify the motor is connected and is of the expected type, without waiting for full initialization.
WAIT_UNTIL_FULLY_READY: Wait until the motor is fully initialized and ready for normal use. You may use this before commanding the motor to ensure it is fully ready for normal use.

WAIT_UNTIL_CORRECT_TYPE

Wait only until the motor type is confirmed correct

WAIT_UNTIL_FULLY_READY

Wait until the motor is fully initialized and ready for normal use

Motor class objects

class Motor()

A class to manage and control motor operations.

motor_type

@property
def motor_type() -> 'MotorType'

Check what motor type was this object initialized with.

Returns:

Properties and default settings of the connected motor type.

init

def __init__(port: MotorPort)

Tries to autodetect a motor, connected to the given port and initialize a new motor class.

Arguments:

port: Motor port to use.

Raises:

MotorInitializationFailedError: If autodetect fails (motor is not connected, unknown type of the connected motor).
MotorPortAlreadyInUse: When trying to create new Motor on a port that is already in use.

del

def __del__()

Release the motor port for other uses.

close_motor

def close_motor()

Release the motor port for other uses.

is_connected

def is_connected() -> bool

Check if something is connected to the port.

Returns:

True if a non-empty port was detected; False otherwise.

is_ready

def is_ready() -> bool

Check if the motor is connected, of the correct type, and ready to be controlled.

Ready-state indicates that the attempt to control the motor will succeed.

When the motor is not connected, this function returns False. When the wrong motor type is connected, this function raises an exception.

Raises:

brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.

Returns:

True if the motor meets the readiness criteria, False if not connected.

wait_until_ready

def wait_until_ready(
        timeout_ms: Optional[int] = None,
        optimism_level: Optional[MotorWaitOptimismLevel] = None) -> bool

Waits until the motor is ready. This function is blocking.

Arguments:

timeout_ms: Milliseconds to wait for readiness.
If None, there is no per-call wall-clock limit (wait until ready).
If 0 or negative, return/raise immediately without waiting.
If positive, wait at most that many milliseconds.
optimism_level: Level of optimism to use when checking readiness.
WAIT_UNTIL_CORRECT_TYPE: More optimistic - returns as soon as correct type is detected.
WAIT_UNTIL_FULLY_READY: Less optimistic - waits until motor is fully ready (default).

Raises:

brian.motors.MotorNotConnectedError: If no motor is connected to the port.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready for other reasons.

Returns:

success: - True: The motor is ready at the specified optimism level.

current_angle

def current_angle() -> int

Query the current motor angle.

This function will wait for the motor to be ready before returning. The wait timeout is controlled by set_wait_until_timeout_ms().

Raises:

brian.motors.MotorNotConnectedError: If no motor is connected.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready after timeout.

Returns:

Motor axle angle in degrees.

reset_angle

def reset_angle(new_value: int = 0) -> None

Set the accumulated angle to the provided position.

Assuming that the motor will not move, current_angle() will start returning the value in newValue.

This function will wait for the motor to be ready before executing. The wait timeout is controlled by set_wait_until_timeout_ms().

Arguments:

new_value: New motor position in degrees.

Raises:

brian.motors.MotorNotConnectedError: If no motor is connected.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready after timeout.

current_speed

def current_speed() -> int

Query the current motor rotational speed.

This function will wait for the motor to be ready before returning. The wait timeout is controlled by set_wait_until_timeout_ms().

Raises:

brian.motors.MotorNotConnectedError: If no motor is connected.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready after timeout.

Returns:

Motor axle speed in degrees/second.

current_torque

def current_torque() -> int

Query the current estimated motor torque.

This function will wait for the motor to be ready before returning. The wait timeout is controlled by set_wait_until_timeout_ms().

Raises:

brian.motors.MotorNotConnectedError: If no motor is connected.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready after timeout.

Returns:

Motor torque in milli-newton-meters.

is_stalled

def is_stalled() -> bool

Check if the motor is currently stalled.

This function will wait for the motor to be ready before checking. The wait timeout is controlled by set_wait_until_timeout_ms().

Raises:

brian.motors.MotorNotConnectedError: If no motor is connected.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready after timeout.

Returns:

True if the motor is exceeding some limit, False otherwise.

coast

def coast() -> None

Let the motor spin freely.

This will float the motor windings.

This function will wait for the motor to be ready before executing. The wait timeout is controlled by set_wait_until_timeout_ms().

Raises:

brian.motors.MotorPortAlreadyInUse: If the port is currently controlled by Pilot.
brian.motors.MotorNotConnectedError: If no motor is connected.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready after timeout.

brake

def brake() -> None

Passively brake the motor.

This will short the motor windings.

This function will wait for the motor to be ready before executing. The wait timeout is controlled by set_wait_until_timeout_ms().

Raises:

brian.motors.MotorPortAlreadyInUse: If the port is currently controlled by Pilot.
brian.motors.MotorNotConnectedError: If no motor is connected.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready after timeout.

hold

def hold() -> None

Actively brake the motor at the current position.

This will actively control the motor to stay at the current position.

This function will wait for the motor to be ready before executing. The wait timeout is controlled by set_wait_until_timeout_ms().

Raises:

brian.motors.MotorPortAlreadyInUse: If the port is currently controlled by Pilot.
brian.motors.MotorNotConnectedError: If no motor is connected.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready after timeout.

run_unregulated

def run_unregulated(fraction: float) -> None

Run the motor at a given fraction of the maximum available voltage.

This function will wait for the motor to be ready before executing. The wait timeout is controlled by set_wait_until_timeout_ms().

Arguments:

fraction: Value between -1.0 and +1.0 that determines the duty cycle.

Raises:

brian.motors.MotorPortAlreadyInUse: If the port is currently controlled by Pilot.
brian.motors.MotorNotConnectedError: If no motor is connected.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready after timeout.

run_at_voltage

def run_at_voltage(volts: float) -> None

Run the motor at the given voltage.

This function will wait for the motor to be ready before executing. The wait timeout is controlled by set_wait_until_timeout_ms().

Arguments:

volts: Desired voltage on the motors, in volts. Useful range is -battery voltage to +battery voltage (this is cca. -8V to +8V). The maximum range accepted by this function is -12V to +12V.

Raises:

brian.motors.MotorPortAlreadyInUse: If the port is currently controlled by Pilot.
brian.motors.MotorNotConnectedError: If no motor is connected.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready after timeout.

run_at_speed

def run_at_speed(deg_per_sec: int) -> None

Run the motor at a constant speed.

This function will wait for the motor to be ready before executing. The wait timeout is controlled by set_wait_until_timeout_ms().

Arguments:

deg_per_sec: Desired rotational speed, in degrees per second.

Raises:

brian.motors.MotorPortAlreadyInUse: If the port is currently controlled by Pilot.
brian.motors.MotorNotConnectedError: If no motor is connected.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready after timeout.

rotate

def rotate(angle: int,
           speed: int,
           timeout_ms: Optional[int] = None) -> 'EndReason'

Turn the motor to a new position, relative to the current position.

This function will wait for the motor to be ready before executing. The wait timeout is controlled by set_wait_until_timeout_ms().

Arguments:

angle: Angle to rotate by, in degrees.
speed: Speed to use for the maneuver, in degrees per second. If the provided speed is negative, absolute value is used.
timeout_ms: How long to wait for the maneuver to complete, in milliseconds. If None, wait until the move completes (no wall-clock cap). If 0 or negative, return from the wait immediately (typically TIMED_OUT if still moving). If the timeout expires, the motor is not stopped.

Raises:

brian.motors.MotorPortAlreadyInUse: If the port is currently controlled by Pilot.
brian.motors.MotorNotConnectedError: If no motor is connected.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready after timeout.

Returns:

Whether the wait-for-end was successful or why it ended, if it ended early.

rotate_to

def rotate_to(position: int,
              speed: int,
              timeout_ms: Optional[int] = None) -> 'EndReason'

Turn the motor to a new position, relative to the zero position.

This function will wait for the motor to be ready before executing. The wait timeout is controlled by set_wait_until_timeout_ms().

Arguments:

position: Angle to rotate to, in degrees.
speed: Speed to use for the maneuver, in degrees per second. If the provided speed is negative, absolute value is used.
timeout_ms: How long to wait for the maneuver to complete, in milliseconds. If None, wait until the move completes (no wall-clock cap). If 0 or negative, return from the wait immediately (typically TIMED_OUT if still moving). If the timeout expires, the motor is not stopped.

Raises:

brian.motors.MotorPortAlreadyInUse: If the port is currently controlled by Pilot.
brian.motors.MotorNotConnectedError: If no motor is connected.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready after timeout.

Returns:

Whether the wait-for-end was successful or why it ended, if it ended early.

rotate_to_angle_without_speed_control

def rotate_to_angle_without_speed_control(position: int) -> None

Try to get as fast as possible to the specified position.

This will ignore any speed and acceleration limits - you must provide these yourself by periodically calling this function with new positions.

This function will wait for the motor to be ready before executing. The wait timeout is controlled by set_wait_until_timeout_ms().

Arguments:

position: Angle to rotate to relative to the zero position, in degrees.

Raises:

brian.motors.MotorPortAlreadyInUse: If the port is currently controlled by Pilot.
brian.motors.MotorNotConnectedError: If no motor is connected.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready after timeout.

is_done

def is_done() -> bool

Check whether the last invoked position command has completed.

This function will wait for the motor to be ready before checking. The wait timeout is controlled by set_wait_until_timeout_ms().

Raises:

brian.motors.MotorNotConnectedError: If no motor is connected.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready after timeout.

Returns:

True if the motor has reached the goal. True if the maneuver had to be interrupted (e.g., motor was unplugged). False if the motor is still moving.

wait_until_done

def wait_until_done(timeout_ms: Optional[int] = None) -> 'EndReason'

Wait for the motor to complete the last position command.

This function will wait for the motor to be ready before waiting for movement. The wait timeout is controlled by set_wait_until_timeout_ms().

Arguments:

timeout_ms: How long to wait for the maneuver to complete, in milliseconds. If None, wait until the move completes (no wall-clock cap). If 0 or negative, return from the wait immediately (typically TIMED_OUT if still moving). If the timeout expires, the motor is not stopped.

Raises:

brian.motors.MotorNotConnectedError: If no motor is connected.
brian.motors.MotorIncompatibleTypeError: If wrong motor type is connected.
brian.motors.MotorIsNotReadyError: If motor is not ready after timeout.

Returns:

Whether the wait-for-end was successful or why it ended, if it ended early.

get_acceleration_limit

def get_acceleration_limit() -> int

Query the acceleration limit.

This acceleration is used for ramping speed in position and speed commands.

Returns:

Maximum acceleration in degrees per second squared.

set_acceleration_limit

def set_acceleration_limit(deg_per_sec_sq: int) -> None

Set the acceleration limit.

This acceleration is used for ramping speed in position and speed commands.

Arguments:

deg_per_sec_sq: Maximum acceleration in degrees per second squared. Use brian.motors.UNLIMITED_ACCELERATION to disable speed ramping.

get_torque_limit

def get_torque_limit() -> int

Query the torque limit.

Returns:

Maximum torque that will be applied to the motor axle, in milli-newton-meters.

set_torque_limit

def set_torque_limit(mNm: int) -> None

Set the torque limit.

Arguments:

mNm: Maximum torque that will be applied to the motor axle, in milli-newton-meters. Use brian.motors.UNLIMITED_TORQUE to remove the limit.

get_battery_power_limit

def get_battery_power_limit() -> int

Query the power draw limit.

Returns:

Battery power consumption limit, in milli-watts.

set_battery_power_limit

def set_battery_power_limit(mW: int) -> None

Set the power draw limit.

Arguments:

mW: Maximum power allowed to draw from the battery, in milli-watts. Use brian.motors.UNLIMITED_POWER to remove the limit.