Overpowered ESP32-S3 Maze Solver (V5.0 Meta)

A high-performance autonomous line-maze solver robot built for the IIT Bombay Techfest — Meshmerize competition. Powered by an ESP32-S3 dual-core SoC (Xtensa LX7 @ 240 MHz) running ESP-IDF FreeRTOS with continuous DMA ADC sensor acquisition, hardware pulse_cnt encoder feedback, cascaded PID velocity control, Left-Hand Rule exploration, BLE GATT telemetry (Nordic UART Service), and multi-pass path reduction for optimal high-speed runs.

---

📐 Repository Structure

MazeSolver/
├── .gitignore
├── platformio.ini              # PlatformIO environment configuration (ESP32-S3)
├── CMakeLists.txt              # Root ESP-IDF project CMake configuration
├── sdkconfig.defaults          # Default ESP32-S3 SDK configuration (BLE / Bluedroid)
├── README.md                   # Project documentation & reference
├── docs/                       # Specifications, architecture & reports
│   ├── hardware/
│   │   └── hardware_design_spec_v5.md  # Production V5.0 hardware & schematic spec
│   └── reports/
│       ├── v4_full_system_audit_report.md  # System verification & audit report
│       └── analysis_results.md             # Code analysis & check scan report
├── include/                    # Custom modular C headers
└── src/                        # Main firmware component
    ├── CMakeLists.txt          # Component CMake registration
    └── overpowered_maze_solver_v5_meta.c  # Production firmware (V5.0 Meta for ESP32-S3)

---

⚡ Key Hardware & Architectural Specifications

• MCU: ESP32-S3-WROOM-1-N8 (Dual-Core Xtensa LX7 @ 240 MHz, 8MB Flash)
• Sensing: 8-Channel QTR-8A Analog Reflectance Array routed to ADC1 (GPIO 1, 2, 4, 5, 6, 7, 8, 9; skipping GPIO 3 strapping pin) via Continuous DMA conversion @ 80 kHz.
• Odometry: Dual N20 Micro Metal Gearmotors with Quadrature Magnetic Encoders tied to Hardware Pulse Counter (pulse_cnt) Units.
• Motor Driver: TB6612FNG Dual H-Bridge with 20 kHz 10-bit PWM (LEDC_LOW_SPEED_MODE).
• Core Isolation:
  • Core 1: Real-time hard-deadline tasks (1 kHz control loop, cascaded PID, ADC sampling, junction state machine).
  • Core 0: Bluetooth Low Energy (BLE GATT NUS Server), Live PID parameter tuning, and background communications.
• Power Architecture: 2S LiPo (7.4 V nominal) with MP1584EN high-efficiency DC-DC buck converter (5.0 V logic rail) and star-grounded PGND/AGND routing.

---

🔌 Authoritative Pin Mapping

Subsystem / Peripheral	ESP32-S3 GPIO	ADC / Driver Resource	Description
Sensor S1 (QTR-8A)	GPIO 1	ADC1_CH0	ADC1 continuous DMA line sensor
Sensor S2 (QTR-8A)	GPIO 2	ADC1_CH1	ADC1 continuous DMA line sensor
Sensor S3 (QTR-8A)	GPIO 4	ADC1_CH3	ADC1 continuous DMA line sensor
Sensor S4 (QTR-8A)	GPIO 5	ADC1_CH4	ADC1 continuous DMA line sensor
Sensor S5 (QTR-8A)	GPIO 6	ADC1_CH5	ADC1 continuous DMA line sensor
Sensor S6 (QTR-8A)	GPIO 7	ADC1_CH6	ADC1 continuous DMA line sensor
Sensor S7 (QTR-8A)	GPIO 8	ADC1_CH7	ADC1 continuous DMA line sensor
Sensor S8 (QTR-8A)	GPIO 9	ADC1_CH8	ADC1 continuous DMA line sensor
Encoder Left (Ch A / B)	GPIO 38 / 39	pulse_cnt Unit 0	Hardware quadrature odometry
Encoder Right (Ch A / B)	GPIO 40 / 41	pulse_cnt Unit 1	Hardware quadrature odometry
Motor Left (PWM / IN1 / IN2)	GPIO 11 / 12 / 13	LEDC Ch 0 / GPIO	TB6612 PWMA, AIN1, AIN2
Motor Right (PWM / IN1 / IN2)	GPIO 14 / 15 / 16	LEDC Ch 1 / GPIO	TB6612 PWMB, BIN1, BIN2
TB6612 Standby (STBY)	GPIO 17	GPIO Out	Active-HIGH driver enable
End-Zone Finish LED	GPIO 18	GPIO Out	Mandatory Techfest $L=5\text{ pts}$ bonus signal
Start / Boot Pushbutton	GPIO 0	GPIO In (Pullup)	Active-LOW mission trigger

Note: GPIO 3 is deliberately unused as it serves as an ESP32-S3 boot strapping pin.

---

🛠️ Build & Flash Instructions

Prerequisites

• PlatformIO Core (CLI) or PlatformIO IDE for VS Code
• Espressif 32 platform package

1. Build Firmware

pio run

2. Flash to ESP32-S3

Connect your ESP32-S3 board via USB:

pio run -t upload

3. Open Serial Monitor

pio device monitor

---

📡 Bluetooth LE (BLE) Telemetry & Commands

Pair with BLE GATT device MazeBot_V5_Meta via Nordic UART Service (NUS) terminal apps (e.g., Serial Bluetooth Terminal, nRF Connect):

• Service UUID: 6E400001-B5A3-F393-E0A9-E50E24DCCA9E
• RX Char (Write): 6E400002-B5A3-F393-E0A9-E50E24DCCA9E
• TX Char (Notify): 6E400003-B5A3-F393-E0A9-E50E24DCCA9E

Command	Action
START	Trigger autonomous exploration run (MAZE_EXPLORE)
RUN	Trigger high-speed optimized maze solve (MAZE_SPEED_RUN)
STOP	Immediate motor emergency stop & state reset (MAZE_IDLE)
EXPLORE	Set exploration mode and reset path memory
INVERT	Toggle line inversion (white-on-dark vs dark-on-white)
P<float>	Update Position Loop Proportional Gain ($K_p$)
I<float>	Update Position Loop Integral Gain ($K_i$)
D<float>	Update Position Loop Derivative Gain ($K_d$)
VP<float>	Update Velocity Loop Proportional Gain ($K_{vp}$)
VI<float>	Update Velocity Loop Integral Gain ($K_{vi}$)
VD<float>	Update Velocity Loop Derivative Gain ($K_{vd}$)
V<float>	Set target exploration base speed
T<float>	Set target ticks per ms velocity
TS<float>	Set turn speed
A<float>	Set ticks per degree turn
AL<int>	Set intersection alignment ticks

---

📚 Documentation Reference

• Hardware Design Specification V5.0
• System Verification & Audit Report
• Codebase Scan & Implementation Analysis