Come configurare un UPS per Raspberry Pi con Home Assistant

Prerequisiti & Hardware Necessario

• Hardware: un Raspberry Pi 4, che richiede un alimentatore USB-C da 5,1 V/3 A, oppure un Raspberry Pi 5, per il quale è consigliato un alimentatore USB-C PD da 27 W con profilo 5 V/5 A. Come riferimento: Raspberry Pi 4 Model B 4GB oppure Raspberry Pi 5 4GB con alimentatore ufficiale.
• Hardware: UPS con uscita compatibile con l’alimentatore del Raspberry Pi e collegamento dati USB. Verifica il modello nella Hardware Compatibility List di Network UPS Tools; non usare un collegamento GPIO o una HAT UPS senza lo schema elettrico e il limite di corrente del produttore.
• Software: Home Assistant OS aggiornato, accesso amministratore, add-on Network UPS Tools (NUT) e integrazione Home Assistant Network UPS Tools (NUT).
• Rete: Raspberry Pi raggiungibile dalla rete locale. Il server NUT ascolta normalmente sulla porta TCP 3493.

Procedura passo-passo

1. Controlla la compatibilità dell’UPS. Cerca il driver NUT richiesto dal modello. Per molti UPS USB HID il driver è usbhid-ups, ma il nome non va dedotto dalla marca: confermalo nella documentazione NUT.
2. Collega l’hardware. Collega l’UPS alla rete elettrica, alimenta il Raspberry Pi dall’uscita protetta dell’UPS e inserisci il cavo USB dati tra UPS e Raspberry Pi. Non scollegare l’uscita dell’UPS durante il test.
3. Apri il catalogo degli add-on. In Home Assistant vai in Impostazioni → Componenti aggiuntivi → Negozio dei componenti aggiuntivi, installa Network UPS Tools e non avviare ancora il servizio.
4. Configura il server NUT. Nel pannello di configurazione dell’add-on inserisci una configurazione equivalente a questa. Sostituisci la password con una stringa casuale lunga e conserva gli stessi valori per l’integrazione.

   users:
     - username: homeassistant
       password: CAMBIA_CON_PASSWORD_CASUALE_LUNGA
       instcmds:
         - all
       actions: []
   devices:
     - name: ups
       driver: usbhid-ups
       port: auto
       config: []
       powervalue: 1
   mode: netserver
   shutdown_host: false
   list_usb_devices: true

   usbhid-ups e port: auto sono adatti solo quando l’UPS espone una periferica USB HID compatibile. Se il log dell’add-on indica un driver diverso, usa quello indicato da NUT.

5. Avvia e controlla il log. Avvia l’add-on e apri la scheda Log. Devi vedere il rilevamento del dispositivo ups senza errori di driver, USB o autenticazione. Se attivi il watchdog, fallo dopo un avvio riuscito.
6. Configura l’integrazione. Vai in Impostazioni → Dispositivi e servizi → Aggiungi integrazione e cerca Network UPS Tools (NUT). Inserisci come host il nome host del server NUT fornito dalla documentazione dell’add-on (nelle installazioni Home Assistant OS è normalmente a0d7b954-nut), porta 3493, utente homeassistant e la password configurata. Non usare 127.0.0.1 se il server NUT è in un add-on separato.
7. Controlla le entità. Apri il dispositivo creato dall’integrazione e verifica almeno lo stato dell’UPS, la carica batteria, la tensione o il carico quando esposti dal driver. I nomi delle entità dipendono dal modello e non devono essere copiati alla cieca in un’automazione.
8. Crea una notifica di passaggio a batteria. Sostituisci sensor.ups_status e il servizio di notifica con gli identificativi presenti nella tua installazione:

   alias: Avviso UPS a batteria
   triggers:
     - trigger: state
       entity_id: sensor.ups_status
       to: "On Battery"
   actions:
     - action: notify.mobile_app_TELEFONO
       data:
         title: "UPS"
         message: "Il Raspberry Pi è alimentato dalla batteria dell’UPS."
   mode: single

9. Prova il failover. Con il Raspberry Pi acceso e l’UPS carico, disattiva soltanto l’alimentazione a monte dell’UPS. Attendi il cambio di stato, controlla la notifica e riattiva la rete entro pochi secondi. Non scaricare completamente la batteria durante una prova.

Verifica del funzionamento

La verifica è corretta quando il dispositivo NUT risulta disponibile, il sensore di stato passa da OL (on line) a OB (on battery) durante il test e torna a OL dopo il ripristino della rete. Il Raspberry Pi deve restare acceso e Home Assistant deve registrare gli eventi senza riavvio. Se il driver espone il livello batteria, controlla che il valore non sia nullo e che diminuisca durante il funzionamento a batteria.

Problemi comuni

Problema	Causa	Soluzione
L’add-on non rileva l’UPS	Cavo USB solo di ricarica, dispositivo non passato al sistema o driver errato	Usa un cavo dati, controlla il log e seleziona il driver NUT previsto dal modello.
Errore di connessione sulla porta 3493	NUT non avviato, modalità diversa da netserver o host errato	Avvia il server, verifica la porta 3493 e usa il nome host dell’add-on invece di localhost.
Home Assistant vede l’UPS ma non cambia stato	È stata scollegata l’uscita protetta invece della rete a monte dell’UPS, oppure il driver non aggiorna lo stato	Ripeti il test togliendo la rete all’UPS e controlla nel log i valori OL/OB.
Raspberry Pi 5 si riavvia sotto carico	Alimentatore o UPS non fornisce il profilo/corrente richiesti	Usa un alimentatore USB-C PD da 27 W e un UPS dimensionato per il consumo reale; non aumentare la tensione oltre quella prevista.

FAQ essenziali

Posso usare una power bank come UPS?

Solo se il dispositivo supporta esplicitamente il passaggio senza interruzione, l’uscita è stabile e dispone di telemetria leggibile da NUT. Una power bank comune può interrompere l’alimentazione o non fornire dati; in quel caso protegge solo parzialmente e non permette un arresto controllato.

Devo configurare lo spegnimento automatico del Raspberry Pi?

Non durante il primo test. Prima verifica che NUT rilevi correttamente OB e LB. Solo dopo definisci una policy di shutdown coerente con autonomia, carico e supporto del tuo add-on; uno spegnimento configurato male può causare arresti prematuri.