MojoScale Studio Docs
API Reference

motor

DC motor and simple robot drive helpers.

All modules Open Studio
Studio Docs Sensors & I/O

import motor

The motor module controls brushed DC motors through common H-bridge motor drivers. It supports signed speed control for one motor and a differential drive helper for two-motor robots.

Quick example

import motor
import system

left = motor.dc(pwm=5, in1=6, in2=7)
right = motor.dc(pwm=8, in1=9, in2=10, inverted=True)

left.run(60)
right.run(60)

def stop_left():
    left.stop()

system.schedule("stop_left", 2000, 0, 1, stop_left)

robot = motor.differential(left, right)
robot.move(speed=60, turn=-20)

importmotor

DC motor and simple robot drive helpers.

The motor module controls brushed DC motors through common H-bridge motor drivers. It supports signed speed control for one motor and a differential drive helper for two-motor robots.

API 24 available

motor.dc(pwm: int, in1: int = None, in2: int = None, direction: int = None, enable: int = None, standby: int = None, frequency: int = None, inverted: bool = None, stop_mode: str = None, min_speed: int = None, max_speed: int = None) -> dc_motor

Create one DC motor controller.

Use this for a single brushed DC motor connected through a motor driver. V1 supports PWM plus two direction pins, or PWM plus one direction pin. Speed values are normalized from -100 to 100.

Parameters
Name Type Pass as Required Description
pwm int positional or keyword Yes PWM GPIO connected to the motor driver's speed input.
in1 int positional or keyword No Optional first direction GPIO for IN1/IN2-style drivers.
in2 int positional or keyword No Optional second direction GPIO for IN1/IN2-style drivers.
direction int positional or keyword No Optional GPIO for PWM + DIR drivers.
enable int positional or keyword No Optional enable GPIO. Studio drives this high while active.
standby int positional or keyword No Optional standby GPIO, commonly used by TB6612FNG.
frequency int positional or keyword No Optional PWM frequency in Hz. Defaults to 20000.
inverted bool positional or keyword No Optional bool that flips forward and reverse.
stop_mode str positional or keyword No Optional default stop behavior. Use "coast" or "brake".
min_speed int positional or keyword No Optional minimum non-zero duty percentage.
max_speed int positional or keyword No Optional maximum duty percentage.
Returns

dc_motor dc_motor object.

motor.dc().run(speed, ramp_ms=0) -> bool

Set signed speed from -100 to 100. Positive is forward, negative is reverse.

Parameters
Name Type Pass as Required Description
speed int positional or keyword Yes Required value.
ramp_ms int positional or keyword No Optional value. Defaults to 0.

motor.dc().forward(speed=100, ramp_ms=0) -> bool

Run forward at a normalized speed.

Parameters
Name Type Pass as Required Description
speed int positional or keyword No Optional value. Defaults to 100.
ramp_ms int positional or keyword No Optional value. Defaults to 0.

motor.dc().reverse(speed=100, ramp_ms=0) -> bool

Run backward at a normalized speed.

Parameters
Name Type Pass as Required Description
speed int positional or keyword No Optional value. Defaults to 100.
ramp_ms int positional or keyword No Optional value. Defaults to 0.

motor.dc().run_for(speed, duration_ms, callback=None) -> bool

Run at signed speed and stop after duration_ms. Callback is reserved for future firmware.

Parameters
Name Type Pass as Required Description
speed int positional or keyword Yes Required value.
duration_ms int positional or keyword Yes Required value.
callback callback positional or keyword No Optional value. Defaults to None.

motor.dc().forward_for(speed, duration_ms, callback=None) -> bool

Run forward and stop after duration_ms.

Parameters
Name Type Pass as Required Description
speed int positional or keyword Yes Required value.
duration_ms int positional or keyword Yes Required value.
callback callback positional or keyword No Optional value. Defaults to None.

motor.dc().reverse_for(speed, duration_ms, callback=None) -> bool

Run backward and stop after duration_ms.

Parameters
Name Type Pass as Required Description
speed int positional or keyword Yes Required value.
duration_ms int positional or keyword Yes Required value.
callback callback positional or keyword No Optional value. Defaults to None.

motor.dc().stop(ramp_ms=0) -> bool

Stop using the configured stop_mode.

Parameters
Name Type Pass as Required Description
ramp_ms int positional or keyword No Optional value. Defaults to 0.

motor.dc().brake() -> bool

Actively brake when the driver wiring supports it.

motor.dc().coast() -> bool

Let the motor coast by removing drive.

motor.dc().duty(value) -> bool

Advanced raw duty command from 0 to 100.

Parameters
Name Type Pass as Required Description
value any positional or keyword Yes Required value.

motor.dc().speed() -> int

Return the last commanded signed speed.

motor.dc().direction() -> str

Return "forward", "reverse", or "stopped".

motor.dc().running() -> bool

Return True when the commanded speed is non-zero.

motor.dc().stop_mode() -> str

Return the configured stop mode.

motor.dc().info() -> dict

Return pins, PWM channel, mode, speed, and stop behavior.

motor.dc().close() -> bool

Stop the motor and release the native PWM channel.

motor.differential(left: dc_motor, right: dc_motor) -> differential_drive

Create a two-motor differential drive helper.

Pass two dc_motor objects and use move/drive/turn helpers for small robots. The helper does not own the motors; keep the left and right motor variables.

Parameters
Name Type Pass as Required Description
left dc_motor positional or keyword Yes Left dc_motor object.
right dc_motor positional or keyword Yes Right dc_motor object.
Returns

differential_drive differential_drive object.

motor.differential().move(speed, turn) -> bool

Mix speed and turn into left/right motor speeds.

Parameters
Name Type Pass as Required Description
speed int positional or keyword Yes Required value.
turn int positional or keyword Yes Required value.

motor.differential().drive(speed) -> bool

Drive both motors at the same signed speed.

Parameters
Name Type Pass as Required Description
speed int positional or keyword Yes Required value.

motor.differential().turn_left(speed=50) -> bool

Rotate left by reversing the left motor and driving the right motor.

Parameters
Name Type Pass as Required Description
speed int positional or keyword No Optional value. Defaults to 50.

motor.differential().turn_right(speed=50) -> bool

Rotate right by driving the left motor and reversing the right motor.

Parameters
Name Type Pass as Required Description
speed int positional or keyword No Optional value. Defaults to 50.

motor.differential().stop() -> bool

Stop both motors.

motor.differential().info() -> dict

Return left/right speed and running state.