esp32-debug-dongle/README.md

# ESP32 Debug Dongle

A WiFi/Bluetooth serial debugging tool for ESP32. Access serial ports via web browser or Bluetooth terminal.

## Features

- **Web Terminal**: Browser-based serial terminal using xterm.js
- **Bluetooth SPP**: Classic Bluetooth serial port for desktop/mobile apps
- **Multi-Port**: Switch between internal debug, USB serial, and external serial
- **Virtual Serial**: Internal loopback for ESP32's own debug output
- **Configurable**: Change baud rates on the fly

## Hardware

### Requirements
- ESP32 DevKit v1 (or compatible ESP32 board with Classic Bluetooth)
- **Note**: ESP32-S2, S3, C3 do NOT support Classic Bluetooth SPP

### Pin Connections for External Serial (Serial1)

| ESP32 Pin | Function | Connect To |
|-----------|----------|------------|
| GPIO16    | RX1      | External device TX |
| GPIO17    | TX1      | External device RX |
| GND       | Ground   | External device GND |

## Quick Start

### 1. Install PlatformIO

```bash
# Install PlatformIO CLI (if not already installed)
pip install platformio

# Or use VS Code with PlatformIO IDE extension
```

### 2. Build and Upload

```bash
# Clone/copy this project
cd esp32-debug-dongle

# Build the firmware
pio run

# Upload firmware to ESP32
pio run -t upload

# Upload web files to LittleFS
pio run -t uploadfs
```

### 3. Connect

#### Via WiFi (Web Terminal)

1. Connect to WiFi network: `ESP32-DebugDongle`
2. Password: `debug1234`
3. Open browser: `http://192.168.4.1`

#### Via Bluetooth

1. Pair with device: `ESP32-Debug`
2. Use any Bluetooth serial terminal app:
   - **Android**: "Serial Bluetooth Terminal" by Kai Morich
   - **Windows**: PuTTY (use assigned COM port after pairing)
   - **Linux**: `rfcomm connect 0 XX:XX:XX:XX:XX:XX` then use `/dev/rfcomm0`
   - **macOS**: Pair in System Preferences, use `/dev/tty.ESP32-Debug`

## Usage

### Web Interface

The web terminal provides:
- **Port Selection**: Choose between Internal, USB Serial, or External
- **Baud Rate**: Configure serial speed (9600 - 921600)
- **Clear**: Clear terminal screen
- **Reconnect**: Re-establish WebSocket connection

### Serial Ports

| Port | Description | Use Case |
|------|-------------|----------|
| Internal | Virtual loopback buffer | ESP32's own debug output |
| USB Serial | UART0 (USB connection) | Shared with programming |
| External | Serial1 (GPIO16/17) | External device debugging |

### Using Internal Debug Output

In your ESP32 code, use the provided helper functions:

```cpp
// Write to internal virtual serial
debugPrint("Sensor value: %d", sensorValue);
debugPrintln("Status: OK");

// Or write directly to the loopback stream
internalSerial.println("Debug message");
```

These messages appear when "Internal" port is selected.

## Configuration

Edit `src/main.cpp` to change defaults:

```cpp
// WiFi Access Point
const char* AP_SSID = "ESP32-DebugDongle";
const char* AP_PASSWORD = "debug1234";

// Bluetooth name
const char* BT_NAME = "ESP32-Debug";

// Serial1 pins
#define SERIAL1_RX_PIN 16
#define SERIAL1_TX_PIN 17

// Default baud rates
#define DEFAULT_BAUD_SERIAL  115200
#define DEFAULT_BAUD_SERIAL1 115200
```

## Project Structure

```
esp32-debug-dongle/
├── platformio.ini          # PlatformIO configuration
├── src/
│   └── main.cpp            # Main ESP32 firmware
├── data/
│   └── index.html          # Web interface (uploaded to LittleFS)
├── scripts/
│   └── download_xterm.py   # Optional: download xterm.js locally
└── README.md
```

## xterm.js Setup

The web interface uses xterm.js loaded from CDN. If you need offline operation:

```bash
# Download files locally
python scripts/download_xterm.py --local

# Then edit data/index.html to use local paths:
# <link rel="stylesheet" href="/css/xterm.min.css">
# <script src="/js/xterm.min.js"></script>
# etc.
```

## WebSocket Protocol

The WebSocket endpoint is `ws://192.168.4.1/ws`

### Data Format

- **Regular serial data**: Raw bytes sent/received directly
- **Commands**: JSON prefixed with `0x00` byte

### Commands

```javascript
// Switch serial port
{ "cmd": "setPort", "port": 0 }  // 0=Internal, 1=USB, 2=External

// Set baud rate
{ "cmd": "setBaud", "port": 2, "baud": 115200 }

// Get status
{ "cmd": "getStatus" }
```

### JavaScript Example

```javascript
const ws = new WebSocket('ws://192.168.4.1/ws');
ws.binaryType = 'arraybuffer';

// Send serial data
ws.send(new TextEncoder().encode('Hello\r\n'));

// Send command
function sendCommand(cmd) {
    const json = JSON.stringify(cmd);
    const data = new Uint8Array(json.length + 1);
    data[0] = 0x00;
    new TextEncoder().encodeInto(json, data.subarray(1));
    ws.send(data);
}

// Receive data
ws.onmessage = (e) => {
    const data = new Uint8Array(e.data);
    if (data[0] === 0x00) {
        // Command response
        const json = JSON.parse(new TextDecoder().decode(data.slice(1)));
        console.log('Response:', json);
    } else {
        // Serial data
        console.log('Serial:', new TextDecoder().decode(data));
    }
};
```

## Troubleshooting

### Can't connect to WiFi
- Ensure you're connecting to `ESP32-DebugDongle` network
- Password is `debug1234` (case-sensitive)
- Try resetting the ESP32

### Web page won't load
- Make sure you uploaded the filesystem: `pio run -t uploadfs`
- Check serial monitor for errors
- Try `http://192.168.4.1` (not https)

### Bluetooth won't pair
- Only works on original ESP32 (not S2, S3, C3)
- Delete existing pairing and try again
- Check that Bluetooth is enabled in build flags

### No serial data
- Verify baud rate matches your device
- Check TX/RX connections (try swapping them)
- Ensure common ground connection

### Build errors
- Ensure you have the ESP32 board package installed in PlatformIO
- Library dependencies should auto-install on first build

## License

MIT License - Feel free to use and modify.

## Credits

- [xterm.js](https://xtermjs.org/) - Terminal emulator
- [ESPAsyncWebServer](https://github.com/me-no-dev/ESPAsyncWebServer) - Async web server
- [ArduinoJson](https://arduinojson.org/) - JSON library by Benoît Blanchon