Documentazione · Italiano

Installare Home Assistant su un controllore Wiren Board

revisione 112324

Descrizione

Home Assistant è una piattaforma di automazione open source sviluppata e mantenuta dalla comunità home-assistant.io . L’app mobile permette di controllare il sistema tramite la rete locale o il servizio cloud della piattaforma.

È possibile installarla su un controllore Wiren Board per comandare i dispositivi collegati al posto dell’ interfaccia web standard.

Compatibilità

Si consigliano i controllori Wiren Board 8/8M e successivi. Il supporto di Home Assistant per Wiren Board 6 e 7 (armhf) è terminato alla fine del 2025; questi modelli non ricevono più aggiornamenti. Vedere l’ annuncio degli sviluppatori.

Installazione

La memoria flash del controllore è suddivisa in partizioni. Una partizione utente separata è montata in /mnt/data. Se la partizione root è stata estesa fino a occupare quasi tutta la eMMC, /mnt/data è una normale directory della partizione root. Tenerne conto durante l’installazione del software o l’aggiornamento del firmware.

Copiare i comandi nella console del controllore con Shift+Insert ed eseguirli con Enter. Prima di eseguire un comando, assicurarsi di comprenderne lo scopo e le modifiche che apporterà. Leggere attentamente i messaggi di errore, che contengono indicazioni e suggerimenti.

Utilizzare nano per modificare i file di configurazione. Se il software di terze parti richiede più spazio, è possibile estendere la partizione root fino a occupare quasi tutta la eMMC.

Questa guida utilizza il metodo Home Assistant Container consigliato dagli sviluppatori. Non include Supervisor, quindi non è possibile installare componenti aggiuntivi dall’interfaccia web di Home Assistant. I componenti aggiuntivi contengono generalmente software di terze parti come zigbee2mqtt, ESPHome o Node-RED, installabile separatamente in contenitori.

Installare Docker seguendo la guida all’installazione di Docker.

Creare la directory di installazione e accedervi:

mkdir -p /mnt/data/.docker-compose/home-assistant
cd /mnt/data/.docker-compose/home-assistant

Creare le directory di configurazione e dei contenuti multimediali:
```
mkdir -p config/home-assistant
mkdir -p store/media
```
Aprire docker-compose.yaml nell’editor:
```
nano docker-compose.yaml
```

Incollare la seguente configurazione per Wiren Board 8:

services:
  # HomeAssistant
  homeassistant:
    container_name: home-assistant
    image: homeassistant/home-assistant:latest

    volumes:
      # Local path where your home assistant config will be stored
      - ./config/home-assistant:/config
      - ./store/media:/media
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro # <-- Bluetooth adapter
    restart: unless-stopped
    network_mode: host
    environment:
      TZ: "${MYTZ}"
    privileged: true
    labels:
      - "com.centurylinklabs.watchtower.monitor-only=true"

Per Wiren Board 6 e 7, utilizzare invece questa configurazione:

services:
  # HomeAssistant
  homeassistant:
    container_name: home-assistant
    image: ghcr.io/home-assistant/armhf-homeassistant:latest

    volumes:
      # Local path where your home assistant config will be stored
      - ./config/home-assistant:/config
      - ./store/media:/media
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro # <-- Bluetooth adapter
    restart: unless-stopped
    network_mode: host
    environment:
      TZ: "${MYTZ}"
    privileged: true
    labels:
      - "com.centurylinklabs.watchtower.monitor-only=true"

Salvare con Ctrl+S e chiudere con Ctrl+X.
Impostare il fuso orario nel file .env. Scegliere uno degli esempi seguenti o un altro fuso orario Linux valido:
UTC (tempo coordinato universale):
```
echo "MYTZ=UTC" >> .env
```
Europa centrale (CEST/CET):
```
echo "MYTZ=Europe/Berlin" >> .env
```
Mosca (MSK):
```
echo "MYTZ=Europe/Moscow" >> .env
```
Elencare tutti i fusi orari disponibili in Linux:
```
timedatectl list-timezones
```
Avviare il contenitore in background:
```
docker compose up -d
```

