Motors¶

Brian allows you to work with three different types of motors:

EV3 Large Motor
EV3 Medium Motor
NXT Motor

After initialisation, all motor types will work the same way.

Initialisation and Connection¶

First, you have to initialize the motor. You must specify the motor type and port (A, B, C, D). Here is an example of initialization:

import brian.motors as motors

large = motors.EV3LargeMotor(motors.MotorPort.A)
medium = motors.EV3MediumMotor(motors.MotorPort.B)
nxt = motors.NXTMotor(motors.MotorPort.C)

Now you can use your own names to control motors, just separate method with dot. For example large.is_connected().

After initialisation, you have to check, whether is motor ready. These functions will help you:

is_connected¶

is_connected(self) → bool

Check if something is connected to the port.

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

is_ready¶

is_ready(self) → bool

Check if a correct motor is connected to the port and is ready to be controlled.

Test for is_connected is done internally, if it returns false, is_ready will always return false.

Returns:: True if a motor is connected, and it is the correct type; False otherwise.

wait_until_ready¶

wait_until_ready(self, timeout_ms: int | None = None) → bool

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

Parameters:

timeout_ms – Maximum number of milliseconds to wait. - If the timeout is not provided or is None, the function will wait indefinitely.

Return success:

True: The sensor is ready.
False: The sensor is not ready and timeout ran out.

close_motor¶

close_motor(self): Release the motor port for other uses.

Movement Control¶

Now you can control the motor with these functions:

run_unregulated¶

run_unregulated(self, fraction: float) → None

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

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

run_at_voltage¶

run_at_voltage(self, volts: float) → None

Run the motor at the given voltage.

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

run_at_speed¶

run_at_speed(self, deg_per_sec: int) → None

Run the motor at a constant speed.

Parameters:: deg_per_sec – Desired rotational speed, in degrees per second.

rotate_by_angle¶

rotate_by_angle(self, angle: int, speed: int, timeout: int | None = None) → MovementEnd

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

Parameters:

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 – How long to wait for the maneuver to complete, in milliseconds. If zero, the function will return immediately. If the timeout expires, the motor is not stopped.

Returns:

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

rotate_to_angle¶

rotate_to_angle(self, position: int, speed: int, timeout: int | None = None) → MovementEnd

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

Parameters:

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 – How long to wait for the maneuver to complete, in milliseconds. If zero, the function will return immediately. If the timeout expires, the motor is not stopped.

Returns:

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

rotate_to_angle_without_speed_control¶

rotate_to_angle_without_speed_control(self, 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.

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

movement_done¶

movement_done(self) → bool

Check whether the last invoked position command has completed.

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_for_movement¶

wait_for_movement(self, timeout_ms: int | None = None) → MovementEnd

Wait for the motor to complete the last position command.

Parameters:: timeout_ms – How long to wait for the maneuver to complete, in milliseconds. If zero, the function will return immediately. If the timeout expires, the motor is not stopped.
Returns:: Whether the wait-for-end was successful or why it ended, if it ended early.

Stopping¶

Here are functions to stop the motor from moving:

coast¶

coast(self) → None

Let the motor spin freely.

This will float the motor windings.

brake¶

brake(self) → None

Passively brake the motor.

This will short the motor windings.

hold¶

hold(self) → None

Actively brake the motor at the current position.

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

Motor Measurements¶

Information about the motor state during the program is provided by these functions:

current_angle¶

current_angle(self) → int

Query the current motor angle.

Returns:: Motor axle angle in degrees.

reset_angle¶

reset_angle(self, 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.

Parameters:: new_value – New motor position in degrees.

current_speed¶

current_speed(self) → int

Query the current motor rotational speed.

Returns:: Motor axle speed in degrees/second.

current_torque¶

current_torque(self) → int

Query the current estimated motor torque.

Returns:: Motor torque in milli-newton-meters.

is_stalled¶

is_stalled(self) → bool

Check if the motor is currently stalled.

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

limits¶

property Motor.limits: MotorLimits

Configure various controller limits.

Returns:: MotorLimits object that can be used for configuring the limits.

motor_type¶

property Motor.motor_type: MotorType

Check what motor type was this object initialized with.

Returns:: Properties and default settings of the connected motor type.

Further Information¶

For further information about motors, go check API Reference.