Funzioni del box: cosa fanno e chi usa il risultato

Ricognizione del 29/10/2026 sul codice di mdm_installation (origin/main 3.2.9 e origin/stage 3.9.0), cercando le funzioni del box poco o per nulla documentate e controllando, per ognuna, se il risultato arriva a qualcuno (midserver, pannello, qAlarm, sistema vecchio). Nessuna prova sul campo, salvo dove indicato.

Riepilogo

Funzione	Linee	Funziona?	Il risultato arriva a qualcuno?	Dettaglio
Anti-manomissione (telecamera coperta o spostata)	entrambe	sì, con limiti	no	pagina dedicata
Rilevamento incendio e fumo	entrambe	no: analizza e poi scarta	no	sotto
Ritardo dell'ingresso di allarme GANZ (monitoring_ganz_alarm_in)	main letto, stage non usato	—	—	sotto
Pulizia del disco (clean_disk)	entrambe	in parte	—	sotto
Inserimento e disinserimento automatico a orario	stage	da provare	eventi verso midserver e Telegram	sotto
Rifiuto dell'inserimento con componenti critici non sani	stage	da provare	evento dedicato	sotto
Eventi del box e Telegram diretto dal box	stage	da provare	MQTT verso midserver e Telegram	sotto
Controlli di salute e azioni di ripristino	stage	controlli sì, ripristino non collegato	eventi di guasto	sotto
Protezione delle API /api/v1 (allarmi, inserimento, panico)	stage	da verificare subito	—	sotto

Rilevamento incendio e fumo

app/services/fire_detection/fire_smoke_detector.py, avviato all'accensione del box in entrambe le linee. Si accende dal pannello (Installation Config, fire_detection.enable, spento di default).

• Cosa fa: a intervalli (monitoring_interval, 120 s), per ogni telecamera prende uno snapshot, lo passa al modello YOLO fire_smoke.pt e disegna un rettangolo sui riquadri trovati.
• Cosa non fa: non applica soglie di confidenza, non salva l'immagine, non genera eventi, non avvisa nessuno. Il risultato viene scartato.
• Probabile errore: la chiamata cv2.putText ha parametri scambiati (per esempio lineType con un colore e thickness=0.5). Andrebbe in errore a ogni riquadro trovato, con l'errore scritto solo nei log.
• Effetto se acceso: consuma CPU (modello YOLO su ogni telecamera) senza nessun beneficio. Chi lo accende dal pannello crede di avere una protezione antincendio che non esiste.

Impostazioni senza effetto

• check_camera_damage nella stage: dal 29/10 accende il nuovo rilevamento di manomissione, con eventi verso il midserver (anti-manomissione).
• monitoring_ganz_alarm_in (attivazione e time_out): nella 3.2.x viene letta come ritardo dell'ingresso di allarme del GANZ; nella stage esiste nel modello ma nessun codice la usa.
• Da tenere presente per l'import delle configurazioni (MDM-080) e per il pannello, che la mostra ancora.

Pulizia del disco

clean_disk: se attiva e il disco supera l'80%, il monitoraggio manda all'host docker image prune -af (app/utils/system_utils.py).

• Cosa libera: solo le immagini Docker non usate.
• Cosa non libera: le registrazioni di Frigate e le immagini degli allarmi, che di solito sono ciò che riempie il disco.
• Effetto collaterale: cancella anche l'immagine della versione precedente, quindi un ritorno indietro richiede di riscaricarla da ECR.
• Nella stage c'è in più una pulizia giornaliera dei log del box (log_retention_days, 90 giorni).

Inserimento e disinserimento automatico a orario

stage, app/services/alarm_schedule_manager/alarm_schedule_manager.py; si attiva con enable_automated_arming e la tabella alarm_schedule (fasce per giorno della settimana, grace_minutes), configurabili via MQTT dal midserver.

• Ogni minuto: nella finestra di chiusura, se il box è disinserito, inserisce; nella finestra di apertura, se è inserito, disinserisce.
• Negli impianti con cluster lo comunica anche agli slave.
• Gli eventi risultano generati dal sistema (AUTOMATED).
• Da decidere con la centrale: cosa succede se l'inserimento automatico fallisce (vedi sotto) e chi viene avvisato. Va deciso anche il rapporto con gli inserimenti a orario del sistema vecchio, cioè gli automatismi del progetto di Michele (arm-disarm_automated), per non avere due sistemi che inseriscono lo stesso impianto.

Rifiuto dell'inserimento con componenti critici non sani

stage, alarm_system_manager.py: prima di inserire il box controlla i componenti critici, per default detector, trombe e ingressi di allarme (health_config.critical_components).

• Se uno non è sano, rifiuta l'inserimento e manda l'evento "inserimento rifiutato per salute critica".
• Nello stato ERROR il box rifiuta sia l'inserimento sia il disinserimento.
• Conseguenza da valutare: una tromba guasta, o un ingresso di allarme non collegato, può lasciare un impianto disinserito, anche con l'inserimento automatico a orario. Va deciso con la centrale se è il comportamento voluto (meglio disinserito che inserito senza tromba?) e come viene avvisato l'operatore.

