Serving a fully functional public website on a microcontroller with just 520 KB of RAM and a $25 parts bill sounds like a stretch. Yet HelloESP pulls it off by flipping the usual architecture: instead of exposing the ESP32 directly to the internet, it uses a persistent outbound WebSocket connection to a Cloudflare Worker, which relays HTTPS requests in and streams responses back. This keeps the device safely behind NAT with no open inbound ports, while delivering live sensor data, a guestbook, an embedded Snake game, and an admin panel — all from the same tiny device.
Architecture and core functionality of HelloESP
HelloESP is a complete public website running entirely on an ESP32 microcontroller. The device serves over 200 endpoints, including static assets like HTML, CSS, and images, dynamic content such as live sensor readings (temperature, humidity, pressure, eCO₂, VOC), interactive features like a guestbook and a Snake game with leaderboards, and an admin panel for configuration and management.
The architecture centers around the ESP32 maintaining a persistent outbound WebSocket connection to a Cloudflare Worker deployed at the edge. This Worker acts as a relay proxy: it accepts HTTPS requests from the public internet, forwards them over the WebSocket to the ESP32, and streams the ESP32’s responses back to the client. This approach avoids exposing the ESP32 directly to inbound connections, keeping it behind NAT and firewall.
Real-time updates flow via Server-Sent Events (SSE) pushed through the Worker, enabling live sensor data and status badges that anyone can embed. The badges report uptime, temperature, and power draw without adding load to the ESP32 itself thanks to caching at the Cloudflare edge.
The ESP32’s firmware is designed to be lightweight and efficient, fitting within 520 KB of RAM and running on inexpensive hardware (approximately $25 total). Storage-heavy assets and data, like the guestbook and over 200 endpoints, live on an SD card accessible to the device. Integration with Shelly smart plugs optionally provides live power monitoring, cost, and CO₂ tracking, and a Chronicle system logs owner notes with optional cross-posting to X/Twitter.
Technical strengths and design tradeoffs
HelloESP’s standout technical feature is its use of a persistent outbound WebSocket tunnel to a Cloudflare Worker as the sole internet-facing interface. This inversion of the typical client-server model solves a long-standing problem: how to safely expose a low-power, behind-NAT microcontroller to the public internet without static IPs, port forwarding, or security risks.
The Cloudflare Worker relay is lightweight but powerful, forwarding requests and pushing SSEs without burdening the device or requiring complex NAT traversal protocols. This design means the ESP32 never has to accept inbound connections, which significantly reduces attack surface and complexity.
The firmware itself is surprisingly feature-rich given the constrained environment. It handles over 200 endpoints, including admin-only routes, and supports live sensor data streaming, interactive games, and a guestbook. The use of an SD card for assets and data offloads flash storage requirements, increasing flexibility and ease of updates.
Tradeoffs include the dependency on Cloudflare Workers — while optional, this does centralize part of the system externally. The persistent WebSocket connection requires robust handling of disconnections and reconnections, which adds complexity to the firmware. The 520 KB RAM limit and CPU power limit what can run locally, so the design carefully balances functionality with resource constraints.
The use of Server-Sent Events rather than WebSockets for live updates keeps the device’s network stack simpler. SSEs are unidirectional and fit well with the model of pushing sensor data and status updates to clients.
Overall, the code quality and architecture reflect a pragmatic approach to embedded web serving: minimal dependencies, clear separation between device and edge relay, and extensive use of caching to scale beyond the low-power hardware’s raw capabilities.
Setup and installation steps
To get HelloESP running, the README provides clear instructions for firmware upload, SD card preparation, and optional Cloudflare Worker deployment:
git clone https://github.com/Tech1k/helloesp.git
cd helloesp
pio run -t upload
This requires PlatformIO installed and configured for the ESP32 target.
Next, format a FAT32 SD card (up to 32 GB) and copy the contents of the data/ directory from the repo to the SD card’s root. Note that data/ is not included in the firmware flash but lives on the SD card.
Configure your network and credentials by renaming config.example.txt to config.txt on the SD card and filling in your Wi-Fi SSID, password, admin user and password, and timezone. The config supports optional Cloudflare Worker URLs and keys for public access.
If you want to expose the device publicly via Cloudflare, you’ll also set up the Worker relay following the README’s instructions. This step is optional — running locally on LAN is supported.
The firmware upgrade path is well documented, including notes about migrating guestbook data if upgrading from versions before 1.4.
Who should consider HelloESP and final thoughts
HelloESP is a compelling project for embedded developers and hobbyists interested in exposing low-power microcontrollers as full-featured public web servers without compromising security or requiring complex network setups.
Its architecture offers a neat blueprint for safe IoT exposure, leveraging Cloudflare Workers for relay and caching while preserving a minimal device footprint. The project balances rich functionality with tight resource constraints, demonstrating what’s possible on mid-range ESP32 hardware.
Limitations include the reliance on Cloudflare for public access (though local LAN use is fully supported), the complexity of the persistent WebSocket relay, and the inherent ceiling imposed by the ESP32’s RAM and CPU.
If you want to learn how to serve a dynamic, interactive website from a tiny device behind NAT, or build similar IoT applications with live data streaming and secure public exposure, HelloESP is worth a close look. The codebase is mature with over 350 commits and a well-documented setup.
It’s not a turnkey commercial solution, but it’s a valuable reference for embedded web servers, edge relay patterns, and secure IoT architectures.
Related Articles
- Waveshare Watch Rust firmware: efficient no_std embedded Rust for ESP32-S3 AMOLED smartwatch — A no_std Rust firmware replacing C/C++ for the Waveshare ESP32-S3 AMOLED smartwatch, achieving >99% CPU sleep with async
- Real-time flight control on ESP32: how drone_meishi runs a 500 Hz IMU fusion and PID loop alongside WebSocket I/O — drone_meishi runs a 500 Hz IMU fusion and PID control loop with 20 kHz motor PWM on ESP32, while handling WebSocket joys
- frp: a fast, extensible reverse proxy evolving towards cloud-native architecture — frp is a Go-based reverse proxy enabling NAT traversal with TCP/UDP/HTTP support and P2P mode. Its upcoming V2 rethinks
- tinyCore: An open-source ESP32-S3 educational development board with full hardware transparency — tinyCore offers a fully open hardware ESP32-S3 board designed for embedded systems education, with complete KiCad/Altium
- Crawlee: a TypeScript library for stealthy web scraping and browser automation — Crawlee is a TypeScript library for web scraping and browser automation with human-like stealth. Supports Playwright, Pu
→ GitHub Repo: Tech1k/helloesp ⭐ 369 · HTML