ESP32 Pendulum Assist Controller

Firmware for ESP32-based pendulum assist controllers that drive a stepper-based crank mechanism.

The project uses:

• FastAccelStepper for motion control
• PlatformIO with the Arduino framework
• Ethernet plus a built-in Wi-Fi access point on WT32-ETH01
• A built-in Wi-Fi access point on YD-ESP32-23 / ESP32-S3-N16R8
• Serial logging at 115200

Overview

The controller does the following:

• Homes the crankshaft on startup using a single 0° sensor
• Watches a left-side pendulum sensor and estimates swing timing
• Detects when swing energy is too low or pulses disappear
• Schedules a full 360° assist move aligned to the predicted pendulum phase
• Exposes live state, logs, and runtime tuning through a web interface

Hardware

Target board

• WT32-ETH01
• YD-ESP32-23 with ESP32-S3-N16R8

Stepper pins

• WT32-ETH01
  • STEP: GPIO33
  • DIR: GPIO5
  • ENABLE: GPIO17
• YD-ESP32-23
  • STEP: GPIO4
  • DIR: GPIO5
  • ENABLE: GPIO6
• ENABLE active low: true

Sensor pins

• WT32-ETH01
  • Pendulum sensor: GPIO14
  • Home sensor: GPIO4
• YD-ESP32-23
  • Pendulum sensor: GPIO7
  • Home sensor: GPIO15

Expected pendulum sensor

The current firmware is written for a digital hall sensor such as:

• A3144

Important:

• The analog 49E is not supported by this firmware as-is.
• On classic ESP32, the practical analog pins available here are tied to ADC2, which conflicts with Wi-Fi use. Since this project runs its own Wi-Fi AP, the digital hall path is the intended setup.

Electrical cautions

• GPIO4 and GPIO5 are ESP32 strapping pins.
• External hardware must not force invalid levels on these pins during reset, or the board may fail to boot.
• Sensor polarity is configurable in the web UI and stored in NVS.
• The WT32-ETH01 pin map is only valid on a plain WT32-ETH01 carrier. Some custom carrier boards repurpose GPIO4 / GPIO14.
• YD-ESP32-23 does not provide the onboard Ethernet path used by WT32-ETH01.

Startup Behavior

On boot the firmware:

1. Starts serial logging
2. Loads persisted settings from NVS
3. Initializes the stepper driver
4. Starts networking for the selected board
5. Starts the web server
6. Homes the crankshaft using the home sensor
7. Waits for repeated pendulum motion to lock onto timing

Network Access

The firmware exposes the web UI over:

• WT32-ETH01: Ethernet via DHCP and the board's own Wi-Fi AP
• YD-ESP32-23: the board's own Wi-Fi AP only

Default AP settings

• SSID: PendulumAssist
• Password: pendulum123

The AP IP is normally:

• 192.168.4.1

The Ethernet hostname on WT32-ETH01 is:

• pendulum-assist

Web Interface

The web UI provides:

• Live controller state
• Estimated swing period and left-side window time
• Motor position and move telemetry
• Command buttons for Home, Force Assist, and Stop Motion
• Runtime configuration for assist direction, homing direction, sensor polarity, debounce, timing thresholds, and motion limits
• Recent debug log output

Configuration changes made in the web UI are persisted to NVS.

Build Requirements

Install:

• PlatformIO Core or PlatformIO IDE

This project currently uses the environments defined in platformio.ini:

• wt32-eth01
• wt32-eth01-sensor-test
• yd-esp32-23
• yd-esp32-23-sensor-test
• framework: arduino

Build

From the project root:

pio run -e wt32-eth01

To build the YD-ESP32-23 firmware:

pio run -e yd-esp32-23

To build the dedicated manual sensor test firmware:

pio run -e wt32-eth01-sensor-test
pio run -e yd-esp32-23-sensor-test

Upload

Connect the selected board over USB/serial and run:

pio run -e wt32-eth01 -t upload

For YD-ESP32-23:

pio run -e yd-esp32-23 -t upload

To upload the dedicated sensor test firmware:

pio run -e wt32-eth01-sensor-test -t upload
pio run -e yd-esp32-23-sensor-test -t upload

If needed, specify the port explicitly:

