Blipputer — Live Plane Scanner Radar for M5Stack Cardputer / Cardputer ADV

Radar in stile ATC che mostra il traffico aereo reale intorno a una posizione di riferimento, usando WiFi + l'API pubblica di OpenSky Network (nessun modulo RF 1090MHz richiesto: niente ADS-B via SDR, tutto via rete).

Articolo di presentazione: Blipputer: un radar aerei sul Cardputer, senza SDR

Come funziona

1. Il Cardputer si connette al WiFi.
2. Ogni REFRESH_MS (default 20s) interroga opensky-network.org/api/states/all con un bounding box calcolato intorno alla posizione "home" (fissa da config.h, oppure dal GPS — vedi sotto).
3. Per ogni aereo calcola distanza (haversine) e rilevamento (bearing) dalla posizione di casa, poi li disegna come radar: anelli di distanza, lettere cardinali, blip colorati per quota (rosso <2000m, giallo medio, ciano >9000m).

Setup

1. Copia include/config.example.h in include/config.h (quest'ultimo è ignorato da git apposta — contiene la password del tuo WiFi, non va mai committato) e imposta:
   • WIFI_SSID / WIFI_PASSWORD (rete di partenza — puoi comunque cambiare rete in qualsiasi momento dal dispositivo, vedi tasto w sotto)
   • HOME_LAT / HOME_LON (default: Milano — cambiali con la tua posizione esatta per letture precise; usati anche come fallback se il GPS non ha fix)
   • opzionale: OPENSKY_USER / OPENSKY_PASS se hai un account gratuito OpenSky (alza il rate limit rispetto all'accesso anonimo)
   • GPS_RX_PIN / GPS_TX_PIN / GPS_BAUD: il GPS non è vincolato al Cap LoRa-1262 — qualsiasi modulo GPS/GNSS che parli NMEA su UART va bene, basta collegarlo a due pin liberi e impostare questi tre valori di conseguenza (default già pronti per il Cap LoRa-1262: G15/G13 a 115200 baud)
   • opzionale: SD_SPI_*_PIN / LOG_DIR per la registrazione dati su microSD (default già impostati per lo slot del Cardputer)
2. Apri la cartella in VS Code con PlatformIO installato.
3. Collega il Cardputer via USB-C, poi PlatformIO: Upload.

Schermate (i per passare alla successiva)

1. Lista voli (schermata iniziale) — elenco dei voli nel raggio impostato, ordinati dal più vicino. Ogni riga mostra callsign, distanza e quota. Selezionando un volo (,/.) il pannello sotto mostra distanza, rilevamento, quota, velocità e tendenza (salita/discesa/livello) — tutti dati già presenti nella risposta OpenSky, senza chiamate aggiuntive.

Premendo l sul volo selezionato parte una ricerca extra (una singola richiesta a adsbdb.com, gratuita) per recuperare costruttore, modello e immatricolazione dell'aereo — dato che OpenSky non lo fornisce. Viene fatta solo per il volo che selezioni esplicitamente, per non rallentare l'app con una richiesta per ogni aereo in lista. Il risultato resta in cache finché non selezioni un aereo diverso.

2. Radar — vista classica a cerchi concentrici. Il cerchio radar è tenuto volutamente compatto e spostato a sinistra, separato da una linea verticale dal pannello informazioni a destra, per non affollare lo schermo.

3. Stato — schermata di debug e controllo, compatta:

• Batteria: percentuale (BATT xx%, con + se in carica)
• WiFi: connesso/disconnesso, IP, RSSI. Premendo w si apre il menu reti WiFi: scansiona le reti disponibili, permette di sceglierne una (digitando la password da tastiera se serve) e la salva in memoria per i riavvii successivi — comodo per passare alla rete di casa a un hotspot del telefono quando sei in giro, senza dover riflashare config.h
• Registrazione su SD: stato scheda SD, tasto s per avviare/fermare la registrazione dei dati mostrati a schermo in un file CSV (vedi sezione dedicata sotto)
• OpenSky: se i dati stanno arrivando (FLOWING / STALE / NONE YET), ultimo codice HTTP, conteggio fetch riusciti/tentati, aerei grezzi vs mostrati, eventuale messaggio d'errore
• GPS (richiede il modulo Cap LoRa-1262, o altro GPS collegato secondo GPS_RX_PIN/GPS_TX_PIN): stato fix, numero satelliti, coordinate se disponibili. Premendo g puoi passare la posizione "home" usata dal radar tra quella manuale (fissa, da config.h) e quella GPS (live) — utile se usi il Cardputer in mobilità. Se il GPS non ha ancora un fix, g non fa nulla finché non arriva.

4. Aiuto — elenco completo dei comandi, comodo ora che sono diventati parecchi. Premi i di nuovo per tornare alla lista voli.

Registrazione dati su microSD

Con una microSD FAT32 inserita, il tasto s sulla schermata di stato avvia la registrazione: viene creata la cartella /blipputer (se non esiste, nome configurabile via LOG_DIR in config.h) e un nuovo file CSV per la sessione, con nome basato su data/ora GPS se disponibile. Ad ogni aggiornamento dati riuscito viene scritta una riga CSV per ogni aereo visibile: timestamp, posizione home, ICAO24, callsign, lat/lon, quota, velocità, rotta, rateo verticale, distanza e rilevamento — esattamente ciò che è mostrato a schermo in quel momento. Un indicatore rosso REC compare su tutte le schermate mentre la registrazione è attiva.

Controlli da tastiera

Tasto	Azione
+ / -	cambia raggio radar (20 / 50 / 100 / 200 km)
, / .	seleziona aereo/rete precedente/successiva
r	forza un refresh immediato
i	passa tra lista voli → radar → stato → aiuto → lista voli
l	(nella lista) cerca modello/costruttore del volo selezionato
g	(nella schermata stato) passa la posizione home tra manuale e GPS
w	(nella schermata stato) apre il menu reti WiFi
s	(nella schermata stato) avvia/ferma la registrazione su SD
invio	(nel menu WiFi) connette alla rete selezionata / conferma la password
`	(nel menu WiFi) annulla / torna indietro
f	(nel menu WiFi) ripristina la rete di default da config.h

Note sui limiti API

L'accesso anonimo a OpenSky è rate-limited (~400 crediti/giorno, 4 crediti a richiesta bbox). Non scendere sotto i 15-20s di REFRESH_MS o esaurirai la quota in fretta. Un account gratuito OpenSky alza il limite.

Uso con M5Launcher (bmorcelli)

Se vuoi installare il radar come "app" dentro Launcher (https://bmorcelli.github.io/Launcher/) invece di flasharlo come firmware principale:

1. Flasha Launcher una tantum (sovrascrive il firmware attuale): apri https://bmorcelli.github.io/Launcher/webflasher.html con Chrome o Edge (serve WebSerial), collega il Cardputer via USB-C, seleziona la board e segui il flasher. Al riavvio comparirà il menu di Launcher.
2. Compila il radar come al solito: pio run da PlatformIO. Il file da installare è .pio/build/cardputer/firmware.bin (il binario "nudo", non un merged/bootloader).
3. Installa l'app:
   • Via SD card (FAT32): copia il .bin sulla SD, inseriscila nel Cardputer, in Launcher vai su SD → naviga fino al file → Install. Launcher crea/assegna da solo una partizione adatta.
   • Via WebUI (senza toccare la SD): in Launcher vai su CFG → WebUI, apri l'indirizzo IP mostrato a schermo da un browser sulla stessa rete WiFi, e carica lì il .bin.
4. Avvia l'app dal menu principale di Launcher, selezionandola come qualsiasi altra della lista.

Note:

• Se il binario non entra nella partizione di default, in CFG → Change Partition Scheme puoi allargare lo spazio (il nostro firmware usa WiFi + HTTPS + JSON, non è piccolissimo).
• Non usiamo SPIFFS: se Launcher chiede di installarlo, rispondi No.
• Per tornare a un Cardputer dedicato solo al radar (senza il menu Launcher in mezzo), basta riflashare firmware.bin direttamente da PlatformIO come prima — questo sovrascrive Launcher.

M5Burner

Il repo include quanto serve per pubblicare Blipputer su M5Burner:

• m5burner.json — manifest con nome, descrizione, versione e categoria firmware.
• firmware/ — i quattro binari già agli indirizzi di flash corretti (verificati dalla build, non a caso): bootloader_0x0.bin, partitions_0x8000.bin, boot_app0_0xe000.bin, blipputer_0x10000.bin.
• assets/blipputer_icon_square.png — icona 1024×1024 senza scritta, per chi serve un formato quadrato pulito (oltre a blipputer_icon.png con il wordmark, usata nel README).

Nota: M5Burner ha due percorsi di pubblicazione distinti, non documentati in dettaglio da M5Stack:

1. Upload diretto dall'app (USER CUSTOM → Publish): basta caricare firmware/blipputer_0x10000.bin come firmware e un'icona come cover image, senza bisogno del manifest.
2. Catalogo ufficiale: fork di m5stack/M5Stack-Firmware, aggiunta di questo repository a firmware-repo.list, pull request — è qui che contano m5burner.json e la cartella firmware/.

Possibili estensioni

• Cache locale per evitare richieste duplicate quando non ci si sposta.
• Allarme sonoro/vibrazione quando un aereo entra sotto una certa quota/distanza.
• Passare a un provider con più dettagli (es. ADSBexchange) se serve maggiore copertura o frequenza di aggiornamento.
• Filtro aereo/volo + LoRa Meshtastic (in progettazione): una watchlist ICAO24/callsign che, quando un aereo tracciato fa match, ne trasmette i dati su un canale Meshtastic privato via la radio SX1262 del Cap LoRa-1262 (oggi usato solo per il GPS).

Licenza

MIT — vedi LICENSE