motor¶

The motor module contains functions to control and query individual motors attached to the Spike hub.

To use the motor module, add the following import statement to your project:

import motor

All functions in the module should be called inside the motor module as a prefix like so:

motor.run(port.A, 1000)

The following constants are defined:

READY = 0
RUNNING = 1
STALLED = 2
CANCELLED = 3
ERROR = 4
DISCONNECTED = 5
COAST = 0
BRAKE = 1
HOLD = 2
CONTINUE = 3
SMART_COAST = 4
SMART_BRAKE = 5
CLOCKWISE = 0
COUNTERCLOCKWISE = 1
SHORTEST_PATH = 2
LONGEST_PATH = 3

NOTE: The motor module contains several functions that are not documented in the official LEGO materials. These are marked as UNDOCUMENTED in the function descriptions below. Their behavior has been determined empirically and they should be used with caution.

Functions

`absolute_position`(port)	Get the absolute position of a Motor in degrees.
`get_duty_cycle`(port)	Get the PWM duty cycle of a Motor.
`info`(port)	UNDOCUMENTED Get the device ID and maximum speed of the Motor as a tuple.
`relative_position`(port)	Get the relative position of a Motor.
`reset_relative_position`(port, position)	Set the position used as the offset when using the `relative_position` or `run_to_relative_position` functions.
`run`(port, velocity, *[, acceleration])	Run a Motor at a constant speed until a new command is given.
`run_for_degrees`(port, degrees, velocity, *)	Turn a Motor for a specific number of degrees.
`run_for_time`(port, duration, velocity, *[, ...])	Run a Motor for a specific amount of time.
`run_to_absolute_position`(port, position, ...)	Turn a Motor to an absolute position.
`run_to_relative_position`(port, position, ...)	Turn a Motor to a position relative to its reference position (see `reset_relative_position`).
`set_duty_cycle`(port, pwm)	Start a Motor with a specific PWM.
`status`(port)	UNDOCUMENTED Get the Motor status as one of:
`stop`(port, *[, stop])	Stop the Motor given by `port`.
`velocity`(port)	Get the velocity (deg/sec) of a Motor (NOTE: empirical testing suggests the unit of the returned value is not in deg/sec).

motor.absolute_position(port)¶

Get the absolute position of a Motor in degrees. Return values range from -179 to 180. Positive values indicate clockwise rotation from zero; negative values indicate counter-clockwise rotation.

Parameters:: port (int) – A port from the port submodule in the hub module
Return type:: int

motor.get_duty_cycle(port)¶

Get the PWM duty cycle of a Motor.

Parameters:: port (int) – A port from the port submodule in the hub module
Return type:: int

motor.info(port)¶

UNDOCUMENTED Get the device ID and maximum speed of the Motor as a tuple.

Parameters:: port (int) – A port from the port submodule in the hub module
Return type:: tuple[device_id: int, max_speed: int]

motor.relative_position(port)¶

Get the relative position of a Motor. This is the cumulative number of degrees the motor has moved (positive or negative) from its starting position (either at hub boot or after a call to reset_relative_position). Positive values indicate clockwise rotation (looking at the motor from the top); negative values indicate counter-clockwise rotation.

Parameters:: port (int) – A port from the port submodule in the hub module
Return type:: int

motor.reset_relative_position(port, position)¶

Set the position used as the offset when using the relative_position or run_to_relative_position functions. If no position is given, resets to zero.

Parameters:

port (int) – A port from the port submodule in the hub module
position (int) – New reference position in degrees

Return type:

None

motor.run(port, velocity, *, acceleration=1000)¶

Run a Motor at a constant speed until a new command is given.

from hub import port
import motor, time

# Start motor
motor.run(port.A, 1000)

Parameters:

port (int) – A port from the port submodule in the hub module
velocity (int) – The velocity in degrees/sec; value ranges depends on motor type: Small motor (essential): -660 to 660; Medium motor: -1110 to 1110; Large motor: -1050 to 1050
acceleration (int) – The acceleration to use at start of run (deg/sec²) (1–10000)

Return type:

None

motor.run_for_degrees(port, degrees, velocity, *, stop=1, acceleration=1000, deceleration=1000)¶

