Remote Motor Control — Build Tutorial

How It Works

A browser-based frontend connects over secure WebSockets to a relay server running on a publicly reachable Linux server — a VPS (Virtual Private Server) or a private machine with a public IP both work. The relay forwards commands to a Raspberry Pi, which translates them into a compact serial protocol and sends them to an Arduino over USB. The Arduino drives a stepper motor through a CL57T driver. The specific hardware used here was chosen for availability — the architecture itself is not tied to any of these particular components, and substitutions are straightforward if you understand what each piece is doing.

The split between the Pi and the Arduino is intentional and worth understanding before building. The Raspberry Pi's GPIO pins operate at 3.3 V, which is insufficient to directly drive the CL57T's optocoupler inputs in 5 V mode without additional circuitry (a level shifter or resistor network). The Arduino UNO R4, on the other hand, outputs 5 V logic and is dedicated entirely to generating precise step pulses — a timing-critical task. Attempts to have the Arduino also manage a WebSocket or network connection while pulsing were unsuccessful: being single-core, it could not reliably balance network handling with the microsecond-level pulse timing the driver requires. The Pi handles all networking; the Arduino handles all motor timing. Each does one job well.

Because server.js runs continuously and independently on the VPS, connections are fully asynchronous — the Pi and the browser UI connect and disconnect on their own schedules. This also means the design scales to multiple devices: each Raspberry Pi registers with a unique deviceId, and any browser UI can target any connected device by selecting that ID. Multiple UIs can monitor the same device simultaneously.

Figure 1 — Full system component overview

1 — Parts & Software You Need

The hardware listed below is what was used in this project. It is not the only combination that will work — if you have experience with similar components, feel free to substitute where it makes sense. The core requirements are: a microcontroller that can output step/direction pulses over a serial interface, a compatible stepper driver, and a Linux-capable SBC (single-board computer) with network access to act as the bridge. Specific substitution notes are included in each row.

Hardware

Software & Accounts

2 — Hardware Assembly & Wiring

Wiring: Arduino → CL57T Driver (Signal Lines)

The Arduino sends three logic-level signals to the CL57T driver. These are low-voltage (5 V) connections and are safe to wire while the Arduino is unpowered. Always complete signal wiring before applying motor supply power.

Figure 2 — Arduino pins 8 / 9 / 10 to CL57T PUL+ / DIR+ / ENA+ with shared GND

Wiring: CL57T Driver → NEMA 24 Motor

The motor connects to the CL57T via two separate cables: four phase wires (motor coils) and a six-wire encoder cable. The tables below show the most common wire color conventions used by NEMA closed-loop stepper manufacturers (STEPPERONLINE, RTELLIGENT, Leadshine, and most generic Chinese motors). Always verify against the datasheet or wiring diagram that shipped with your specific motor — colors can differ between manufacturers and even between production batches of the same model.

You will notice that some colors appear in both the phase and encoder tables (for example, red and green each show up in both). This is not a problem — the two cables are physically separate and terminate on completely different sets of driver terminals, so there is no ambiguity in practice. Treat each cable as its own independent group and wire them one at a time.

Motor Phase Wires (A+, A−, B+, B−)

If the motor runs in the wrong direction, swap A+ and A− (or reverse direction in the UI or code instead).

Encoder Cable (EA+, EA−, EB+, EB−, VCC, EGND)

Power Supply → CL57T (+VDC, GND)

Connect your DC power supply to the CL57T's power input terminals. The cables used in this project are: black for +VDC and green for GND.

Figure 3 — Motor phase wires and encoder cable connected to CL57T driver terminals

CL57T DIP Switch Settings

The CL57T's DIP switches set the signal input voltage mode, microstep resolution, and peak current. The configuration used in this project is:

Connecting Arduino to Raspberry Pi

Use a USB-C to USB-C cable to connect the Arduino UNO R4 WiFi to the Raspberry Pi 5 — both devices use USB-C. The Pi will appear to the Arduino as a serial host. On the Pi, the Arduino typically enumerates as /dev/ttyACM0 (confirm with ls /dev/ttyACM* after plugging in).

Figure 4 — Assembled hardware: Arduino, CL57T driver, and NEMA 24 motor

3 — Arduino Setup

1 Install the Arduino IDE and Board Package

Download and install the Arduino IDE 2.x. Open it, go to Tools → Board → Boards Manager and install the package for your board. If using the UNO R4 WiFi, search for "Arduino UNO R4".

