AdvPiStepper Documentation

The AdvPiStepper Class

The AdvPiStepper class is the main interface

class advpistepper.stepper.AdvPiStepper(driver=None, parameters: Dict[str, Any] = None)

Parameters:

• driver (DriverBase) – The GPIO driver used to translate steps to pigpio pulses and waves. The stepper may contain some optional info about the actual stepper motor (max. speed etc.). Defaults to a dummy driver (no actual gpio).
• parameters (Dict[str,Any]) – Optinal list of parameters to override default values. Refer to parameters for more details

current_position

The current position of the motor.

The position will be in steps or microsteps from the origin.

While the motor is running the reported current position might lag the true current position by 1 or more steps due to the asynchrounous nature of AdvPiStepper.

This property is read-only.

Type:int

target_position

The current target position of the driver.

This is the position the stepper driver is currently moving to.

This property is read-only.

Type:int

target_speed

The selected target speed in steps or microsteps per second.

This is the speed the stepper will accelerate to and maintain during moves. It is independant of the direction and must be greater than 0. Setting a target speed of 0 or less will cause a ValueError exception.

Note

High values (>1.000 sps) may cause timing jitter and even lost steps.

Type:float

current_speed

The current speed in steps or microsteps per second.

During acceleration / deceleration the current speed will be less than the target speed. Due to the asynchronous nature of AdvPiStepper the returned value might lag the actual speed.

This property is read-only.

Type:float

acceleration

The current acceleration rate in steps or microsteps per second ²

This property will override any default acceleration rate set by the driver. Any changes to this rate will be applied immediately and will affect any ongoing acceleration.

Note

High values may cause lost steps and motor stalls.

The value must be greater than zero. Trying to set a value of 0 or less will cause a ValueError exception.

Type:float

deceleration

The current deceleration rate in steps or microsteps per second ²

This property will override any default deceleration rate set by the driver. Any changes to this rate will be applied immediately and will affect any ongoing deceleration.

Note

High values may cause unaccounted steps due to motor inertia.

The value must be greater than zero. Trying to set a value of 0 or less will cause a ValueError exception.

Type:float

full_steps_per_rev

The number of full steps for one complete revolution of the motor.

Overrides any default value that may have been set by the driver.

Is applied immediately and will effect any succeding move_deg() or moveto_deg() calls.

The value must be 2 or greater. Trying to set a value less of 1 or less will cause a ValueError exception.

Type:int

microsteps

Number of microsteps per full step.

The number must be from the list of supported MICROSTEP_OPTIONS. Changing microsteps while the stepper motor is running may or may not work - depending on the driver. Refer to the driver documentation for changing microsteps while running. Some drivers need to sync their internal step sequencer before changing the microstep setting. Therefore the change may happen at some point in the future without any guarantee about the exact step.

Note

If the microstep setting is changed while the motor is running the absolute speed will be unchanged, i.e. the target speed (in steps per second) will be scaled by new_microsteps / old_microsteps.

Trying to set a value that is not supported by the driver will cause a ValueError exception.

Type:int

is_running

Flag to indicate that the the stepper is still running.

Returns:True if the stepper engine is not idle.

move(steps: int, speed: float = None, block: bool = False)

Move the given number of steps relative to a position.

If called while the motor is idle the move will be relative to the current position. If the motor is already executing a move the new move will be relative to the previous target position. If the motor is running in continuous mode the new move will be relative to the current position.

Parameters:

• steps (int) – Number of steps, full or microsteps. Positiv for forward / clockwise, negative for backwards / counterclockwise.
• speed (float) – Target speed in steps or microsteps per second. Must be >0. Optional, default is the most recent target speed.
• block (bool) – When True waits for the move to complete. Default False, i.e. call will return immediately.

Raises:

ValueError – if the speed is 0 or less.

move_to(position: int, speed: float = None, block: bool = False)

Move to the given absolute location.

Location is in steps or microsteps from the origin, which is the position set by zero() (or the position at initialization) and can be negative. This can be called while a move is underway.

Parameters:

• position (int) – Target position in steps or microsteps.
• speed (float) – Target speed in steps or microsteps per second. Must be >0. Optional, default is the most recent target speed.
• block (bool) – When True waits for the move to complete. Default False, i.e. call will return immediately.

