Bluetooth-LE-Audio-Auracast-Transmitter/CLAUDE.md

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

# 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).

# 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

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