ESP32 VESC Controller

Hiking Trailer

A motorised hiking trailer that follows its handle. You walk; the trailer pushes itself. A spring-centred potentiometer in the handle measures how hard you pull or push, and an ESP32-S3 controller turns that into a speed (or torque) command for a VESC motor controller over CAN. The trailer watches its own orientation with an IMU and cuts the motor if it tips over, shows live status on a small touchscreen, and hosts its own WiFi dashboard for telemetry, tuning and calibration — no app, no internet, no reflashing to change settings.

by Jawed Hakimi

Contents

• How it works
• Features
• Repository layout
• Hardware
• Software
• Getting started
• Safety
• Project status

How it works

   handle pot ──► ADS1115 ──I2C──┐
                                 │
   ICM-20948 IMU ──────SPI───────┤        ┌──────────────┐   CAN    ┌──────┐
   touch LCD (ST7789+CST816S) ───┼─► ESP32-S3 controller ─┼─TJA1051─► VESC ├─► hub motor
   buzzer / LEDs / VBAT divider ─┘        └──────┬───────┘          └──────┘
                                                 │ WiFi AP
                                           phone / laptop
                                       (web dashboard, 192.168.4.1)

1. Handle → command. The pot sits at centre when nobody touches the handle. Its position (after calibration, filtering and a dead-band) maps to a forward/backward ERPM (Speed mode) or motor current (Current mode), with separate forward/backward limits set in km/h or ERPM.
2. Optional speed PID. In Speed mode a closed-loop trim compares the requested ERPM with the VESC's measured ERPM and corrects for slopes and load.
3. Safety gating. Before anything is sent, the command is forced to zero on a fall, an invalid/missing pot signal, calibration, a direction change, park, or motor power off. After any interruption the motor only resumes once the handle is back at centre and a warning beep sequence has played.
4. CAN to the VESC. The command is sent at a fixed rate, so the VESC's own timeout stops the motor if the controller ever dies. The VESC's status broadcasts come back over CAN for speed, current, temperatures, battery and distance.
5. Feedback to the user. The touchscreen and the web dashboard both show speed, battery, trip, heading and every active error or warning.

Features

Drive

• Pot-follow control in Speed (RPM) or Current (torque) mode
• Separate forward / backward limits, optional reverse disable
• Optional closed-loop speed PID trim
• Downhill braking (VESC current brake) when the trailer runs faster than requested
• Park — holds the wheel with the VESC handbrake
• Motor-power enable switch (web + touchscreen); off at every boot

Safety

• Fall detection with the ICM-20948: tilt past a threshold or an impact spike stops the motor; two-stage automatic recovery (upright, then handle centred + beeps)
• Rising-pitch buzzer warning as the tilt approaches the fall angle
• Fault detection for a missing pot ADC, disconnected pot, CAN failure, silent VESC, missing IMU, over-temperature, and more — shown on both displays, error LED blinks
• Time-bounded sensor reads so a dropped I2C device can't freeze the control loop

Touchscreen (1.69", 280×240)

• Speed arc, battery voltage, trip distance, compass heading, live pot position
• WiFi name/password/address
• Pop-up warning panel listing all active issues

Web dashboard (WiFi AP Hiking-trailer, http://192.168.4.1/ or http://hiking-trailer.local/)

• Speed gauge with actual vs requested speed, drive command, battery, currents, energy, temperatures, orientation
• Error window with every active error/warning and what to check
• CAN Monitor — live per-ID frame table with decoded VESC status values
• Pot calibration wizard, IMU upright-zero + magnetometer calibration, fall-threshold tuning
• Speed PID tuning with a live target-vs-actual chart
• System settings: controller ID, CAN baud, pole pairs, wheel, gear ratio, battery source + calibration, WiFi credentials, restart / factory reset — all saved to flash, no reflashing

Repository layout

Hardware

Custom 4-layer PCB, 82.65 × 47.63 mm, 4 × M2.5 mounting holes (75 × 40 mm).

Power comes in on J2 (+48 V nominal, max ≈ 80 V) or USB-C for programming.

Main pins: CAN TX/RX = IO17/IO18 · I2C (ADS1115) SDA/SCL = IO7/IO6 · IMU CS/SCK/MOSI/MISO = IO8/IO12/IO11/IO13 (SPI bus shared with the LCD, LCD CS = IO10) · touch I2C SDA/SCL = IO47/IO48 · buzzer IO39 · VBAT IO4. Full tables: firmware README and hardware template.

Software

• Framework: Arduino on ESP-IDF 5 via the pioarduino PlatformIO platform (Arduino-ESP32 core 3.x is required by the display library).
• Libraries: LVGL 8 + GFX Library for Arduino (display), ESPAsyncWebServer/AsyncTCP, ArduinoJson 7, Adafruit ADS1X15, SparkFun ICM-20948.
• Two flash images: the firmware, and the web dashboard (data/) on LittleFS.
• Settings live in NVS flash and are edited from the dashboard; include/config.h only holds pins and first-boot defaults.

Getting started

1. Install PlatformIO (VS Code extension).
2. Open SW/VESC CAN interface/ as a PlatformIO project.
3. In VESC Tool: set up and detect the motor, set CAN ID / baud, enable CAN status messages 1, 4 and 5, set a sensible timeout and current/ERPM limits (details in the firmware README).
4. Flash both images:

   pio run --target upload     # firmware
   pio run --target uploadfs   # web dashboard

5. Connect to WiFi Hiking-trailer (password trailerhiking), open http://192.168.4.1/, and change the password on the System tab.
6. With the wheel off the ground: calibrate the pot (Pot Calibration tab), set the IMU upright zero (IMU tab), enter pole pairs / wheel diameter / gear ratio (System tab), then enable motor power and test.

Safety

This is a home-built motorised vehicle that moves on its own. The firmware's fail-safes are a backstop, not a guarantee:

• Test with the wheel off the ground first, and again after every change.
• Fit a physical emergency power cut-off for the VESC, independent of this controller.
• Set conservative current/ERPM limits in the VESC itself — they apply whatever the controller sends.
• Fall-detection thresholds are untuned defaults; verify them by hand before relying on them.
• Change the default WiFi password.

Project status

Work in progress. Working: CAN control of the VESC, pot calibration, web dashboard, IMU, touchscreen. Still to verify on the real trailer: fall thresholds, the new fault detection, the touchscreen layout, and real wheel diameter / gear ratio. Ideas for later: live requested-vs-actual speed chart and data logging, hill hold, battery range estimate, GPS, lights.