pio run -e <environment> -t upload --upload-port <PORT>

Serial Monitor

Open the serial monitor with:

pio device monitor

The project is configured for:

• baud rate: 115200

For the sensor test firmware, a typical session is:

pio run -e wt32-eth01-sensor-test -t upload
pio device monitor -b 115200

For YD-ESP32-23, use the corresponding environment:

pio run -e yd-esp32-23-sensor-test -t upload
pio device monitor -b 115200

First Bring-Up Checklist

1. Verify the stepper driver wiring matches the configured pins.
2. Verify the home sensor really marks mechanical 0°.
3. Confirm the pendulum sensor is a digital hall sensor and wired to the correct board pin.
4. Power the board and open the serial monitor.
5. Open the web UI over Ethernet or http://192.168.4.1 on WT32-ETH01, or over http://192.168.4.1 on YD-ESP32-23.
6. Confirm homing succeeds.
7. If homing moves the wrong way, change Home Search Direction in the UI.
8. If the assist moves the wrong direction, change Assist Direction in the UI.
9. Tune Weak Window, Missed Pulse Slack, and the assist speed/acceleration limits conservatively on the bench first.

Manual Sensor Test Firmware

A dedicated firmware image is available for manual bench testing of the inputs.

Purpose:

• Wait for you to trigger the sensors by hand
• Print ACTIVE / INACTIVE transitions over serial
• Count changes for each input
• Mark the mandatory inputs as passed once each has been seen in both states

Inputs observed:

• WT32-ETH01
  • Pendulum sensor on GPIO14
  • Home sensor on GPIO4
  • Optional auxiliary input on GPIO12
• YD-ESP32-23
  • Pendulum sensor on GPIO7
  • Home sensor on GPIO15
  • Optional auxiliary input on GPIO12

Behavior:

• Pendulum and home inputs are configured as INPUT_PULLUP and treated as active-low
• GPIO12 is monitored as an optional raw input
• The test prints a periodic status summary and a final SENSOR TEST PASS message when both mandatory inputs have toggled active and inactive

Use it like this:

pio run -e wt32-eth01-sensor-test -t upload
pio device monitor -b 115200

Or for YD-ESP32-23:

pio run -e yd-esp32-23-sensor-test -t upload
pio device monitor -b 115200

Then:

1. Trigger and release the pendulum sensor by hand.
2. Trigger and release the home sensor by hand.
3. Optionally toggle GPIO12.

Motion and Control Notes

• The home sensor provides one absolute reference at 0°.
• A full assist move is one full revolution: 400 steps per assist cycle by default.
• The controller estimates swing timing from repeated pendulum sensor passes.
• A short left-side window or a missing expected pulse can trigger a scheduled assist.

Important Runtime Parameters

These are adjustable in the web UI:

• Assist Direction
• Home Search Direction
• Pendulum Sensor Polarity
• Home Sensor Polarity
• Auto Assist
• Debounce
• Lock Cycles
• Period Min / Max
• Weak Window
• Missed Pulse Slack
• Schedule Guard
• Assist Acceleration
• Assist Max Speed
• Home Speed / Creep / Acceleration

Project Structure

• src/main.cpp: minimal entry point
• src/PendulumApplication.cpp: top-level app wiring
• src/PendulumController.cpp: motion, homing, pulse tracking, assist scheduling
• src/WebInterface.cpp: HTTP API, AP/Ethernet startup, route handling
• src/WebUiPage.cpp: embedded dashboard page
• src/Logger.cpp: in-memory log buffer and JSON export
• include/AppTypes.h: shared types and defaults

Known Limitations

• The firmware compiles successfully, but it has not been hardware-validated in this repository.
• Analog hall support for 49E is not implemented.
• The control model assumes pendulum timing is stable enough to predict the assist phase from recent pulses.
• Missed steps are not actively detected; homing is the absolute reference.
• YD-ESP32-23 support is Wi-Fi AP only. The firmware does not provide Ethernet on that board.

Recommended Next Steps

• Bench-test homing with the mechanism disconnected or unloaded if possible.
• Verify the sensor polarity and direction settings first.
• Capture real pendulum timing logs and retune the assist thresholds from observed data.
• Add fault handling for motor stalls or repeated homing failures if this moves toward production use.