Struct drv8825::Stepper

pub struct Stepper<Driver> { /* fields omitted */ }

Unified stepper motor interface

Wraps a driver that interfaces with the motor-controlling hardware and abstracts over it, providing an interface that works the same, no matter what kind of hardware controls the stepper motor.

You can construct an instance of this type using Stepper::from_driver.

Nomenclature

This structs wraps a software component that interfaces with hardware that controls a stepper motor. That software component is called a “driver”, because it “drives” the hardware it interfaces with.

The driven hardware typically comes in two forms:

• A low-level chip controlled by STEP and DIR signals, often called a stepper driver (yes, somewhat confusing) or stepper controller.
• A higher-level chip, typically controlled through some serial interface, often called a motion controller.

In practice, a given product can cleanly fall into one of the two camps, both, or anything in between.

Hardware capabilities

Depending on the actual hardware we’re interfacing with, we might only have access to the bare minimum functionality (STEP and DIR pins) or high-level motion control features. Since Stepper is agnostic on the driver and the hardware it interfaces with, there must be a way to deal with those differing capabilities.

Stepper provides a number of enable_* methods that enable access to a specific hardware capability, if the hardware and driver support this. Once that method has been called, the methods that control the hardware capability are available.

Step mode control

Enable this capability with Stepper::enable_step_mode_control and use it with Stepper::set_step_mode. Since not all stepper drivers support microstepping and of those that do, not all support setting it from software, this capability might not be available for all drivers.

Direction control & step control

Enable direction control with Stepper::enable_direction_control and use it with Stepper::set_direction. Enable step control with Stepper::enable_step_control and use ith with Stepper::step.

These capabilities are supported by virtually all stepper drivers, but might not be available for motion controllers. Where they are available, they are typically available together. They are modeled as separate capabilities, as to not make any assumptions. If you want to generate steps from software, for example, but control direction via some other means, then you can.

Motion control

Enable motion control with Stepper::enable_motion_control and use it with Stepper::move_to_position and Stepper::reset_position.

Motion control capability is directly supported by motion control chips, but a software implementation based on direction and step control exists in the motion_control module, to make the capability available for all drivers.

Notes on timer use

Some of this struct’s methods take a timer argument. This is expected to be an implementation of [embedded_hal::timer::CountDown], with the additional requirement that CountDown::Time has a TryFrom<Nanoseconds> implementation, where Nanoseconds refers to [embedded_time::duration::Nanoseconds].

Not every CountDown implementation provides this for its Time type, so it might be necessary that the user either adds this embedded_time integration to the HAL library they are using, or provides a wrapper around the CountDown implementation in their own code, adding the conversion there.

Every method that takes a timer argument internally performs the conversion from Nanoseconds to the timers Time type. Since the nanosecond values are constant and the CountDown implementation is known statically, the compiler should have enough information to perform this conversion at compile-time.

Unfortunately there is currently no way to make sure that this optimization actually happens. Additions like RFC 2632, RFC 2920, and possibly others along those lines, could help with this in the future. For now, users must manually inspect the generated code and tweak optimization settings (and possibly the HAL-specific conversion code), if this level of performance is required.

Implementations

impl<Driver> Stepper<Driver>

pub fn from_driver(driver: Driver) -> Stepper<Driver>

Create a new Stepper instance from a driver

pub fn driver(&self) -> &Driver

Access a reference to the wrapped driver

Can be used to access driver-specific functionality that can’t be provided by Stepper’s abstract interface.

pub fn driver_mut(&mut self) -> &mut Driver

Access a mutable reference to the wrapped driver

Can be used to access driver-specific functionality that can’t be provided by Stepper’s abstract interface.

pub fn release(self) -> Driver

Release the wrapped driver

Drops this instance of Stepper and returns the wrapped driver.

pub fn enable_step_mode_control<Resources, Timer>(
    self,
    res: Resources,
    initial: <<Driver as EnableStepModeControl<Resources>>::WithStepModeControl as SetStepMode>::StepMode,
    timer: &mut Timer
) -> Result<Stepper<<Driver as EnableStepModeControl<Resources>>::WithStepModeControl>, SignalError<<<Driver as EnableStepModeControl<Resources>>::WithStepModeControl as SetStepMode>::Error, <<Timer as CountDown>::Time as TryFrom<Nanoseconds<u32>>>::Error, <Timer as CountDown>::Error>> where
    Timer: CountDown,
    Driver: EnableStepModeControl<Resources>,
    <Timer as CountDown>::Time: TryFrom<Nanoseconds<u32>>, 

Enable microstepping mode control

Consumes this instance of Stepper and returns a new instance that provides control over the microstepping mode. Once this method has been called, the Stepper::set_step_mode method becomes available.

Takes the hardware resources that are required for controlling the microstepping mode as an argument. What exactly those are depends on the specific driver. Typically they are the output pins that are connected to the mode pins of the driver.

This method is only available, if the driver supports enabling step mode control. It might no longer be available, once step mode control has been enabled.

pub fn set_step_mode<Timer>(
    &'r mut self,
    step_mode: <Driver as SetStepMode>::StepMode,
    timer: &'r mut Timer
) -> SetStepModeFuture<RefMut<'r, Driver>, RefMut<'r, Timer>> where
    Timer: CountDown,
    Driver: SetStepMode,
    <Timer as CountDown>::Time: TryFrom<Nanoseconds<u32>>, 

