ESP32 Web Server: Control Stepper Motor (WebSocket)

In this guide you’ll learn how to create a web server with the ESP32 that displays a web page to control a stepper motor. The web page allows you to insert the number of steps and select clockwise or counterclockwise direction. Additionally, it also shows whether the motor is currently spinning or if it is stopped. The communication between the client and the server is achieved via WebSocket protocol. All clients are updated with the current motor state.
This tutorial is the second part of this article
ESP32 Web Server: Control Stepper Motor (HTML Form)
, but it can also be followed as a standalone tutorial.
To better understand how this project works, you can take a look at the following tutorials:
ESP32 with Stepper Motor (28BYJ-48 and ULN2003 Motor Driver)
ESP32 Web Server: Control Stepper Motor (HTML Form)
ESP32 WebSocket Server: Control Outputs (Arduino IDE)
Table of Contents
Prerequisites
Project Overview
Organizing your files:
HTML File
CSS File
JavaScript File
Arduino Sketch
Upload Code and Files
Demonstration
Prerequisites
Before proceeding with the tutorial, make sure you check the following prerequisites.
1) Parts Required
To follow this tutorial, you need the following parts:
28BYJ-48 Stepper Motor + ULN2003 Motor Driver
ESP32
(read
Best ESP32 Development Boards
)
Jumper Wires
5V Power Supply
You can use the preceding links or go directly to
MakerAdvisor.com/tools
to find all the parts for your projects at the best price!
2) Arduino IDE and ESP32 Boards Add-on
We’ll program the ESP32 using Arduino IDE. So, you must have the ESP32 add-on installed. Follow the next tutorial if you haven’t already:
Installing ESP32 Board in Arduino IDE (Windows, Mac OS X, Linux)
If you want to use VS Code with the PlatformIO extension, follow the next tutorial instead to learn how to program the ESP32:
Getting Started with VS Code and PlatformIO IDE for ESP32 and ESP8266 (Windows, Mac OS X, Linux Ubuntu)
3) Filesystem Uploader Plugin
To upload the HTML, CSS, and JavaScript files needed to build this project to the ESP32 filesystem (LittleFS), we’ll use a plugin for Arduino IDE:
LittleFS
Filesystem uploader
. Follow the next tutorial to install the filesystem uploader plugin if you haven’t already:
Arduino IDE 2: Install ESP32 LittleFS Uploader (Upload Files to the Filesystem)
If you’re using VS Code with the PlatformIO extension, read the following tutorial to learn how to upload files to the filesystem:
ESP32 with VS Code and PlatformIO: Upload Files to LittleFS Filesystem
4) Libraries
To build this project, you need to install the following libraries:
ESPAsyncWebServer
by ESP32Async
AsyncTCP
by ESP32Async
You can install these libraries in the Arduino Library Manager. Open the Library Manager by clicking the Library icon at the left sidebar.
ESPAsyncWebServer
and install the
ESPAsyncWebServer by ESP32Async
Then, install the AsyncTCP library. Search for
AsyncTCP
and install the
AsyncTCP by ESP32Async
5) Schematic Diagram
The following schematic diagram shows the connections between the stepper motor and the ESP32.
Note:
you should power the ULN2003APG motor driver using an external 5V power supply.
Motor Driver
ESP32
IN1
GPIO 19
IN2
GPIO 18
IN3
GPIO 5
IN4
GPIO 17
Project Overview
The following video shows a quick demonstration of what you’ll achieve by the end of this tutorial.
The following image shows the web page you’ll build for this project.
The web page shows a form where you can enter the number of steps you want the motor to move and select the direction: clockwise or counterclockwise.
It also shows the motor state:
motor spinning
or
motor stopped
. Additionally, there’s a gear icon that spins as long as the motor is spinning. The gear spins clockwise or counterclockwise accordingly to the chosen direction.
The server and the client communicate using WebSocket protocol.
When you click on the
GO!
button, it calls a Javascript function that sends a message via WebSocket protocol with all the information: steps and direction (
3
). The message is in the following format:
steps
&
direction
So, if you submit 2000 steps and clockwise direction, it will send the following message:
2000&CW
At the same time, it will change the motor state on the web page, and the gear will start spinning in the proper direction (
2
).
Then, the server receives the message (
4
) and spins the motor accordingly (
5
).
When the motor stops spinning (
6
), the ESP will send a message to the client(s), also via WebSocket protocol, informing that the motor has stopped (
7
).
The client(s) receive this message and update the motor state on the web page (
8
).
Organizing your Files
The files you want to upload to the ESP filesystem should be placed in a folder called
data
under the project folder. We’ll move three files to that folder:
index.html
to build the web page;
style.css
to style the web page;
script.js
to handle websocket communication and start/stop the gear animation.
You should save the HTML, CSS, and JavaScript files inside a folder called
data
inside the Arduino sketch folder, as shown in the previous diagram. We’ll upload those files to the ESP32 filesystem (LittleFS).
You can download all project files:
Download All the Arduino Project Files
HTML File
Create a file called
index.html
with the following content:
<!DOCTYPE html>
<html>
<head>
<title>Stepper Motor</title>
<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">
<link rel=\"stylesheet\" type=\"text/css\" href=\"style.css\">
<link rel=\"icon\" type=\"image/png\" href=\"favicon.png\">
<link rel=\"stylesheet\" href=\"https://use.fontawesome.com/releases/v5.7.2/css/all.css\" integrity=\"sha384-fnmOCqbTlWIlj8LyTjo7mOUStjsKC4pOpQbqyi7RrhN7udi9RwhKkMHpvLbHG9Sr\" crossorigin=\"anonymous\">
</head>
<body>
<div class=\"topnav\">
Stepper Motor Control <i class=\"fas fa-cogs\"></i></h1>
</div>
<div class=\"content\">
<form>
<input type=\"radio\" id=\"CW\" name=\"direction\" value=\"CW\" checked>
<label for=\"CW\">Clockwise</label>
<input type=\"radio\" id=\"CCW\" name=\"direction\" value=\"CCW\">
<label for=\"CW\">Counterclockwise</label>
<label for=\"steps\">Number of steps:</label>
<input type=\"number\" id=\"steps\" name=\"steps\">
</form>
<button onclick=\"submitForm()\">GO!</button>
Motor state: <span id=\"motor-state\">Stopped</span></p>
<i id=\"gear\" class=\"fas fa-cog\"></i> </p>

