Monitor Dashboard

Cette documentation décrit de manière exhaustive l’architecture, le fonctionnement et les procédures de maintenance du projet PiAware Monitor. Pour utiliser ce projet, il faut disposer d’un raspberry équipé du système Piaware de FlightAware. Ce document est structuré pour offrir une lecture technique fluide et un apprentissage pas-à-pas pour tout développeur ou administrateur système.

Introduction et Objectifs du Projet

PiAware Monitor est une application web locale (local-first) offrant un tableau de bord analytique et géographique des données de trafic aérien captées par un récepteur ADS-B (typiquement un Raspberry Pi équipé de PiAware / dump1090).

Vision Globale et Contexte

L’application agit comme une surcouche intelligente à dump1090. Au lieu de se contenter d’afficher le trafic instantané, PiAware Monitor historise les données, génère des statistiques, croise les identifiants OACI (Hex IDs) avec des bases de données externes (Planespotters, HexDB, Wikimedia) pour récupérer le type d’appareil et des photographies, et intègre des calques météorologiques (RainViewer) en temps réel.

Problématiques Résolues

• Volatilité des données ADS-B : Par défaut, dump1090 ne conserve pas l’historique des vols. PiAware Monitor intègre une base de données locale (SQLite) assurant une rétention configurable.
• Manque d’enrichissement visuel : dump1090 est basique. Ce projet ajoute des photos, le nom des compagnies aériennes, la météo radar dynamique et des trophées (records d’altitude, de vitesse).
• Consommation d’API externe : Une stratégie agressive de mise en cache locale (tuiles cartographiques, JSON de détails, images) est mise en place pour limiter le trafic externe et prévenir les blocages (rate-limiting).

Valeur Ajoutée Technique

• Autonomie (Local-First) : Le cœur fonctionnel repose sur le réseau local (piaware.local). Les dépendances externes (météo, photos) dégradent gracieusement en cas de perte de connexion internet.
• Architecture robuste : Backend Python Flask léger, séparation des responsabilités entre la collecte (Worker ADS-B), le stockage (Manager SQLite) et la présentation (API REST).

Manuel Utilisateur – PiAware Monitor

Bienvenue dans le manuel d’utilisation de PiAware Monitor. Ce document vous guidera à travers les différentes fonctionnalités de votre tableau de bord interactif, conçu pour enrichir et visualiser les données de votre récepteur ADS-B PiAware.

---

1. Accéder au Tableau de Bord

Une fois le serveur PiAware Monitor démarré, l’interface est accessible depuis n’importe quel appareil connecté à votre réseau local (ordinateur, tablette, smartphone).

1. Ouvrez votre navigateur web préféré (Chrome, Firefox, Safari, etc.).
2. Dans la barre d’adresse, tapez l’adresse IP de la machine hébergeant le moniteur suivie du port 8000.

• Exemple : http://192.168.1.50:8000

Vous arriverez directement sur l’interface principale présentant la carte de suivi en direct.

---

2. Découvrir l’Interface Principale

L’interface a été pensée pour être à la fois lisible et riche en informations. Elle se divise en plusieurs zones clés :

• La Carte Interactive (Vue Principale)
  • La carte au centre de l’écran affiche en temps réel la position de tous les aéronefs captés par votre antenne.
  • Les avions se déplacent dynamiquement. Vous pouvez zoomer et vous déplacer sur la carte à l’aide de votre souris ou de vos doigts sur un écran tactile.
  • Bouton de Recadrage : Un bouton permet de recentrer rapidement la carte sur votre zone de couverture optimale.

• Le Panneau Latéral (Liste des Aéronefs)
  • Situé sur le côté, ce panneau liste tous les avions actuellement visibles.
  • Il offre un résumé rapide pour chaque vol : l’identifiant (Hex ID ou Callsign), l’altitude, et la vitesse.
  • Ce panneau a été récemment optimisé pour une clarté maximale, en supprimant les données redondantes de l’en-tête.

• La Météo Radar en Direct
  • Une surcouche météorologique (via RainViewer) est superposée à la carte, vous permettant de voir les conditions de précipitations (pluie, neige) directement sous le trajet des avions.

---

3. Explorer les Détails d’un Vol

Pour en savoir plus sur un avion spécifique, il vous suffit de cliquer sur son icône sur la carte ou sur sa ligne dans le panneau latéral.

• Photographie de l’Appareil : Le système interroge automatiquement des bases de données comme Planespotters ou Wikimedia pour afficher la meilleure photo disponible du modèle exact de l’avion.
• Informations Enrichies : Vous y trouverez le type d’appareil précis, la compagnie aérienne associée, ainsi que les données télémétriques détaillées (cap, taux de montée/descente).

---

4. Statistiques et « Trophées »

PiAware Monitor ne se contente pas du direct : il historise vos données dans une base locale.