Sets the microstepping mode

This method is only available, if the wrapped driver supports microstepping, and supports setting the step mode through software. Some hardware might not support microstepping at all, or only allow setting the step mode by changing physical switches.

You might need to call Stepper::enable_step_mode_control to make this method available.

pub fn enable_direction_control<Resources, Timer>(
    self,
    res: Resources,
    initial: Direction,
    timer: &mut Timer
) -> Result<Stepper<<Driver as EnableDirectionControl<Resources>>::WithDirectionControl>, SignalError<<<Driver as EnableDirectionControl<Resources>>::WithDirectionControl as SetDirection>::Error, <<Timer as CountDown>::Time as TryFrom<Nanoseconds<u32>>>::Error, <Timer as CountDown>::Error>> where
    Timer: CountDown,
    Driver: EnableDirectionControl<Resources>,
    <Timer as CountDown>::Time: TryFrom<Nanoseconds<u32>>, 

Enable direction control

Consumes this instance of Stepper and returns a new instance that provides control over the motor direction. Once this method has been called, the Stepper::set_direction method becomes available.

Takes the hardware resources that are required for controlling the direction as an argument. What exactly those are depends on the specific driver. Typically it’s going to be the output pin that is connected to the hardware’s DIR pin.

This method is only available, if the driver supports enabling direction control. It might no longer be available, once direction control has been enabled.

pub fn set_direction<Timer>(
    &'r mut self,
    direction: Direction,
    timer: &'r mut Timer
) -> SetDirectionFuture<RefMut<'r, Driver>, RefMut<'r, Timer>> where
    Timer: CountDown,
    Driver: SetDirection,
    <Timer as CountDown>::Time: TryFrom<Nanoseconds<u32>>, 

Set direction for future movements

You might need to call Stepper::enable_direction_control to make this method available.

pub fn enable_step_control<Resources>(
    self,
    res: Resources
) -> Stepper<<Driver as EnableStepControl<Resources>>::WithStepControl> where
    Driver: EnableStepControl<Resources>, 

Enable step control

Consumes this instance of Stepper and returns a new instance that provides control over stepping the motor. Once this method has been called, the Stepper::step method becomes available.

Takes the hardware resources that are required for controlling the stepping as an argument. What exactly those are depends on the specific driver. Typically it’s going to be the output pin that is connected to the hardware’s STEP pin.

This method is only available, if the driver/controller supports enabling step control. It might no longer be available, once step control has been enabled.

pub fn step<Timer>(
    &'r mut self,
    timer: &'r mut Timer
) -> StepFuture<RefMut<'r, Driver>, RefMut<'r, Timer>> where
    Timer: CountDown,
    Driver: Step,
    <Timer as CountDown>::Time: TryFrom<Nanoseconds<u32>>, 

Rotates the motor one (micro-)step in the given direction

Steps the motor one step in the direction that was previously set, according to current microstepping configuration. To achieve a specific speed, the user must call this method at an appropriate frequency.

You might need to call Stepper::enable_step_control to make this method available.

pub fn pulse_length(&self) -> Nanoseconds<u32> where
    Driver: Step, 

Returns the step pulse length of the wrapped driver/controller

The pulse length is also available through the Step trait. This method provides a more convenient way to access it.

You might need to call Stepper::enable_step_control to make this method available.

pub fn enable_motion_control<Resources>(
    self,
    res: Resources
) -> Stepper<<Driver as EnableMotionControl<Resources>>::WithMotionControl> where
    Driver: EnableMotionControl<Resources>, 

Enable motion control

Consumes this instance of Stepper and returns a new instance that provides motion control capabilities. Once this method has been called, the motion control API (Stepper::move_to_position, Stepper::reset_position) becomes available.

Takes the hardware resources that are required for motion control as an argument. What exactly those are depends on the specific driver. Typically it’s either going to be some kind of communication interface, for drivers that have access to hardware support for motion control, or a motion profile from the RampMaker library, for drivers that have support for setting direction and stepping and require a software fallback for motion control.

This method should be available for virtually all drivers, either via hardware support, or through the aforementioned software fallback. It might no longer be available, once motion control support has been enabled.

pub fn move_to_position(
    &'r mut self,
    max_velocity: <Driver as MotionControl>::Velocity,
    target_step: i32
) -> MoveToFuture<RefMut<'r, Driver>> where
    Driver: MotionControl, 

Move the motor to the given position

Moves the motor to the given position (target_step), while respecting the maximum velocity (max_velocity). The specifics of the motion profile (like acceleration and jerk) are driver-defined.

It might be possible to influence the parameters of the motion profile through the resources passed to Stepper::enable_motion_control, which might include configuration.

To modify on ongoing movement, you can drop the future returned by this method and call it again with different parameters (or call another method).

You might need to call Stepper::enable_motion_control to make this method available.

pub fn reset_position(
    &mut self,
    step: i32
) -> Result<(), <Driver as MotionControl>::Error> where
    Driver: MotionControl, 

Reset the position to the given value

This should never result in a movement, as this method only overwrites the internal position counter of the driver. However, it might influence an already ongoing movement.

You might need to call Stepper::enable_motion_control to make this method available.