Turn a Motor for a specific number of degrees. Positive values for degrees indicate clockwise rotation (when viewed from the top); negative values indicate counter-clockwise rotation. When awaited, returns a status of the movement that corresponds to one of the following constants:

motor.READY
motor.RUNNING
motor.STALLED
motor.CANCELED
motor.ERROR
motor.DISCONNECTED

Parameters:

port (int) – A port from the port submodule in the hub module
degrees (int) – The number of degrees to turn
velocity (int) – The velocity in degrees/sec; value ranges depends on motor type: Small motor (essential): -660 to 660; Medium motor: -1110 to 1110; Large motor: -1050 to 1050
stop (int) –
The behavior of the Motor after it has stopped. Use the constants in the motor module. Possible values are:
- motor.COAST to make the motor coast until a stop
- motor.BRAKE to brake and continue to brake after stop
- motor.HOLD to tell the motor to hold it’s position
- motor.CONTINUE to tell the motor to keep running at whatever velocity it’s running at until it gets another command
- motor.SMART_COAST to make the motor brake until stop and then coast and compensate for inaccuracies in the next command
- motor.SMART_BRAKE to make the motor brake and continue to brake after stop and compensate for inaccuracies in the next command
acceleration (int) – The acceleration to use at start of run (deg/sec²) (1–10000)
deceleration (int) – The deceleration to use at end of run (deg/sec²) (1–10000)

Return type:

Awaitable

motor.run_for_time(port, duration, velocity, *, stop=1, acceleration=1000, deceleration=1000)¶

Run a Motor for a specific amount of time. When awaited, returns a status of the movement that corresponds to one of the following constants:

motor.READY
motor.RUNNING
motor.STALLED
motor.CANCELED
motor.ERROR
motor.DISCONNECTED

from hub import port
import runloop
import motor

async def main():
    # Run at 1000 velocity for 1 second
    await motor.run_for_time(port.A, 1000, 1000)

    # Run at 280 velocity for 1 second
    await motor_pair.run_for_time(port.A, 1000, 280)

    # Run at 280 velocity for 10 seconds with a slow deceleration
    await motor_pair.run_for_time(port.A, 10000, 280, deceleration=10)

runloop.run(main())

Parameters:

port (int) – A port from the port submodule in the hub module
duration (int) – The duration in milliseconds
velocity (int) – The velocity in degrees/sec; value ranges depends on motor type: Small motor (essential): -660 to 660; Medium motor: -1110 to 1110; Large motor: -1050 to 1050
stop (int) –
The behavior of the Motor after it has stopped. Use the constants in the motor module. Possible values are:
- motor.COAST to make the motor coast until a stop
- motor.BRAKE to brake and continue to brake after stop
- motor.HOLD to tell the motor to hold it’s position
- motor.CONTINUE to tell the motor to keep running at whatever velocity it’s running at until it gets another command
- motor.SMART_COAST to make the motor brake until stop and then coast and compensate for inaccuracies in the next command
- motor.SMART_BRAKE to make the motor brake and continue to brake after stop and compensate for inaccuracies in the next command
acceleration (int) – The acceleration to use at start of run (deg/sec²) (1–10000)
deceleration (int) – The deceleration to use at end of run (deg/sec²) (1–10000)

Return type:

Awaitable

motor.run_to_absolute_position(port, position, velocity, *, direction=2, stop=1, acceleration=1000, deceleration=1000)¶

Turn a Motor to an absolute position. While the value returned by absolute_position() is bounded between -179 and 180, you can provide position values outside of that range to this function and the hub will “wrap them around” into range. For example, specifying a position of 200 is identical to specifying a position of -160; a subsequent call to motor.absolute_position() will return -160 (or therearouts) in either case.

When awaited, returns a status of the movement that corresponds to one of the following constants:

motor.READY
motor.RUNNING
motor.STALLED
motor.CANCELED
motor.ERROR
motor.DISCONNECTED

Parameters:

