❌ ❌ ❌ ❌ ❌ ❌ ✅

Motors with rotation sensors

ev3motors

Figure 4 EV3 and NXT motors with rotation sensors. The arrows indicate the default positive direction.

Amotoronwith forward
class Motor(port, positive_direction=Direction.CLOCKWISE, gears=None, reset_angle=True, profile=None)

LEGO® MINDSTORMS® EV3 Motor.

Parameters:

  • port (Port) – Port to which the motor is connected.

  • positive_direction (Direction) – Which direction the motor should turn when you give a positive speed value or angle.

  • gears (list) –

    List of gears linked to the motor. The gear connected to the motor comes first and the gear connected to the output comes last.

    For example: [12, 36] represents a gear train with a 12-tooth gear connected to the motor and a 36-tooth gear connected to the output. Use a list of lists for multiple gear trains, such as [[12, 36], [20, 16, 40]].

    When you specify a gear train, all motor commands and settings are automatically adjusted to account for the resulting gear ratio. The motor direction remains unchanged by this.

  • reset_angle (bool) – Choose True to reset the rotation sensor value to the absolute marker angle (between -180 and 179). Choose False to keep the current value, so your program knows where it left off last time.

  • profile (Number, deg) – Precision profile. This is the approximate position tolerance in degrees that is acceptable in your application. A lower value gives more precise but more erratic movement; a higher value gives less precise but smoother movement. If no value is given, a suitable profile for this motor type will be selected automatically (about 11 degrees).

Measuring

motorgetangle
angle() → int: deg

Gets the rotation angle of the motor.

Returns:

Motor angle.

motor0°reset angle to
reset_angle(angle)

Sets the accumulated rotation angle of the motor to a desired value.

If this motor is also being used by a drive base, its distance and angle values will also be affected. You might want to use its reset method instead.

Parameters:

angle (Number, deg) – Value to which the angle should be reset.

motorgetspeed
100msmotorgetaverage speedduring
speed(window=100) → int: deg/s

Gets the speed of the motor.

The speed is measured as the change in the motor angle during the given time window. A short window makes the speed value more responsive to motor movement, but less steady. A long window makes the speed value less responsive, but more steady.

Parameters:

window (Number, ms) – The time window used to determine the speed.

Returns:

Motor speed.

motorgetload
load() → int: mNm

Estimates the load that holds back the motor when it tries to move.

Returns:

The load torque.

motorgetstalled
stalled() → bool

Checks if the motor is currently stalled.

It is stalled when it cannot reach the target speed or position, even with the maximum actuation signal.

Returns:

True if the motor is stalled, False if not.

Stopping

motorcoaststop
stop()

Stops the motor and lets it spin freely.

The motor gradually stops due to friction.

motorbrakestop
brake()

Passively brakes the motor.

The motor stops due to friction, plus the voltage that is generated while the motor is still moving.

motorholdstop
hold()

Stops the motor and actively holds it at its current angle.

Running forever

motor500°/srun atforever
run(speed)

Runs the motor at a constant speed.

The motor accelerates to the given speed and keeps running at this speed until you give a new command.

Parameters:

speed (Number, deg/s) – Speed of the motor.

motor50%power atduty cycle
dc(duty)

Rotates the motor at a given duty cycle (also known as “power”).

Parameters:

duty (Number, %) – The duty cycle (-100.0 to 100).

Running by a fixed amount

await run_time(speed, time, then=Stop.HOLD, wait=True)

Runs the motor at a constant speed for a given amount of time.

The motor accelerates to the given speed, keeps running at this speed, and then decelerates. The total maneuver lasts for exactly the given amount of time.

Parameters:

  • speed (Number, deg/s) – Speed of the motor.

  • time (Number, ms) – Duration of the maneuver.

  • then (Stop) – What to do after coming to a standstill.

  • wait (bool) – Wait for the maneuver to complete before continuing with the rest of the program.

360°holdmotor500°/srun atbythen
await run_angle(speed, rotation_angle, then=Stop.HOLD, wait=True)

Runs the motor at a constant speed by a given angle.

Parameters:

  • speed (Number, deg/s) – Speed of the motor.

  • rotation_angle (Number, deg) – Angle by which the motor should rotate.

  • then (Stop) – What to do after coming to a standstill.

  • wait (bool) – Wait for the maneuver to complete before continuing with the rest of the program.

360°holdmotor500°/srun attowardsthen
await run_target(speed, target_angle, then=Stop.HOLD, wait=True)

Runs the motor at a constant speed towards a given target angle.

The direction of rotation is automatically selected based on the target angle. It does not matter if speed is positive or negative.

Parameters:

  • speed (Number, deg/s) – Speed of the motor.

  • target_angle (Number, deg) – Angle that the motor should rotate to.

  • then (Stop) – What to do after coming to a standstill.

  • wait (bool) – Wait for the motor to reach the target before continuing with the rest of the program.

50%coastmotor500°/srun atto end stopwith power limitthen
await run_until_stalled(speed, then=Stop.COAST, duty_limit=None) → int: deg