Raises:

ValueError – if the speed is 0 or less.

run(direction: int, speed: float = 0.0)

Run the motor constantly.

The motor will accelerate to and maintain a given speed. It will run until either stopped with stop() or overriden by any move() / move_to() call. This method can only be run as non-blocking for obvious reasons.

Parameters:

• direction (int) – Direction of movement. Either CW (1) or CCW (-1).
• speed (float) – Speed in steps per second. Optional, default is target_speed.

Raises:

ValueError – if either the direction is not CW/CCW or if the speed is 0 or less.

stop(block: bool = False)

Decelerate the motor to a complete stop.

Parameters:block (bool) – When True waits for the stop to complete. Default False, i.e. call will return immediately.

hardstop(block: bool = False)

Stops the motor immediately.

How the motor is stopped depends on the motor driver. Usually the driver will just deenergize all motor coils.

Due to inertia calling this on a moving motor will probably cause unaccounted motor steps. The current_position may not be accurate anymore and it is up to the caller to get the motor to a consistent state if so required.

Parameters:block (bool) – When True waits for the driver to initiate the hard stop. Default False, i.e. call will return immediately.

wait(timeout: float = None) → bool

Wait for the current move to finish.

When invoked with a positive, floating-point value for timeout, block for at most the number of seconds specified by timeout.

Warning

If called without a timeout value while a run() is running this method will not return.

Parameters:timeout – timeout in seconds Returns:True is the move has finished, False if the wait timed out.

zero()

Reset the current position to 0.

If called during a move the move will not be affected, i.e. it will continue for the given number of steps. But after it has finished the current position will be the number of steps performed since the call to zero().

engage(block: bool = False)

Energize the coils of the stepper motor.

The coils are automatically engaged by any move / run command. This method should not be called while the motor is already moving.

Parameters:block (bool) – When True waits for the driver to energize. Default False, i.e. call will return immediately.

release(block: bool = False)

Deenergize the coils of the stepper motor.

Deenergizing the coils will stop the motor from converting current into heat at the expense of yreduced holding torque. Also, when using microsteps the motor may (or may not) move to an adjacent full step.

Calling this method while a move is underway is similar to a hard stop.

Parameters:block (bool) – When True waits for the driver to release. Default False, i.e. call will return immediately.

close()

End the stepper driver.

All resources are released. This is called automatically when the AdvPiStepper object is garbage collected.

advpistepper.common module

Definitions used by the AdvPiStepper

CW and CCW constants defining clockwise / couterclockwise motions.

The Keys which are used as parameters to describe a motor and the driver.

• DRIVER_NAME Human readable name of the driver.
• MAX_SPEED: Maximum speed in steps per second. This is not a limit, just a recommendation.
• MAX_TORQUE_SPEED: Maximum speed at which the motor will still deliver full torque (optional, if known)
• ACCELERATION_RATE: Acceleration in steps per second squared.
• DECELERATION_RATE: Deceleration in steps per second squared.
• FULL_STEPS_PER_REV: Number of full (not micro-)steps per one revolution.
• MICROSTEP_OPTIONS: Tupel of all microsteps options.
• MICROSTEP_DEFAULT: The prefered microstep rate of the driver.

Other parameters which can be passed to the AdvPiStepper class

• PIGPIO_ADDR: The hostname of the system where the pigpio daemon is running on.
• PIGPIO_PORT: The port on which the pigpio daemon is listening on.

advpistepper.common.CW = 1

Clockwise/forward rotation. Just an internal designation. True direction may depend on the wiring of the stepper motor.

advpistepper.common.CCW = -1

Counterclockwise/backward rotation. Just an internal designation. True direction may depend on the wiring of the stepper motor.

advpistepper.common.MAX_SPEED = 'max_speed'

Maximum speed in steps per second. This is not a limit, just a recommendation

advpistepper.common.MAX_TORQUE_SPEED = 'max_torque_speed'

Maximum speed at which the motor will still deliver full torque.

advpistepper.common.ACCELERATION_RATE = 'acceleration_rate'

Acceleration in steps per second squared.

advpistepper.common.DECELERATION_RATE = 'deceleration_rate'

Decelearation in steps per second squared.

