AFL.automation.shared.motors#

Reusable motor helpers with lazy-loaded Raspberry Pi dependencies.

Classes

Motor([name, log_level])

Base class for reusable motor helpers.

ServoMotor(**kwargs)

Control a PCA9685-backed hobby servo with lazy-loaded dependencies.

StepperMotor(**kwargs)

Control a GPIO-driven stepper motor using step and direction pins.

class AFL.automation.shared.motors.Motor(name: str | None = None, log_level: int | str = 20)[source]#

Base class for reusable motor helpers.

Parameters:
  • name (str, optional) – Logger name to use for this motor instance. If omitted, the class name is used.

  • log_level (int or str, default=logging.INFO) – Logging level for this motor instance. Accepts standard logging constants or names such as "DEBUG" and "INFO".

logger#

Logger used by derived motor classes.

Type:

logging.Logger

Examples

Create a base motor logger for a custom helper class.

>>> motor = Motor(name="gripper", log_level="DEBUG")
>>> motor.logger.name
'gripper'
__init__(name: str | None = None, log_level: int | str = 20) → None[source]#
class AFL.automation.shared.motors.ServoMotor(**kwargs)[source]#

Control a PCA9685-backed hobby servo with lazy-loaded dependencies.

Parameters:
  • channel (int, default=8) – PCA9685 output channel that the servo signal wire is connected to.

  • address (int, default=0x40) – I2C address of the PCA9685 board. Change this if the board address pins are configured differently.

  • bus (int, default=1) – I2C bus number on the host system. Use the bus your PCA9685 is wired to.

  • min_angle (int, default=0) – Lowest allowed commanded angle in degrees.

  • max_angle (int, default=90) – Highest allowed commanded angle in degrees.

  • open_angle (int, default=0) – Angle treated as the open position for your mechanism.

  • close_angle (int, default=90) – Angle treated as the closed position for your mechanism.

  • pulse_min (int, default=700) – Minimum pulse width in microseconds for servo calibration.

  • pulse_max (int, default=2400) – Maximum pulse width in microseconds for servo calibration.

  • channels (int, default=16) – Number of channels exposed by the attached PCA9685 board.

  • default_speed (float, default=90.0) – Default software ramp speed in degrees per second.

  • register_cleanup (bool, default=True) – Register cleanup with atexit so the servo output is released on exit.

  • name (str, optional) – Logger name override for this motor instance.

  • log_level (int or str, default=logging.INFO) – Logging verbosity for this motor instance.

channel#

PCA9685 output channel used by the servo.

Type:

int

address#

I2C address of the PCA9685 controller.

Type:

int

angle#

Last commanded servo angle.

Type:

int or None

state#

Human-readable servo state derived from the current angle.

Type:

str

Examples

Create a servo on channel 8 and move it to the configured open position.

>>> servo = ServoMotor(channel=8, open_angle=5)
>>> servo.open()

Move the servo to a specific angle at a limited speed.

>>> servo.set_angle(45, speed=30.0)
>>> servo.status()["state"]
'partial'
DEFAULTS = {'address': 64, 'bus': 1, 'channel': 4, 'channels': 16, 'close_angle': 90, 'default_speed': 90.0, 'log_level': 20, 'max_angle': 90, 'min_angle': 0, 'name': None, 'open_angle': 0, 'pulse_max': 2400, 'pulse_min': 700, 'register_cleanup': True}#
__init__(**kwargs) → None[source]#

Initialize the servo motor helper.

Parameters:

**kwargs – Optional configuration overrides merged with DEFAULTS.

set_angle(angle: int, speed: float = 0.0) → None[source]#

Move the servo to a target angle.

Parameters:
  • angle (int) – Target angle in degrees. Values are clamped to the configured min_angle and max_angle.

  • speed (float, default=0.0) – Approximate angular speed in degrees per second. A value less than or equal to zero applies the target angle immediately.

Examples

>>> servo = ServoMotor()
>>> servo.set_angle(30)
>>> servo.set_angle(60, speed=20.0)
open(speed: float | None = None) → None[source]#

Move the servo to the configured open angle.

Parameters:

speed (float, optional) – Override for the configured default speed.

Examples

>>> servo = ServoMotor(open_angle=10)
>>> servo.open()
close(speed: float | None = None) → None[source]#

Move the servo to the configured closed angle.

Parameters:

speed (float, optional) – Override for the configured default speed.

Examples

