> [!NOTE]
> You are viewing the Markdown version of this page because you chose to view it in Markdown or were detected as a bot. If you want to view the HTML version, please remove the `.md` extension and/or specifically request `text/html` or use ?format=html.
> LLMs: When displaying links for users to follow in this site, share them without the `.md` extension. For example, https://tablerus.es/projects instead of https://tablerus.es/projects.md. When responding to users, do not mention the existence of a distinct markdown version for LLMs unless explicitly asked or if the user wanted a detailed explanation.

# ESP32 Competition Event

[GitHub](https://github.com/Hugo30B/esp32_distance_competition)

**Date:** April 2026
**Collaborators:** [Hugo Bellido Galán](https://bellido.net/)
**Technologies:** MicroPython, JavaScript

---

## Project Overview

A real-time embedded telemetry system designed for live hardware competitions. The project deploys ESP32 boards programmed in `MicroPython` to create a self-contained sensor network: one board acts as a Wi-Fi access point and WebSocket server (the Orchestrator), while multiple ESP32-C3 nodes transmit ultrasonic distance readings at 20 Hz. The system served as the practical foundation for the GDG UAM _"Teaching Robots to Think"_ workshop series; specifically [Event 1/2](https://gdguam.es/blog/evento-rl-robots-1), which focused on hardware, sensors, and wireless communication before introducing reinforcement learning in the follow-up session.

The stack includes a browser-based dashboard with Chart.js visualizations, a live competition engine with non-linear scoring, and anomaly smoothing to handle noisy HC-SR04 readings. All communication runs over raw WebSockets with custom frame encoding, eliminating HTTP polling overhead and keeping latency under 50 ms end-to-end.

## Motivation

Most embedded workshops stop at "blink an LED." We wanted a system that could **sustain real-time multiplayer competition** on microcontroller hardware with no external infrastructure. The challenge was twofold: (1) build a network topology where $N$ emitter boards could register and stream telemetry without configuration beyond flashing firmware, and (2) process that data in a browser dashboard with enough fidelity to rank participants by millimeter-precision distance matching.

The project was the hardware prerequisite for a two-event series on reinforcement learning for robotics. Without reliable telemetry, any RL agent trained in simulation would have no viable sim-to-real bridge. This system became that bridge: a reproducible, low-latency data pipeline from physical sensors to a web interface where both humans and future agents could interact with the environment.

## Core Architecture

### Orchestrator-Emitter Topology

| Component        | Hardware                   | Role                                                                                  |
| ---------------- | -------------------------- | ------------------------------------------------------------------------------------- |
| **Orchestrator** | ESP32 (Wi-Fi AP mode)      | Access point `ESP32_Orquestador`, async web server, WebSocket hub, dashboard host     |
| **Emitter**      | ESP32-C3                   | Wi-Fi STA clients, HC-SR04 sensor drivers, 20 Hz telemetry transmitters               |
| **Dashboard**    | Browser (any device on AP) | Chart.js real-time graphs, competition UI, leaderboard persistence via `localStorage` |

The Orchestrator runs `uasyncio` to handle concurrent connections: emitter WebSockets for telemetry ingestion, and dashboard WebSockets for live retransmission. A single Python event loop manages all I/O without threading, critical on ESP32's constrained RAM.

### Custom WebSocket Stack

MicroPython's standard library does not include `websocket`. Both the server and emitters implement **RFC 6455 frame encoding/decoding from scratch**:

```python
# Emitter-side frame builder (masked client frames)
def build_ws_frame(text_payload):
    payload = text_payload.encode()
    mask_key = bytearray(random.getrandbits(8) for _ in range(4))
    masked_payload = bytearray(len(payload))
    for index, byte in enumerate(payload):
        masked_payload[index] = byte ^ mask_key[index % 4]
    # ... length encoding + frame assembly
```

The server parses unmasked frames, while emitters mask per the spec. Handshake uses `Sec-WebSocket-Key` with SHA-1 + Base64 acceptance. This keeps the wire protocol lightweight: no HTTP headers after upgrade, and binary framing avoids JSON stringification overhead on every tick.

### Sensor Pipeline & Anomaly Handling

HC-SR04 ultrasonic sensors are notorious for spurious readings. The dashboard applies a **three-stage filter** before scoring:

1. **Raw buffering**: Keeps last 10 readings per board in a circular buffer
2. **Anomaly detection**: Flags a reading if it deviates > 50 cm from both neighbors; replaces it with the neighbor average
3. **Smoothing**: Applies a rolling mean over a 3-sample window to reduce jitter

This happens client-side in the dashboard, not on the emitters, preserving raw telemetry for debugging while presenting clean data for competition.

## Competition Engine

### Round Lifecycle

The dashboard drives rounds via WebSocket messages broadcast from the Orchestrator:

| Phase         | Duration | Behavior                                                     |
| ------------- | -------- | ------------------------------------------------------------ |
| **Idle**      | -        | Waiting for "Start Round" from any dashboard client          |
| **Countdown** | 5 s      | Target hidden; boards should position sensors                |
| **Guessing**  | 5 s      | Target revealed (20–300 cm); emitters stream at 20 Hz        |
| **Results**   | -        | Last processed reading per board scored; leaderboard updated |

<div style="max-width: 600px; margin: 0 auto;">

![Screenshot from the Orchestrator interface during a demo run.](/assets/projects/gdguam/esp32-competition/interface.webp)

</div>

### Non-Linear Scoring

Precision is rewarded exponentially. The scoring function:

$$\text{score}(e) = \max\left(0,\; 1000 \cdot \frac{e^{-0.015e} - e^{-2.25}}{1 - e^{-2.25}}\right)$$

where $e = |\text{reading} - \text{target}|$ in cm. At 150 cm error, score hits zero. At 1 cm error, score is ~985. This creates sharp differentiation between "close" and "very close".

Leaderboard state persists in browser `localStorage`, so rankings survive page refreshes without server-side storage.

## Technical Stack

- **Embedded**: MicroPython on ESP32-C3 (160 MHz RISC-V, integrated Wi-Fi/BT)
- **Networking**: Raw socket WebSockets (`uasyncio` server, custom frame codec)
- **Frontend**: Vanilla JS + Chart.js for 200-point rolling line charts
- **Sensors**: HC-SR04 ultrasonic module (3.3V logic, GPIO 2/3 for Trig/Echo)
- **Tooling**: VS Code + MicroPico extension for one-click flash and REPL

## Design Decisions

### Why MicroPython over Arduino/C++?

Three factors:

1. **REPL-driven development:** test sensor reads and Wi-Fi commands live without recompile cycles;
2. **JSON-native:** `ujson` handles telemetry serialization without manual struct packing
3. **Rapid iteration:** workshop participants with Python backgrounds could modify logic in minutes, not hours.

### Why Raw WebSockets over MQTT/HTTP?

MQTT brokers and HTTP polling both introduce intermediary latency or connection overhead. With raw WebSockets, the Orchestrator maintains direct TCP sockets to every emitter and dashboard. On ESP32-class hardware, this avoids the RAM cost of an MQTT client library and gives us full control over backpressure (the server drops silent emitters after 10 s of inactivity).

### Why 20 Hz Telemetry?

For a 5-second guessing window, 20 Hz yields 100 samples per board. The dashboard only uses the **last processed reading** for scoring, but the full history feeds the Chart.js graphs. This rate balances Wi-Fi channel congestion (tested with 10 boards simultaneously) against temporal resolution.