advpistepper.common.FULL_STEPS_PER_REV = 'full_steps_per_rev'

Number of full (not micro-)steps per one revolution.

advpistepper.common.MICROSTEP_OPTIONS = 'microstep_options'

Tupel of all microsteps options. Default is only full steps.

advpistepper.common.MICROSTEP_DEFAULT = 'microstep_default'

The prefered microstep rate of the driver.

advpistepper.common.PIGPIO_ADDR = 'pigpio_addr'

The hostname of the system where the pigpio daemon is running on. Default is empty for the localhost.

advpistepper.common.PIGPIO_PORT = 'pigpio_port'

The port on which the pigpio daemon is listening on. Default is empty to use the default pigpio port (8888).

advpistepper.common.DIRECTION_INVERT = 'direction_invert'

If this key exists then the direction signal is inverted by the driver, i.e. Clockwise and Counterclockwise are swaped.

advpistepper.common.DIRECTION_CHANGE_DELAY = 'direction_change_delay'

The time between a change in direction and the first step pulse (in microseconds)

advpistepper.common.STEP_PULSE_LENGTH = 'step_pulse_length'

The time for a step pulse (in microseconds)

advpistepper.common.STEP_PULSE_DELAY = 'step_pulse_delay'

The minimum time between step pulses (in microseconds)

advpistepper.driver_base module

class advpistepper.driver_base.DriverBase(parameters: Dict[str, Any] = None)

The base class for all stepper drivers. This class should be subclassed for specfic drivers.

At a minimum a driver should override perform_step() to generate the gpio pulses. All other methods can be overridden as required.

db_defaults = {'acceleration_rate': 1000, 'deceleration_rate': 1000, 'driver_name': 'Debug Driver (No GPIO)', 'full_steps_per_rev': 400, 'max_speed': 1000.0, 'max_torque_speed': 100.0, 'microstep_default': 1, 'microstep_options': (1,)}

engaged = None

Falg to indicate that the driver is engaged, i.e. current is supplied to the coils.

parameters

returns the physical parameters of the associated hardware (driver and motor). See common.py for the list of parameters :return: Dictionary with a copy of all parameters. :rtype: Dict[str, Any]

max_speed

Returns the maximum recommended speed in steps per second. :returns: max speed :rtype: int

microstep_options

Return a tuple with all microstep options. :returns: tuple with int microstep options, e.g. (1,2,4,8) :rtype: Tuple[int]

init(pi: pigpio.pi)

Initializes the driver, setting up the required GPIO pins. :param pi: the pigpio instance to use.

engage()

Energize the coils.

release()

Deenergize all coils.

direction

The current direction of the motor. Can be either clockwise (CW / 1) or counterclockwise (CCW / -1). When changed all subsequent calls to perform_step() will go in the given direction. It is up to the caller to ensure that the motor is able to change the direction of rotation, i.e. has come to a complete stop.

microsteps

The currently set number of microsteps.

This property is read only. Use set_microsteps() to change the microsteps.

set_microsteps(steps: int) → bool

Set the microsteps.

This method will only be successful if the driver is ready for a change in microsteps, which can be checked with steps_until_change_microsteps() method.

Parameters:steps (int) – Value from the list of MICROSTEP_OPTIONS. Returns:‘True’ if the change was successfull, ‘False’ if the microsteps could not be changed.

steps_until_change_microsteps(microsteps: int) → int

Checks when the the requested microstep setting can be changed.

The result is in steps. If the result is 0 the driver is ready for a change in microsteps. Positive values are the number of steps which have to be performed before the change is possible (e.g. to sync to the next full step first). A negative return value means that the driver can not change to the new value, either because it is not supported or the change can only be made when the motor is not running.

Parameters:microsteps (int) – Requested microstep option, either FULLSTEP (1) or HALFSTEP (2) Returns:number of steps before microsteps value can be changed. 0 if change is possible right now. negative if the requested microsteps can not be set at the moment. Return type:int

perform_step(delay: int) → list

Returns a list of pigpio pulse objects (a wave) for a single step lasting delay microseconds. :param delay: total time for the step. :return: a pigpio wave (list of pulses)

hard_stop()

