# AGENTS.md

This file provides guidance to agents when working with code in this repository.

## Project Overview

PlatformIO project for ESP32 LOLIN32 Rev1 controlling **two BTS7960 dual H-bridge motor drivers** for a differential drive robot (12V DC).

## Build Commands

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

## Hardware-Specific Notes

- **Board**: ESP32 LOLIN32 Rev1 (use `lolin32` in platformio.ini)
- **Motor Drivers**: 2× BTS7960 dual H-bridge - shared enable pins, independent PWM and current sense
- **Motor 1**: RPWM=25, LPWM=26, R_IS=34, L_IS=35 (PWM channels 0,1)
- **Motor 2**: RPWM=32, LPWM=33, R_IS=36, L_IS=39 (PWM channels 2,3)
- **Shared enables**: R_EN=27, L_EN=14 (both drivers enable together)
- **Power**: 12V DC input to motor drivers - logic level is 3.3V compatible with ESP32
- **WiFi**: Connects to SSID 'tami' with static IP 10.81.2.185
- **Reference**: https://deepbluembedded.com/arduino-bts7960-dc-motor-driver/

## Non-Obvious Notes

- Use built-in `WebServer` library (NOT ESPAsyncWebServer - has enum compatibility issues with ESP32 Arduino 3.x)
- WebServer requires `handleClient()` call in loop() - unlike async version
- LEDC PWM at 20kHz reduces motor noise
- Enable pins (R_EN, L_EN) must be HIGH before PWM works - configured once by first motor init
- **BTS7960 is 3.3V compatible**: Inputs are TTL/CMOS compatible (VIL<0.8V, VIH>2.0V) - ESP32 GPIOs work directly without level shifters (per BTN7960 datasheet section 5.4.1)
- **MotorController is parameterized**: Instances `motor1` and `motor2` are created with `MotorPins` struct
- **Legacy compatibility**: `motor` macro aliases to `motor1`, legacy `/speed` and `/direction` endpoints map to motor1