Sparklet

A little screen for a lot of compute.

Sparklet turns a Waveshare ESP32-C6 AMOLED touchscreen into a native, Wi-Fi-connected companion for sparkDash. Swipe through your DGX nodes, check GPU allocation and temperature, and see which model is running—all from a small display on your desk.

One node at a time. Real metrics from your existing server. No server changes.

V1 status: phone setup and live five-node operation have been demonstrated on the actual board. V1 implements the daily-use dashboard and has passed bounded setup, transport, memory and interaction checks. The earlier USB stall recovered after physical reconnection; its cause was not isolated. See the validation report. The 24-hour soak test is explicitly excluded.

1.1.0 (source): Sparklet now runs as one app next to a launcher on the esp32-playground platform. Migration, switching and the new buttons were checked on the actual board; see Launcher platform.

On the real device

These close-ups are cropped from real device photographs of an earlier development build. The desk, hands and cable are outside the crop; the photographed UI is unchanged.

Head node	Worker node	Node details

The missing-glyph rectangle visible in these photos was subsequently addressed with display-only punctuation normalization. The corrected dash and navigation/dim-wake behavior were subsequently confirmed on the physical device. The cover above is an original generated illustration; the photos preserve the actual recorded screen content. Asset provenance

What it does

• Browse your cluster: discover up to 16 nodes in server order; swipe or tap arrows, with wraparound navigation.
• Read the useful numbers: GPU allocation, available memory, utilization, temperature and power; CPU, root storage and network rates in Details.
• Understand node roles: show the first available LLM backend on head/standalone nodes and the head relationship on workers.
• Set up with your phone: scan a Wi-Fi QR, scan the setup-page QR, then enter your local network and server details.
• Turn the screen: automatic rotation through all four orientations, with aligned touch controls and a saved Settings toggle (source build; not included in the v1.0.0 bundle).
• Keep running independently: saved settings, automatic reconnect, cached data during outages and adjustable inactivity dimming.

Sparklet is read-only. It does not shut down, wake, update or otherwise control DGX nodes. “Received Ns ago” describes HTTP receipt time, not collector sample age. Missing values and valid zero are handled separately.

Hardware

Component	Configuration
Board	Waveshare ESP32-C6-Touch-AMOLED-2.16
Display	480 × 480 AMOLED, capacitive touch
Network	Personal 2.4 GHz Wi-Fi
Framework	ESP-IDF 5.5.3, target esp32c6
UI	LVGL 9; partial rendering with 11,520-byte draw and rotation buffers (23,040 bytes total)
Power	Primarily USB
Server	Existing sparkDash HTTP API; default http://dgx01.local:5555

This firmware targets that exact board. Its schematic-corrected display CS and touch interrupt are GPIO15 and GPIO5, respectively. Do not reuse an ESP32-S3 or another display-size pin map. Hardware details · Provenance

Get started

Sparklet 1.1.0 requires the platform layout described in Running with the launcher. The v1.0.0 firmware bundle and checksums is a standalone single-app image: flashing it replaces the platform layout, including the launcher, so it is only a downgrade path.

With firmware installed:

1. Scan the display's join setup Wi-Fi QR code and accept joining SparkDash-XXXX.
2. Stay connected when your phone reports “No Internet Connection.” Tap Next: setup page and scan the URL QR, or open http://192.168.4.1.
3. Enter your personal 2.4 GHz Wi-Fi credentials and sparkDash URL in the local portal.
4. Save, wait for connection, then browse nodes with swipes or the arrow buttons.

The temporary setup password changes each session. Saved credentials survive ordinary firmware updates. The firmware currently keeps the on-device sparkDash label and the SparkDash-XXXX setup SSID; Sparklet is the project/repository name.

Full user guide · Connection troubleshooting

Running with the launcher

The esp32-playground platform splits the 16 MiB flash into a launcher (factory partition at 0x20000), the sparklet app slot (ota_0, 4 MiB at 0x220000), a reserved hermes slot and shared NVS. The platform bootloader starts the selected app; the launcher shows one tile per installed app. Sparklet's saved Wi-Fi, server and display settings stay in NVS namespace sparkdash and survive app switches and Sparklet updates.

