# Hardware Setup Guide

How to set up the ESP32 hardware and build environment for the mcbluetooth-esp32 test harness.

## Requirements

- **ESP32 dev board** -- must be an original ESP32 (ESP32-D0WD or similar) with Classic Bluetooth support. ESP32-S3, ESP32-C3, ESP32-H2, and ESP32-S2 lack the BR/EDR radio and will not work for Classic BT pairing tests.
- **USB cable** (USB-A to micro-USB or USB-C depending on your board)
- **Linux host** with BlueZ installed (for the `mcbluetooth` MCP server on the other side of E2E tests)
- **ESP-IDF v5.x** toolchain

## Verified Hardware

| Property | Value |
|----------|-------|
| Chip | ESP32-D0WD-V3 (rev 3.1) |
| Flash | 4MB |
| Crystal | 40MHz |
| Features | Wi-Fi, Bluetooth (dual-mode), Dual Core, 240MHz |

Any ESP32 board based on the original ESP32 chip should work. Commonly available boards include ESP32-DevKitC, ESP32-WROOM-32, and NodeMCU-32S.

## Wiring

### Default: USB only

For most development, a single USB cable handles both flashing and protocol communication. The ESP32's built-in USB-to-UART bridge (typically CP2102 or CH340) provides the serial link.

The firmware uses **UART1** (GPIO4/GPIO5) for the NDJSON protocol and keeps **UART0** for ESP-IDF console logging. When using USB only, the USB bridge connects to UART0 by default -- so you will need either:

1. A board that routes UART1 through the USB bridge (uncommon), or
2. A separate USB-UART adapter connected to GPIO4/GPIO5 (described below)

For quick testing with the firmware's default pin assignment, connect a USB-UART adapter.

### Dedicated UART (GPIO4/GPIO5)

Connect a USB-UART adapter (e.g., FTDI FT232R, CP2102, CH340) to the ESP32:

```
ESP32 GPIO4 (TX) ----> USB-UART adapter RX
ESP32 GPIO5 (RX) <---- USB-UART adapter TX
ESP32 GND        ----> USB-UART adapter GND
```

The adapter appears as a second `/dev/ttyUSB*` device on the host. Use this device path for `ESP32_SERIAL_PORT`.

Do not connect voltage lines (VCC/3V3) between the adapter and the ESP32 if the board is already powered via its own USB port.

### Pin reassignment

If GPIO4/GPIO5 conflict with other peripherals on your board, change the pin definitions in `firmware/main/uart_handler.c`:

```c
#define UART_TX_PIN  GPIO_NUM_4
#define UART_RX_PIN  GPIO_NUM_5
```

Rebuild and reflash after changing pins.

## ESP-IDF Setup

### 1. Install ESP-IDF v5.x

Follow the official installation guide: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/

On Arch Linux:

```bash
# Install dependencies
sudo pacman -S cmake ninja python

# Clone ESP-IDF
mkdir -p ~/esp && cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32

# Activate the environment (add to .bashrc or run each session)
. ~/esp/esp-idf/export.sh
```

### 2. Set the target

```bash
cd firmware
idf.py set-target esp32
```

This only needs to be done once per checkout. It configures the build system for the ESP32 chip.

### 3. Build

```bash
idf.py build
```

Or using the project Makefile from the repository root:

```bash
make build
```

### 4. Flash

```bash
idf.py -p /dev/ttyUSB4 flash
```

Or:

```bash
make flash SERIAL_PORT=/dev/ttyUSB4
```

### 5. Monitor (optional)

Open the ESP-IDF serial monitor to see console logs from UART0:

```bash
idf.py -p /dev/ttyUSB4 monitor
```

Press `Ctrl+]` to exit the monitor.

### 6. Flash and monitor in one step

```bash
make flash-monitor SERIAL_PORT=/dev/ttyUSB4
```

## Quick Verification

### Using the MCP server

```bash
# Set the serial port and start the server
ESP32_SERIAL_PORT=/dev/ttyUSB4 uvx mcbluetooth-esp32
```

Then from a Claude Code session with the MCP server configured, call:

1. `esp32_connect` -- opens the serial link
2. `esp32_ping` -- should return `{"pong": true}`
3. `esp32_get_info` -- should return chip model, firmware version, MAC address

### Using the Makefile ping target

```bash
make ping SERIAL_PORT=/dev/ttyUSB4
```

This runs a standalone Python script that connects, sends a `ping` command, prints the response, and disconnects.

### Raw serial check

If everything else fails, use `screen` or `minicom` to send raw JSON:

```bash
screen /dev/ttyUSB4 115200
```

Type (all on one line, then press Enter):

```json
{"type":"cmd","id":"1","cmd":"ping"}
```

You should see:

```json
{"type":"resp","id":"1","status":"ok","data":{"pong":true}}
```

Press `Ctrl+A` then `K` then `Y` to exit screen.

## sdkconfig

The project ships `firmware/sdkconfig.defaults` with the required Bluetooth configuration pre-set:

| Setting | Value | Purpose |
|---------|-------|---------|
| `CONFIG_BT_ENABLED` | y | Enable Bluetooth controller |
| `CONFIG_BT_BLUEDROID_ENABLED` | y | Use Bluedroid host stack |
| `CONFIG_BT_CLASSIC_ENABLED` | y | Enable BR/EDR (Classic BT) |
| `CONFIG_BT_BLE_ENABLED` | y | Enable BLE |
| `CONFIG_BT_SSP_ENABLED` | y | Enable Secure Simple Pairing |
| `CONFIG_BT_SPP_ENABLED` | y | Enable Serial Port Profile |
| `CONFIG_BT_GATTS_ENABLE` | y | Enable GATT Server |
| `CONFIG_BTDM_CTRL_MODE_BTDM` | y | Dual-mode controller (Classic + BLE simultaneously) |
| `CONFIG_NVS_ENABLED` | y | Non-volatile storage for bonding data |

Do not modify these unless you understand the implications. Disabling `CONFIG_BT_CLASSIC_ENABLED` breaks all Classic BT pairing tests. Disabling `CONFIG_BT_SSP_ENABLED` forces legacy PIN-only pairing.

## Troubleshooting

### Permission denied on `/dev/ttyUSB*`

Add your user to the `dialout` group (or `uucp` on Arch Linux):

```bash
# Debian/Ubuntu
sudo usermod -aG dialout $USER

# Arch Linux
sudo usermod -aG uucp $USER
```

Log out and back in for the group change to take effect.

### Device not found

Check what serial devices are present:

```bash
ls -la /dev/ttyUSB* /dev/ttyACM*
```

If nothing appears, verify the USB cable is a data cable (not charge-only) and that the board's USB-UART chip driver is loaded:

```bash
dmesg | tail -20
```

Look for lines mentioning `cp210x`, `ch341`, or `ftdi_sio`.

### Flash fails or hangs

Some ESP32 boards require holding the **BOOT** button during the initial flash sequence. Hold BOOT, press and release EN (reset), then release BOOT. The flash should proceed.

If the board has auto-download circuitry (most DevKitC boards do), this should not be necessary.

### No response over UART

1. **Verify TX/RX pin assignment.** The firmware uses UART1 on GPIO4 (TX) and GPIO5 (RX). If your adapter is connected to different pins, update `uart_handler.c`.

2. **Check baud rate.** Both sides must use 115200. Verify in `screen` or your terminal emulator.

3. **Check the correct serial device.** If the board has two USB-UART interfaces (one for UART0 console, one for UART1 protocol), make sure you are talking to the right one.

4. **Look at UART0 console output.** Connect the ESP-IDF monitor to the console port. Boot messages and error logs appear there. If you see `UART1 ready (TX=4 RX=5 @ 115200 baud)` in the log, the firmware started correctly.

### Build errors about missing Bluetooth headers

Make sure `idf.py set-target esp32` was run. The ESP32-S3 and ESP32-C3 targets do not expose Classic BT APIs, which causes build failures.

### NVS errors on first boot

If the console shows `NVS partition issue, erasing and re-initializing`, this is expected on first flash or after a partition table change. The firmware handles it automatically by erasing and reinitializing NVS.