Perform a hard stop where the motor is stop immediately, even at the expense of lost steps. The default is just to de-energize the coils, but some more advanced stepper drivers may have braking or other means to come to a quick stop. Due to the asynchronous nature of the engine there might be multiple stepper motor pulses already in the pipeline that will be transmitted even after a call to hard_stop(). Subclasses should take care that these pulses do not cause any further motor movement, e.g. by deactivtiong any GPIO output.

advpistepper.driver_unipolar_28byj48 module

Driver for the popular 28BYJ-48 stepper motor.

The 28BYJ-48 is a small, 5V or 12V stepper motor with an integrated reduction gear which results in 2048 full steps per revolution of the output shaft. Due to the high reduction gear (64:1), this stepper motor is rather slow. Without any hacks (e.g. higher voltage; bipolar mods) and without much load the 28BYJ-48 should be able to do about 15 rpm or about 500 steps per second.

The 28BYJ-48 is a unipolar motor and is often sold together with a small driver board based on the ULN2003 Darlington array for less than 3€.

This driver just defines the following parameters for this motor, guessed from this datasheet with the help of the stepper motor glossary

There are numerous variants of the 28BYJ-48 on the market with slightly different parameters, so these parameters are on the conservative side. Each can be overriden by providing an optional dictionary with alternative values to the constructor.

• MAX_SPEED: 650 steps/second (~10 rpm)
• MAX_TORQUE_SPEED: 120 steps/second
• ACCELERATION_RATE: 2000 steps / second^2
• DECELERATION_RATE: 4000 steps / second^2
• FULL_STEPS_PER_REV: 2048 Full steps per revolution
• MICROSTEP_OPTIONS: FULLSTEP or HALFSTEP.
• MICROSTEP_DEFAULT: HALFSTEP

Halfstep is the recommended rate for the 28BYJ-48

Besides the motor characteristics this driver uses colors for the 4 control wires which seem to be standard for all 28BYJ-48 variants.

• pink / orange for A+ and A-
• yellow / blue for B+ and B-

Note

The motor wires should not be connected to the Raspberry directly. To provide sufficient power to the motor a driver IC like the ULN2003A should be used.

class advpistepper.driver_unipolar_28byj48.Driver28BYJ48(pink, orange, yellow, blue, parameters: Dict[str, Any] = None)

Bases: advpistepper.driver_unipolar_generic.DriverUnipolarGeneric

Parameters:

• pink (int) – GPIO pin the pink wire (A+)is connect to (Broadcom / pigpio numbering)
• orange (int) – GPIO pin the orange wire (A-) is connect to (Broadcom / pigpio numbering)
• yellow (int) – GPIO pin the yellow wire (B+) is connect to (Broadcom / pigpio numbering)
• blue (int) – GPIO pin the blue wire (B-) is connect to (Broadcom / pigpio numbering)
• parameters (dict, optional) – Optional parameters to override the default values.

advpistepper.driver_unipolar_generic module

Driver for generic Unipolar Stepper Motors.

Baseclass for all unipolar motor drivers, but can also be used by itself. It generates the GPIO sequences for eiter FULLSTEP mode, where two coils are powered for each step, or HALFSTEP mode, wher either one or two coils are powered at each step.

Unless overridden by a subclass or by the user this driver uses the following default parameters:

• MAX_SPEED: 800 steps/second (120rpm)
• MAX_TORQUE_SPEED: 100 steps/second
• ACCELERATION_RATE: 2000 steps / second^2
• DECELERATION_RATE: 3000 steps / second^2
• FULL_STEPS_PER_REV: 200 Full steps per revolution (1.8° per step)
• MICROSTEP_OPTIONS: FULLSTEP or HALFSTEP.
• MICROSTEP_DEFAULT: FULLSTEP

Besides the (optional) parameters this driver needs the the 4 GPIO pins connected to the A+, A-, B+ and B- coils (called a1, a2, b1 and b2 by the driver)

Note

Except for very low power stepper motors the motor wires should not be connected to the Raspberry directly. To provide sufficient power to the motor a driver like the ULN2003A should be used.

class advpistepper.driver_unipolar_generic.DriverUnipolarGeneric(a1, a2, b1, b2, parameters: Dict[str, Any] = None)

Bases: advpistepper.driver_base.DriverBase

Basic Unpolar driver module.