2 Install the LED Matrix Library (UNO R4 WiFi only)

Go to Tools → Manage Libraries, search for Arduino_LED_Matrix, and install it. This library powers the built-in LED matrix on the UNO R4 WiFi, which the sketch uses to show motor state at a glance (enabled/disabled, direction, speed). It is a nice addition but not essential to the control pipeline — if you are using a different Arduino board, you can remove all LED matrix code from the sketch (#include "Arduino_LED_Matrix.h", the matrix object, and all updateMatrixFromState() calls) and the rest of the sketch will work unchanged.

3 Open and Configure the Sketch

Open a_DRIVER/a_DRIVER.ino from this repository. No WiFi credentials are needed — the Arduino communicates only over USB serial regardless of board. The pin assignments at the top of the sketch can be changed to match whatever pins you use on your board.

// Pin assignments — top of a_DRIVER.ino
const int stepPin      = 8;   // → CL57T PUL+
const int directionPin = 9;   // → CL57T DIR+
const int enaPin       = 10;  // → CL57T ENA+

4 Upload the Sketch

Connect the Arduino to your computer via USB. Select Tools → Board → Arduino UNO R4 WiFi and the correct port. Click Upload.

5 Verify via Serial Monitor

Open Tools → Serial Monitor at baud 115200. You should see the self-test messages, ending with:

Startup tests complete. Ready for USB commands.

You can test commands manually here before wiring up the Pi:

START 800      ← start motor at 800 µs interval (~1250 steps/sec)
STOP           ← stop motor
DIR 0          ← set direction CCW
DIR 1          ← set direction CW
ENA 0          ← disable driver
ENA 1          ← enable driver
SET_SPEED 400  ← change speed to 400 µs (~2500 steps/sec)

4 — Raspberry Pi Setup

A Raspberry Pi 5 connected over Wi-Fi was used in this project. The Pi runs pi_controller.js — a Node.js bridge that sits between the Arduino (USB serial) and the VPS (WebSocket). It also hosts a local control UI on port 3000. Ethernet works as a drop-in alternative to Wi-Fi. The steps below apply to any Pi model or Debian-based Linux SBC.

1 Install Node.js and Dependencies

SSH into your Pi and run:

sudo apt update
sudo apt-get install -y nodejs npm

Then navigate to the project directory and install the required packages:

cd /path/to/Capstone
npm install ws serialport express

2 Find the Arduino's Serial Port

Plug the Arduino into the Pi via USB, then run:

ls /dev/ttyACM*

It will typically appear as /dev/ttyACM0. If it shows a different number, note it for the next step.

3 Edit pi_controller.js

Open pi_controller.js and update the two constants at the top:

const DEVICE_ID   = "pi-motor-1";                          // must match what you use in the UI
const VPS_WS_URL  = "wss://your-domain.com/ws/?role=device&deviceId=" + DEVICE_ID;
const SERIAL_PORT = "/dev/ttyACM0";                        // adjust if different

4 Start the Bridge

node pi_controller.js

You should see:

Connecting to VPS: wss://your-domain.com/ws/?role=device&deviceId=pi-motor-1
Local control UI at http://localhost:3000

Once the VPS relay is running (Step 5), the Pi will also print Connected to VPS.

Local UI (Optional)

While on the same network as the Pi, you can open http://<pi-ip>:3000 in a browser to control the motor directly without going through the VPS. This is useful for testing before VPS setup is complete.

5 — Server Setup (Nginx, TLS, WebSocket Relay)

Your server — whether a VPS or a private machine — hosts the WebSocket relay (server.js) and the frontend UI (motor.html). It just needs to be running Linux with a public IP. Nginx acts as a reverse proxy, handles TLS termination, and enforces HTTPS.

1 Install Nginx and Node.js on the VPS

sudo apt update
sudo apt install -y nginx nodejs npm

2 Install the WebSocket Relay Dependencies

Copy server.js to your VPS (e.g., /opt/motor/server.js), then:

cd /opt/motor
npm install ws

3 Obtain a TLS Certificate with Certbot

A domain name was used here for convenience, but it is not strictly required. Certbot and Let's Encrypt do require a domain pointed at your VPS IP — if you have one, this is the easiest path:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

Certbot will modify your Nginx config automatically. The certificate auto-renews via a systemd timer or cron job.

4 Configure Nginx

Copy nginx_config.txt to /etc/nginx/sites-available/motor.conf and update server_name to your domain. Enable the site and reload:

sudo ln -s /etc/nginx/sites-available/motor.conf /etc/nginx/sites-enabled/
sudo nginx -t          # test config — must say "ok"
sudo systemctl reload nginx

Key sections of the Nginx config:

# Proxy WebSocket traffic to the Node relay
location /ws/ {
    proxy_pass http://127.0.0.1:4000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
}

# Protect the motor control UI with a password
location = /motor.html {
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.motor_passwd;
    root /var/www/html;
}

5 Create the Basic Auth Password (Optional but Recommended)

The Nginx config protects /motor.html with HTTP basic authentication. Create the password file:

sudo apt install -y apache2-utils
sudo htpasswd -c /etc/nginx/.motor_passwd your-username

You will be prompted to enter and confirm a password. Reload Nginx after.

6 Start the WebSocket Relay

node /opt/motor/server.js

You should see:

WebSocket server listening on 127.0.0.1:4000

Once running, server.js operates independently of the Pi and the browser. Devices and UIs connect and disconnect asynchronously — the relay just routes messages between them. This makes it easy to scale: add more Raspberry Pis by running pi_controller.js on each with a unique DEVICE_ID, and the relay will track them all simultaneously without any changes to the VPS.

6 — Deploy the Frontend UI

Copy motor.html from the repository to your VPS web root:

sudo cp motor.html /var/www/html/motor.html

The file is self-contained — no build step needed. It connects to the WebSocket relay at wss://your-domain.com/ws/ automatically using the page's own hostname.

Access it in a browser at: https://your-domain.com/motor.html

You will be prompted for the basic auth username and password you created in Step 5.

7 — Using the System

Startup Order

1. Power on the Raspberry Pi. Start pi_controller.js.
2. Ensure server.js is running on the VPS.
3. Power on the Arduino (USB from Pi is sufficient).
4. Power on the motor driver's DC supply last.
5. Open https://your-domain.com/motor.html in a browser.

The Browser UI

The UI connects to the relay automatically on page load. The status dot in the header shows:

• Green — WebSocket connected to VPS
• Orange — Connecting
• Red — Disconnected (check that server.js is running)

Controls

What a Successful Run Looks Like

Once everything is connected and running, open the UI and confirm the status dot is green. Click Start — the motor will begin spinning and, given the size of a NEMA 24, you will hear it clearly. The sound is a good immediate indicator: a steady hum or whir means the driver is receiving pulses correctly. From there, try adjusting the pulse interval and clicking Set speed — you should hear the motor speed up or slow down in response. Clicking CW / CCW reverses direction. The Latest State box at the bottom of the UI updates in real time to confirm what the Pi has applied.

Figure 5 — The browser UI (motor.html) connected and controlling the motor

Shutdown Order

1. Click Stop in the UI to disable the driver before cutting power.
2. Power off the motor driver's DC supply.
3. Stop the Pi bridge.
4. Stop the VPS relay process. (Optional)

Future Improvements

The current system is a working proof of concept. If the project grows, here are natural areas to build on:

• Proper authentication — HTTP basic auth is a minimal barrier. A token-based or session-based auth layer on the WebSocket relay would be more robust, especially if multiple users or devices are involved.
• Multi-device dashboard — the relay already supports multiple connected Pis, but the current UI targets one device at a time. A dashboard view showing all connected devices and their states simultaneously would make the many-to-many capability more practical.
• Persistent state and logging — the relay currently holds no state between connections. Adding a lightweight database or log would let you review command history, detect faults, or replay sequences.
• Different actuator types — the command scheme (START, STOP, DIR, ENA, SET_SPEED over serial) is simple enough to adapt to other hardware. Any microcontroller that can parse the same serial protocol could control a different motor, relay, or actuator through the same relay without changes to the VPS or Pi code.
• Closed-loop feedback to the UI — the encoder on the NEMA 24 is used by the CL57T internally, but encoder position data is not currently surfaced to the browser. Passing encoder counts back through the chain would enable position tracking in the UI.
• Systemd service hardening — running pi_controller.js and server.js as proper systemd services with restart policies, logging to journald, and watchdog timers would make the system more reliable for long-running or unattended use.

Contributing

All source code and documentation for this project is publicly available on GitHub. If you spot an error, have an improvement, or want to share a build variation, pull requests are welcome.

Repository: github.com/TWLG/Capstone

# Clone the repo
git clone https://github.com/TWLG/Capstone.git