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
• 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)

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

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

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

Via WiFi (AP Mode Fallback)

If station mode fails, or you set WIFI_STATION_MODE false:

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