Skip to content

Api Documentation ‐ Motor

Jump to bottom
carl wheezer with dreads edited this page Sep 24, 2025 · 1 revision

Motor Module Documentation

The motor module provides functions and constants for controlling motors connected to the hub.

Requiring the Module

To use the motor module, you can require it as follows:

local motor = require("src.modules.motor")
local Port = require("src.modules.hub.ports") -- For accessing port constants

Constants

The motor module defines several constants for movement status, stop behaviors, and directions.

Movement Status

Constant Value Description
motor.READY 0 Movement is ready.
motor.RUNNING 1 Movement is in progress.
motor.STALLED 2 Movement has stalled.
motor.CANCELED 3 Movement was canceled.
motor.ERROR 4 An error occurred.
motor.DISCONNECTED 5 The motor was disconnected.

Stop Behaviors

Constant Value Description
motor.COAST 10 Motor will coast freely.
motor.BRAKE 11 Motor will actively brake.
motor.HOLD 12 Motor will hold its current position.
motor.CONTINUE 13 Motor will continue running.
motor.SMART_COAST 14 Brake then coast and compensate.
motor.SMART_BRAKE 15 Brake and compensate.

Directions

Constant Value Description
motor.CLOCKWISE 20 Turn clockwise.
motor.COUNTERCLOCKWISE 21 Turn counter-clockwise.
motor.SHORTEST_PATH 22 Turn via the shortest path.
motor.LONGEST_PATH 23 Turn via the longest path.

Functions

motor.absolute_position(port)

Gets the absolute position of a Motor.

  • port (number): A port from the Port module (e.g., Port.A).
  • Returns (number): The absolute position in degrees.
local absPos = motor.absolute_position(Port.A)
print("Motor A absolute position:", absPos)

motor.get_duty_cycle(port)

Gets the current PWM duty cycle of a Motor.

  • port (number): A port from the Port module.
  • Returns (number): The PWM value.
local pwm = motor.get_duty_cycle(Port.B)
print("Motor B PWM duty cycle:", pwm)

motor.relative_position(port)

Gets the relative position of a Motor.

  • port (number): A port from the Port module.
  • Returns (number): The relative position in degrees.
local relPos = motor.relative_position(Port.C)
print("Motor C relative position:", relPos)

motor.reset_relative_position(port, position)

Resets the motor's relative position counter.

  • port (number): A port from the Port module.
  • position (number): The degree to set as the new zero position.
  • Returns (void)
motor.reset_relative_position(Port.A, 0) -- Set current position of Motor A as 0 degrees

motor.run(port, velocity, acceleration)

Starts a Motor at a constant speed.

  • port (number): A port from the Port module.
  • velocity (number): The velocity in degrees/sec.
  • acceleration? (number): The acceleration (deg/sec²) from 1-10000 (optional).
  • Returns (void)
motor.run(Port.A, 360, 5000) -- Run Motor A at 360 deg/sec with 5000 deg/sec² acceleration

motor.run_for_degrees(port, degrees, velocity, stop, acceleration, deceleration)

Turns a motor for a specific number of degrees.

  • port (number): A port from the Port module.
  • degrees (number): The number of degrees to turn.
  • velocity (number): The velocity in degrees/sec.
  • stop? (number): The behavior after stopping (e.g., motor.BRAKE) (optional).
  • acceleration? (number): The acceleration (deg/sec²) (optional).
  • deceleration? (number): The deceleration (deg/sec²) (optional).
  • Returns (number): A status constant like motor.READY or motor.STALLED.
local status = motor.run_for_degrees(Port.B, 720, 180, motor.BRAKE)
if status == motor.READY then
    print("Motor B finished turning 720 degrees.")
end

motor.run_for_time(port, duration, velocity, stop, acceleration, deceleration)

Runs a Motor for a limited amount of time.

  • port (number): A port from the Port module.
  • duration (number): The duration in milliseconds.
  • velocity (number): The velocity in degrees/sec.
  • stop? (number): The behavior after stopping (e.g., motor.BRAKE) (optional).
  • acceleration? (number): The acceleration (deg/sec²) (optional).
  • deceleration? (number): The deceleration (deg/sec²) (optional).
  • Returns (number): A status constant like motor.READY or motor.STALLED.
local status = motor.run_for_time(Port.C, 2000, 90, motor.COAST)
if status == motor.READY then
    print("Motor C ran for 2 seconds.")
end

motor.run_to_absolute_position(port, position, velocity, direction, stop, acceleration, deceleration)

Turns a motor to an absolute position.

  • port (number): A port from the Port module.
  • position (number): The absolute degree to turn to.
  • velocity (number): The velocity in degrees/sec.
  • direction? (number): The direction to turn (e.g., motor.SHORTEST_PATH) (optional).
  • stop? (number): The behavior after stopping (e.g., motor.BRAKE) (optional).
  • acceleration? (number): The acceleration (deg/sec²) (optional).
  • deceleration? (number): The deceleration (deg/sec²) (optional).
  • Returns (number): A status constant like motor.READY or motor.STALLED.
local status = motor.run_to_absolute_position(Port.A, 90, 100, motor.SHORTEST_PATH, motor.HOLD)
if status == motor.READY then
    print("Motor A reached absolute position 90 degrees.")
end

motor.run_to_relative_position(port, position, velocity, stop, acceleration, deceleration)

Turns a motor to a position relative to its current position.

  • port (number): A port from the Port module.
  • position (number): The relative degree to turn to.
  • velocity (number): The velocity in degrees/sec.
  • stop? (number): The behavior after stopping (e.g., motor.BRAKE) (optional).
  • acceleration? (number): The acceleration (deg/sec²) (optional).
  • deceleration? (number): The deceleration (deg/sec²) (optional).
  • Returns (number): A status constant like motor.READY or motor.STALLED.
local status = motor.run_to_relative_position(Port.B, 180, 200, motor.BRAKE)
if status == motor.READY then
    print("Motor B turned 180 degrees relative to its current position.")
end

motor.set_duty_cycle(port, pwm)

Starts a Motor with a specific PWM value.

  • port (number): A port from the Port module.
  • pwm (number): The PWM value (-10000 to 10000).
  • Returns (void)
motor.set_duty_cycle(Port.C, 5000) -- Set Motor C to 50% power forward

motor.stop(port, stop)

Stops a motor.

  • port (number): A port from the Port module.
  • stop? (number): The stop behavior (e.g., motor.BRAKE) (optional).
  • Returns (void)
motor.stop(Port.A, motor.BRAKE) -- Stop Motor A with braking

Clone this wiki locally