Motor

This class is the blueprint for the motor attributes of the ports in the hub.port module, which in turn are instances of the Port class. You cannot import or instantiate this class manually.

class Motor

Control a motor.

Methods inherited from Device

get(format: Optional[int]) → list

Gets the values that the active device mode provides.

Parameters

format – Format of the data. Choose FORMAT_RAW, FORMAT_PCT, or FORMAT_SI.

Returns

Values or measurements representing the device state.

mode(mode: Iterable[Tuple[int, int]]) → None

Configures which measurements get() must return.

Motors with rotation sensors have four useful modes:

  1. PWM currently applied to the motor.

  2. Speed as a percentage of design speed.

  3. Angular position in degrees relative to the position on boot.

  4. Absolute position in degrees between -180 and +179.

The default mode setting used by the MINDSTORMS app is [(1, 0), (2, 0), (3, 0), (0, 0)]. When you select this mode, you can read all values as follows:

speed_pct, rel_pos, abs_pos, pwm = hub.port.A.motor.get()

Simple motors like train motors only have mode 0. See Device.mode for details and other use cases of modes.

Parameters

mode – A list of multi-mode tuples.

pwm(value: int) → None

Applies a PWM signal to the power pins of the port or device.

A PWM value of 0 has the same effect as float().

Parameters

value – PWM value between -100 and +100. The polarity of the PWM signal matches the sign of the value. A value of 0 stops the PWM signal and leaves the port driver in the floating state.

Motor Methods

float() → None

Floats (coasts) the motor, as if disconnected from the hub.

brake() → None

Passively brakes the motor, as if shorting the motor terminals.

hold() → None

Actively hold the motor in its current position.

busy(type=0) → bool

Checks whether the motor is busy changing modes, or executing a motor command such as running to a position.

Parameters

type – Choose BUSY_MODE or BUSY_MOTOR.

Returns

Whether the motor is busy with the specified activity.

run_at_speed(speed: int) → None
run_at_speed(speed: int, max_power: int, acceleration: int, deceleration: int, stall: bool) → None

Starts running a motor at the given speed.

If a keyword argument is not given, its default value will be used.

Parameters

speed – Sets the speed as a percentage of the rated speed for this motor. Positive means clockwise, negative means counterclockwise.

Keyword Arguments

  • max_power – Sets percentage of maximum power used during this command.

  • acceleration – The time in milliseconds (0-10000) for the motor to reach maximum rated speed from standstill.

  • deceleration – The time in milliseconds (0-10000) for the motor to stop when starting from the maximum rated speed.

  • stall – Selects whether the motor should stop when stalled (True) or not (False).

run_for_time(msec: int) → None
run_for_time(msec: int, speed: int, max_power: int, stop: int, acceleration: int, deceleration: int, stall: bool) → None

Runs a motor for a given amount of time.

If a keyword argument is not given, its default value will be used.

Parameters

msec – How long the motor should run in milliseconds. Negative values will be treated as zero.

Keyword Arguments

  • speed – Sets the speed as a percentage of the rated speed for this motor. Positive means clockwise, negative means counterclockwise.

  • max_power – Sets percentage of maximum power used during this command.

  • stop – How to stop. Choose type: Choose STOP_FLOAT, STOP_BRAKE, or STOP_HOLD.

  • acceleration – The time in milliseconds (0-10000) for the motor to reach maximum rated speed from standstill.

  • deceleration – The time in milliseconds (0-10000) for the motor to stop when starting from the maximum rated speed.

  • stall – Selects whether the motor should stop trying to reach the endpoint when stalled (True) or not (False).

run_for_degrees(degrees: int) → None
run_for_degrees(degrees: int, speed: int, max_power: int, stop: int, acceleration: int, deceleration: int, stall: bool) → None

Runs a motor for a given number of degrees at a given speed.

If a keyword argument is not given, its default value will be used.

Parameters

degrees – How many degrees to rotate relative to the starting point.

