🏠 Agente su Home Assistant

Se hai già un Home Assistant acceso giorno e notte nel laboratorio, hai già dove mettere l'agente: è sempre in funzione, è nella tua rete e ha il suo store di app. Questa pagina spiega come installarlo lì, collegarlo al tuo laboratorio e tenerlo aggiornato.

Se il tuo computer è un altro (un NAS, un PC, un server con Docker), scegli il tuo in L'agente locale, dove trovi anche cosa fa l'agente, qualunque sia il computer.

---

Cosa ti serve

• Home Assistant OS, che è l'installazione con lo store delle app. Anche le installazioni «Supervised» ce l'hanno, ma Home Assistant non le mantiene più. Se il tuo Home Assistant gira in Docker («Container»), non ha app: installa l'agente con Docker, come spiega Agente su Docker.
• Un dispositivo a 64 bit: un mini-PC o un PC con Intel o AMD, un Raspberry Pi 4 o 5, oppure un Home Assistant Green o Yellow. Su un Raspberry Pi 3 o su un sistema a 32 bit l'app non si può installare.
• Che Home Assistant sia nella stessa rete delle tue stampanti. Se gira in una macchina virtuale, la sua rete deve essere in modalità bridge, non NAT.
• La porta 8257 libera su quel computer. Se la usa qualcos'altro, si cambia in un attimo (più sotto).
• Essere proprietario del laboratorio in BolloPrint: l'agente si può collegare solo a un laboratorio tuo.

---

Installarlo

1. Da un computer o da un telefono collegato alla tua rete, apri questo link: Aggiungi BolloPrint al mio Home Assistant. È una pagina di Home Assistant: la prima volta ti chiede l'indirizzo del tuo Home Assistant, per esempio http://homeassistant.local:8123.
2. Premi Open link. Il tuo Home Assistant ti chiede se vuoi aggiungere l'archivio digitale delle app di BolloPrint: premi Aggiungi.
3. Si apre la pagina di BolloPrint Agent, con il cane di BolloPrint. Premi Installa. Home Assistant prepara l'app da solo; ci vogliono uno o due minuti.
4. Premi Avvia. Lascia attivo Esegui dall'avvio, così l'agente torna da solo ogni volta che Home Assistant si riavvia.

---

Collegarlo al tuo laboratorio

1. Nella pagina dell'app, premi Apri interfaccia utente Web. La pagina dell'agente si apre in una nuova scheda: dice che non appartiene ancora a nessun laboratorio e mostra un codice, come 8054-627E.
2. Premi Collega a BolloPrint. Ti porta su BolloPrint; accedi con il tuo account se te lo chiede.
3. Scegli il laboratorio, controlla che il codice sia lo stesso della pagina dell'agente, rivedi il nome che ti propone (quello del tuo Home Assistant; puoi cambiarlo) e conferma.
4. Torni alla pagina dell'agente, che ora dice «Collegato a …». In meno di un minuto lo vedrai Online in Impostazioni → Stampanti → Agente locale, con il logo di Home Assistant, e inizierà a cercare le tue stampanti.

In BolloPrint non bisogna creare niente prima. Il riquadro Home Assistant di Nuovo agente ti ricorda solo questi passaggi.

---

La porta della pagina

La pagina dell'agente usa la porta 8257 del dispositivo Home Assistant. Se qualcos'altro la sta già usando, l'app si ferma appena avviata e la sua scheda Registro dice address already in use. Per cambiarla:

1. Nella pagina dell'app, apri la scheda Configurazione.
2. In Rete, metti un altro numero (per esempio 8364) e premi Salva.
3. Home Assistant ti chiede se riavviare l'app: accetta. Apri interfaccia utente Web ora ti porta alla nuova porta.

Cambiare la porta non scollega l'agente: resta lo stesso, con le sue stampanti.

---

Tenerlo aggiornato

Qui si aggiornano due cose, e non devi quasi mai fare nulla:

Cosa	Come si aggiorna
L'agente, la parte che parla con le tue stampanti	Da solo. Quando BolloPrint pubblica una nuova versione, la scarica e la installa da sé.
L'app di Home Assistant, la parte che avvia l'agente	Quando Home Assistant ti segnala un aggiornamento di BolloPrint Agent, premi Aggiorna nella sua pagina. Se attivi Aggiornamento automatico nella pagina, lo farà da solo.

Aggiornare l'app non scollega l'agente. La sua identità è salvata nei dati dell'app, che rientrano anche nei backup di Home Assistant.

---

Cambiarlo di dispositivo o reinstallarlo

• Se reinstalli l'app o la metti su un altro Home Assistant, collegala di nuovo: sarà un agente nuovo. Aggiungi le tue stampanti con lui (le troverà da solo se sono nella sua rete, oppure per IP) e passeranno con il loro numero e tutto il loro storico. Poi elimina l'agente vecchio, che sarà rimasto senza stampanti.
• Se ripristini sullo stesso Home Assistant un backup che include l'app, l'agente torna tale e quale, già collegato.

---

Disinstallarlo

1. In BolloPrint, vai su Impostazioni → Stampanti → Agente locale, apri il menu ⋮ dell'agente e premi Elimina. Le stampanti che arrivavano solo tramite lui spariscono dall'elenco; se un giorno le aggiungi di nuovo, tornano con il loro storico.
2. In pochi secondi, la pagina dell'agente torna a offrire Collega a BolloPrint. Se non lo vuoi più, nella pagina dell'app in Home Assistant apri il menu ⋮ e premi Disinstalla.
3. Se vuoi, togli anche l'archivio digitale: Raccolta delle app → ⋮ → Archivi digitali, e il cestino accanto a BolloPrint.

Se disinstalli l'app senza eliminare prima l'agente, in BolloPrint resta come Offline. Eliminalo dal suo menu ⋮.

---

Quando qualcosa non va

La prima cosa da guardare è la scheda Registro dell'app in Home Assistant: racconta cosa fa l'agente e, se si ferma, perché.

Sintomo	Cosa fare
BolloPrint Agent non compare nella raccolta	In Raccolta delle app, menu ⋮ → Controlla gli aggiornamenti, e ricarica la pagina. Se in Impostazioni non hai Applicazioni, il tuo Home Assistant non ha app: installa l'agente con Docker.
Non ti lascia installarla	Il tuo dispositivo è a 32 bit, come un Raspberry Pi 3. L'app ha bisogno di 64 bit.
L'installazione si interrompe a metà	Home Assistant scarica l'agente quando lo installa: controlla che abbia internet e riprova.
L'app si ferma appena avviata	Guarda il Registro. Se dice address already in use, la porta è occupata: cambiala come spiegato sopra.
Apri interfaccia utente Web non apre nulla	Sei fuori dalla rete del laboratorio (accesso remoto, VPN, dati mobili). Aprilo dalla rete locale.
Al momento di collegarlo non compare il tuo laboratorio	Puoi collegare l'agente solo ai laboratori di cui sei proprietario. Chiedi al proprietario di collegarlo lui.
Non trova nessuna stampante	Home Assistant è nella stessa rete delle stampanti? In una macchina virtuale, la sua rete deve essere in modalità bridge. Se sono in reti separate, aggiungile per IP: funzionano lo stesso.
L'hai eliminato in BolloPrint e la pagina dice ancora «Collegato»	Aspetta un minuto e ricarica: l'agente si riavvia da solo, senza collegamento.