Eventi del box e Telegram diretto

stage, app/services/event_manager/.

• Eventi: inserimento e disinserimento, allarme, intrusione, panico, guasto, ripristino (avvio, eseguito, non riuscito, riuscito), inserimento rifiutato.
• Due consegne per ogni evento:
• via MQTT al midserver, verso qAlarm;
• a un provider di notifiche, oggi solo Telegram, con tre chat: cliente, centrale operativa, centro guasti (notification_config.provider).
• Coda: gli eventi non consegnati restano in coda (pending_events) e vengono rimandati ogni 30 s.
• Messaggio al cliente: per inserimento e disinserimento parte solo se notify_client è attivo.
• Effetti:
• il box diventa un altro mittente Telegram, oltre al sistema vecchio, con il token del bot salvato nella configurazione del box;
• quando si spegnerà Telegram (T10.2) andrà cambiato anche qui;
• se il provider non è configurato, _get_context solleva un errore: da verificare che l'evento MQTT parta comunque.

Controlli di salute e ripristino

stage, app/services/health_manager/.

• Controlli:
• VPN, cioè una connessione TCP sulla porta 80 verso un indirizzo di destinazione;
• detector;
• ogni telecamera, dalla salute riportata dal wrapper;
• dispositivi (trombe, ingressi);
• carico di CPU, RAM e disco (soglia 90%).
• Guasto: dopo fault_threshold controlli falliti (3) il box genera un evento di guasto, con promemoria ogni ora finché dura, e un evento di ripristino quando torna normale.
• Azioni di ripristino automatiche: l'infrastruttura c'è (ShellRecoveryAction, che esegue un comando sull'host), ma nessun controllo ha un'azione configurata: oggi il box segnala e non ripara.

Protezione delle API /api/v1

stage, app/routes/v1/v1_routes.py e app/services/security/validate_vpn_ip.py. Le API per inserire, disinserire, panico, allarme del detector (/api/v1/alarm/detection) e intrusione richiedono:

1. utente e password del box (autenticazione base). L'utente admin viene creato dalla prima migrazione con la stessa password su tutti i box (initial_migration_001.py);
2. indirizzo di origine in un elenco scritto nel codice: 127.0.0.0/8, 192.168.1.0/24, 192.168.3.0/24, 172.16.16.0/24 (VPN), 172.17.0.0/16 (Docker).

Il box gira in rete host, quindi vede l'IP reale di chi chiama.

• Il GANZ manda gli allarmi al box su http://<IP box>:5005/api/v1/alarm/... (Event Action → HTTP, gestione-telecamere). Se la rete locale del cliente non è 192.168.1.x o 192.168.3.x, la richiesta viene rifiutata (403) e l'allarme non entra nel box.
• Il GANZ di laboratorio è su 192.168.200.x.
• Lo stesso vale per qualsiasi apparato locale che usa queste API.
• Restano invece aperte, senza autenticazione, le rotte vecchie (/ganz/alarm, /frigate/alarm/{name}), che salvano l'allarme nei log.

Da verificare subito sul box di prova MDMTESTGANZ1: quale indirizzo è configurato nel GANZ, se gli allarmi arrivano e con quale codice di risposta (MDM-083).

Soluzione ideale

Ogni funzione accesa dal pannello fa quello che promette, e il suo risultato arriva all'operatore in qAlarm; le funzioni non finite non si possono accendere.

• Incendio e fumo: si completa con soglia, conferma su più immagini ed evento in qAlarm con l'immagine, oppure si toglie dal pannello e dall'avvio finché non è pronta.
• Impostazioni senza effetto: tolte dal pannello o ricollegate.
• Pulizia del disco: libera anche registrazioni e immagini vecchie secondo una politica di conservazione, e mantiene l'immagine della versione precedente.
• Inserimento a orario e rifiuto per salute critica: comportamento deciso con la centrale e scritto; ogni inserimento automatico fallito arriva all'operatore come evento.
• Notifiche: un solo canale verso gli operatori, cioè gli eventi via midserver verso qAlarm. Telegram dal box resta solo finché serve, e non manda doppioni.
• API v1: reti consentite configurabili per impianto (la rete locale del cliente), credenziali diverse per ogni box, verifica che gli apparati locali (GANZ) usino utente e password.
• Ripristino automatico: azioni configurate solo dove sono sicure (per esempio il riavvio del wrapper), sempre con evento.

Cosa dobbiamo fare

#	Passo	Ticket
1	Sul box di prova: verificare che gli allarmi del GANZ arrivino a /api/v1/alarm/... (IP di origine, credenziali, codice di risposta); rendere configurabili le reti consentite e le credenziali per box	MDM-083
2	Decidere con la centrale: rifiuto dell'inserimento per salute critica, inserimento a orario (e convivenza con gli automatismi del sistema vecchio), notifiche Telegram dal box	A24
3	Incendio e fumo, monitoring_ganz_alarm_in, pulizia del disco: completare o togliere dal pannello e dall'avvio	MDM-084
4	Verificare che senza provider di notifiche l'evento MQTT parta comunque	MDM-084
5	Anti-manomissione	MDM-082