• Historisation Automatique : Chaque vol capté est enregistré.

• Le Mur des Trophées : Le système calcule et enregistre les records absolus captés par votre station. Vous pouvez consulter les « Trophées » pour découvrir :
  • L’avion passé à la plus haute altitude.
  • L’avion ayant enregistré la vitesse la plus élevée.
  • L’avion capté le plus loin de votre position (record de distance).

---

5. Le Mode « Vue ATC » (Tour de Contrôle)

Pour les passionnés d’aviation, une vue alternative est disponible : La Vue ATC.

• Cette vue transforme votre écran en un écran radar classique de contrôleur aérien.
• L’affichage est simplifié, sur fond sombre, avec des tracés radar verts, mettant en valeur les trajectoires et les étiquettes de vol de manière hautement contrastée.
• Idéal pour être laissé en plein écran sur un moniteur dédié dans une pièce sombre.

---

En Cas de Problème

• Aucun avion sur la carte : Vérifiez que votre récepteur matériel (clé SDR, antenne) est bien branché, et que le service PiAware officiel tourne correctement. Assurez-vous également que l’IP configurée dans config.json est la bonne.
• Pas de météo : Vérifiez que la machine exécutant le moniteur dispose d’une connexion internet active pour récupérer les calques radar.
• Affichage incorrect : N’hésitez pas à rafraîchir la page (F5) ou à vider le cache de votre navigateur web.

Bon vol virtuel avec votre PiAware Monitor !

Architecture et Structure Logicielle

L’application repose sur une architecture Monolithique Modulaire de type Client-Serveur léger (Flask pour le backend, JS vanille pour le frontend).

Choix de Conception

• Backend (Python / Flask) : Choisi pour sa légèreté, sa vaste écosystème d’intégration et sa facilité de déploiement sur des systèmes embarqués (Raspberry Pi).
• Base de données (SQLite) : Parfaitement adaptée aux lectures/écritures locales de faible concurrence. Élimine le besoin d’un serveur SGBD lourd (type PostgreSQL).
• Frontend (Vanilla JS / CSS) : Minimise la taille des assets, garantit une exécution rapide sur des navigateurs clients aux ressources limitées.

Arborescence du Projet

/home/pi/env_gravity/piaware/
├── app.py                 # Point d'entrée principal (Serveur Flask, Routes API, Gestion du cache tuiles)
├── database.py            # ORM léger et requêtes SQLite (Classe DatabaseManager)
├── piaware_monitor.py     # Client d'interrogation de l'API JSON locale dump1090/PiAware
├── flight_history.db      # (Généré) Base de données SQLite de production
├── config.json            # Configuration utilisateur (Coordonnées, IP PiAware, Rétention)
├── requirements.txt       # Dépendances Python (Flask, requests, rich)
├── start.sh / stop.sh     # Scripts Bash pour le contrôle du démon de l'application
├── data/
│   └── airports.csv       # (Généré) Cache CSV des aéroports locaux
├── cache/                 # Dossier de mise en cache dynamique (Généré)
│   ├── details.json       # Cache persistant des métadonnées avions (photos, types)
│   └── tiles/             # Tuiles cartographiques et météo (OSM, CartoDB, RainViewer)
├── static/                # Assets Frontend servis par Flask
│   ├── css/style.css      # Feuille de style principale
│   └── js/app.js          # Logique applicative côté client (Cartographie, requêtes API)
└── templates/             # Vues HTML (Jinja2)
    ├── index.html         # Tableau de bord principal et carte en temps réel
    ├── atc.html           # Vue "Air Traffic Control" (radar classique)
    ├── history.html       # Historique tabulaire des vols captés
    └── stats.html         # Graphiques analytiques et trophées

Flux de Données (Data Flow)

1. Acquisition : À chaque requête frontend (polling), app.py sollicite PiAwareClient (piaware_monitor.py) qui effectue une requête HTTP vers http://<PIAWARE_IP>:8080/data/aircraft.json.
2. Traitement : Les données JSON brutes sont parsées, filtrées (validation des altitudes, calcul des distances 3D), et transformées en objets Dataclass Python.
3. Persistance : Les objets sont passés à DatabaseManager (database.py). La méthode update_flight insère les nouveaux vols ou met à jour les maximums (vitesse, altitude) des vols existants (UPSERT logique).
4. Enrichissement (Asynchrone/Lazy) : Lorsqu’un utilisateur clique sur un vol, le frontend appelle /api/details/<hex>. Le backend interroge d’abord details.json (Cache). Si vide, il cascade les appels : Planespotters -> HexDB -> Wikimedia, puis met en cache le résultat.

Gestion des Dépendances et Prérequis

Prérequis Système et Matériel

