Add Claude.md

CLAUDE.md

@@ -0,0 +1,94 @@
+# 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