Keyword Arguments

  • speed –

    Sets the speed as a percentage of the rated speed for this motor.

    • If degrees > 0 and speed > 0, the motor turns clockwise.

    • If degrees > 0 and speed < 0, the motor turns counterclockwise.

    • If degrees < 0 and speed > 0, the motor turns clockwise.

    • If degrees < 0 and speed < 0, the motor turns counterclockwise.

  • max_power – Sets percentage of maximum power used during this command.

  • stop – How to stop. Choose type: Choose STOP_FLOAT, STOP_BRAKE, or STOP_HOLD.

  • acceleration – The time in milliseconds (0-10000) for the motor to reach maximum rated speed from standstill.

  • deceleration – The time in milliseconds (0-10000) for the motor to stop when starting from the maximum rated speed.

  • stall – Selects whether the motor should stop trying to reach the endpoint when stalled (True) or not (False).

run_to_position(position: int) → None
run_to_position(position: int, speed: int, max_power: int, stop: int, acceleration: int, deceleration: int, stall: bool) → None

Runs a motor to the given position.

The angular position is measured relative to the motor position when the hub was turned on or when the motor was plugged in. You can preset this starting position using preset.

If a keyword argument is not given, its default value will be used.

Parameters

position – Position to rotate to.

Keyword Arguments

  • speed – Sets the speed as a percentage of the rated speed for this motor. The sign of the speed will be ignored.

  • max_power – Sets percentage of maximum power used during this command.

  • stop – How to stop. Choose type: Choose STOP_FLOAT, STOP_BRAKE, or STOP_HOLD.

  • acceleration – The time in milliseconds (0-10000) for the motor to reach maximum rated speed from standstill.

  • deceleration – The time in milliseconds (0-10000) for the motor to stop when starting from the maximum rated speed.

  • stall – Selects whether the motor should stop trying to reach the endpoint when stalled (True) or not (False).

preset(position: int) → None

Presets the starting position used by run_to_position.

Parameters

position – The new position preset.

callback(function: Callable[[int], None]) → None

Sets the callback function that is called when a command is completed, interrupted, or stalled.

The function must accept one argument, which indicates why the callback was called. It will receive either EVENT_COMPLETED, EVENT_INTERRUPTED, or EVENT_STALLED.

Parameters

function – Callable function that takes one argument. Choose None to disable the callback.

pid() → tuple
pid(p: int, i: int, d: int) → None

Sets the p, i, and d constants of the motor PID controller.

Parameters

  • p – Proportional constant.

  • i – Integral constant.

  • d – Derivative constant.

Returns

If no arguments are given, this returns the values previously set by the user, if any. The system defaults cannot be read.

default() → dict
default(speed: int, max_power: int, acceleration: int, deceleration: int, stop: int, pid: tuple, stall: bool, callback: Optional[Callable[[int], None]]) → None

Gets or sets the motor default settings. These are used by some of the methods listed above, when no explicit argument is given.

Keyword Arguments

  • speed – The default speed.

  • max_power – The default max_power.

  • acceleration – The default acceleration.

  • deceleration – The default deceleration.

  • stop – The default stop argument.

  • pid – Tuple of p, i, and d. See also pid.

  • stall – The default stall argument.

Returns

If no arguments are given, this returns the current settings.

pair(other_motor: Motor) → MotorPair

Pairs this motor to other_motor to create a MotorPair object.

You can only pair two different motors that are not already part of another pair. Both motors must be of the same type.

Parameters

other_motor – The motor to pair to.

Returns

On success, this returns the MotorPair object. It returns False to indicate an incompatible pair or None for other errors.

Constants inherited from Device

FORMAT_RAW = 0

The data has no particular unit.

FORMAT_PCT = 1

The data is a percentage.

FORMAT_SI = 2

The data has SI units, if available.

Motor Constants

BUSY_MODE = 0

The port is busy configuring the device mode.

BUSY_MOTOR = 1

The motor is busy executing a command.

STOP_FLOAT = 0

When stopping, the motor floats. See also float().

STOP_BRAKE = 1

When stopping, the motor brakes. See also brake().

STOP_HOLD = 2

When stopping, the motor holds position. See also hold().

EVENT_COMPLETED = 0

The motor command completed successfully.

EVENT_INTERRUPTED = 1

The motor command was interrupted.

EVENT_STALLED = 2

The motor command stopped because the motor was stalled.