Passa al contenuto principale

Webcam USB

Una webcam USB collegata direttamente all'host Home Assistant può essere un'ottima soluzione se una camera wireless è troppo lenta o va a scatti: non c'è rete di mezzo, quindi la latenza è minima. Superhome legge solo RTSP, perciò la webcam va prima esposta come stream RTSP. Su Home Assistant OS il modo più pulito per farlo è l'add-on go2rtc.

Funziona su qualsiasi hardware HAOS

Questi passaggi funzionano su Home Assistant OS a prescindere dalla macchina: un Raspberry Pi oppure un mini-PC / server di casa x86. Abbiamo validato questa procedura su un Raspberry Pi 5. Se non stai usando Home Assistant OS (per esempio un normale PC Linux o un worker Docker standalone), salta all'alternativa più in basso.

Consigliato su HAOS: l'add-on go2rtc​

go2rtc è integrato nel core di Home Assistant dalla versione 2024.11, ma per le webcam USB conviene l'add-on dedicato. L'add-on viene avviato con accesso ai device video/audio dell'host (video: true), quindi vede la webcam su /dev/video0 senza dover mappare manualmente il device. Il go2rtc integrato nel core gira invece in un container che non sempre ha accesso a /dev/video*.

1. Aggiungere il repository dell'add-on​

  1. Vai su Impostazioni → Add-on → Store add-on.

  2. In alto a destra apri il menu a tre puntini (⋮) → Repository.

  3. Incolla questo URL e premi Aggiungi:

    https://github.com/AlexxIT/hassio-addons

  4. Chiudi la finestra.

2. Installare go2rtc​

  1. Ricarica la pagina dello store (a volte serve un refresh del browser).
  2. Scorri in fondo fino alla sezione AlexxIT add-ons e apri go2rtc.
  3. Premi Installa. Il download dell'immagine richiede qualche minuto su un Raspberry Pi.

3. Avviare l'add-on​

Nella scheda Info dell'add-on attiva Avvia all'avvio (Start on boot) e Watchdog, poi premi Avvia.

4. Configurare lo stream​

Puoi modificare la configurazione direttamente dalla Web UI di go2rtc (consigliato), oppure modificare il file /config/go2rtc.yaml (stessa cartella di configuration.yaml) con un add-on tipo File editor o Studio Code Server. Per aprire la Web UI premi Apri interfaccia web nella pagina dell'add-on: gira sulla porta 1984.

Questa configurazione minima è quella che ha funzionato per noi, ed è la prima da provare:

streams:
  usb_cam:
    - ffmpeg:device?video=/dev/video0#video=h264

Nella maggior parte dei casi una singola webcam USB è /dev/video0, quindi questa configurazione funziona così com'è (usa sempre il path completo, non solo video0). Se la tua camera non è su /dev/video0 (per esempio hai più di un device video, oppure questa configurazione non mostra immagine), la Web UI di go2rtc elenca i device rilevati: premi add per vedere le sorgenti disponibili e i relativi path, poi metti il /dev/videoN corretto nella configurazione qui sopra.

#video=h264 dice a go2rtc di transcodificare il flusso in H264. È necessario perché molte webcam USB escono in MJPEG o YUV raw, formati che RTSP/WebRTC gestiscono male.

Dopo aver salvato, riavvia l'add-on. Poi, dalla home page della Web UI di go2rtc, clicca stream accanto alla voce usb_cam per vederne l'anteprima dal vivo. È il modo più rapido per confermare che la camera funziona prima di agganciare l'URL a Superhome.

Minor consumo di CPU

Se la webcam supporta l'uscita H264 nativa, puoi evitare la transcodifica con #video=copy, molto più leggero sull'host:

streams:
  usb_cam:
    - ffmpeg:device?video=/dev/video0&input_format=h264&video_size=1280x720#video=copy

Qui video_size=1280x720 è solo un placeholder: impostalo a una risoluzione che la tua webcam supporta davvero (es. 1920x1080). Se scegli una dimensione che la camera non offre, lo stream non parte. Nel dubbio, la configurazione con transcodifica qui sopra (#video=h264, senza video_size) è la prima scelta più sicura.

5. Verificare l'URL RTSP​

L'URL RTSP da usare è:

rtsp://<host-ip>:8554/usb_cam

Usa l'indirizzo IP della macchina che esegue HAOS. Prima di agganciarlo a Superhome, testalo con VLC (Media → Apri flusso di rete) da un computer sulla stessa rete.

6. Usarlo in Superhome​

Incolla l'URL RTSP nel campo rtsp_url della scheda Configurazione di Superhome. La connessione si ristabilisce automaticamente, senza bisogno di riavviare.

Tieni la Web UI di go2rtc sulla rete di casa

La Web UI di go2rtc (porta 1984) non è protetta da password, e chiunque sia sulla tua rete locale può aprirla e vedere le anteprime delle camere. Per il normale uso domestico su una rete fidata va bene. L'importante è non esporre la porta 1984 su internet. Se ti serve farlo, go2rtc supporta l'autenticazione nella sezione api della sua configurazione.

Alternativa per un PC normale (non HAOS)​

Se non sei su Home Assistant OS, per esempio un normale PC Linux o un worker Docker standalone, non hai lo store degli add-on, quindi devi configurare tu lo stream RTSP. Due opzioni semplici:

Opzione A: eseguire go2rtc direttamente. go2rtc è un singolo binario (disponibile anche come immagine Docker, alexxit/go2rtc). Crea un go2rtc.yaml con lo stesso identico blocco streams: mostrato sopra ed eseguilo; l'URL risultante è lo stesso rtsp://<host-ip>:8554/usb_cam. Su Linux la webcam compare comunque come /dev/video0.

Opzione B: usare v4l2rtspserver per qualsiasi webcam UVC:

# Install v4l2rtspserver (Debian/Ubuntu/Raspbian)
apt install v4l2rtspserver

# Run (adjust /dev/video0 and resolution as needed)
v4l2rtspserver -W 1280 -H 720 -F 15 /dev/video0

Poi usa questo URL come rtsp_url:

rtsp://<host-ip>:8554/unicast

In entrambi i casi, verifica prima lo stream con VLC, poi incolla l'URL nella scheda Configurazione di Superhome esattamente come al passo 6.