Dopo l’avvio del contenitore, aprire nel browser l’indirizzo IP del controllore sulla porta 8123, ad esempio http://192.168.42.1:8123. È ora possibile chiudere la console.

Aggiornamento

Collegare il controllore a Internet, quindi scaricare l’immagine aggiornata e ricreare il contenitore:

cd /mnt/data/.docker-compose/home-assistant
docker compose pull homeassistant  # Update the image
docker compose up -d homeassistant  # Recreate the container

Tutte le impostazioni vengono conservate quando il contenitore viene ricreato, poiché la configurazione è salvata nella directory config.

Utilizzo dei dispositivi Wiren Board

Installare l’integrazione Wiren Board

L’ integrazione personalizzata Wiren Board crea automaticamente le entità Home Assistant dai topic MQTT dei dispositivi. L’integrazione attuale richiede Home Assistant 2025.6 o successivo.

Copiare la cartella wirenboard dal repository in /mnt/data/.docker-compose/home-assistant/config/home-assistant/custom_components/.
Aprire l’interfaccia web di Home Assistant.
Riavviare Home Assistant tramite Developer Tools → Restart.
Aprire Settings → Devices & Services → Add Integration e selezionare wirenboard.
I campi Host e Port contengono le impostazioni predefinite di connessione al controllore. Modificarle solo se necessario.

Installare l’integrazione MQTT

Home Assistant può controllare dispositivi Modbus tramite MQTT. Installare l’integrazione MQTT, quindi configurare la ricezione e l’invio dei dati. I passaggi e le schermate seguenti utilizzano il precedente menu Configuration; le versioni più recenti utilizzano Settings.

Aprire l’interfaccia web di Home Assistant.
Selezionare Configuration nella barra laterale sinistra, quindi aprire Devices & Services.
Fare clic su Add Integration in fondo alla pagina, cercare MQTT e selezionare l’integrazione.
Attendere la finestra di configurazione. Impostare Broker su localhost e Port su 1883. Lasciare vuoti nome utente e password se il controllore utilizza la configurazione standard. Fare clic su Submit.

Configurare manualmente i dispositivi

Dopo aver configurato l’integrazione, descrivere ogni dispositivo in configuration.yaml. Aprire il file nell’editor:

nano /mnt/data/.docker-compose/home-assistant/config/home-assistant/configuration.yaml

La directory di configurazione è /mnt/data/.docker-compose/home-assistant/config/home-assistant/. Aggiungere sezioni con i parametri dei dispositivi; ad esempio, descrivere i relè nella sezione switch.

Salvare il file e riavviare Home Assistant. Nell’interfaccia precedente, aprire Configuration → Settings e fare clic su Restart. La configurazione viene verificata prima del riavvio e gli errori vengono segnalati in dettaglio. Una causa frequente è il rientro errato, che in YAML è significativo.

Lo spazio di archiviazione del controllore è limitato. Aggiungere la seguente impostazione recorder per conservare 14 giorni di cronologia. Controllare lo spazio libero su disco: questo periodo di conservazione non impone un limite fisso alle dimensioni del database.

recorder:
  purge_keep_days: 14

Consultare MQTT Discovery per la sintassi completa e i tipi di dispositivi supportati.
Gli indirizzi dei topic MQTT sono disponibili nell’interfaccia web standard del controllore, in Settings → MQTT Channels.
Impostare state_topic sull’indirizzo del topic MQTT. Per command_topic, utilizzare lo stesso indirizzo aggiungendo /on.
Definire i sensori sotto mqtt:, come nell’esempio della temperatura seguente. Per il formato, consultare la documentazione dei sensori MQTT di Home Assistant . Inserire switch e light sotto la stessa chiave mqtt:, senza duplicare la chiave mqtt: al livello principale.