Parameters:

• a1 (int) – GPIO pin number for coil A+ (pigpio/broadcom numbering)
• a2 (int) – GPIO pin number for coil A- (pigpio/broadcom numbering)
• b1 (int) – GPIO pin number for coil B+ (pigpio/broadcom numbering)
• b2 (int) – GPIO pin number for coil B- (pigpio/broadcom numbering)
• parameters (dict, optional) – Optional parameters to override the default values.

gpio_pins

Tupel with the four GPIO pins used by the driver. The are in the order A+, A-, B+ and B- and use the Broadcom pin numbering as used by pigpio. This property can be written to, however changing the GPIO pins while the motor is running is propably not a good idea.

Type:Tupel with 4 int, 0 <= n <= 56

init(pi: pigpio.pi)

Initialize the driver by setting all GPIO pins to output and to LOW. This method should only be called by the stepper process.

Parameters:pi – the pigpio instance to use.

engage()

Energize the coils. Only the coils for the current step are energized, the other coils will not be powered.

release()

Deenergize all coils.

set_microsteps(steps: int) → bool

Set the microsteps.

This method will only be successful if the driver is ready for a change in microsteps, which can be checked with steps_until_change_microsteps() method.

Parameters:steps (int) – either FULLSTEP (1) or HALFSTEP (2) Returns:‘True’ if the change was successfull, ‘False’ if the microsteps could not be changed.

steps_until_change_microsteps(microsteps: int) → int

Checks when the the requested microstep setting can be changed.

The result is in steps. If the result is 0 the driver is ready for a change in microsteps. Positive values are the number of steps which have to be performed before the change is possible (e.g. to sync to the next full step first). A negative return value means that the driver can not change to the new value, either because it is not supported or the change can only be made when the motor is not running.

Parameters:microsteps (int) – Requested microstep option, either FULLSTEP (1) or HALFSTEP (2) Returns:Either 0 (change possible right now) or 1 (change possibel after the next step). Negative if microstep was neither 1 nor 2. Return type:int

direction

The current direction of the motor. Can be either clockwise (CW / 1) or counterclockwise (CCW / -1). When changed all subsequent calls to perform_step() will go in the given direction. It is up to the caller to ensure that the motor is able to change the direction of rotation, i.e. has come to a complete stop.

perform_step(delay: int) → list

Generate the pigpio wave list for a single step.

The generated wave starts with the given delay and then sets the GPIOs for the step.

hard_stop()

Perform a hard stop where the motor is stop immediately, even at the expense of lost steps. This is done by pulling all 4 GPIO pins to LOW and changing the pins to input to prevent any steps which are still in the pipeline to go to the motor.

advpistepper.stepper_process module

The backend Process for the AdvPiStepper.

This class accepts commands from the frontend, calculates target positions and speed, including accelerations and decelerations, and finally converts these into steps and the time delay between them. A driver is then used to generate pigpio pulse sequences which can finally be sent to the pigpio daemon for the actual GPIO pulses.

class advpistepper.stepper_process.State

Bases: enum.Enum

Enum of all states of the stepper engine.

IDLE = 1

Stepper is not running and the coils are deenergized.

STOP = 2

Stepper is not running but the coils are energized to hold the last position.

ACCEL = 3

Stepper is accelerating to the target speed.

INC = 4

After being in the RUN state the stepper is accelerating to a new target speed.

RUN = 5

Stepper is running at the target speed.

DEC = 6

Stepper is decelerating to a new, slower target speed.

DECEL = 7

Stepper is decelerating to a STOP.

class advpistepper.stepper_process.ControllerData(state: int = <State.IDLE: 1>, current_direction: int = 0, c_n: int = 0, c_min: int = 1000, c_0: int = 10000, c_target: int = 2000, delay: int = 0, target_speed: float = 100, speed: float = 0.0, step: int = 0, decel_steps: int = 0)

Bases: object

Object containing all data for the speed controller.

state = 1

Current state of the stepper.

current_direction = 0

0 = at rest, CW = forward, CCW = backward.

c_n = 0

time from the current step to the next (in microseconds).

c_min = 1000

Minimum time between steps (at max rate) in microseconds.

