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

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

# Or use VS Code with PlatformIO IDE extension

2. Build and Upload

# 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:

// 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:

// 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:

# 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

// 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

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 - Terminal emulator
• ESPAsyncWebServer - Async web server
• ArduinoJson - JSON library by Benoît Blanchon