Is A4988 Stepper Motor Driver Shield Compatible with Home Assistant (ESPHome)?
Electrical Specifications
Always confirm pin assignments against the manufacturer datasheet before wiring.
Compatibility Overview
Microstepping stepper motor driver for automated window blinds 3D printers and motorized camera sliders.
Wiring
Host connections for this device
Technical Specification Matrix
| Feature / Attribute | Specification / Status |
|---|---|
| Hardware Protocol | Step/Dir GPIO / 5V-12V |
| Bridge Required | NO |
| Border Router Needed | None |
| Hardware Capabilities & Peripherals | Stepper Position Speed (Steps/s) Direction Note: these entities come from the ESPHome configuration you flash — each one needs its matching component in that YAML before it appears. |
| Pairing Complexity | Intermediate |
| Factory Reset Instruction | Hold BOOT button for 3s. |
Wire, Flash, Adopt, Check
Wire it up
Follow the bus reference above. The host pins in the configuration are defaults — any free GPIO of the right kind will do, as long as the YAML names the pin you actually used.
Flash the configuration
Create a new device in the ESPHome dashboard (the Home Assistant add-on) and paste the configuration below into it, or save it as emb_esp32_stepper_a4988.yaml and run esphome run emb_esp32_stepper_a4988.yaml. The first flash goes over USB. If it is not detected, hold BOOT button for 3s to put it in download mode. Every update after that is over the air.
Adopt it in Home Assistant
Settings → Devices & Services. A node on the same network shows up as a discovered ESPHome device within a minute of joining Wi-Fi; choose Configure and enter the API encryption key from your secrets.yaml. If discovery does not find it, add the ESPHome integration by hand with the node's IP address.
Check it works
The entities on this page appear under the device in Home Assistant and update at the configured interval. The ESPHome log (Logs in the dashboard, or esphome logs) reports the setup of each component and any bus scan results at boot.
ESPHome Configuration
Starting configuration for A4988 Stepper Motor Driver Shield on ESP32. Untested on hardware — verify wiring and pins against your own board.
# ESPHome configuration for A4988 Stepper Motor Driver Shield
# Host: ESP32. Pin numbers below are host-side defaults — any free
# GPIO will do, and you should change them to match your own wiring.
esphome:
name: emb_esp32_stepper_a4988
friendly_name: "A4988 Stepper Motor Driver Shield"
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
api:
encryption:
key: !secret api_encryption_key
ota:
- platform: esphome
password: !secret ota_password
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
# Wire GPIO18 to the driver's SLEEP pin (it is active-low: high runs,
# low sleeps) and tie ENABLE to ground. Set the current-limit pot before
# the first move — the default on most boards will overheat a small motor.
stepper:
- platform: a4988
id: motor
step_pin: GPIO16
dir_pin: GPIO17
sleep_pin:
number: GPIO18
inverted: true
max_speed: 250 steps/s
acceleration: 500
deceleration: 500
# One revolution of a 200-step motor at full steps.
button:
- platform: template
name: "Turn One Revolution"
on_press:
then:
- stepper.set_target:
id: motor
target: !lambda 'return id(motor).current_position + 200;'
Before you flash:
the !secret values come from your
secrets.yaml, and the GPIO numbers are host-side
defaults rather than properties of this part — change them to match how you actually wired it.
Report a Pinout Error or Submit Tested Code Snippets
Found a pin mapping quirk or built a custom ESPHome YAML driver for A4988 Stepper Motor Driver Shield? Submit a pull request or report corrections to our index.