Struct stepper::Stepper [−][src]
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>
[src]
pub fn from_driver(driver: Driver) -> Self
[src]
Create a new Stepper
instance from a driver
pub fn driver(&self) -> &Driver
[src]
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
[src]
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
[src]
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::WithStepModeControl as SetStepMode>::StepMode,
timer: &mut Timer
) -> Result<Stepper<Driver::WithStepModeControl>, SignalError<<Driver::WithStepModeControl as SetStepMode>::Error, <Timer::Time as TryFrom<Nanoseconds>>::Error, Timer::Error>> where
Driver: EnableStepModeControl<Resources>,
Timer: CountDown,
Timer::Time: TryFrom<Nanoseconds>,
[src]
self,
res: Resources,
initial: <Driver::WithStepModeControl as SetStepMode>::StepMode,
timer: &mut Timer
) -> Result<Stepper<Driver::WithStepModeControl>, SignalError<<Driver::WithStepModeControl as SetStepMode>::Error, <Timer::Time as TryFrom<Nanoseconds>>::Error, Timer::Error>> where
Driver: EnableStepModeControl<Resources>,
Timer: CountDown,
Timer::Time: TryFrom<Nanoseconds>,
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<'r, Timer>(
&'r mut self,
step_mode: Driver::StepMode,
timer: &'r mut Timer
) -> SetStepModeFuture<RefMut<'r, Driver>, RefMut<'r, Timer>> where
Driver: SetStepMode,
Timer: CountDown,
Timer::Time: TryFrom<Nanoseconds>,
[src]
&'r mut self,
step_mode: Driver::StepMode,
timer: &'r mut Timer
) -> SetStepModeFuture<RefMut<'r, Driver>, RefMut<'r, Timer>> where
Driver: SetStepMode,
Timer: CountDown,
Timer::Time: TryFrom<Nanoseconds>,
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::WithDirectionControl>, SignalError<<Driver::WithDirectionControl as SetDirection>::Error, <Timer::Time as TryFrom<Nanoseconds>>::Error, Timer::Error>> where
Driver: EnableDirectionControl<Resources>,
Timer: CountDown,
Timer::Time: TryFrom<Nanoseconds>,
[src]
self,
res: Resources,
initial: Direction,
timer: &mut Timer
) -> Result<Stepper<Driver::WithDirectionControl>, SignalError<<Driver::WithDirectionControl as SetDirection>::Error, <Timer::Time as TryFrom<Nanoseconds>>::Error, Timer::Error>> where
Driver: EnableDirectionControl<Resources>,
Timer: CountDown,
Timer::Time: TryFrom<Nanoseconds>,
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<'r, Timer>(
&'r mut self,
direction: Direction,
timer: &'r mut Timer
) -> SetDirectionFuture<RefMut<'r, Driver>, RefMut<'r, Timer>> where
Driver: SetDirection,
Timer: CountDown,
Timer::Time: TryFrom<Nanoseconds>,
[src]
&'r mut self,
direction: Direction,
timer: &'r mut Timer
) -> SetDirectionFuture<RefMut<'r, Driver>, RefMut<'r, Timer>> where
Driver: SetDirection,
Timer: CountDown,
Timer::Time: TryFrom<Nanoseconds>,
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::WithStepControl> where
Driver: EnableStepControl<Resources>,
[src]
self,
res: Resources
) -> Stepper<Driver::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<'r, Timer>(
&'r mut self,
timer: &'r mut Timer
) -> StepFuture<RefMut<'r, Driver>, RefMut<'r, Timer>> where
Driver: Step,
Timer: CountDown,
Timer::Time: TryFrom<Nanoseconds>,
[src]
&'r mut self,
timer: &'r mut Timer
) -> StepFuture<RefMut<'r, Driver>, RefMut<'r, Timer>> where
Driver: Step,
Timer: CountDown,
Timer::Time: TryFrom<Nanoseconds>,
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 where
Driver: Step,
[src]
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::WithMotionControl> where
Driver: EnableMotionControl<Resources>,
[src]
self,
res: Resources
) -> Stepper<Driver::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>(
&'r mut self,
max_velocity: Driver::Velocity,
target_step: i32
) -> MoveToFuture<RefMut<'r, Driver>> where
Driver: MotionControl,
[src]
&'r mut self,
max_velocity: Driver::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::Error> where
Driver: MotionControl,
[src]
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.
Auto Trait Implementations
impl<Driver> Send for Stepper<Driver> where
Driver: Send,
Driver: Send,
impl<Driver> Sync for Stepper<Driver> where
Driver: Sync,
Driver: Sync,
impl<Driver> Unpin for Stepper<Driver> where
Driver: Unpin,
Driver: Unpin,
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Az for T
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> CheckedAs for T
[src]
pub fn checked_as<Dst>(self) -> Option<Dst> where
T: CheckedCast<Dst>,
[src]
T: CheckedCast<Dst>,
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<Src, Dst> LosslessTryInto<Dst> for Src where
Dst: LosslessTryFrom<Src>,
[src]
Dst: LosslessTryFrom<Src>,
pub fn lossless_try_into(self) -> Option<Dst>
[src]
impl<Src, Dst> LossyInto<Dst> for Src where
Dst: LossyFrom<Src>,
[src]
Dst: LossyFrom<Src>,
pub fn lossy_into(self) -> Dst
[src]
impl<T> OverflowingAs for T
[src]
pub fn overflowing_as<Dst>(self) -> (Dst, bool) where
T: OverflowingCast<Dst>,
[src]
T: OverflowingCast<Dst>,
impl<T> Same<T> for T
type Output = T
Should always be Self
impl<T> SaturatingAs for T
[src]
pub fn saturating_as<Dst>(self) -> Dst where
T: SaturatingCast<Dst>,
[src]
T: SaturatingCast<Dst>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> UnwrappedAs for T
[src]
pub fn unwrapped_as<Dst>(self) -> Dst where
T: UnwrappedCast<Dst>,
[src]
T: UnwrappedCast<Dst>,
impl<T> WrappingAs for T
[src]
pub fn wrapping_as<Dst>(self) -> Dst where
T: WrappingCast<Dst>,
[src]
T: WrappingCast<Dst>,