Stepper Motor

Overview

Stepper motor peripherals support 4-pin half-step/full-step drive modes, enabling precise control of speed and direction. Suitable for precision positioning, robotic arms, 3D printing, and other scenarios.

Supported Peripheral Types

Type	type Value	Description
STEPPER_MOTOR	42	Stepper motor (4-pin drive)

Hardware Wiring

ULN2003 Driver Board + 28BYJ-48 Stepper Motor

Driver Board Pin	ESP32 GPIO	Description
IN1	GPIO 32	Phase A
IN2	GPIO 33	Phase B
IN3	GPIO 25	Phase C
IN4	GPIO 26	Phase D
VCC	5V	Power supply (requires external power)
GND	GND	Ground

Stepper motors draw significant current; it is recommended to use an external 5V power supply, do not power directly from ESP32.

Configuration

Method 1: Web Interface Configuration (Recommended)

Before saving stepper motor configuration, verify driver board IN1-IN4 pin sequence, step count, and speed parameters.

Step 1: Navigate to Peripheral Management Page

1. Open a browser and navigate to the ESP32 IP address
2. After logging in, click Peripheral Configuration in the left menu

Step 2: Add Stepper Motor Peripheral

1. Click the Add Peripheral button

2. Fill in the configuration:

   Field	Value	Description
   Peripheral ID	stepper1	Unique identifier
   Name	28BYJ-48 Stepper Motor	Display name
   Peripheral Type	Stepper Motor (type: 42)	4-pin drive
   Pin Configuration	32,33,25,26	IN1-IN4 corresponding GPIOs
   Steps Per Revolution	2048	28BYJ-48 half-step mode
   Speed	10	RPM (recommend ≤15)
   Half-Step Drive	true	Half-step = smoother

3. Click Save

Step 3: Verify Configuration

1. Find the newly added peripheral in the peripheral list
2. Click the Enable toggle
3. Use the control panel to test rotation (input step count)

⚠️ Important: Stepper motor requires external 5V power supply; pin sequence must correspond to IN1-IN4

---

Method 2: JSON Configuration File Import

Add the following configuration to the peripherals array in data/config/peripherals.json:

{
  "id": "stepper1",
  "name": "Stepper Motor",
  "type": 42,
  "enabled": false,
  "pins": [32, 33, 25, 26],
  "params": {
    "stepsPerRevolution": 2048,
    "speed": 10,
    "halfStep": true
  }
}

Parameter Description

Parameter	Description
stepsPerRevolution	Steps per revolution (2048 for 28BYJ-48 half-step mode)
speed	Speed (RPM)
halfStep	Whether to use half-step drive (true=half-step, false=full-step)

pins[0]-pins[3] correspond to driver board IN1-IN4 respectively

Control Commands

Send control commands via MQTT or Web interface:

[{"id": "stepper1", "value": "2048"}]

• Positive value: Forward rotation for specified steps
• Negative value: Reverse rotation for specified steps
• 0: Stop

Peripheral Execution Integration

Web Interface Configuration Steps

Create Stepper Motor Control Rule

1. Switch to the Peripheral Execution Management tab
2. Click the Add Rule button
3. Configure trigger (timer trigger or event trigger)
4. Add stepper motor action:
   • Action Type: Set PWM (stepper motor uses step count control)
   • Target Peripheral: stepper1
   • Action Value: 2048 (one full forward revolution) or -2048 (one full reverse revolution)
5. Click Save

💡 Tip: Positive=forward, negative=reverse, 0=stop

---

JSON Configuration Example

Timed Rotation

{
  "name": "Timed Rotation Stepper Motor",
  "enabled": true,
  "triggers": [
    {
      "type": "timer",
      "params": { "interval": 5000 }
    }
  ],
  "actions": [
    {
      "type": "gpio_write",
      "params": {
        "periphId": "stepper1",
        "value": "512"
      }
    }
  ]
}

Button Triggered Rotation

{
  "name": "Button Control Stepper Motor",
  "enabled": true,
  "triggers": [
    {
      "type": "event",
      "params": { "periphId": "btn1", "event": "pressed" }
    }
  ],
  "actions": [
    {
      "type": "gpio_write",
      "params": {
        "periphId": "stepper1",
        "value": "2048"
      }
    }
  ]
}

Notes

1. Power Requirements: Stepper motor requires independent 5V power supply; never power directly from ESP32 USB port
2. Heat Issues: Prolonged locking (maintaining power) will cause driver board and motor to heat up; recommend powering off when not in use
3. Step Accuracy: 28BYJ-48 gear ratio is 1:64, actual steps per revolution is approximately 2048 (half-step mode)
4. Speed Limit: Too high speed will cause step loss; recommend RPM ≤ 15
5. Pin Sequence: 4 pin sequence must correspond to driver board IN1-IN4; reversed connection will cause motor to vibrate without rotating