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
Robust Server: Uses PsychicHttp - stable under load (unlike ESPAsyncWebServer)

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 (Station Mode - Default)

Edit src/main.cpp and set your WiFi credentials:

const char* STA_SSID = "YourNetworkSSID";
const char* STA_PASSWORD = "YourPassword";

Upload and check serial monitor for the assigned IP address
Open browser: http://<ip-address>

Via WiFi (AP Mode Fallback)

If station mode fails, or you set WIFI_STATION_MODE false:

Connect to WiFi network: ESP32-DebugDongle
Password: debug1234
Open browser: http://192.168.4.1

Via Bluetooth

Pair with device: ESP32-Debug
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 Mode: true = connect to existing network, false = create AP
#define WIFI_STATION_MODE true

// Your WiFi network credentials (station mode)
const char* STA_SSID = "YourNetworkSSID";
const char* STA_PASSWORD = "YourPassword";

// Fallback Access Point settings
const char* AP_SSID = "ESP32-DebugDongle";
const char* AP_PASSWORD = "debug1234";

// Connection timeout before falling back to AP mode
#define WIFI_CONNECT_TIMEOUT 15000

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

WiFi Modes

Station Mode (WIFI_STATION_MODE true):

Connects to your existing WiFi network
Access the dongle from any device on the same network
Falls back to AP mode if connection fails

Access Point Mode (WIFI_STATION_MODE false):

Creates its own WiFi network
Connect directly to the ESP32's network
IP address: 192.168.4.1

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
PsychicHttp - Robust HTTP/WebSocket server for ESP32
ArduinoJson - JSON library by Benoît Blanchon