---
title: StepperController Component
description: A component for controlling stepper motors with AccelStepper library
keywords: [stepper, motor, controller, modbus, hardware]
---

# StepperController

**Path**: [`src/components/StepperController.h`](../src/components/StepperController.h)

**Revision History**: Initial documentation

The StepperController component provides an interface for controlling stepper motors using the AccelStepper library. It supports configuration of motor parameters such as speed, direction, and pulse width, and integrates with the Modbus system for remote control capabilities. The component monitors motor status including overload conditions.

## Requirements

### Hardware
- Direction pin (GPIO)
- Pulse pin (GPIO)
- Feedback pin (analog input, optional)
- Overload pin (analog input, optional)

### Software
- AccelStepper library
- Arduino framework

## Features

- Configurable motor direction and rotation speed
- Adjustable pulse width for motor stepping
- Modbus integration for remote control
- Motor status monitoring (running, idle, overload, error)
- Overload detection using analog feedback
- Speed clamping to prevent damage

## Dependencies

- [Component](../src/Component.h) - Base component class
- [ModbusValue](../src/ModbusValue.h) - Modbus interface
- [AccelStepper](https://www.airspayce.com/mikem/arduino/AccelStepper/) - Stepper motor control library

```mermaid
graph TD
    StepperController --> Component
    StepperController --> ModbusValue
    StepperController --> AccelStepper
```

## Behaviour

The StepperController continuously updates the motor based on either local settings or values received via Modbus. It monitors for overload conditions and updates the motor status accordingly.

```mermaid
stateDiagram-v2
    [*] --> IDLE
    IDLE --> RUNNING: Speed > 0
    RUNNING --> IDLE: Speed = 0
    RUNNING --> OVERLOAD: Analog reading > threshold
    OVERLOAD --> RUNNING: Analog reading < threshold
    RUNNING --> ERROR: Hardware failure
    ERROR --> IDLE: Reset
```

## TODOs

### Performance

- Consider implementing acceleration and deceleration profiles for smoother motor operation
- Evaluate interrupt-based stepping for more precise timing
- Optimize speed scaling for different motor types

### Security

- Implement limits on maximum speed and acceleration to prevent mechanical damage
- Add authentication for modbus commands that control the motor
- Consider adding emergency stop functionality

### Compliance

- Verify compatibility with industrial motor control standards
- Ensure proper error handling meets safety requirements
- Document power requirements and limitations

### Recommendations

- Use external motor drivers with proper current limiting for larger motors
- Implement soft limits and homing procedures for positioning applications
- Add physical endstops for critical applications
- Consider adding encoder feedback for closed-loop operation

## Example

Below is an example of how to instantiate and configure a StepperController:

```cpp
#ifdef ENABLE_STEPPER_0
  // Create stepper controller instance
  stepperController_0 = new StepperController(
      this,                        // owner
      PIN_STEPPER_0_DIR,           // dirPin
      PIN_STEPPER_0_PULSE,         // pulsePin
      PIN_STEPPER_0_FEEDBACK,      // feedbackPin
      PIN_STEPPER_0_OVERLOAD,      // overloadPin
      STEPPER_0_ENABLED,           // enabled
      STEPPER_0_SPEED,             // speed
      STEPPER_0_PULSE_WIDTH,       // pulseWidth
      STEPPER_0_DIR,               // dir
      COMPONENT_KEY_STEPPER_0,     // id
      MB_RW_STEPPER_0_START        // addressStart
  );
  
  if (stepperController_0)
  {
    components.push_back(stepperController_0);
    Log.infoln(F("StepperController_0 initialized. Dir:%d, Pulse:%d, Speed:%d"),
              PIN_STEPPER_0_DIR, PIN_STEPPER_0_PULSE, STEPPER_0_SPEED);
  }
  else
  {
    Log.errorln(F("StepperController_0 initialization failed."));
  }
#endif
```

### References

${DOXYGEN_PLACEHOLDER}

${VENDOR_PLACEHOLDER}