ESP8266 Ultrasonic Radar

IT: piccolo radar DIY basato su ESP8266, servo MG90S e sensore di distanza selezionabile, con visualizzazione live su pagina web generata direttamente dal dispositivo.

EN: a compact DIY radar built with an ESP8266, an MG90S servo and a selectable distance sensor, with a live web interface served directly by the device.

---

ITA

Panoramica

Questo progetto trasforma pochi componenti economici in una demo interattiva: il sensore ultrasonico ruota sul servo, misura la distanza degli ostacoli e aggiorna in tempo reale una UI stile radar nel browser.

E' pensato come progetto maker/showcase, ma la struttura del firmware lo rende anche una buona base di sperimentazione per sensori, telemetria e interfacce embedded.

Cosa fa

• scandisce da 10 a 170 gradi
• esegue una misura a ogni posizione angolare
• supporta sweep automatico e posizionamento manuale per taratura
• offre media runtime selezionabile in modalita' manuale
• espone una UI web direttamente dall'ESP8266
• aggiorna i dati live tramite endpoint /data
• prova la connessione Wi-Fi in STA e fa fallback in AP

Hardware

• Wemos D1 mini / board ESP8266
• servo MG90S
• sensore HC-SR04 oppure TOF200C
• alimentazione stabile
• cavi jumper
• supporto meccanico per il sensore

Configurazione firmware

La configurazione centrale ora vive in include/config.h. Da li puoi scegliere:

• sensore attivo: SENSOR_HC_SR04 oppure SENSOR_TOF200C
• pin servo e pin sensore
• pin I2C per TOF200C
• range angolare e timing loop
• numero campioni, aggregazione e filtro anti-spike
• modalita' AUTO / MANUAL, media manuale e timing del TOF200C
• distanza massima e timeout specifici del sensore

Se usi TOF200C, il firmware legge il sensore via I2C usando il driver VL53L0X all'indirizzo 0x29.

Collegamenti HC-SR04

• servo -> D5
• trigger ultrasuoni -> D6
• echo ultrasuoni -> D7 tramite partitore resistivo / level shifter

Nota: il servo va alimentato bene. Se usi un'alimentazione esterna, collega il GND in comune con l'ESP8266.

Nota importante: l'HC-SR04 porta tipicamente il pin ECHO a 5V, mentre l'ESP8266 lavora a 3.3V e non e' 5V tolerant. Inserisci un partitore resistivo o un level shifter tra ECHO e D7.

Schema di collegamento: docs/wiring-diagram.md

Collegamenti TOF200C

• servo -> D5
• TOF200C SDA -> D2
• TOF200C SCL -> D1
• TOF200C VIN -> 3.3V o 5V
• TOF200C GND -> GND
• TOF200C SHUT -> VCC oppure pin configurato in config.h
• TOF200C INT -> D7

Nota: TOF200C usa I2C e non richiede il partitore resistivo necessario per il pin ECHO dell'HC-SR04.

Stack software

• framework: Arduino
• ambiente: PlatformIO
• board target: d1_mini
• librerie: ESP8266WiFi, ESP8266WebServer, Servo
• sensori supportati: HC-SR04, TOF200C (VL53L0X)

Come funziona nel codice

Dal firmware in src/main.cpp:

• la scansione e' bidirezionale con inversione ai limiti
• MAX_CM e' la source of truth della portata massima
• il timeout eco deriva direttamente dalla distanza massima
• il sensore attivo e i relativi pin vengono scelti in include/config.h
• ogni angolo mantiene memoria dell'ultimo valore valido per il filtro anti-spike
• la UI e' embedded in PROGMEM, senza file statici esterni
• il browser ricostruisce l'effetto radar su canvas

In pratica l'ESP8266 fa sia da controller hardware sia da mini web server.

Configurazione rete

Le impostazioni di default stanno in include/secrets.h, mentre le credenziali locali possono stare in include/secrets.local.h (ignorato da Git). Parti da include/secrets.example.h:

#pragma once

#define WIFI_SSID "nome-wifi"
#define WIFI_PASS "password-wifi"
#define WIFI_HOSTNAME "esp8266-radar"

#define FALLBACK_AP_SSID "ESP8266-Radar"
#define FALLBACK_AP_PASS "12345678"

