Tank

ESP32-S3 Robotics Controller PCB

Table of Contents

1. Board Gallery
2. System Architecture
3. Feature Overview
4. PCB Design
   • Layer Stackup
   • Signal Integrity
   • Key Components (BOM Summary)
5. GPIO Pin Reference
6. Peripheral Details
   • Motor Control — DRV8871
   • Servo Outputs
   • Ultrasonic Sensors — HC-SR04
   • Hall Effect Sensors
   • IMU — I2C
   • SPI Display
   • Push Buttons
   • Expansion Header
7. Firmware
   • Quick Start
   • Library Dependencies
   • Firmware Architecture
   • PWM Configuration
   • WiFi Access Point & Web Dashboard
   • BLE GATT Server
   • On-Device UI
     • Main Menu
     • Robot Modes
     • Games
8. Repository Structure
9. Hardware Files
10. Contributing
11. License

Board Gallery

PCB Layout (Top)	3D Render	PCB Back

System Architecture

The diagram below shows how all onboard subsystems connect to the ESP32-S3:

                        ┌─────────────────────────────────────┐
                        │           ESP32-S3-WROOM-1           │
                        │     240 MHz Xtensa LX7 Dual-Core     │
                        │     WiFi 802.11 b/g/n  •  BT 5.0    │
                        └───┬───┬───┬───┬───┬───┬───┬───┬─────┘
                            │   │   │   │   │   │   │   │
          ┌─────────────────┘   │   │   │   │   │   │   └──────────────────┐
          │ LEDC PWM            │   │   │   │   │   │ GPIO ISR             │
          ▼                     │   │   │   │   │   ▼                      │
 ┌─────────────────┐            │   │   │   │   │  ┌────────────────┐      │
 │   DRV8871 ×2    │            │   │   │   │   │  │  Hall Sensors  │      │
 │  DC Motor Ctrl  │            │   │   │   │   │  │   ×2 inputs    │      │
 │  (PWM IN1/IN2)  │            │   │   │   │   │  └────────────────┘      │
 └────────┬────────┘            │   │   │   │   │                          │
          │ VM (motor power)    │   │   │   │   │ INPUT_PULLUP             │
          ▼                     │   │   │   │   ▼                          │
    ┌───────────┐               │   │   │   │  ┌──────────────┐            │
    │  Motor ×2 │               │   │   │   │  │  Buttons ×2  │            │
    └───────────┘               │   │   │   │  └──────────────┘            │
                      PWM 50Hz  │   │   │   │                              │
                                ▼   │   │   │ SPI                          │
                       ┌────────────┐  │   ▼                               │
                       │  Servo 1   │  │  ┌──────────────────┐             │
                       └────────────┘  │  │   SPI Display    │             │

Feature Overview

PCB Design

Layer Stackup

The board uses a 4-layer stackup (1.6 mm total thickness) to provide dedicated power and ground planes, minimizing noise and improving signal integrity:

  ┌─────────────────────────────────────────────┐  ← Component side
  │  Layer 1 — F.Cu (Top)                        │  Signal routing + high-current motor traces
  ├─────────────────────────────────────────────┤
  │  Prepreg                                     │
  ├─────────────────────────────────────────────┤
  │  Layer 2 — In1.Cu                            │  Solid GND plane (unbroken)
  ├─────────────────────────────────────────────┤
  │  Core                                        │
  ├─────────────────────────────────────────────┤
  │  Layer 3 — In2.Cu                            │  VM + 3.3 V power distribution
  ├─────────────────────────────────────────────┤
  │  Prepreg                                     │
  ├─────────────────────────────────────────────┤
  │  Layer 4 — B.Cu (Bottom)                     │  Additional signals + local copper pours
  └─────────────────────────────────────────────┘  ← Solder side

Signal Integrity

Design decisions to ensure reliable operation in a noisy motor-drive environment:

