HelioDrive — Single Actuator

ESP32 firmware for controlling one BTS7960/IBT-2 linear actuator from a self-hosted mobile web page. Motion continues only while the operator holds a button, with an independent FreeRTOS watchdog providing automatic stop.

Available versions

Branch	Actuators	Control GPIO
main (this version)	1	25, 26
feature/dual-bts7960	2	25, 26, 32, 33
feature/quad-bts7960	4	25, 26, 32, 33, 18, 19, 21, 22

Wiring

ESP32	BTS7960
5V/VIN	VCC, R_EN, L_EN
GND	GND
GPIO25	RPWM
GPIO26	LPWM

Connect battery power only to B+ and B-, and connect the actuator to M+ and M-. Power the ESP32 separately over USB and share signal ground with the bridge. Never connect 12/24 V directly to an ESP32 power pin.

Use a fuse sized for the actuator and wiring. Software safety features do not replace a physical emergency power disconnect.

Wi-Fi and web control

Setting	Value
Network	HelioDrive-71A0
Demo password	12345678
Controller URL	http://192.168.4.1/

The demo password is public. For real use, copy include/secrets.example.h to include/secrets.h and choose a private password of at least eight characters. The private file is excluded from Git and overrides the built-in demo password.

Build and upload

Requires PlatformIO Core and an ESP32 connected as COM3:

py -m platformio run
py -m platformio run --target upload --upload-port COM3
py -m platformio device monitor --port COM3 --baud 115200

Disconnect B+ from the bridge before erasing or uploading firmware. For the first flash, erase the board before uploading:

py -m esptool --port COM3 erase-flash

HTTP API

• GET /api/state returns the commanded direction, reversal and watchdog state.
• POST /api/drive?direction=up|down&client=TOKEN starts motion or refreshes the command heartbeat.
• POST /api/stop stops the actuator unconditionally.

Only one browser owns motion control at a time. Any client may send STOP.

Safety behavior

• GPIO25 and GPIO26 are forced LOW before Wi-Fi starts.
• The browser sends a heartbeat every 150 ms while a button is held.
• Missing commands stop motion after 600 ms.
• Direction reversal inserts a 150 ms all-LOW dead time.
• The reported state is commanded state, not measured position.

With R_IS and L_IS disconnected, the ESP32 cannot detect actual position, skew or activation of an internal limit switch.

License

Released under the MIT License.