</div>
</body>
<script src=\"script.js\"></script>
</html>
This HTML file is very similar to the one used in the
previous tutorial
. You can
for a complete explanation of the HTML file.
We’ve added ids to the HTML elements we want to manipulate using JavaScript—the radio buttons and the input field:
clockwise radio button:
id=”CW”
counterclowise radio button:
id=”CCW”
steps input field:
id=”steps”
<input type=\"radio\" id=\"CW\" name=\"direction\" value=\"CW\" checked>
<label for=\"CW\">Clockwise</label>
<input type=\"radio\" id=\"CCW\" name=\"direction\" value=\"CCW\">
<label for=\"CW\">Counterclockwise</label>
<label for=\"steps\">Number of steps:</label>
<input type=\"number\" id=\"steps\" name=\"steps\">
We want to send the form results to the server (ESP32) via WebSocket protocol. So, we’ve added a button, that when clicked (
onclick
event) calls the
submitForm()
user-defined javascript function that sends the results to the server as you’ll see later in the
JavaScript section
<button onclick=\"submitForm()\">GO!</button>
Additionally, we also added a paragraph to display the motor state. We’ve added a

tag with the
motor-state
id so that we’re able to manipulate the text between the

tags using Javascript.
Motor state: <span id=\"motor-state\">Stopped</span></p>
Finally, there’s a paragraph displaying a gear with the
id=”gear”
. We need this id to make the gear move.
<i id=\"gear\" class=\"fas fa-cog\"></i> </p>
Don’t