Skip to content

Commit eb08efd

Browse files
finger563finger563
authored
feat(remote_debug): Add new RemoteDebug component for WiFi GPIO/ADC and logfile access (#589)
* feat(remote_debug): Add new RemoteDebug component * update kconfig to default to saved ssid; update example / code to better handle input/output and lables for adc and io; update debug to use espp adc * update to allow labels in kconfig * Working remote logging with colorization :) * finalizing the component * cleanup * wip better analog plotting * improve behavior / performance * minor updates for good common config * clean up component * update ci and doc * readme: update * fix sa * readme: update * address comments and improve behavior * fix reamdes * fix doc * fix sa * comment update * final cleanup
1 parent 4a41ade commit eb08efd

18 files changed

+2180
-0
lines changed

‎.github/workflows/build.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,8 @@ jobs:
165165
target: esp32s3
166166
- path: 'components/qwiicnes/example'
167167
target: esp32
168+
- path: 'components/remote_debug/example'
169+
target: esp32s3
168170
- path: 'components/rmt/example'
169171
target: esp32s3
170172
- path: 'components/rtsp/example'

‎.github/workflows/upload_components.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,7 @@ jobs:
103103
components/qmi8658
104104
components/qtpy
105105
components/qwiicnes
106+
components/remote_debug
106107
components/rmt
107108
components/rtsp
108109
components/runqueue

‎components/remote_debug/CMakeLists.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
idf_component_register(
2+
INCLUDE_DIRS "include"
3+
SRC_DIRS "src"
4+
REQUIRES esp_http_server driver adc base_component file_system timer
5+
)

