Readme Update

README.md

@@ -1,63 +1,162 @@
 # Bluetooth LE Audio (Auracast) Transmitter
-**Phase:** Proof of Concept (Simulation)
+**Phase:** Proof of Concept (PoC) — Simulation
 
 ---
 
 ## Overview
-This project focuses on the development of a **Bluetooth Low Energy (LE) Audio Transmitter** supporting the **Auracast** standard. The current phase is a **Proof of Concept (PoC) simulation**, demonstrating system functionality without physical hardware implementation. The project uses an **NXP NXH3675** transceiver integrated with an **Arduino-compatible controller** for simulation purposes.
+
+This is a **Proof of Concept (PoC)** simulation of a **Bluetooth Low Energy (LE) Audio Transmitter** supporting the **Auracast** standard. The system runs on an **ESP32** acting as both a BLE GATT server and passive BLE scanner, with a **Node.js** backend bridging serial communication to a browser-based monitoring dashboard. No physical NXH3675 hardware is required in this PoC phase.
 
 ---
 
-## Objectives
-- Simulate the transmission of BLE Audio streams using Auracast protocol.
-- Validate communication between NXH3675 transceiver and controller firmware.
-- Demonstrate Proof of Concept without creating physical hardware.
-- Provide a basis for future hardware development and testing.
+## System Architecture
+
+```text
+ESP32 (BLE Server + Scanner)
+        │ UART Serial (115200 baud, COM8)
+        ▼
+Node.js Backend (Express + WebSocket + SerialPort)
+        │ WebSocket (ws://localhost:8080)
+        ▼
+Browser Dashboard (index.html)
+```
+
+**ESP32** (`src/main/main.ino`):
+
+- Acts as a BLE GATT server advertising service UUID `4fafc201-1fb5-459e-8fcc-c5c9c331914b`
+- Scans for nearby BLE devices and collects RSSI, TX power, and name
+- Emits newline-delimited JSON events over Serial on connect/disconnect
+- Accepts `DISCONNECT <connId>` commands via Serial input to force-disconnect clients
+
+**Node.js Backend** (`src/web_side/read_serial.js`):
+
+- Express server on port 8080 serves the frontend
+- WebSocket server relays ESP32 serial data to connected browsers in real time
+- Translates browser commands (`OPEN_SERIAL`, `CLOSE_SERIAL`, `DISCONNECT`) to serial writes
+
+**Browser Dashboard** (`src/web_side/index.html`):
+
+- Displays connected BLE device cards (MAC, connection ID, interval, latency, timeout)
+- Shows a live connection log panel
+- Allows force-disconnect of individual clients
 
 ---
 
-## Features (Simulation Phase)
-- BLE Audio packet simulation
-- Controller-to-transceiver communication over I²C/SPI (simulated)
-- Basic audio stream configuration and management
-- Logging of simulated data for analysis
+## Requirements
+
+- **ESP32** board (tested with ESP32-S3)
+- **ESP-IDF v5.5.1** (or Arduino IDE with ESP32 BLE libraries)
+- **Node.js v18+**
+- **Python 3** with `pyserial` and `numpy` (for LC3 codec simulation only)
+- Serial-to-USB cable connecting ESP32 to PC
 
 ---
 
-## Hardware (Simulation Reference)
-- **NXH3675** BLE Audio Transceiver (NXP)
-- Arduino-compatible MCU (simulation platform)
-> Note: Hardware is referenced for simulation purposes; no physical hardware is required in this phase.
+## Setup & Running
+
+### 1. Flash the ESP32
+
+Using ESP-IDF (VS Code extension configured for `c:\Dev\esp\v5.5.1\esp-idf`):
+
+```bash
+idf.py set-target esp32s3
+idf.py -p COM8 flash monitor
+```
+
+Or open `src/main/main.ino` in Arduino IDE with the ESP32 BLE libraries installed.
+
+### 2. Start the Node.js Backend
+
+```bash
+npm install
+npm start
+```
+
+The web server starts at `http://localhost:8080`.
+
+### 3. Open the Dashboard
+
+Open `http://localhost:8080` in your browser (or open `src/web_side/index.html` directly).
+
+Click **Open Port** to connect to the ESP32 via serial. BLE device cards will appear when clients connect to the ESP32.
 
 ---
 