• Continuous GND plane on In1.Cu with stitching vias throughout — minimises return-path inductance for both digital signals and motor switching transients.
• Wide copper pours on VM traces and high-current motor paths — rated for DRV8871 peak current with thermal headroom.
• Local decoupling capacitors placed directly at each ESP32-S3 power pin and each DRV8871 VCC/VM pin — suppresses switching noise at the source.
• Physical separation between sensitive I2C/SPI/UART traces and high-current motor/PWM traces — reduces capacitive and inductive coupling.
• Short SPI routes between ESP32-S3 and the display connector — maintains signal integrity at SPI bus speeds.
• Motor VM routed on power layer (In2.Cu) — keeps motor current off the signal layers.

Key Components (BOM Summary)

Full BOM with part numbers and quantities is available in hardware/bom/.

GPIO Pin Reference

Peripheral Details

Motor Control — DRV8871

The DRV8871 is a brushed DC motor driver with an integrated H-bridge, supporting up to 3.6 A peak current with current-limit protection. Two independent drivers are included for dual-motor operation.

Control truth table:

// Example: drive Motor 1 forward at ~70% speed
motor_set(MotorId::MOTOR1, 180);   // 180/255 ≈ 70%

// Brake Motor 1
motor_brake(MotorId::MOTOR1);

// Coast Motor 2
motor_coast(MotorId::MOTOR2);

PWM frequency: 20 kHz (above audible range — eliminates motor whine).
Resolution: 8-bit (0–255 duty cycle values).

Servo Outputs

Servo 1 outputs a standard 50 Hz RC-servo PWM signal compatible with common hobby servos. Servo 2 hardware exists on GPIO 9, but the current firmware repurposes GPIO 9 as the ADC potentiometer input, so only Servo 1 is active.

Pulse width to angle mapping:

1000 µs  ──►  0°   (full left)
1500 µs  ──►  90°  (center / neutral)
2000 µs  ──►  180° (full right)

// Example: center Servo 1
servo_set_angle(ServoId::SERVO1, 90);

Ultrasonic Sensors — HC-SR04

Four HC-SR04 interfaces provide omnidirectional environmental awareness. Each sensor uses two GPIO pins: one for triggering and one for echo timing.

Operating principle:

MCU                    HC-SR04
 │                        │
 │── 10 µs HIGH ─────────►│  TRIG pulse sent
 │                        │── 40 kHz ultrasonic burst ──►
 │                        │                    ◄── echo return
 │◄── pulse width (ECHO) ─│  width ∝ distance
 │
 Distance (cm) = pulse_width_µs × 0.0343 / 2

Timeout: 30 ms (~5 m) — sensors beyond range return -1.

Hall Effect Sensors

Two digital Hall effect sensor inputs support wheel speed measurement, odometry, and position feedback. Sensors are read via GPIO interrupts for accurate pulse counting.

// Example: read rotational speed
float pps1 = hall_get_pulses_per_second(1);   // pulses per second
float pps2 = hall_get_pulses_per_second(2);

To calculate RPM, divide pulses per second by the number of magnet poles on the wheel.

IMU — I2C

A dedicated I2C header supports any standard I2C IMU module.

Compatible IMUs (non-exhaustive):

// Example: read IMU data
ImuData imu;
if (imu_read(imu)) {
    // accel in g, gyro in °/s
    Serial.printf("ax=%.2f  ay=%.2f  az=%.2f\n",
                  imu.accel_x, imu.accel_y, imu.accel_z);
}

SPI Display

An SPI display connector supports ST7735, ST7789, ILI9341, or any SPI display with a compatible driver.

The firmware uses TFT_eSPI for hardware-accelerated graphics and text rendering on the ST7735S 160×80 display. A custom colour palette and tabbed on-device UI are implemented in display.h/cpp and ui.h/cpp.

Push Buttons

The current firmware uses two tactile buttons. Firmware enables INPUT_PULLUP, treats LOW as pressed, and applies software debouncing with BUTTON_DEBOUNCE_MS (default 20 ms).

GPIO 47 / Button 3 is not populated or used by the current 2-button UI.

// Example: detect button press events
buttons_update();   // call every loop iteration

if (nav_enter_just_pressed()) {
    // top button pressed
}

if (nav_back_just_pressed()) {
    // bottom button pressed
}

