276 lines
7.1 KiB
Markdown
276 lines
7.1 KiB
Markdown
# 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
|
|
|
|
```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 (Station Mode - Default)
|
|
|
|
1. Edit `src/main.cpp` and set your WiFi credentials:
|
|
```cpp
|
|
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:
|
|
|
|
```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 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:
|
|
|
|
```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
|
|
- [PsychicHttp](https://github.com/hoeken/PsychicHttp) - Robust HTTP/WebSocket server for ESP32
|
|
- [ArduinoJson](https://arduinojson.org/) - JSON library by Benoît Blanchon
|