ESP32 Obstacle-Avoiding Car: a robot that dodges things on its own

/*
 * TinyBot Forge — ESP32 Obstacle-Avoiding Car
 * https://tinybotforge.com/en/
 *
 * Hardware: ESP32 DevKit V1, HC-SR04 ultrasonic sensor, L298N motor driver, two TT DC motors
 * Toolchain: Arduino IDE 2.x + ESP32 board package 3.x (uses the new ledcAttach / ledcWrite API)
 *
 * WARNING: the HC-SR04 ECHO pin outputs 5 V, but ESP32 pins are 3.3 V only.
 *          Route ECHO through a 1 kΩ + 2 kΩ voltage divider before GPIO 19.
 */

// ---------- Pins ----------
const int PIN_TRIG = 18;   // HC-SR04 TRIG
const int PIN_ECHO = 19;   // HC-SR04 ECHO (through the divider)

const int PIN_ENA = 25;    // left motor speed (PWM)
const int PIN_IN1 = 26;    // left motor direction
const int PIN_IN2 = 27;
const int PIN_ENB = 33;    // right motor speed (PWM)
const int PIN_IN3 = 32;    // right motor direction
const int PIN_IN4 = 13;

// ---------- Tuning ----------
const int PWM_FREQ = 1000;      // 1 kHz PWM
const int PWM_BITS = 8;         // 8-bit resolution -> speed 0-255
const int SPEED_CRUISE = 170;   // straight-line speed
const int SPEED_TURN   = 160;   // turning speed
const float STOP_CM    = 20.0;  // avoid anything closer than this
const unsigned long BACK_MS = 350;  // how long to reverse
const unsigned long TURN_MS = 450;  // how long to turn

// ---------- Motors ----------
// speed: -255 (full reverse) to 255 (full forward)
void setMotor(int pinEn, int pinA, int pinB, int speed) {
  speed = constrain(speed, -255, 255);
  digitalWrite(pinA, speed > 0 ? HIGH : LOW);
  digitalWrite(pinB, speed < 0 ? HIGH : LOW);
  ledcWrite(pinEn, abs(speed));
}

void drive(int left, int right) {
  setMotor(PIN_ENA, PIN_IN1, PIN_IN2, left);
  setMotor(PIN_ENB, PIN_IN3, PIN_IN4, right);
}

void stopCar() { drive(0, 0); }

// ---------- Ultrasonic distance ----------
// Returns centimetres; 999 if nothing is in range
float readOnceCm() {
  digitalWrite(PIN_TRIG, LOW);
  delayMicroseconds(2);
  digitalWrite(PIN_TRIG, HIGH);
  delayMicroseconds(10);
  digitalWrite(PIN_TRIG, LOW);
  unsigned long us = pulseIn(PIN_ECHO, HIGH, 25000UL);  // 25 ms ≈ 4 m
  if (us == 0) return 999.0;
  return us / 58.0;  // speed of sound: ~58 µs per cm, round trip
}

// Take three readings and keep the median to reject glitches
float readDistanceCm() {
  float a = readOnceCm(); delay(10);
  float b = readOnceCm(); delay(10);
  float c = readOnceCm();
  if (a > b) { float t = a; a = b; b = t; }
  if (b > c) { float t = b; b = c; c = t; }
  if (a > b) { float t = a; a = b; b = t; }
  return b;
}

// ---------- Avoidance ----------
void avoid() {
  stopCar();
  delay(100);
  drive(-SPEED_CRUISE, -SPEED_CRUISE);   // back up
  delay(BACK_MS);

  drive(SPEED_TURN, -SPEED_TURN);        // try turning right first
  delay(TURN_MS);
  stopCar();
  delay(80);
  if (readDistanceCm() > STOP_CM * 1.5) return;

  drive(-SPEED_TURN, SPEED_TURN);        // right is blocked too: turn left for twice as long
  delay(TURN_MS * 2);
  stopCar();
  delay(80);
}

void setup() {
  Serial.begin(115200);

  pinMode(PIN_TRIG, OUTPUT);
  pinMode(PIN_ECHO, INPUT);
  pinMode(PIN_IN1, OUTPUT);
  pinMode(PIN_IN2, OUTPUT);
  pinMode(PIN_IN3, OUTPUT);
  pinMode(PIN_IN4, OUTPUT);

  ledcAttach(PIN_ENA, PWM_FREQ, PWM_BITS);
  ledcAttach(PIN_ENB, PWM_FREQ, PWM_BITS);

  stopCar();
  Serial.println("TinyBot obstacle car: starting in 2 seconds");
  delay(2000);
}

void loop() {
  float cm = readDistanceCm();
  Serial.printf("distance %.1f cm\n", cm);

  if (cm < STOP_CM) {
    avoid();
  } else {
    drive(SPEED_CRUISE, SPEED_CRUISE);
  }
  delay(40);
}