Visualizzare la lettura del sensore di temperatura della CPU:

mqtt:
  sensor:
    - unique_id: wb_cpu_temperature
      name: "CPU Temperature"
      state_topic: "/devices/hwmon/controls/CPU Temperature"
      unit_of_measurement: "°C"

Controllare le uscite A1 e A2. Questo esempio può essere utilizzato anche per controllare moduli relè:

#mqtt:
  switch:
    - unique_id: wb_a1_switch
      name: "WB A1 Switch"
      state_topic: "/devices/wb-gpio/controls/A1_OUT"
      command_topic: "/devices/wb-gpio/controls/A1_OUT/on"
      payload_on: "1"
      payload_off: "0"
      retain: true
    - unique_id: wb_a2_switch
      name: "WB A2 Switch"
      state_topic: "/devices/wb-gpio/controls/A2_OUT"
      command_topic: "/devices/wb-gpio/controls/A2_OUT/on"
      payload_on: "1"
      payload_off: "0"
      retain: true

Controllare il cicalino del controllore. Questo esempio può essere adattato a un dimmer per lampade LED:

#mqtt:
  light:
    - unique_id: wb_buzzer
      name: "Buzzer"
      state_topic: "/devices/buzzer/controls/enabled"
      command_topic: "/devices/buzzer/controls/enabled/on"
      brightness_state_topic: '/devices/buzzer/controls/volume'
      brightness_command_topic: '/devices/buzzer/controls/volume/on'
      brightness_scale: 100
      payload_on: "1"
      payload_off: "0"
      retain: true

Topic MQTT nell’interfaccia web del controllore

Dispositivi nell’interfaccia web di Home Assistant

Accesso tramite cloud

Per accedere dall’esterno della rete locale, aggiungere Home Assistant come servizio in Wiren Board Cloud. Nella pagina del controllore, fare clic su Services e selezionare Home Assistant dal catalogo. La porta 8123 viene inserita automaticamente.

Inizialmente Home Assistant restituisce 400: Bad Request perché non considera attendibili le richieste provenienti dal proxy cloud. Aprire Home Assistant nella rete locale con l’indirizzo del controllore e la porta 8123, quindi andare in Settings → System → Network. I passaggi successivi dipendono dalla versione di Home Assistant.

Se la pagina Network contiene la sezione HTTP server, si sta utilizzando Home Assistant 2026.8 o successivo. In queste versioni, configurare le impostazioni HTTP nell’interfaccia web:

In HTTP server, espandere Reverse proxy.
Attivare Trust X-Forwarded-For.
Aggiungere singolarmente 127.0.0.1, ::1 e 172.16.0.0/12 in Trusted proxies.
Fare clic su Save, quindi su Save and restart.
Dopo il riavvio, fare clic su Confirm nella finestra che richiede di confermare la nuova configurazione del server HTTP. Confermare entro 5 minuti, altrimenti Home Assistant ripristina le impostazioni precedenti.

Se la sezione HTTP server non è presente, la versione è precedente alla 2026.8. Ciò vale anche per Wiren Board 6 e 7, che non ricevono più nuove versioni:

Aggiungere quanto segue a /mnt/data/.docker-compose/home-assistant/config/home-assistant/configuration.yaml:
```
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1
    - ::1
    - 172.16.0.0/12
```
Riavviare il contenitore:
```
docker restart home-assistant
```

Quando si esegue l’aggiornamento a Home Assistant 2026.8 o successivo, al primo avvio le impostazioni HTTP vengono migrate nella sezione HTTP server. Se richiesto, fare clic su Confirm entro 5 minuti; altrimenti le impostazioni vengono ripristinate e devono essere reinserite seguendo i passaggi precedenti. Verificare gli indirizzi in Trusted proxies, quindi rimuovere il blocco http: da configuration.yaml.