• Matériel : Un Raspberry Pi (3B, 4B ou 5) ou toute machine Linux (Debian/Ubuntu recommandé).
• Réseau : Accès local au récepteur PiAware (IP fixe ou piaware.local).
• Python : Version 3.9 ou supérieure.

Dépendances Logicielles (requirements.txt)

• Flask==3.0.3 : Framework web WSGI léger.
• requests==2.31.0 : Bibliothèque HTTP pour interroger PiAware, Rainviewer et les API de métadonnées.
• rich==13.7.0 : Utilisé (potentiellement) pour les affichages CLI esthétiques et le logging.

Note : La bibliothèque standard Python (sqlite3, json, math, shutil, pathlib) est massivement utilisée pour limiter les dépendances externes, améliorant ainsi la robustesse et la sécurité.

Guide de Déploiement et Mode Opératoire

Installation Pas-à-Pas (Environnement Linux/Raspberry OS)

1. Clonage ou copie des fichiers : Placez le dossier piaware dans le répertoire utilisateur (ex: /home/pi/piaware).
2. Création de l’environnement virtuel :

   cd /home/pi/piaware
   python3 -m venv venv
   source venv/bin/activate

3. Installation des dépendances :

   pip install -r requirements.txt

4. Configuration initiale : Éditez (ou créez) le fichier config.json à la racine :

   {
       "PIAWARE_IP": "127.0.0.1",
       "RECEIVER_LAT": 48.8566,
       "RECEIVER_LON": 2.3522,
       "HISTORY_RETENTION_DAYS": 30,
       "REFRESH_RATE": 5
   }

Remplacez PIAWARE_IP par l’IP de votre récepteur, et RECEIVER_LAT / RECEIVER_LON par vos coordonnées géographiques exactes.

Démarrage et Contrôle

L’application inclut des scripts bash pour un contrôle aisé en tâche de fond.

• Démarrer l’application :

  ./start.sh