port (int) – A port from the port submodule in the hub module
position (int) – The final position of the motor in degrees
velocity (int) – The velocity in degrees/sec; value ranges depends on motor type: Small motor (essential): -660 to 660; Medium motor: -1110 to 1110; Large motor: -1050 to 1050
direction (int) –
The direction to turn. Options are:
- motor.CLOCKWISE
- motor.COUNTERCLOCKWISE
- motor.SHORTEST_PATH
- motor.LONGEST_PATH
stop (int) –
The behavior of the Motor after it has stopped. Use the constants in the motor module. Possible values are:
- motor.COAST to make the motor coast until a stop
- motor.BRAKE to brake and continue to brake after stop
- motor.HOLD to tell the motor to hold it’s position
- motor.CONTINUE to tell the motor to keep running at whatever velocity it’s running at until it gets another command
- motor.SMART_COAST to make the motor brake until stop and then coast and compensate for inaccuracies in the next command
- motor.SMART_BRAKE to make the motor brake and continue to brake after stop and compensate for inaccuracies in the next command
acceleration (int) – The acceleration to use at start of run (deg/sec²) (1–10000)
deceleration (int) – The deceleration to use at end of run (deg/sec²) (1–10000)

Return type:

Awaitable

motor.run_to_relative_position(port, position, velocity, *, stop=1, acceleration=1000, deceleration=1000)¶

Turn a Motor to a position relative to its reference position (see reset_relative_position). When awaited, returns a status of the movement that corresponds to one of the following constants:

motor.READY
motor.RUNNING
motor.STALLED
motor.CANCELED
motor.ERROR
motor.DISCONNECTED

Parameters:

port (int) – A port from the port submodule in the hub module
position (int) – The degree of the motor
velocity (int) – The velocity in degrees/sec; value ranges depends on motor type: Small motor (essential): -660 to 660; Medium motor: -1110 to 1110; Large motor: -1050 to 1050
stop (int) –
The behavior of the Motor after it has stopped. Use the constants in the motor module. Possible values are:
- motor.COAST to make the motor coast until a stop
- motor.BRAKE to brake and continue to brake after stop
- motor.HOLD to tell the motor to hold it’s position
- motor.CONTINUE to tell the motor to keep running at whatever velocity it’s running at until it gets another command
- motor.SMART_COAST to make the motor brake until stop and then coast and compensate for inaccuracies in the next command
- motor.SMART_BRAKE to make the motor brake and continue to brake after stop and compensate for inaccuracies in the next command
acceleration (int) – The acceleration to use at start of run (deg/sec²) (1–10000)
deceleration (int) – The deceleration to use at end of run (deg/sec²) (1–10000)

Return type:

Awaitable

motor.set_duty_cycle(port, pwm)¶

Start a Motor with a specific PWM.

Parameters:

port (int) – A port from the port submodule in the hub module
pwm (int) – The PWM value (-10000–10000)

Return type:

None

motor.status(port)¶

UNDOCUMENTED Get the Motor status as one of:

motor.READY
motor.RUNNING
motor.STALLED
motor.CANCELED
motor.ERROR
motor.DISCONNECTED

NOTE: Based on empirical testing,``motor.run`` does not set status to motor.RUNNING; other run_* functions do.

Parameters:: port (int) – A port from the port submodule in the hub module
Return type:: int

motor.stop(port, *, stop=1)¶

Stop the Motor given by port. If no port is specified, stop all attached motors.

from hub import port
import motor, time

# Start motor
motor.run(port.A, 1000)

# Wait for 2 seconds
time.sleep_ms(2000)

# Stop motor
motor.stop(port.A)

Parameters:

port (int) – A port from the port submodule in the hub module
stop (int) –
The behavior of the Motor after it has stopped. Use the constants in the motor module. Possible values are:
- motor.COAST to make the motor coast until a stop
- motor.BRAKE to brake and continue to brake after stop
- motor.HOLD to tell the motor to hold it’s position
- motor.CONTINUE to tell the motor to keep running at whatever velocity it’s running at until it gets another command
- motor.SMART_COAST to make the motor brake until stop and then coast and compensate for inaccuracies in the next command
- motor.SMART_BRAKE to make the motor brake and continue to brake after stop and compensate for inaccuracies in the next command

Return type:

None

motor.velocity(port)¶

Get the velocity (deg/sec) of a Motor (NOTE: empirical testing suggests the unit of the returned value is not in deg/sec).

Parameters:: port (int) – A port from the port submodule in the hub module
Return type:: int

motor¶

Table of Contents

Previous topic

Next topic

This Page