Debug dongle test code
This commit is contained in:
241
README.md
Normal file
241
README.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user