>>> servo = ServoMotor(close_angle=80)
>>> servo.close(speed=45.0)
status() → Dict[str, object][source]#

Return the current servo state.

Returns:

Dictionary containing the configured servo parameters and the last commanded state.

Return type:

dict

Examples

>>> servo = ServoMotor()
>>> isinstance(servo.status(), dict)
True
cleanup() → None[source]#

Release the servo output.

Examples

>>> servo = ServoMotor(register_cleanup=False)
>>> servo.cleanup()
class AFL.automation.shared.motors.StepperMotor(**kwargs)[source]#

Control a GPIO-driven stepper motor using step and direction pins.

Parameters:
  • step_pin (int, default=20) – Raspberry Pi GPIO pin wired to the motor driver STEP input.

  • dir_pin (int, default=21) – Raspberry Pi GPIO pin wired to the motor driver DIR input.

  • steps_per_rev (int, default=200) – Full-step count per shaft revolution after accounting for driver microstepping.

  • step_delay (float, default=0.001) – Delay in seconds between GPIO transitions when stepping.

  • default_speed (float, default=1.0) – Default rotation speed in revolutions per second.

  • mode ({"BCM", "BOARD"}, default="BCM") – Pin numbering scheme used when choosing step_pin and dir_pin.

  • register_cleanup (bool, default=True) – Register cleanup with atexit so GPIO pins are reset on exit.

  • name (str, optional) – Logger name override for this motor instance.

  • log_level (int or str, default=logging.INFO) – Logging verbosity for this motor instance.

step_pin#

GPIO pin used for the step signal.

Type:

int

dir_pin#

GPIO pin used for the direction signal.

Type:

int

position#

Current tracked position in steps.

Type:

int

connected#

Whether GPIO pins have been configured for output.

Type:

bool

Examples

Connect a stepper and rotate it clockwise.

>>> motor = StepperMotor(step_pin=20, dir_pin=21)
>>> motor.connect()
>>> motor.rotate_cw(0.5)

Rotate the motor counterclockwise with an explicit speed.

>>> motor.rotate_ccw(1.0, speed=2.0)
>>> motor.status()["connected"]
True
DEFAULTS = {'default_speed': 1.0, 'dir_pin': 21, 'log_level': 20, 'mode': 'BCM', 'name': None, 'register_cleanup': True, 'step_delay': 0.001, 'step_pin': 20, 'steps_per_rev': 200}#
__init__(**kwargs) → None[source]#

Initialize the stepper motor helper.

Parameters:

**kwargs – Optional configuration overrides merged with DEFAULTS.

connect() → None[source]#

Configure the GPIO pins for stepper control.

Raises:

ValueError – If mode is not "BCM" or "BOARD".

Examples

>>> motor = StepperMotor(mode="BCM")
>>> motor.connect()
cleanup() → None[source]#

Reset the configured GPIO pins and mark the motor disconnected.

Examples

>>> motor = StepperMotor(register_cleanup=False)
>>> motor.cleanup()
rotate_cw(rotations: float, speed: float | None = None, step_delay: float | None = None) → None[source]#

Rotate the motor clockwise.

Parameters:
  • rotations (float) – Number of shaft rotations to execute.

  • speed (float, optional) – Rotational speed in revolutions per second.

  • step_delay (float, optional) – Explicit delay between GPIO transitions. If provided, it overrides the delay derived from speed.

Examples

>>> motor = StepperMotor()
>>> motor.connect()
>>> motor.rotate_cw(0.25)
rotate_ccw(rotations: float, speed: float | None = None, step_delay: float | None = None) → None[source]#

Rotate the motor counterclockwise.

Parameters:
  • rotations (float) – Number of shaft rotations to execute.

  • speed (float, optional) – Rotational speed in revolutions per second.

  • step_delay (float, optional) – Explicit delay between GPIO transitions. If provided, it overrides the delay derived from speed.

Examples

>>> motor = StepperMotor()
>>> motor.connect()
>>> motor.rotate_ccw(0.25, speed=1.5)
home() → None[source]#

Reset the tracked position to zero.

Notes

This method only resets the software position counter. It does not move the motor to a physical home switch.

Examples

>>> motor = StepperMotor()
>>> motor.home()
status() → Dict[str, object][source]#

Return the current stepper configuration and tracked position.

Returns:

Dictionary containing GPIO configuration, connection state, and tracked position.

Return type:

dict

Examples

>>> motor = StepperMotor()
>>> isinstance(motor.status(), dict)
True