# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a **Bluetooth LE Audio (Auracast) Transmitter** — Proof of Concept simulation. The system uses an ESP32 as a BLE server/scanner, a Node.js backend to bridge Serial↔WebSocket, and a browser frontend to monitor connected BLE devices in real time. No physical NXH3675 hardware is required in this phase.

## Two Independent Runtimes

The project has two separate runtimes that must be operated independently:

**1. ESP32 Firmware** (`src/main/main.ino`) — Arduino/ESP-IDF on ESP32
- Runs a BLE GATT server + passive BLE scanner
- Serializes connection/disconnection events as JSON over UART at 115200 baud
- Accepts `DISCONNECT <connId>` commands via Serial input
- Serial port is configured as `COM8` in both the firmware side and the Node.js side

**2. Node.js Web Backend** (`src/web_side/read_serial.js`) — Express + WebSocket + SerialPort
- Bridges the ESP32's serial output to browser clients via WebSocket on port 8080
- Serves `index.html` as a static file from the `public/` directory
- Translates browser `OPEN_SERIAL` / `CLOSE_SERIAL` / `DISCONNECT` WebSocket commands to serial writes

## Commands

### Node.js Backend

```bash
# Install dependencies (first time)
npm install

# Start the web server + serial bridge
npm start
# or directly:
node src/web_side/read_serial.js
```

Then open `src/web_side/index.html` in a browser.

### ESP32 Firmware (ESP-IDF via VS Code extension)

The project uses ESP-IDF v5.5.1. The VS Code ESP-IDF extension is configured in `.vscode/settings.json` (IDF path: `c:\Dev\esp\v5.5.1\esp-idf`, tools: `c:\Dev\.espressif`).

```bash
# Set target chip
idf.py set-target esp32s3

# Build
idf.py build

# Flash and monitor (adjust port as needed)
idf.py -p COM8 flash monitor
```

For the PlatformIO path (target `esp32s3usbotg`), use the PlatformIO sidebar or CLI.

### Python LC3 Codec Simulation

```bash
cd src/LC3_Codec_Python
pip install pyserial numpy
python testlc3.py
```
Requires a WAV file named `audio.wav` (mono, 16-bit) in the same directory. Sends dummy LC3 frames (60 bytes each) to the ESP32 over `COM8`.

## Test Projects (`test/`)

The `test/` directory contains self-contained ESP-IDF example projects for exploring BLE primitives. Each is built and flashed independently using `idf.py` from within its own folder:

| Folder | Purpose |
|---|---|
| `NimBLE_Beacon` | Non-connectable BLE beacon advertising |
| `NimBLE_Connection` | BLE connection with GAP + LED feedback |
| `NimBLE_Conn_Disconn` | Connection/disconnection lifecycle |
| `NimBLE_GATT_Server` | GATT server with heart rate mock service |
| `get_RSSI_Device_Name` | Arduino sketch: scan and print RSSI/device names |

Each ESP-IDF test project follows the pattern: `main/main.c` (entry point) + `main/src/gap.c` (advertising/connection logic) + optional `gatt_svc.c`, `led.c`.

## Serial Port Configuration

The serial port is hardcoded as `COM8` in two places — update both when changing hardware:
- `src/web_side/read_serial.js` line 29: `path: "COM8"`
- `src/LC3_Codec_Python/testlc3.py` line 7: `ser = serial.Serial("COM8", 115200)`

The VS Code ESP-IDF monitor port is set in `.vscode/settings.json` (`idf.monitorPort`, `idf.portWin`).

## JSON Protocol (ESP32 → Node.js → Browser)

ESP32 emits newline-delimited JSON. Key status values:

- `NEW_CONNECT` — new BLE client connected; includes `Devices` array with `connectedID`, `mac`, `connInterval`, `latency`, `timeout`
- `DEVICE_DISCONNECTED` — client disconnected; updated `Devices` array
- `NO_CONNECTED` — all clients gone