This determines the maximum speed of the motor. Default is 1ms (1000steps per second), but the motor stepper driver should supply a more appropriate value for the connected motor and its GPIO stepper.

c_0 = 10000

Initial time between steps at the start of a move (in microseconds). 10000 is just a placeholder. The actual value is calculated from the set acceleration.

c_target = 2000

Time between steps for the target speed (as set by speed()) (in microseconds).

delay = 0

int: delay until the next step in microseconds.

target_speed = 100

Target speed in steps per second. Default is 100 steps per second.

speed = 0.0

Current speed in steps per second.

step = 0

The current step in the acceleration and deceleration phases.

decel_steps = 0

Number of steps required to decelerate to a full stop.

class advpistepper.stepper_process.Verb

Bases: enum.Enum

List of Commands that can be send to the stepper background process.

SPEED = 1

ACCELERATION = 2

DECELERATION = 3

FULL_STEPS_PER_REV = 4

MICROSTEPS = 5

MOVE = 6

MOVE_DEG = 7

MOVE_RAD = 8

MOVETO = 9

MOVETO_DEG = 10

MOVETO_RAD = 11

RUN = 12

STOP = 13

ZERO = 14

HARD_STOP = 15

QUIT = 16

ENGAGE = 17

RELEASE = 18

GET = 19

NOP = 20

ACKNOWLEDGE = 21

class advpistepper.stepper_process.Noun

Bases: enum.Enum

List of values that can be queried with the GET Verb.

VAL_CURRENT_SPEED = 1

VAL_TARGET_SPEED = 2

VAL_CURRENT_POSITION = 3

VAL_TARGET_POSITION = 4

VAL_ACCELERATION = 5

VAL_DECELERATION = 6

VAL_FULL_STEPS_PER_REV = 7

VAL_MICROSTEPS = 8

VAL_ACKNOWLEDGE = 9

MICROSTEP_NOT_POSSIBLE = 10

MICROSTEP_CHANGE_AT = 11

class advpistepper.stepper_process.Command(verb: advpistepper.stepper_process.Verb, noun: Union[advpistepper.stepper_process.Noun, int, float] = None)

Bases: object

Command object passed from the frontend to the background Process.

verb = None

noun = None

class advpistepper.stepper_process.Result(noun: advpistepper.stepper_process.Noun, value: Union[int, float, bool, advpistepper.stepper_process.Verb])

Bases: object

Result object passed from the background Process to the frontend.

noun = None

value = None

class advpistepper.stepper_process.StepperProcess(command_pipe: multiprocessing.context.BaseContext.Pipe, results_pipe: multiprocessing.context.BaseContext.Pipe, run_lock: multiprocessing.context.BaseContext.Lock, driver: advpistepper.driver_base.DriverBase = None, parameters: Dict[str, Any] = None)

Bases: multiprocessing.context.Process

Stepper engine background process.

Parameters:

• command_pipe (multiprocessing.Pipe) – Pipe which will receive Command objects.
• results_pipe (multiprocessing.Pipe) – Pipe where Result objects are send back to the frontend.
• run_lock (multiprocessing.Lock) – A lock which the backend uses while busy
• driver (DriverBase) – The GPIO driver used to translate steps to pigpio pulses and waves.
• parameters (Dict[str,Any]) – Optinal list of parameters to override default values.

current_position = None

Where the motor is at any given moment in steps/microsteps.

target_position = None

Where the motor should drive to (in steps/microsteps).

microsteps = None

Number of microsteps per full step currently set.Default supplied by driver.

move_required = None

Flag to indicate that the Process has received a command to move the motor

quit_now = None

Flag to indicate that the Process should terminate nicely.

run()

Method to be run in sub-process; can be overridden in sub-class

connect_pigpio()

command_handler(command: advpistepper.stepper_process.Command)

set_speed(speed)

set_acceleration(rate: float)

set_deceleration(rate: float)

set_full_steps_per_rev(steps: int)

set_microsteps(steps: int)

move(relative)

move_deg(angle: float)

moveto(absolute)

moveto_deg(angle: float)

continuous(direction: int)

stop()

zero()

hard_stop()

quit()

engage()

release()

get_value(noun: advpistepper.stepper_process.Noun)

idle_loop()

init_move()

busy_loop()

calculate_delay

Module contents