Le serveur écoutera sur le port 8000 (accessible via http://<IP_DU_PI>:8000). Les logs seront redirigés vers app.log.

• Arrêter l’application :

  ./stop.sh

Guide de Maintenance et Robustesse

Tolérance aux Pannes

• API Externes : Tous les appels réseaux externes (tuiles météo, API d’images) sont encapsulés dans des blocs try/except avec un timeout=5. Si une API (ex: Planespotters) tombe, l’application retourne une image transparente ou un statut silencieux sans faire crasher l’interface ni le serveur.
• Cache de Tuiles Cartographiques : La fonction tile_cache de app.py sauvegarde les PNG OSM/CartoDB localement (/cache/tiles). Une fois une région téléchargée, l’application peut fonctionner presque intégralement hors-ligne (Air-Gapped).

Gestion de la Base de Données (Purge et Rotation)

La base flight_history.db est auto-maintenue.

• Routine de nettoyage : Toutes les 100 requêtes API globales (compteur interne cleanup_counter dans app.py), la méthode cleanup_history(days) est appelée.
• Sécurité des données : Cette purge est intelligente. Elle supprime les vols vieux de X jours (HISTORY_RETENTION_DAYS) SAUF s’ils détiennent un record absolu (vitesse max, altitude max de toute la base). Cela garantit que les « Trophées » de la page Statistiques ne sont jamais perdus.

Logs et Debug

• Les erreurs système et exceptions API sont écrites dans app.log.
• Le niveau par défaut est configuré sur INFO via logging.basicConfig(level=logging.INFO) dans app.py. Pour du debug, modifiez cette valeur à logging.DEBUG.

Améliorations et Évolutions Futures (Roadmap)

Optimisations de la Dette Technique

1. Migration vers une file d’attente asynchrone (Celery/RQ) : Actuellement, le téléchargement des images et la vérification des API se font au sein de la requête synchrone Flask (/api/details/<hex>). Pour éviter le blocage du thread (Worker), il serait pertinent de déporter ces appels lourds vers un Worker asynchrone (Redis/RQ).
2. WebSockets pour le Temps Réel : Remplacer le polling HTTP (intervalle de 5 secondes) du frontend par des WebSockets (Flask-SocketIO). Cela réduirait drastiquement la charge CPU et réseau sur le Raspberry Pi.
3. Indexation SQLite : Ajouter des index B-Tree sur les colonnes souvent requêtées comme max_altitude et last_seen pour améliorer les performances de la page historique lorsque la base dépasse les 100 000 entrées.

Nouvelles Fonctionnalités

• Alertes (Push/Email) : Possibilité de configurer des filtres (ex: « Alerte si Hélicoptère de la sécurité civile à moins de 5km » ou « Alerte si avion en code Squawk 7700 (Urgence) »).
• Export CSV/JSON : Ajout d’un bouton sur l’interface pour extraire l’historique brut afin que les utilisateurs puissent réaliser leurs propres tableaux croisés dynamiques (Excel/PowerBI).
• Support Multi-Récepteurs : Capacité d’agréger les flux JSON de plusieurs dump1090 sur un même réseau local.

Qu’est-ce que PiAware de FlightAware ?

PiAware est une plateforme logicielle développée par FlightAware qui permet de créer sa propre station de réception radar au sol. Elle sert à recevoir, décoder et partager les données de trafic aérien (ADS-B).

En participant au réseau, les utilisateurs aident à suivre les vols en temps réel à travers le monde. En échange du partage de leurs données, FlightAware offre aux contributeurs un compte premium gratuit (d’une valeur d’environ 90$/mois) donnant accès à des fonctionnalités avancées sur leur site.

---

1. La Partie Matérielle (Hardware)

Une station PiAware repose sur des composants physiques accessibles au grand public. Voici les éléments nécessaires pour construire son propre récepteur :

• L’Ordinateur central : Raspberry Pi
  • Généralement un Raspberry Pi 3, 4 ou Zero 2 W.
  • C’est le « cerveau » qui héberge le système d’exploitation et fait tourner les logiciels en permanence (24h/24, 7j/7).
  • Nécessite une carte MicroSD pour stocker le système, ainsi qu’une alimentation stable.
• Le Récepteur Radio : Clé USB RTL-SDR
  • La technologie SDR (Software-Defined Radio) permet de capter des fréquences radio à l’aide d’un composant USB bon marché.
  • FlightAware commercialise ses propres modèles optimisés : les Pro Stick et Pro Stick Plus (reconnaissables à leur couleur orange ou bleue), qui intègrent des amplificateurs spécifiques pour l’ADS-B.
• L’Antenne et les Câbles
  • Une antenne accordée spécifiquement sur la fréquence de 1090 MHz (la fréquence sur laquelle les avions transmettent leurs données).
  • Plus l’antenne est placée haut et de manière dégagée (sur un toit, par exemple), meilleure sera la portée (pouvant atteindre plus de 400 kilomètres).
  • Un câble coaxial à faible perte est utilisé pour relier l’antenne à la clé USB SDR.
• Filtre (Optionnel mais recommandé)
  • Dans les zones urbaines, les antennes de téléphonie mobile (GSM, 4G, 5G) peuvent créer des interférences. Un filtre passe-bande à 1090 MHz permet de bloquer ces bruits parasites pour ne garder que le signal des avions. (Le Pro Stick Plus possède déjà ce filtre en interne).

---

2. La Partie Logicielle (Software)

Les composants matériels ne seraient rien sans une suite logicielle performante pour traiter le signal. L’écosystème logiciel de PiAware est composé de plusieurs éléments clés :

• Le Système d’Exploitation (OS)
  • Le système est généralement basé sur Raspberry Pi OS (une distribution Linux Debian).
  • FlightAware propose une image système « prête à l’emploi » (PiAware SD Card Image) qui contient déjà tout le nécessaire préinstallé, facilitant grandement la vie des débutants.
• Dump1090-fa (Le Décodeur)
  • C’est le moteur du système. dump1090 dialogue avec la clé USB SDR pour écouter les signaux radio analogiques.
  • Il décode ensuite ces signaux bruts en données exploitables, extrayant l’identifiant de l’avion, sa position GPS (latitude/longitude), son altitude, sa vitesse et son cap.
• Le Client PiAware (Le Transmetteur)
  • Ce service logiciel fonctionne en arrière-plan. Il récupère les informations décodées par Dump1090 et établit une connexion sécurisée avec les serveurs de FlightAware.
  • Il transmet le flux de données en continu, contribuant ainsi à la couverture mondiale du site FlightAware.com.
• SkyAware / Tar1090 (L’Interface Locale)
  • PiAware héberge son propre petit serveur web local.
  • En se connectant à l’adresse IP du Raspberry Pi via un navigateur (ex: http://<ip-du-pi>:8080), l’utilisateur accède à SkyAware (ou Tar1090, une interface plus avancée souvent utilisée). C’est une carte interactive qui affiche en direct les avions captés uniquement par sa propre antenne.
• Multilatération (MLAT)
  • Le logiciel intègre un client MLAT. Certains avions (souvent plus anciens ou militaires) n’émettent pas leur position GPS exacte, mais seulement un identifiant.
  • Le client envoie les signaux bruts avec un horodatage extrêmement précis à FlightAware. En croisant les réceptions de plusieurs antennes PiAware différentes, les serveurs de FlightAware peuvent calculer la position de cet avion par triangulation, une fonctionnalité très puissante.

En Résumé

PiAware est le mariage parfait entre la bidouille électronique accessible (Raspberry Pi + clé SDR) et un logiciel réseau optimisé. Il permet à n’importe quel passionné d’aéronautique de participer activement à l’un des plus grands réseaux de suivi de vols participatifs au monde, tout en disposant de son propre « radar » personnel à la maison.