BTS7960 Motor Controller

ESP32-based DC motor controller with web interface, using BTS7960 dual H-bridge driver with current sensing and stall protection.

Features

• Web-based control panel with real-time current monitoring
• Forward/Reverse/Stop motor control with speed slider (20-100%)
• Current sensing on both H-bridge sides (R_IS and L_IS)
• Sample-based stall detection with automatic motor shutoff
• ADC offset calibration at startup for accurate current readings
• Stall warning displayed on web interface

Hardware

Components

Component	Model/Specification
Microcontroller	ESP32 LOLIN32 Rev1
Motor Driver	BTS7960 Dual H-Bridge Module
Power Supply	12V DC
Sense Resistors	2× 1kΩ (for current sensing)

BTS7960 Module Reference

• DeepBlue Embedded Guide
• BTN7960 Datasheet

Wiring

Motor Control Pins

BTS7960 Pin	ESP32 GPIO	Function
RPWM	GPIO25	Forward PWM
LPWM	GPIO26	Reverse PWM
R_EN	GPIO27	Right Enable
L_EN	GPIO14	Left Enable
VCC	3.3V	Logic Power
GND	GND	Ground

Current Sensing Circuit

The BTS7960 has IS (Current Sense) pins that output current proportional to motor load. A resistor converts this to voltage for ESP32 ADC.

BTS7960 Module                    ESP32
┌─────────────────┐              ┌──────┐
│                 │              │      │
│  R_IS (pin 7)  ─┼──────┬───────┤GPIO34│
│                 │      │       │      │
│                 │     [R1]     │      │
│                 │     1kΩ      │      │
│                 │      │       │      │
│  GND           ─┼──────┴───────┤GND   │
│                 │              │      │
│  L_IS (pin 8)  ─┼──────┬───────┤GPIO35│
│                 │      │       │      │
│                 │     [R2]     │      │
│                 │     1kΩ      │      │
│                 │      │       │      │
│  GND           ─┼──────┴───────┤GND   │
└─────────────────┘              └──────┘

Connection	Details
R_IS → GPIO34	Through 1kΩ resistor to GND
L_IS → GPIO35	Through 1kΩ resistor to GND

Note: GPIO34 and GPIO35 are input-only pins on ESP32, ideal for ADC readings.

Current Sensing Math

Parameter	Value	Formula
Sense Ratio	8500:1	I_sense = I_motor / 8500
Sense Resistor	1kΩ	V_sense = I_sense × R
At 4A motor current	0.47V	(4 / 8500) × 1000
Max readable current	28A	(3.3V × 8500) / 1000

Configuration

Key settings in include/config.h:

Setting	Default	Description
STALL_THRESHOLD	8.0A	Current threshold for stall detection
STALL_CONFIRM_SAMPLES	3	Number of consecutive samples to confirm stall (~300ms)
STALL_STABILIZE_MS	500ms	Ignore current spikes after direction change
PWM_FREQ	20kHz	PWM frequency (reduces motor noise)
MIN_PWM_PERCENT	20%	Minimum PWM when motor is running
CURRENT_LOG_INTERVAL_MS	100ms	Current sampling/logging interval
CURRENT_SENSING_ENABLED	true	Enable/disable in src/motor.cpp

Network

Setting	Value
WiFi SSID	tami
Static IP	10.81.2.185
HTTP Port	80

Build & Upload

pio run              # Build
pio run -t upload    # Build and upload
pio device monitor   # Serial monitor (115200 baud)

Web Interface

Access the control panel at http://10.81.2.185 (or the IP shown on serial monitor).

Features

• Current Display: Real-time left (L) and right (R) current readings in amps
• Direction Status: Shows FORWARD, REVERSE, or STOPPED
• Speed Slider: Adjustable from 20% to 100% (minimum PWM prevents motor stalling at low speeds)
• Stall Warning: Red banner appears when stall is detected

API Endpoints

Endpoint	Method	Parameters	Description
/	GET	-	Control panel HTML page
/status	GET	-	JSON: {speed, direction, currentR, currentL, stalled}
/speed	POST	value (0-100)	Set motor speed percentage
/direction	POST	value (-1, 0, 1)	Set direction (reverse/stop/forward)
/stop	POST	-	Emergency stop

Stall Protection

The stall detection uses a sample-based approach for reliability:

1. Threshold: Current above 8.0A indicates potential stall (based on observed ~2A running vs ~17A stalled)
2. Debounce: 3 consecutive samples above threshold confirms stall (~300ms at 100ms intervals)
3. Stabilization: Ignores current spikes for 500ms after direction changes

When stall is confirmed:

1. Motor stops immediately
2. Serial log: STALL PROTECTION: Stopping motor (current: X.XXA)
3. Web interface shows red "STALL DETECTED" warning

To resume operation, send a new direction command via the web interface.