‎components/remote_debug/README.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Remote Debug
2+
3+
[![Badge](https://components.espressif.com/components/espp/remote_debug/badge.svg)](https://components.espressif.com/components/espp/remote_debug)
4+
5+
Web-based remote debugging interface providing GPIO control, real-time ADC
6+
monitoring, and optional console log viewing over HTTP. Uses `espp::Timer` for
7+
efficient, configurable periodic updates.
8+
9+
https://github.com/user-attachments/assets/ee806c6c-0f6b-4dd0-a5b0-82b80410b5bc
10+
11+
<img width="607" height="2048" alt="image" src="https://github.com/user-attachments/assets/5977033c-eee8-4be2-a9c4-634fd3100480" />
12+
13+
## Features
14+
15+
- **GPIO Control**: Configure pins as input/output, read states, control outputs via web interface
16+
- **ADC Monitoring**: Real-time visualization of ADC channels with configurable sample rates
17+
- **Console Log Viewer**: Optional stdout redirection to web-viewable log with ANSI color support
18+
- **Efficient Updates**: Uses `espp::Timer` for optimal performance with configurable priority
19+
- **RESTful API**: JSON endpoints for programmatic access
20+
- **Responsive UI**: Modern web interface that works on desktop and mobile
21+
- **Multi-client Support**: Optimized for multiple concurrent clients through batched updates
22+
23+
## Performance
24+
25+
The component has been optimized for efficiency:
26+
27+
- Uses `espp::Timer` for precise, lightweight periodic updates
28+
- Configurable task priority and stack size
29+
- Batched ADC data updates reduce HTTP overhead
30+
- Ring buffer implementation for efficient data management
31+
- Efficient JSON generation minimizes processing overhead
32+
33+
## Dependencies
34+
35+
- `espp::Timer` - Periodic task execution
36+
- `espp::Adc` - ADC channel management
37+
- `espp::FileSystem` - LittleFS for optional log storage
38+
- ESP HTTP Server - Web interface hosting
39+
40+
## Console Logging
41+
42+
When `enable_log_capture` is enabled in the config, stdout is redirected to a file
43+
viewable in the web interface. The log viewer supports ANSI color codes.
44+
45+
**Important**: For real-time log updates, enable LittleFS file flushing:
46+
47+
```
48+
CONFIG_LITTLEFS_FLUSH_FILE_EVERY_WRITE=y
49+
```
50+
51+
## API Endpoints
52+
53+
The component exposes the following HTTP endpoints:
54+
55+
- `GET /` - Main web interface (HTML page)
56+
- `GET /api/gpio/get` - Get all GPIO states and configurations (JSON)
57+
- `POST /api/gpio/set` - Set GPIO output state (JSON: `{"pin": N, "value": 0|1}`)
58+
- `POST /api/gpio/config` - Configure GPIO direction (JSON: `{"pin": N, "mode": 1|3}`)
59+
- Mode values: `1` = INPUT, `3` = INPUT_OUTPUT (OUTPUT is promoted to INPUT_OUTPUT for safety)
60+
- `GET /api/adc/data` - Get ADC readings and plot data (JSON with ring buffer indices)
61+
- `GET /api/logs` - Get console log contents (text/plain with ANSI colors)
62+
- `POST /api/logs/start` - Start log capture (redirects stdout to file)
63+
- `POST /api/logs/stop` - Stop log capture (restores stdout to /dev/console)
64+
65+
Set this in your `sdkconfig.defaults` or via `idf.py menuconfig` → Component
66+
config → LittleFS. Without this, logs only appear after the buffer fills.
67+
68+
## Example
69+
70+
See the example in the `example/` folder for a complete demonstration with WiFi
71+
connection, GPIO control, ADC monitoring, and console log viewing.
72+
73+
## External Resources
74+
75+
- [ESP-IDF HTTP Server Documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/protocols/esp_http_server.html)
76+
- [ADC Continuous Mode](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/adc_continuous.html)

‎components/remote_debug/example/CMakeLists.txt‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# The following lines of boilerplate have to be in your project's CMakeLists
2+
# in this exact order for cmake to work correctly
3+
cmake_minimum_required(VERSION 3.20)
4+
5+
set(ENV{IDF_COMPONENT_MANAGER} "0")
6+
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
7+
8+
# add the component directories that we want to use
9+
set(EXTRA_COMPONENT_DIRS
10+
"../../../components/"
11+
)
12+
13+
set(
14+
COMPONENTS
15+
"main esptool_py remote_debug task timer nvs_flash wifi"
16+
CACHE STRING
17+
"List of components to include"
18+
)
19+
20+
project(remote_debug_example)
21+
22+
set(CMAKE_CXX_STANDARD 20)

‎components/remote_debug/example/README.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Remote Debug Example
2+
3+
This example demonstrates the `espp::RemoteDebug` component, providing a
4+
web-based interface for GPIO control, real-time ADC monitoring, and console log
5+
viewing.
6+
7+
https://github.com/user-attachments/assets/ee806c6c-0f6b-4dd0-a5b0-82b80410b5bc
8+
9+
<img width="607" height="2048" alt="image" src="https://github.com/user-attachments/assets/5977033c-eee8-4be2-a9c4-634fd3100480" />
10+
11+
## How to use example
12+
13+
### Hardware Required
14+
15+
This example can run on any ESP32 development board. For testing:
16+
- Connect LEDs or other peripherals / inputs to GPIO pins
17+
- Connect analog sensors to ADC-capable pins
18+
19+
### Configure the project
20+
21+
```
22+
idf.py menuconfig
23+
```
24+
25+
Navigate to `Remote Debug Example Configuration`:
26+
- WiFi credentials (SSID and password)
27+
- Server configuration (port, title)
28+
- GPIO configuration (number of pins, pin numbers, labels)
29+
- ADC configuration (channels, attenuation, labels, sample rate, buffer size)
30+
- Console logging (enable/disable, buffer size)
31+
32+
**Important**: If enabling console logging, you must also set:
33+
- Component config → LittleFS → `CONFIG_LITTLEFS_FLUSH_FILE_EVERY_WRITE=y`
34+
35+
This ensures real-time log updates on the web interface.
36+
37+
### Build and Flash
38+
39+
Build the project and flash it to the board, then run monitor tool to view serial output:
40+
41+
```
42+
idf.py -p PORT flash monitor
43+
```
44+
45+
(Replace PORT with the name of the serial port to use.)
46+
47+
(To exit the serial monitor, type ``Ctrl-]``.)
48+
49+
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
50+
51+
### Access the Interface
52+
53+
1. Device connects to configured WiFi network
54+
2. Check serial monitor for assigned IP address
55+
3. Open web browser to `http://<device-ip>:<port>` (default port: 8080)
56+
4. Use the interface to control GPIOs, monitor ADCs, and view console logs
57+
58+
## Example Output
59+
60+
<img width="1396" height="460" alt="CleanShot 2026-01-27 at 00 13 39@2x" src="https://github.com/user-attachments/assets/bc129b24-24c0-4ed0-9976-33035eef5630" />
61+
62+
Screenshots:
63+
<img width="1764" height="2274" alt="CleanShot 2026-01-27 at 00 12 32@2x" src="https://github.com/user-attachments/assets/5a22eb67-8cad-468e-b214-117ff70ed73e" />
64+
<img width="1764" height="2274" alt="CleanShot 2026-01-27 at 00 13 06@2x" src="https://github.com/user-attachments/assets/f893a8b2-35f6-4bc6-81ca-24e500e12232" />
65+
66+
## Web Interface Features
67+
68+
- **GPIO Control**
69+
- Configure pins as input or output
70+
- Read current states in real-time
71+
- Set output pins HIGH or LOW
72+
- Visual state indicators
73+
74+
- **ADC Monitoring**
75+
- Real-time plotting with automatic updates
76+
- Multiple channels displayed simultaneously
77+
- Voltage display (converted from raw values)
78+
- Configurable sample rate and buffer size
79+
80+
- **Console Log Viewer** (when enabled)
81+
- Live stdout output
82+
- ANSI color code support
83+
- Auto-scrolling display
84+
- Configurable buffer size
85+
86+
## API Endpoints
87+
88+
Programmatic access via JSON REST API:
89+
90+
```
91+
GET /api/gpio/get - Get all GPIO states and configurations
92+
POST /api/gpio/set - Set GPIO output state (JSON: {"pin": N, "value": 0|1})
93+
POST /api/gpio/config - Configure GPIO direction (JSON: {"pin": N, "mode": 1|3})
94+
GET /api/adc/data - Get ADC readings and plot data
95+
POST /api/logs/start - Start log capture (redirects stdout to file)
96+
POST /api/logs/stop - Stop log capture (restores stdout to /dev/console)
97+
GET /api/logs - Get console log content (text/plain with ANSI colors)
98+
```
99+
100+
Note: GPIO mode values are `1` for INPUT and `3` for INPUT_OUTPUT. OUTPUT mode (2) is automatically promoted to INPUT_OUTPUT for safety.

‎components/remote_debug/example/main/CMakeLists.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
idf_component_register(SRC_DIRS "."
2+
INCLUDE_DIRS "."
3+
PRIV_REQUIRES remote_debug wifi nvs file_system timer)

0 commit comments

Comments
 (0)