gpio_viewer for ESP32: Live GPIO Monitoring in a Browser

Why GPIOViewer Runs on the ESP32

GPIOViewer addresses a specific embedded debugging problem: a developer needs to see GPIO state changing while an ESP32 sketch is running, without adding a separate instrumentation system or treating the application as a finished product. It is intended for makers, firmware developers, and educators working with ESP32 boards through Arduino or PlatformIO. The supported views cover digital, analog, PWM, and ADC pins, which lets one interface cover several common signal types.

The browser is the main observation surface. Once the ESP32 is connected to a Wi-Fi network, GPIOViewer starts an HTTP server and directs the developer to the board's printed IP address. If mDNS works on that network, the same server can be reached through `gpioviewer.local`. The web application can also use a generic view when the repository has no matching board image. That board-image catalogue is therefore a presentation feature, not a requirement for seeing GPIO activity.

This approach trades isolation for accessibility. The ESP32, phone, browser, Wi-Fi link, and web application all become part of the diagnostic path. It is useful during development, but the library does not remove the need to interpret pin ownership, sampling rate, or board-specific constraints.

From GPIO Sampling to the Browser View

The documented setup sequence is compact: declare a `GPIOViewer`, establish `WIFI_STA` connectivity when the sketch does not already do so, and call `begin()` at the end of `setup()`. The library then samples GPIO activity at a configurable interval. Its default is 100 milliseconds, while the commented example exposes a 25 millisecond setting. That interval controls how frequently state information is generated and transferred, so it directly affects update density and network pressure.

The default HTTP port is 8080. `setPort()` can change it, including when using an mDNS address. The README also says that web assets such as board images are loaded from GitHub Pages rather than embedded in every sketch. The README reports a 50 KB addition to projects for the library itself.

On ESP32 Core 3.x, GPIOViewer skips pins owned by active I2C, SPI, or UART peripherals by default. This prevents peripheral-managed pins from being presented as ordinary GPIO activity. Calling `setSkipPeripheralPins(false)` includes them, but that changes the diagnostic scope. A separate pin-function detection layer can conflict with some boards, including the XiaoESP32-S3-Sense. Defining `NO_PIN_FUNCTIONS` before the library header disables that detection and is the documented board-specific escape hatch.

Arduino IDE and PlatformIO Setup for GPIOViewer

For Arduino IDE 2, the README asks users to install the latest ESP32 boards through Board Manager, add GPIOViewer through Library Manager or the latest stable ZIP, and install both `ESPAsyncWebServer` and `AsyncTCP`. After installation, the main usage example places the header first, while the troubleshooting section suggests trying it after all other includes. The library expects Arduino-ESP32 Core 3.0.0 or newer.

PlatformIO needs extra care because the README says the official `espressif32` platform currently uses Arduino-ESP32 Core 2.x. It directs users to the `pioarduino` platform and the repository URLs for all three libraries:

[env:your_board]
platform = https://github.com/pioarduino/platform-espressif32/releases/download/stable/platform-espressif32.zip
board = <your-esp32-board>
framework = arduino

The dependency block declares the two async server repositories and GPIOViewer:

lib_deps =
    https://github.com/ESP32Async/ESPAsyncWebServer.git
    https://github.com/ESP32Async/AsyncTCP.git
    https://github.com/thelastoutpostworkshop/gpio_viewer.git

Replace `<your-esp32-board>` with the board's PlatformIO ID. The README requires running `PlatformIO: Clean` and building again after changing platforms, allowing PlatformIO to download the new platform. Every sketch still needs both `setup()` and `loop()`, even when `loop()` is empty.

Starting a Browser Session from an Arduino Sketch

The shortest documented sketch creates the global instance, opens a 115200 baud serial connection, connects Wi-Fi when required, and ends setup with `begin()`. The credentials below are placeholders from the README and must be replaced by the reader:

#include <gpio_viewer.h>
GPIOViewer gpio_viewer;