Runs the motor at a constant speed until it stalls.

Parameters:

  • speed (Number, deg/s) – Speed of the motor.

  • then (Stop) – What to do after coming to a standstill.

  • duty_limit (Number, %) – Duty cycle limit during this command. This is useful to avoid applying the full motor torque to a geared or lever mechanism. If it is None, the duty limit won’t be changed during this command.

Returns:

Angle at which the motor becomes stalled.

motor90°track
track_target(target_angle)

Tracks a target angle. This is similar to run_target(), but the usual smooth acceleration is skipped: it will move to the target angle as fast as possible. This method is useful if you want to continuously change the target angle.

Parameters:

target_angle (Number, deg) – Target angle that the motor should rotate to.

done() → bool

Checks if an ongoing command or maneuver is done.

Returns:

True if the command is done, False if not.

Motor settings

9000mVmotorconfiguremaximum voltage
settings(max_voltage)
settings() → tuple[int]

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

Parameters:

max_voltage (Number, mV) – Maximum voltage applied to the motor during all motor commands.

close()

Closes the motor object so you can call Motor again to initialize a new object.

This allows advanced users to change properties such as gearing in the middle of the program, which can be useful for removeable attachments.

Control settings

❌ ✅ ✅ ✅ ✅ ✅ ✅
1000°/smotorconfiguremaximum speed
2000°/s²motorconfigureacceleration
200mNmmotorconfiguremaximum torque
control.limits(speed, acceleration, torque)
control.limits() → tuple[int, int, int]

Configures the maximum speed, acceleration, and torque.

If no arguments are given, this will return the current values.

The new acceleration and speed limit will become effective when you give a new motor command. Ongoing maneuvers are not affected.

Parameters:

  • speed (Number, deg/s or Number, mm/s) – Maximum speed. All speed commands will be capped to this value.

  • acceleration (Number, deg/s² or Number, mm/s²) – Slope of the speed curve when accelerating or decelerating. Use a tuple to set acceleration and deceleration separately. If one value is given, it is used for both.

  • torque (torque: mNm) – Maximum feedback torque during control.

❌ ✅ ✅ ✅ ✅ ✅ ✅
control.pid(kp, ki, kd, integral_deadzone, integral_rate)
control.pid() → tuple[int, int, int, int, int]

Gets or sets the PID values for position and speed control.

If no arguments are given, this will return the current values.

Parameters:

  • kp (int) – Proportional position control constant. It is the feedback torque per degree of error: µNm/deg.

  • ki (int) – Integral position control constant. It is the feedback torque per accumulated degree of error: µNm/(deg s).

  • kd (int) – Derivative position (or proportional speed) control constant. It is the feedback torque per unit of speed: µNm/(deg/s).

  • integral_deadzone (Number, deg or Number, mm) – Zone around the target where the error integral does not accumulate errors.

  • integral_rate (Number, deg/s or Number, mm/s) – Maximum rate at which the error integral is allowed to grow.

❌ ✅ ✅ ✅ ✅ ✅ ✅
50°/s11°motorconfiguretolerancesspeedangle
control.target_tolerances(speed, position)
control.target_tolerances() → tuple[int, int]

Gets or sets the tolerances that say when a maneuver is done.

If no arguments are given, this will return the current values.

Parameters:

  • speed (Number, deg/s or Number, mm/s) – Allowed deviation from zero speed before motion is considered complete.

  • position (Number, deg or distance: mm) – Allowed deviation from the target before motion is considered complete.

❌ ✅ ✅ ✅ ✅ ✅ ✅
control.stall_tolerances(speed, time)
control.stall_tolerances() → tuple[int, int]

Gets or sets stalling tolerances.

If no arguments are given, this will return the current values.

Parameters:

  • speed (Number, deg/s or Number, mm/s) – If the controller cannot reach this speed for some time even with maximum actuation, it is stalled.

  • time (Number, ms) – How long the controller has to be below this minimum speed before we say it is stalled.

❌ ✅ ✅ ✅ ✅ ✅ ✅
control.scale

Number of degrees that the motor turns to complete one degree at the output of the gear train. This is the gear ratio determined from the gears argument when initializing the motor.

Changed in version 3.2: The done(), stalled() and load() methods have been moved.

❌ ✅ ✅ ✅ ✅ ✅ ✅
model.state() → tuple[float, float, float, bool]

Gets the estimated angle, speed, current, and stall state of the motor, using a simulation model that mimics the real motor. These estimates are updated faster than the real measurements, which can be useful when building your own PID controllers.

For most applications it is better to used the measured angle, speed, load, and stall state instead.

Returns:

Tuple with the estimated angle (deg), speed (deg/s), current (mA), and stall state (True or False).

❌ ✅ ✅ ✅ ✅ ✅ ✅
model.settings(values)
model.settings() → tuple

Gets or sets model settings as a tuple of integers. If no arguments are given, this will return the current values. This method is mainly used to debug the motor model class. Changing these settings should not be needed in user programs.

Parameters:

values (tuple) – Tuple with model settings.