Expansion Header

Several GPIO pins are broken out on J9 for custom peripherals, additional sensors, or future expansion. Some physical header pins are shared with active firmware functions, so check config.h before reusing them.

GPIO 43 and 44 are the default UART0 pins and can be used for serial communication with external devices.

Firmware

Quick Start

# 1. Clone the repository
git clone https://github.com/averyizatt/ESP32BasedRobiticsPCB.git

# 2. Open in PlatformIO (recommended)
#    File → Open Folder → ESP32BasedRobiticsPCB
#    PlatformIO auto-resolves all lib_deps from platformio.ini

# 3. Build
pio run --environment esp32s3

# 4. Upload
pio run --target upload --environment esp32s3

1. Install PlatformIO (VS Code extension or CLI)
2. Open the repo root as the workspace
3. PlatformIO resolves all library dependencies automatically from platformio.ini
4. Select the esp32s3 environment, build, and upload
5. After boot, connect to WiFi SSID RoboController (password robot1234) and navigate to http://192.168.4.1

Library Dependencies

All dependencies are declared in platformio.ini and resolved automatically by PlatformIO. For manual Arduino IDE installs use the Library Manager names below.

TFT_eSPI user config: The library reads pin assignments from User_Setup.h. Ensure the file in your PlatformIO build includes the ST7735S settings matching config.h (MOSI=37, SCLK=38, CS=35, DC=36, RST=39).

Firmware Architecture

The firmware is organized as a set of independent peripheral modules — each with its own header and source file — all coordinated from main.cpp:

ESP32RoboticsController/
├── main.cpp                         ← setup() + loop() entry point
├── config.h                         ← All pin definitions and tuning constants
│
├── motors.h / motors.cpp            ← DRV8871 LEDC-based motor control
├── servos.h / servos.cpp            ← RC servo PWM control
├── ultrasonics.h / ultrasonics.cpp  ← HC-SR04 distance measurement
├── hall_sensors.h / hall_sensors.cpp← Interrupt-based pulse counting
├── imu.h / imu.cpp                  ← I2C IMU read abstraction (MPU-6050)
├── buttons.h / buttons.cpp          ← Debounced button state machine
├── led.h / led.cpp                  ← Onboard LED control
├── pot.h / pot.cpp                  ← Potentiometer / ADC helper
│
├── display.h / display.cpp          ← TFT_eSPI display abstraction + colour palette
├── ui.h / ui.cpp                    ← On-device tabbed UI state machine
├── games.h / games.cpp              ← Mini-game / demo logic
├── autonomous_modes.h / autonomous_modes.cpp
│                                      ← Autonomous driving state machine
├── robot_modes.h / robot_modes.cpp  ← Robot mode selector + active-mode runner
│
└── wifi_server.h / wifi_server.cpp  ← WiFi soft AP, AsyncWebServer, WebSocket push,
                                        BLE GATT server, WiFi/BLE scanner helpers

All pin assignments and tunable parameters are centralized in config.h — adapting the firmware to a modified hardware revision only requires editing that single file.

PWM Configuration

Motor PWM is generated using the ESP32-S3's LEDC peripheral, which provides hardware-timed PWM independent of the CPU:

WiFi Access Point & Web Dashboard

The firmware starts a soft Access Point on boot. Connect any browser-capable device to control and monitor the robot.

The dashboard is a single-page app served from PROGMEM with four tabs:

Sensor data is pushed over WebSocket (no polling) at a configurable interval (WIFI_WS_PUSH_MS, default 200 ms).

REST Endpoints

WebSocket Commands (browser → robot)

The robot accepts inbound JSON commands over the same WebSocket connection:

// Drive both motors (speed: -255 to +255)
{ "t": "drive", "l": 200, "r": -150 }

// Set Servo 1 angle (angle: 0–180°)
{ "t": "servo", "id": 1, "angle": 90 }

// Emergency stop — coasts both motors
{ "t": "stop" }

BLE GATT Server

The firmware advertises a custom BLE GATT service alongside the WiFi AP — connect from nRF Connect, LightBlue, or any GATT-capable app.