void setup()
{
  Serial.begin(115200);
  gpio_viewer.connectToWifi("Your SSID network", "Your WiFi Password");
  gpio_viewer.begin();
}

void loop()
{
}

The serial monitor should provide the server address after the connection starts. Open that address in a browser, or try the documented mDNS form when the network permits it:

http://gpioviewer.local:8080

Two optional calls are worth noting before deployment. `setSamplingInterval()` changes the default 100 millisecond interval, while `setPort()` changes the default 8080 port. Their comments in the README show both calls, and any mDNS URL must use the selected port. If the sketch already creates a `WIFI_STA` connection, the README says to omit `connectToWifi()`. `WIFI_AP` and `WIFI_AP_STA` are not supported.

The library assets are fetched remotely, so the working browser also depends on access to the asset host named by the README. The project does not document a fully offline asset mode.

Sampling, Queueing, and Compatibility Limits

A shorter interval gives the web application more frequent samples but increases the chance of a network or processing bottleneck. The README reports that a 25 millisecond interval works well with Wi-Fi 6 at 125 Mbps in its stated environment. That is not a universal Wi-Fi requirement. Its actual warning is the serial-monitor message `ERROR: Too many messages queued`, which means the web application is not reading data quickly enough. Displayed data may remain available while gaining latency. The documented response is to reduce sampling activity or improve Wi-Fi performance.

Core compatibility is a hard boundary. Current GPIOViewer requires Arduino-ESP32 Core 3.x. Projects that need Core 2.x are directed to GPIOViewer 1.6.3. The troubleshooting section identifies v3.3.11 of ESP32 Arduino Core, v3.5.0 of Async TCP, and v3.12.0 of ESP Async WebServer as the versions last documented as working. Those are troubleshooting baselines, not an assurance for every board or future release.

The alternative debugging approach is to rely on the Serial Monitor rather than the browser application. That removes the browser and Wi-Fi display path, but it does not provide GPIOViewer's documented digital, analog, PWM, and ADC board view. GPIOViewer is the wrong tool when serial output is the accepted debugging interface, when the network cannot support the chosen interval, or when a board-specific function detector causes the documented conflict. `NO_PIN_FUNCTIONS` addresses the latter by sacrificing pin-function detection.

Release History, Licensing, and Update Work

The repository is not archived, and its last push was on 2026-08-16. The release list includes GPIOViewer v1.7.1 on 2025-12-13, v1.7.0 on 2025-10-24, and v1.6.3 on 2025-05-03. This history supports paying close attention to Core compatibility before an upgrade: v1.6.3 is preserved as the documented option for Arduino-ESP32 Core 2.x, while current installation guidance requires Core 3.0.0 or newer.

The library is distributed under the MIT License. For an engineer, that means the repository provides a permissive license, but the license text remains the controlling document for redistribution, notices, warranty disclaimers, and other obligations. This review does not interpret the license for a specific product or deployment.

Upgrades are not limited to replacing GPIOViewer. PlatformIO users may need to clean and rebuild after changing the Arduino-ESP32 platform. Arduino users are advised to use the latest stable GPIOViewer release and latest ESP32 boards. If the web UI behaves incorrectly, the README first recommends clearing the browser cache and refreshing the page. If compilation fails, it recommends checking include order before filing an issue. These are specific maintenance steps tied to the library's asynchronous server stack, Core dependency, and browser-delivered assets.

Editorial conclusion

gpio_viewer suits ESP32 developers who want browser-based GPIO inspection while debugging a connected project. It does not fit deployments without Wi-Fi STA, AP-only networks, or Arduino-ESP32 Core 2.x projects that are not pinned to GPIOViewer 1.6.3. Before adoption, verify the board and peripheral ownership, confirm the Core and async server versions, and test the intended sampling interval on the actual Wi-Fi network.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. thelastoutpostworkshop/gpio_viewer on GitHub