Aller au contenu principal

V0.4.0 — Détection des Caméras sur le réseau

Publiée le 02/10/2026.

Documentation fonctionnelle

Ce que change la version pour les collaborateurs

Pourquoi​

Pour ajouter une Caméra, l’Administrateur devait connaître et coller son URL RTSP complète, sans même savoir quelles adresses avaient prises les caméras branchées, ni sur quel sous-réseau chercher. Et l’API, enfermée dans Docker, ne voit pas les prises réseau de la machine.

Ce qu'on peut faire maintenant​

  • Détecter des Caméras depuis l’Administration : en une dizaine de secondes, la liste des Candidats (IP, port), c’est-à-dire les hôtes des sous-réseaux autorisés qui répondent en RTSP, protégés par mot de passe ou non. ArgOS lui-même n’y figure jamais.
  • Les Candidats qui sont déjà des Caméras du Site sont rangés dans « Déjà configurées (n) », repliée, avec leur nom.
  • Des messages clairs quand la Détection n’est pas configurée, quand son réglage est invalide (plafond de 1024 adresses), quand une Détection est déjà en cours, ou quand aucun Candidat n’est trouvé. Le reste d’ArgOS marche dans tous les cas.
  • Le script scripts/cameras/configurer-detection.sh (Linux et macOS), lancé sur la machine hôte, demande une fois la prise des caméras, puis recalcule son sous-réseau dans .env à chaque lancement. lancer-argos.command l’appelle tout seul.
  • Les Caméras simulées sont désormais trois conteneurs RTSP sur le port 554, dont un avec identifiants, déclarés par compose.simulation.yaml, absent de la prod.
  • Une doc pédagogique : Réseau du Site et Détection des Caméras (adresses, sous-réseaux, DHCP, adresses d’usine, service systemd).
  • Diagnostic : l’API renvoie le statut RTSP et l’en-tête Server de chaque Candidat, et journalise chaque Détection.

Documentation technique

Spec versionnée : docs/specs/v0.4.0-detection-des-cameras.md

Issue parente : #18

V0.4.0 — Détection des Caméras sur le réseau

Problem Statement​

Pour ajouter une Caméra, l'Administrateur doit aujourd'hui connaître et coller son URL RTSP complète. Sur un vrai Site, il ne sait même pas quelles adresses ont pris les caméras branchées sur le réseau, ni sur quel sous-réseau chercher : la machine Linux qui héberge ArgOS a une ou plusieurs prises Ethernet, et l'API, enfermée dans Docker, ne voit pas ces prises. Côté dev, les trois Caméras simulées sont trois chemins d'un seul conteneur (mediamtx:8554/camN), ce qui ne ressemble pas à de vraies caméras et ne permettrait pas d'en détecter trois.

Solution​

Depuis l'Administration, l'Administrateur lance une Détection : pendant une dizaine de secondes un chargement s'affiche, puis la liste des Candidats, c'est-à-dire les hôtes des sous-réseaux autorisés qui acceptent une connexion sur un port caméra et répondent en RTSP. Ceux qui correspondent déjà à une Caméra du Site sont rangés dans une liste repliée. Rien n'est ajouté ni stocké : l'ajout depuis un Candidat arrive en 0.4.1.

Les sous-réseaux autorisés sont calculés à chaque lancement par un script lancé sur la machine hôte : il demande une fois quelle(s) prise(s) relient les caméras, puis relit leur adresse à chaque démarrage. Une doc pédagogique explique de A à Z le réseau du Site et ce que fait la Détection.