Se la connessione Wi-Fi fallisce entro circa 12 secondi, il dispositivo crea una propria rete in modalita' AP.

Build e upload

pio run
pio run -t upload
pio device monitor

Interfaccia web

La pagina servita dal dispositivo include:

• griglia radar su canvas
• sweep line opzionale
• persistenza visiva dei punti rilevati
• glow, scanlines e vignettatura in stile CRT/radar
• readout centrale di angolo e distanza
• informazioni di rete, IP, MAX_CM e timeout eco
• pagina Impostazioni dedicata ai parametri runtime
• controlli manuali per angolo, media e accettazione stati S1/S2
• statistiche manuali per l'angolo corrente: intervallo, delta, min/max, sigma, CV e stabilita'
• allarme a schermo quando il sensore non viene rilevato sul bus I2C

Payload tipico di /data:

{
  "a": 87,
  "d": 42.3,
  "mode": "STA",
  "ip": "192.168.1.50",
  "scan_mode": "MANUAL",
  "manual_angle": 90,
  "avg_window": 5,
  "max_cm": 50,
  "echo_to": 0,
  "ui_show_beam": 1,
  "tof_max_cm": 50,
  "tof_min_cm": 3
}

Parametri firmware attuali

• range angolare: 10 -> 170
• passo scansione: 0.5 gradi
• loop HC-SR04: 35 ms
• distanza massima TOF: 50 cm
• campioni per lettura: 1
• assestamento servo: 10 ms
• filtro anti-spike: disattivato
• periodo misura continua TOF: 12 ms

Pagina impostazioni

La pagina Impostazioni permette di modificare a runtime i parametri principali, raggruppati per sezione:

• Visualizzazione: UI_SHOW_BEAM
• Sweep: ANGLE_MIN, ANGLE_MAX, ANGLE_STEP_DEG, LOOP_PERIOD_MS, SERVO_SETTLE_MS
• TOF200C: TOF200C_MAX_CM, TOF200C_MIN_CM
• HC-SR04: HC_SR04_MAX_CM, HC_SR04_TIMEOUT_MARGIN_CM
• Filtro: ENABLE_SPIKE_FILTER, SPIKE_MAX_JUMP_CM

Idee future

• integrazione reale del modulo Bluetooth HC-05
• controlli runtime dalla UI web
• logging o streaming delle scansioni
• supporto a sensori multipli
• miglioramento della meccanica
• snapshot, heatmap e diagnostica avanzata

---

ENG

Overview

This project turns a few affordable components into an interactive demo: the ultrasonic sensor rotates on top of the servo, measures obstacle distance and updates a radar-style browser UI in real time.

It is meant as a maker/showcase project, but the firmware structure also makes it a solid base for experiments with sensors, telemetry and embedded web interfaces.

What it does

• scans from 10 to 170 degrees
• performs one measurement at each angular position
• supports automatic sweep and manual positioning for calibration
• provides runtime-selectable averaging in manual mode
• serves the web UI directly from the ESP8266
• pushes live data through the /data endpoint
• tries Wi-Fi in STA mode and falls back to AP

Hardware

• Wemos D1 mini / ESP8266 board
• MG90S servo
• HC-SR04 ultrasonic sensor or compatible module
• stable power supply
• jumper wires
• mechanical mount for the sensor

Firmware configuration

Central firmware settings now live in include/config.h. From there you can select:

• active sensor: SENSOR_HC_SR04 or SENSOR_TOF200C
• servo and sensor pins
• TOF200C I2C pins
• angular range and loop timing
• sample count, aggregation mode and anti-spike filter
• AUTO / MANUAL mode, manual averaging and TOF200C timing
• sensor-specific maximum range and timeout values

When TOF200C is selected, the firmware reads the sensor over I2C using the VL53L0X driver at address 0x29.

HC-SR04 wiring

• servo -> D5
• ultrasonic trigger -> D6
• ultrasonic echo -> D7 through a resistor divider / level shifter

Note: power the servo properly. If you use an external supply, make sure GND is shared with the ESP8266.

Important: the HC-SR04 usually drives ECHO at 5V, while the ESP8266 expects 3.3V logic and is not 5V tolerant. Add a resistor divider or level shifter between ECHO and D7.