-## Software Requirements
-- Arduino IDE or PlatformIO
-- Python (for simulation scripts)
-- Serial Monitor / Logging tool for output verification
-- Git (for version control)
+## Serial Port Configuration
+
+The serial port is hardcoded as **`COM8`** in two files — update both when using a different port:
+
+| File                              | Location                          |
+| --------------------------------- | --------------------------------- |
+| `src/web_side/read_serial.js`     | `path: "COM8"` (line 29)          |
+| `src/LC3_Codec_Python/testlc3.py` | `serial.Serial("COM8", 115200)`   |
+
+The VS Code monitor port is set in `.vscode/settings.json`.
+
+---
+
+## LC3 Codec Simulation (Optional)
+
+Sends dummy LC3-encoded audio frames to the ESP32 over serial:
+
+```bash
+cd src/LC3_Codec_Python
+pip install pyserial numpy
+python testlc3.py
+```
+
+Requires `audio.wav` (mono, 16-bit PCM) in the same directory.
+
+---
+
+## JSON Event Protocol
+
+ESP32 emits JSON over serial; Node.js forwards it to the browser via WebSocket.
+
+| `Status` value        | Description                                              |
+| --------------------- | -------------------------------------------------------- |
+| `NEW_CONNECT`         | BLE client connected — includes `Devices` array          |
+| `DEVICE_DISCONNECTED` | A client disconnected — includes updated `Devices` array |
+| `NO_CONNECTED`        | All clients disconnected                                 |
+
+Each device entry contains: `connectedID`, `mac`, `connInterval`, `latency`, `timeout`.
 
 ---
 
 ## Project Structure
-/project
-├─ /src # Source code for simulation
-├─ /docs # Documentation and diagrams
-├─ /test # Program for function Test
-├─ README.md
-└─ LICENSE
-
-## How to simulate
-1. Open the src folder.
-2. The ESP32 program is located in src/main.
-3. The Node.js backend program is located in src/web_side/read_serial.js.
-4. The web interface is located in src/web_side/index.html.
-5. Connect the ESP32 to your computer using a Serial-to-USB cable.
-6. Open read_serial.js and adjust the ESP32 port based on the port shown in Device Manager.
-7. Open a terminal and navigate to:
-cd ../ble_auracast/src/web_side
-8. Once the ESP32 is connected, run:
-node read_serial.js
-9. Open index.html in your browser.
-10. Click the "Open Port" button.
-11. After the port is open, all logs and BLE connection information will appear when the ESP32 connects to a BLE client.
+
+```
+/
+├── src/
+│   ├── main/main.ino          # ESP32 BLE firmware (Arduino)
+│   ├── main.cpp               # ESP32 entry point (ESP-IDF / PlatformIO)
+│   ├── web_side/
+│   │   ├── read_serial.js     # Node.js serial-to-WebSocket bridge
+│   │   └── index.html         # Browser dashboard
+│   └── LC3_Codec_Python/
+│       └── testlc3.py         # Dummy LC3 audio frame sender
+├── test/
+│   ├── NimBLE_Beacon/         # Non-connectable beacon example
+│   ├── NimBLE_Connection/     # BLE connection + LED example
+│   ├── NimBLE_Conn_Disconn/   # Connect/disconnect lifecycle
+│   ├── NimBLE_GATT_Server/    # GATT server with heart rate mock
+│   └── get_RSSI_Device_Name/  # Arduino scan + RSSI printer
+├── docs/                      # Project documentation
+├── CMakeLists.txt             # ESP-IDF top-level build file
+├── platformio.ini             # PlatformIO config (target: esp32s3usbotg)
+└── package.json               # Node.js dependencies
+```
+
+---
+
+## Test Examples
+
+Each project under `test/` is a standalone ESP-IDF application. Build and flash from within its directory:
+
+```bash
+cd test/NimBLE_GATT_Server
+idf.py set-target esp32
+idf.py -p <PORT> flash monitor
+```
+
+Use [nRF Connect for Mobile](https://www.nordicsemi.com/Products/Development-tools/nRF-Connect-for-mobile) to interact with the running examples from a phone.