Les Caméras simulées deviennent trois conteneurs distincts sur le port 554, comme de vraies caméras (l'une protégée par un identifiant), sur leur propre réseau, déclarés par un fichier Compose de simulation absent de la prod.

User Stories​

Détection dans l'Administration​

  1. En tant qu'Administrateur, je veux un bouton « Détecter des Caméras » dans l'Administration, pour trouver les caméras branchées sur le réseau sans connaître leurs adresses.
  2. En tant qu'Administrateur, je veux voir un état « Détection en cours… » pendant la Détection, pour savoir qu'il faut attendre.
  3. En tant qu'Administrateur, je veux voir la liste des Candidats (adresse IP et port), triée par adresse, pour savoir quelles caméras répondent.
  4. En tant qu'Administrateur, je veux que les Candidats qui correspondent déjà à une Caméra du Site (active ou désactivée) soient rangés dans une liste « Déjà configurées (n) » repliée par défaut, avec le nom de la Caméra, pour me concentrer sur les nouvelles sans croire que les autres manquent.
  5. En tant qu'Administrateur, je veux un message clair quand aucun Candidat n'est trouvé, pour savoir que la Détection a bien tourné.
  6. En tant qu'Administrateur, je veux voir sur quel(s) sous-réseau(x) la Détection a cherché, pour comprendre ce qu'elle a couvert.
  7. En tant qu'Administrateur, je veux un message « Détection non configurée » qui renvoie à la doc et au script, quand aucun sous-réseau n'est autorisé, pour savoir quoi faire.
  8. En tant qu'Administrateur, je veux un message explicite quand la configuration de la Détection est invalide (plage trop grande, notation incorrecte), pour la corriger.
  9. En tant qu'Administrateur, je veux qu'une seconde Détection lancée pendant la première soit refusée avec un message, pour ne pas inonder le réseau.
  10. En tant qu'Administrateur, je veux qu'une caméra protégée par un mot de passe apparaisse quand même comme Candidat, pour ne rater aucune caméra.
  11. En tant qu'Administrateur, je veux que le serveur ArgOS lui-même (le pont vidéo) n'apparaisse jamais comme Candidat, pour ne voir que des caméras.
  12. En tant qu'Administrateur, je veux que la Détection soit réservée à une session connectée, pour qu'un inconnu du réseau ne puisse pas faire balayer le réseau par ArgOS.
  13. En tant qu'Administrateur, je veux que le reste d'ArgOS (Live, Administration) fonctionne même si la Détection est mal configurée, pour qu'un réglage raté ne coupe pas la surveillance.

Diagnostic​

  1. En tant que développeur, je veux que l'API renvoie pour chaque Candidat le statut RTSP reçu et l'en-tête Server annoncé, sans que l'UI les affiche, pour diagnostiquer une caméra récalcitrante.
  2. En tant que développeur, je veux que chaque Détection écrive dans les journaux de l'API une ligne par Candidat et une ligne de bilan (sous-réseaux, ports, durée, nombre), pour retrouver ce qui s'est passé avec docker compose logs api.

Configuration des sous-réseaux​

  1. En tant qu'installateur, je veux un script qui, au premier lancement, me liste les prises réseau de la machine avec leur sous-réseau et me demande laquelle relie les caméras, pour ne pas avoir à comprendre la notation réseau.
  2. En tant qu'installateur, je veux que le script ne me demande rien quand une seule prise est candidate, pour aller vite.
  3. En tant qu'installateur, je veux que mon choix de prise soit retenu, et que le sous-réseau soit recalculé à chaque lancement, pour que la Détection suive un changement d'adresse sans reconfigurer.
  4. En tant qu'installateur, je veux que le script écarte les réseaux de Docker, la boucle locale et les adresses 169.254.x.x, pour ne me proposer que de vraies prises.
  5. En tant qu'installateur, je veux un avertissement clair quand la prise retenue n'a pas d'adresse (câble débranché, pas de DHCP), pour comprendre pourquoi la Détection n'est pas configurée.
  6. En tant qu'installateur, je veux que le script refuse une plage de plus de 1024 adresses en expliquant pourquoi, pour ne pas lancer une Détection interminable.
  7. En tant qu'installateur, je veux pouvoir écrire les sous-réseaux à la main dans .env en repli, pour garder la main.
  8. En tant que développeur sur Mac, je veux que le lanceur de dev appelle le script avant de démarrer la stack, pour que la Détection marche dès le lancement.
  9. En tant qu'installateur, je veux que la doc explique comment faire lancer le script puis ArgOS à chaque démarrage de la machine Linux (service systemd d'exemple), pour que le bon sous-réseau soit pris après chaque redémarrage.
  10. En tant qu'installateur, je veux pouvoir changer la liste des ports sondés pour les caméras, pour couvrir un modèle exotique.