Wiring reference: docs/wiring-diagram.md

TOF200C wiring

• servo -> D5
• TOF200C SDA -> D2
• TOF200C SCL -> D1
• TOF200C VIN -> 3.3V or 5V
• TOF200C GND -> GND
• TOF200C SHUT -> VCC or the pin configured in config.h
• TOF200C INT -> D7

Note: TOF200C uses I2C and does not need the resistor divider required by the HC-SR04 ECHO pin.

Software stack

• framework: Arduino
• environment: PlatformIO
• target board: d1_mini
• libraries: ESP8266WiFi, ESP8266WebServer, Servo
• supported sensors: HC-SR04, TOF200C (VL53L0X)

How the code works

From the firmware in src/main.cpp:

• scanning is bidirectional and reverses at the limits
• MAX_CM is the single source of truth for maximum range
• echo timeout is derived from the maximum distance
• the active sensor and its pinout are selected in include/config.h
• each angle stores its last valid reading for anti-spike filtering
• the UI is embedded in PROGMEM, so no external static files are needed
• the browser rebuilds the radar effect locally on canvas

In practice, the ESP8266 acts both as hardware controller and as a tiny web server.

Network configuration

Safe defaults are stored in include/secrets.h, while local credentials can live in include/secrets.local.h (ignored by Git). Start from include/secrets.example.h:

#pragma once

#define WIFI_SSID "your-wifi-name"
#define WIFI_PASS "your-wifi-password"
#define WIFI_HOSTNAME "esp8266-radar"

#define FALLBACK_AP_SSID "ESP8266-Radar"
#define FALLBACK_AP_PASS "12345678"

If Wi-Fi connection fails within about 12 seconds, the device starts its own AP network.

Build and upload

pio run
pio run -t upload
pio device monitor

Web interface

The page served by the device includes:

• radar grid on canvas
• optional sweep line
• point persistence
• glow, scanlines and vignette for a CRT/radar look
• central angle/distance readout
• network mode, IP, MAX_CM and echo timeout display
• dedicated Settings page for runtime parameters
• manual controls for angle, averaging and S1/S2 status acceptance
• per-angle manual stats: interval, delta, min/max, sigma, CV and stability
• on-screen alarm when the sensor is not detected on the I2C bus

Typical /data payload:

{
  "a": 87,
  "d": 42.3,
  "mode": "STA",
  "ip": "192.168.1.50",
  "scan_mode": "MANUAL",
  "manual_angle": 90,
  "avg_window": 5,
  "max_cm": 50,
  "echo_to": 0,
  "ui_show_beam": 1,
  "tof_max_cm": 50,
  "tof_min_cm": 3
}

Current firmware parameters

• angular range: 10 -> 170
• scan step: 0.5 degrees
• HC-SR04 loop period: 35 ms
• TOF max distance: 50 cm
• samples per reading: 1
• servo settle time: 10 ms
• anti-spike filter: disabled
• continuous TOF measurement period: 12 ms

Settings page

The Settings page now exposes the main runtime parameters grouped by purpose:

• Visual: UI_SHOW_BEAM
• Sweep: ANGLE_MIN, ANGLE_MAX, ANGLE_STEP_DEG, LOOP_PERIOD_MS, SERVO_SETTLE_MS
• TOF200C: TOF200C_MAX_CM, TOF200C_MIN_CM
• HC-SR04: HC_SR04_MAX_CM, HC_SR04_TIMEOUT_MARGIN_CM
• Filter: ENABLE_SPIKE_FILTER, SPIKE_MAX_JUMP_CM

Future ideas

• real HC-05 Bluetooth integration
• runtime controls from the web UI
• scan logging or streaming
• multiple sensor support
• improved mechanics
• snapshots, heatmaps and advanced diagnostics

---

Project Structure

.
|-- include/
|   `-- secrets.h
|-- LICENSE
|-- docs/
|   `-- wiring-diagram.md
|-- src/
|   `-- main.cpp
|-- platformio.ini
`-- README.md

License

This repository is released under the MIT license. See LICENSE.

Nice additions for GitHub

• a real build photo
• a browser scan GIF
• a wiring diagram
• a short demo video