The sensor characteristic sends a live data notification every 500 ms when a central is connected:

{"ax":0.01,"ay":-0.03,"az":9.81,"gx":0.2,"gy":-0.1,"gz":0.0,"u":[45.2,120.0,-1.0,88.4]}

(u values are ultrasonic distances in cm; -1 = no echo / out of range)

On-Device UI

A tabbed menu system runs on the 160×80 TFT display. Navigation uses two push buttons and the onboard potentiometer. An auto-idle screensaver activates after 20 seconds of inactivity.

Navigation:

• Top button / GPIO 41 — enter, open, select, or primary action
• Bottom button / GPIO 42 — back, stop active mode, or return to menu
• Potentiometer — main menu selection and analog controls inside demos/games

In the main menu the potentiometer maps directly across the list: pot minimum selects the first item, and pot maximum selects the last item. It does not wrap around.

Main Menu

Robot Modes

The Robot Modes menu starts the autonomous-mode engine from the display UI. The top button starts the highlighted mode, the bottom button exits the menu, and while a mode is running the bottom button stops the mode and returns to the Robot Modes list.

Games

The Games menu launches a sub-menu with three sprite-rendered arcade games. All games use a full-screen off-screen framebuffer (TFT_eSprite) pushed via DMA for zero-flicker 40 fps rendering. Win/loss statistics are stored in RAM for the session and displayed in the game menu next to each title.

Snake

Classic snake — eat food to grow, avoid your own tail. Walls wrap.

Pong

Single-player Pong — keep the ball alive and score paddle hits.

Asteroids

Side-scrolling asteroid dodge — survive as long as possible.

All three games share:

• Particle system — 24-particle pool with gravity and colour fade, reused across all effects
• Screen shake — configurable intensity applied as DMA push offset
• Session W/L stats — shown in the games menu and on the game-over screen
• LED feedback — green on score/win, red on death/hit, blue on game start

Repository Structure

ESP32BasedRobiticsPCB/
│
├── platformio.ini                     ← PlatformIO project config + lib_deps
│
├── firmware/
│   └── ESP32RoboticsController/
│       ├── main.cpp                   ← setup() + loop() entry point
│       ├── config.h                   ← Pin map & constants (start here)
│       ├── motors.h / motors.cpp      ← DRV8871 LEDC motor control
│       ├── servos.h / servos.cpp      ← RC servo PWM
│       ├── ultrasonics.h / ultrasonics.cpp  ← HC-SR04 distance
│       ├── hall_sensors.h / hall_sensors.cpp← Interrupt pulse counting
│       ├── imu.h / imu.cpp            ← MPU-6050 I2C abstraction
│       ├── buttons.h / buttons.cpp    ← Debounced buttons
│       ├── led.h / led.cpp            ← Onboard LED
│       ├── pot.h / pot.cpp            ← ADC potentiometer
│       ├── display.h / display.cpp    ← TFT_eSPI wrapper + colour palette
│       ├── ui.h / ui.cpp              ← On-device tabbed UI state machine
│       ├── games.h / games.cpp        ← Demo / mini-game logic
│       ├── autonomous_modes.h / autonomous_modes.cpp
│       │                                ← Autonomous driving state machine
│       ├── robot_modes.h / robot_modes.cpp
│       │                                ← Robot mode selector + active-mode runner
│       └── wifi_server.h / wifi_server.cpp  ← WiFi AP, web dashboard,

Hardware Files

KiCad design files are in the hardware/ directory.

1. Install KiCad 7 or later
2. Open hardware/kicadProject/Tank.kicad_pro
3. The schematic opens in Eeschema; the PCB layout opens in Pcbnew

Generating Gerbers for fabrication (Pcbnew → File → Fabrication Outputs → Gerbers):

Pre-generated Gerber files are available in hardware/gerbers/.

Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-improvement)
3. Commit your changes with a clear message
4. Open a pull request describing what you changed and why

For hardware changes: please include updated Gerber files and a brief description of the PCB modification.
For firmware changes: please test on hardware before submitting.

License

MIT License — see LICENSE for details.