Caméras simulées​

  1. En tant que développeur, je veux trois Caméras simulées qui sont trois hôtes distincts sur le port 554, pour que la Détection les trouve comme de vraies caméras.
  2. En tant que développeur, je veux qu'une des Caméras simulées exige un identifiant et un mot de passe documentés, pour préparer l'ajout avec identifiants (0.4.1) et vérifier qu'elle est détectée quand même.
  3. En tant que développeur, je veux que les Caméras simulées, leur réseau et le sous-réseau à détecter soient déclarés dans un fichier Compose de simulation séparé, pour qu'aucune trace de simulation n'existe dans une stack de prod.
  4. En tant que développeur, je veux que le lanceur de dev et les tests démarrent la stack avec la simulation, pour avoir des Caméras à détecter et à regarder.
  5. En tant que développeur, je veux regarder les Caméras simulées par le Live d'ArgOS (elles ne sont plus publiées sur la machine), pour garder une seule porte vers les Flux.
  6. En tant que développeur, je veux que tous les tests et docs qui utilisaient mediamtx:8554/camN passent aux nouvelles Caméras simulées, pour ne rien laisser de cassé.

Documentation​

  1. En tant qu'Administrateur non spécialiste du réseau, je veux une doc qui explique adresse IP, sous-réseau et notation /24, comment trouver son sous-réseau sur la machine Linux (une ou deux prises), pourquoi Docker ne voit pas les prises, ce que fait exactement la Détection et ce qu'elle ne fait pas, le piège « qui donne une adresse aux caméras » (DHCP, adresses d'usine courantes), le démarrage automatique et le cas du dev, pour pouvoir comprendre et expliquer ce qu'on fait.
  2. En tant que développeur, je veux que le glossaire définisse Détection et Candidat, et ajuste Caméra simulée, pour parler le même langage.
  3. En tant que développeur, je veux une ADR « Détection depuis le réseau bridge : sous-réseaux déclarés », pour savoir pourquoi l'API ne découvre pas seule le réseau et ce que ça implique pour l'adresse MAC (0.4.2).
  4. En tant que développeur, je veux que docs/securite.md décrive la Détection (ce qu'elle envoie, à qui, plafond, réservée à l'Administrateur), pour ne pas oublier qu'ArgOS agit activement sur le réseau.
  5. En tant que développeur, je veux que la feuille de route décrive la 0.4.0 et prévoie « Plus tard — Configuration initiale du Site » (réglages dans l'Administration), pour garder le plan juste.
  6. En tant que nouveau venu, je veux que le README et le schéma des Flux reflètent les Caméras simulées en conteneurs, la Détection et le script, pour lancer et comprendre le Site.

Implementation Decisions​

  • Glossaire :
  • Critère de Candidat : connexion TCP acceptée sur un port caméra, puis requête RTSP OPTIONS (sans chemin ni identifiants) dont la réponse commence par une ligne de statut RTSP, quel que soit le statut. Port ouvert sans réponse RTSP → pas un Candidat. Pas de DESCRIBE (0.4.1).
  • Exclusions : les adresses d'ArgOS lui-même (le pont MediaMTX, l'API) ne sont jamais des Candidats ; identifiées sans aucune référence à la simulation.
  • « Déjà configurée » : un Candidat correspond à une Caméra (active ou désactivée) si l'adresse IP résolue de l'hôte de son URL RTSP et le port sont les mêmes. Résolution de nom faite par l'API.
  • Configuration, uniquement par l'environnement, toute au thème caméras :
    • ARGOS_DETECTION_CAMERAS_INTERFACES : prise(s) retenue(s) par le script (lue par le script seulement).
    • ARGOS_DETECTION_CAMERAS_SOUS_RESEAUX : sous-réseaux IPv4 en notation CIDR, séparés par des virgules ; écrite par le script à chaque lancement, éditable à la main.
    • ARGOS_DETECTION_CAMERAS_PORTS : ports sondés, défaut 554,8554.
    • Plafond : 1024 adresses au total. Réglage vide, invalide ou au-delà du plafond → l'API démarre quand même, seule la Détection est indisponible avec la raison.
  • Contrat de l'API (session requise, 401 sinon) :
    • GET /api/detection : état de la configuration (configurée ou non, sous-réseaux, ports, raison si indisponible), pour que l'UI sache quoi afficher avant le clic.
    • POST /api/detection : lance une Détection synchrone et renvoie sous-réseaux, ports, durée et Candidats (ip, port, statut_rtsp, serveur, Caméra correspondante \{id, nom\} ou null), triés par IP puis port. Non configurée ou invalide → 409 avec la raison ; une Détection déjà en cours → 409 avec un message distinct.
    • Concurrence bornée et délai court par hôte, pour qu'un /24 sur deux ports tienne en une dizaine de secondes.
  • Rien n'est stocké : pas de table, pas de migration. Les Candidats sont éphémères.
  • Journaux : une ligne par Candidat (IP, port, statut, Server) et une ligne de bilan par Détection, sur la sortie de l'API.
  • Module de Détection à interface étroite : sous-réseaux, ports, adresses exclues et délai en entrée ; Candidats en sortie. Le rapprochement avec les Caméras se fait à côté.
  • UI (Administration) : section « Détecter des Caméras » : bouton, chargement, sous-réseaux couverts, tableau des nouveaux Candidats (IP, port), liste repliée « Déjà configurées (n) » avec le nom de la Caméra, messages « aucun Candidat », « non configurée » (renvoi au script et à la doc), « invalide », « déjà en cours ». Pas de bouton d'ajout. Statut RTSP et Server non affichés.
  • Script de configuration (thème caméras, dans un dossier de scripts rangé par thème) : bash, Linux (ip) et macOS (ifconfig). Liste les prises avec une adresse IPv4 privée, écarte boucle locale, interfaces Docker et 169.254.0.0/16. Premier lancement en terminal : demande la ou les prises (pas de question s'il n'y en a qu'une) et les retient dans .env. Chaque lancement : recalcule le(s) sous-réseau(x) des prises retenues et les écrit dans .env ; prise sans adresse → réglage vidé et avertissement ; plage > 1024 adresses → refus expliqué. Sans terminal (démarrage automatique), ne pose aucune question et garde la prise retenue.
  • Lanceur de dev (lancer-argos.command) : appelle le script puis démarre la stack avec le fichier de simulation.
  • Caméras simulées : trois conteneurs camera-simulee-1 à -3, chacun diffusant son camN.mp4 en boucle sans réencodage, en RTSP sur le port 554, sur un chemin unique. camera-simulee-2 exige un identifiant et un mot de passe de dev, documentés avec les vidéos. Non publiées sur la machine hôte. Réseau Compose dédié cameras-simulees à sous-réseau fixe (172.30.0.0/24), rejoint par l'API (Détection, sonde) et le pont (relais).
  • Fichier Compose de simulation, superposé au fichier principal : porte les trois Caméras simulées, leur réseau, et complète ARGOS_DETECTION_CAMERAS_SOUS_RESEAUX de l'API avec le sous-réseau de simulation (même mécanique d'interpolation que MTX_WEBRTCADDITIONALHOSTS). La stack de prod (fichier principal seul) ne contient aucune trace de simulation : plus de chemins cam1–cam3 ni de ffmpeg dans la config MediaMTX, qui ne fait plus que le pont (ADR 0001 inchangée sur le fond).
  • ADR 0002 — Détection depuis le réseau bridge : sous-réseaux déclarés : l'API reste en réseau bridge Docker ; elle joint le réseau local par NAT mais ne voit ni les prises ni les adresses MAC. Alternative écartée : network_mode: host (voit tout, mais casse les noms Compose et ne se comporte pas pareil sous Docker Desktop). Conséquence : sous-réseaux déclarés via le script hôte ; la 0.4.2 (identité par MAC) devra obtenir la MAC autrement.
  • Doc pédagogique : un document dans un dossier de docs du thème caméras (premier dossier par thème ; les docs existantes ne bougent pas), lié depuis le README et docs/securite.md, avec le service systemd d'exemple dans le texte (aucun fichier installé).
  • Sécurité : nouveau paragraphe « Détection » dans docs/securite.md.
  • Feuille de route : 0.4.0 à jour ; nouvelle entrée « Plus tard — Configuration initiale du Site » (sous-réseaux, ports, origines… réglés dans l'Administration).

Testing Decisions​

  • Un bon test vérifie un comportement observable (réponse HTTP, écran, contenu de .env écrit par le script), jamais la structure interne du module de Détection ni ses appels réseau.
  • tests/api/ (HTTP contre la stack lancée avec la simulation), prior art : tests Caméras 0.2.0 et pont 0.3.0. Couvre : GET /api/detection configurée ; POST trouve les trois Caméras simulées (dont celle à identifiant) ; ni la base ni le pont parmi les Candidats ; une Caméra déclarée sur une Caméra simulée → son Candidat porte la Caméra correspondante ; statut_rtsp et serveur présents ; seconde Détection simultanée → 409 ; sans session → 401.
  • tests/web/ (pytest-playwright), prior art : tests Administration 0.3.0. Couvre : clic, chargement, liste des Candidats, liste « Déjà configurées » repliée puis dépliée.
  • Script : tests pytest qui lancent le script avec une fausse commande réseau (sorties ip / ifconfig préenregistrées) et un .env temporaire. Couvre : une seule prise → pas de question ; prise retenue → sous-réseau recalculé ; Docker, boucle locale et 169.254 écartés ; prise sans adresse → réglage vidé et avertissement ; plage > 1024 → refus.
  • tests/flux/ : les Caméras simulées sont sondées depuis le réseau Compose (elles ne sont plus publiées) ; celle à identifiant est lisible avec et refusée sans.
  • Les tests existants qui utilisaient mediamtx:8554/camN migrent vers les nouvelles Caméras simulées.
  • Mêmes règles qu'avant : jamais d'effacement de la base, noms uniques par test puis nettoyage ; /t lance toutes les racines de test-roots (rôle complété si une nouvelle racine apparaît).

Out of Scope​

  • Ajouter une Caméra depuis un Candidat, tester un Flux avec identifiants, gérer le 401, preview (0.4.1).
  • Saisie manuelle d'une IP ou URL pour un appareil non détecté.
  • Adresse MAC, identité stable (0.4.2).
  • Réglage des sous-réseaux et ports dans l'Administration (« Configuration initiale du Site », plus tard).
  • Mettre en place un serveur DHCP sur la machine Linux (expliqué dans la doc seulement).
  • IPv6, ONVIF / WS-Discovery, mDNS, lecture du switch.
  • Historique des Détections, Détection planifiée.

Further Notes​

  • Sous Docker Desktop (Mac, dev), le script trouve aussi le réseau de la box : tout appareil RTSP de la maison apparaîtra comme Candidat, ce qui est attendu.
  • OPTIONS ne demande généralement pas d'identifiants : la Détection ne peut pas dire si une caméra est protégée ; c'est le rôle de la 0.4.1.
  • Contexte : feuille de route de dev (section 0.4.0), spec 0.3.0, ADR 0001, docs/securite.md, docs/features/reseau/schema-flux.md.