Input	Action in Sparklet
Settings → Apps	Opens the launcher
KEY short press	Opens the launcher
BOOT held for 1 s	Opens the launcher
PWR short press	Dims the screen, or wakes it
KEY held while the board resets	The platform bootloader starts the launcher instead of Sparklet

In the launcher, tap the Sparklet tile or press KEY to return. Unplugging and replugging resumes Sparklet if it was running; after leaving through the launcher, a power cycle shows the launcher. The launcher's Device → Reset settings erases the saved settings of every app, including Sparklet's connection. Holding PWR for about 6 s is configured to power the board off through the PMIC; that was not exercised.

To install:

1. A device not yet on the platform layout, such as one running Sparklet 1.0.0, must first be migrated with the platform repository. Follow its migration procedure (fresh full backup, tools/device.py migrate). Saved Sparklet settings were preserved by the observed migration.
2. Build Sparklet (below), then write only the Sparklet slot from a checkout of the platform repository at PLATFORM:

uv run PLATFORM/tools/device.py install sparklet firmware/sparkdash/build

device.py compares the build's partition table with the one on the device, refuses a device that has not been migrated, and never writes NVS, the launcher or the bootloader.

Build and test

Install the pinned ESP-IDF SDK outside the repository and activate its export.sh. From this repository's root:

idf.py -C firmware/sparkdash build

cmake -S tests/host -B tests/host/build
cmake --build tests/host/build
ctest --test-dir tests/host/build --output-on-failure
python3 tests/host/test_http_fixtures.py

The dependency lock and build defaults are committed. The platform contract sdkconfig.defaults.platform is applied before sdkconfig.defaults, and partitions.csv is the platform's layout; both must stay byte-identical to the platform copies or configuration fails. Shared-code tests use address/undefined-behavior sanitizers. Two separate build directories produced identical candidate firmware binaries; that is separate from runtime acceptance.

Flash only the Sparklet slot, from firmware/sparkdash with the discovered port:

idf.py -p PORT sparklet-flash

idf.py flash and app-flash deliberately fail in this project: they would overwrite the launcher and reset the boot selection.

For hardware discovery, install uv and run:

uv run scripts/esp32_serial.py list

Read the build/flash guide and the platform's USB instructions before flashing. Preserve a verified full backup, select the correct USB identity, and use generated flash arguments. Opening USB serial can reboot the display. Factory and custom-snapshot restoration have been physically tested; backups remain private and outside Git.

Documentation

Start with the complete documentation index.

Guide	Covers
User guide	QR setup, controls, metric interpretation, Settings, rotation and dimming
Architecture and API	Task ownership, bounded parsing, data mappings, polling and NVS
Development	Pinned SDK, reproducible inputs and normal/QA builds
Testing	Host tests, real ESP32 failure tests, live API comparison and physical acceptance
Release and operations	Bundles, checksums, flashing, diagnostics and troubleshooting
Validation status	Verified results, failed checks and remaining work
Platform	Launcher, flash layout, board hardware, USB rules and recovery
Bring-up notes	Hardware discoveries and implementation evidence

Project layout

firmware/sparkdash/     ESP-IDF application and shared core (board code comes from the platform)
scripts/               USB discovery and bounded serial monitoring
tests/host/           Shared-code sanitizer and HTTP fixture tests
tools/                Mock server, device validators and release packager
docs/                 User/developer guides and visual assets
notes/                Reviewed hardware and validation history

Generated builds, releases, raw logs, flash backups and local configuration are ignored. They are not part of the published source or public screenshots.

Scope and credits

V1 focuses on the everyday node-card experience. Over-the-air updates, charts/history, automatic slideshows, MQTT, Home Assistant, remote actions, audio, SD storage and battery management are outside this release. The IMU is used only for automatic rotation.

Built around the sparkDash API and the Waveshare board integration, with ESP-IDF, LVGL and their managed components. awesome-esp informed the initial exploration. The research notes and source provenance record the underlying references and license limitations; no blanket license grant for all upstream material is implied.