---
title: "Stepper Controller"
description: "A component for controlling stepper motors with Modbus integration, direction control, and overload protection."
keywords: ["ESP-32", "stepper motor", "Modbus", "motor control", "industrial automation"]
---

## StepperController

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

**Revision History**: Initial documentation

StepperController is a component designed for precise control of stepper motors in industrial applications. It provides Modbus integration through ModbusValue, allowing remote control of motor speed and direction while monitoring status and overload conditions.

## REQUIREMENTS

- Hardware:
  - Direction pin (GPIO)
  - Pulse pin (GPIO)
  - Feedback pin (GPIO) for monitoring motor status
  - Overload pin (analog input) for detecting motor overload
  - Compatible stepper motor driver
- Software:
  - AccelStepper library
  - Modbus capabilities for remote control

## FEATURES

- Control stepper motor speed and direction via Modbus
- Pulse width configuration for different stepper driver requirements
- Overload detection for motor protection
- Status monitoring (running, idle, error states)
- Speed clamping for safety
- Bidirectional control
- Configurable motor parameters

## DEPENDENCIES

- [Arduino.h](https://github.com/arduino/ArduinoCore-avr/blob/master/cores/arduino/Arduino.h)
- [ArduinoLog.h](https://github.com/thijse/Arduino-Log)
- [osr-base.h](../src/osr-base.h)
- [App.h](../src/App.h)
- [Addon.h](../src/Addon.h)
- [Component.h](../src/Component.h)
- [ModbusValue.h](../src/ModbusValue.h)
- [types.h](../src/types.h)
- [AccelStepper.h](https://www.airspayce.com/mikem/arduino/AccelStepper/)
- [xmath.h](../src/xmath.h)
- [features.h](../src/features.h)
- [enums.h](../src/enums.h)
- [config.h](../src/config.h)

```mermaid
graph TD
  StepperController --> Component
  StepperController --> ModbusValue
  StepperController --> AccelStepper
  Component --> osrBase
  ModbusValue --> types
  StepperController --> xmath
```

## BEHAVIOUR

```mermaid
stateDiagram-v2
  [*] --> MOTOR_IDLE
  MOTOR_IDLE --> MOTOR_RUNNING: speed > 0
  MOTOR_RUNNING --> MOTOR_IDLE: speed = 0
  MOTOR_RUNNING --> MOTOR_OVERLOAD: isOverloaded() == true
  MOTOR_OVERLOAD --> MOTOR_RUNNING: isOverloaded() == false
  MOTOR_RUNNING --> MOTOR_ERROR: hardware failure
  MOTOR_ERROR --> MOTOR_IDLE: reset
  MOTOR_UNKNOWN --> [*]
```

## TODOS

### PERFORMANCE

- Add acceleration profiles for smoother movement
- Implement microstepping control for higher precision
- Optimize interrupt handling for more precise timing

### SECURITY

- Add parameter validation before applying motor settings
- Implement authentication for Modbus control commands
- Add motor limits based on system conditions

### COMPLIANCE

- Ensure compliance with motor manufacturer specifications
- Verify compatibility with industrial Modbus implementations
- Review power management for energy efficiency standards

### RECOMMENDATIONS

- Use shielded cables for motor connections to reduce EMI
- Configure appropriate current limits on the stepper driver
- Implement a soft start mechanism for heavy loads
- Add emergency stop functionality for safety-critical applications

## EXAMPLE

```cpp
#ifdef PIN_STEPPER_0
  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
      ID_STEPPER_0,             // id
      STEPPER_0_MB_ADDR         // addressStart
  );
  
  if (stepperController_0)
  {
    components.push_back(stepperController_0);
    Log.infoln(F("StepperController_0 initialized. Dir:%d, Pulse:%d, Speed:%d, ID:%d, MB:%d"),
               PIN_STEPPER_0_DIR, PIN_STEPPER_0_PULSE, STEPPER_0_SPEED,
               ID_STEPPER_0, STEPPER_0_MB_ADDR);
  }
  else
  {
    Log.errorln(F("StepperController_0 initialization failed."));
  }
#endif
```

### References