Índice do manual

🏠 Agente no Home Assistant

Em 30 segundos

Se tens Home Assistant OS na oficina, o agente instala-se como mais uma app, a partir da sua própria loja.
Uma ligação acrescenta o BolloPrint ao teu Home Assistant; depois Instalar, Iniciar e Ligar ao BolloPrint. Não há códigos nem chaves para copiar.
O agente atualiza-se sozinho, e a app quando o Home Assistant to propõe.
Está em beta: se alguma coisa não bater certo, conta-nos a partir da Ajuda.

Se já tens um Home Assistant ligado dia e noite na oficina, já tens onde pôr o agente: está sempre a funcionar, está na tua rede e tem a sua própria loja de apps. Esta página explica como o instalar aí, ligá-lo à tua oficina e mantê-lo atualizado.

Se o teu equipamento é outro (um NAS, um PC, um servidor com Docker), escolhe o teu em O agente local, onde também está o que o agente faz, seja qual for o equipamento.

O que precisas

Home Assistant OS, que é a instalação que traz loja de apps. As instalações «Supervised» também a têm, mas o Home Assistant já não as mantém. Se o teu Home Assistant corre em Docker («Container»), não tem apps: instala o agente com Docker, como explica Agente no Docker.
Um equipamento de 64 bits: um mini-PC ou um PC com Intel ou AMD, um Raspberry Pi 4 ou 5, ou um Home Assistant Green ou Yellow. Num Raspberry Pi 3 ou num sistema de 32 bits a app não se pode instalar.
Que o Home Assistant esteja na mesma rede que as tuas impressoras. Se corre numa máquina virtual, a sua rede tem de estar em modo ponte (bridge), não em NAT.
A porta 8257 livre nesse equipamento. Se outra coisa a usar, muda-se num instante (mais abaixo).
Seres proprietário da oficina no BolloPrint: o agente só se pode ligar a uma oficina tua.

Instalá-lo

A partir de um computador ou de um telemóvel ligado à tua rede, abre esta ligação: Adicionar o BolloPrint ao meu Home Assistant. É uma página do Home Assistant: da primeira vez pede-te o endereço do teu Home Assistant, por exemplo http://homeassistant.local:8123.
Prime Open link. O teu Home Assistant pergunta-te se queres adicionar o repositório de apps do BolloPrint: prime Adicionar.
Abre-se a ficha do BolloPrint Agent, com o cão do BolloPrint. Prime Instalar. O Home Assistant prepara a app sozinho; demora um ou dois minutos.
Prime Iniciar. Deixa ativado Iniciar no arranque, para que o agente volte sozinho sempre que o Home Assistant reiniciar.

Se preferires fazê-lo à mão

No Home Assistant, vai a Configuração → Apps → Loja de apps, abre o menu ⋮ em cima à direita e entra em Repositórios. Prime Adicionar, cola https://github.com/bolloprint/agent-home-assistant e confirma. O BolloPrint Agent aparece na loja, na sua própria secção.

Ligá-lo à tua oficina

Na ficha da app, prime Abrir a IU da Web. Abre-se a página do agente num separador novo: diz que ainda não pertence a nenhuma oficina e mostra um código, como 8054-627E.
Prime Ligar ao BolloPrint. Leva-te ao BolloPrint; entra com a tua conta se to pedir.
Escolhe a oficina, confirma que o código é o mesmo que o da página do agente, revê o nome que te propõe (o do teu Home Assistant; podes mudá-lo) e confirma.
Voltas à página do agente, que já diz «Ligado a …». Em menos de um minuto vais vê-lo Online em Configurações → Impressoras → Agente local, com o logótipo do Home Assistant, e começa a procurar as tuas impressoras.

No BolloPrint não é preciso criar nada antes. O cartão Home Assistant de Novo agente só te lembra estes passos.

Fá-lo a partir da rede da oficina

A página do agente só abre dentro da tua rede local. Se entras no Home Assistant a partir de fora (com o acesso remoto ou uma VPN), Abrir a IU da Web não carrega: liga-o a partir de um computador ou de um telemóvel ligado à rede da oficina.

A porta da página

A página do agente usa a porta 8257 do equipamento do Home Assistant. Se outra coisa já a estiver a usar, a app para logo ao arrancar e o seu separador Registo diz address already in use. Para a mudar:

Na ficha da app, abre o separador Configuração.
Em Rede, põe outro número (por exemplo 8364) e prime Guardar.
O Home Assistant pergunta-te se reinicia a app: aceita. Abrir a IU da Web já te leva à porta nova.

Mudar a porta não desfaz a ligação do agente: continua a ser o mesmo, com as suas impressoras.

Mantê-lo atualizado

Aqui atualizam-se duas coisas, e quase nunca tens de fazer nada:

O quê	Como se atualiza
O agente, o que fala com as tuas impressoras	Sozinho. Quando o BolloPrint publica uma versão nova, descarrega-a e instala-a ele mesmo.
A app do Home Assistant, o que põe o agente a funcionar	Quando o Home Assistant te avisar de uma atualização do BolloPrint Agent, prime Atualizar na sua ficha. Se ativares Auto atualizar na ficha, fá-lo sozinho.

Atualizar a app não desfaz a ligação do agente. A sua identidade guarda-se nos dados da app, que também entram nas cópias de segurança do Home Assistant.

Mudá-lo de equipamento ou reinstalá-lo

Se reinstalares a app ou a puseres noutro Home Assistant, liga-a outra vez: será um agente novo. Adiciona as tuas impressoras com ele (encontra-as sozinho se estiverem na sua rede, ou por IP) e passam com o seu número e todo o seu histórico. Depois elimina o agente antigo, que terá ficado sem impressoras.
Se restaurares no mesmo Home Assistant uma cópia de segurança que inclua a app, o agente volta tal como estava, já ligado.

Desinstalá-lo

No BolloPrint, vai a Configurações → Impressoras → Agente local, abre o menu ⋮ do agente e prime Eliminar. As impressoras que só chegavam por ele desaparecem da lista; se um dia as voltares a adicionar, regressam com o seu histórico.
Em poucos segundos, a página do agente volta a oferecer Ligar ao BolloPrint. Se já não o queres, na ficha da app do Home Assistant abre o menu ⋮ e prime Desinstalar.
Se quiseres, remove também o repositório: Loja de apps → ⋮ → Repositórios, e o caixote do lixo ao lado de BolloPrint.

Se desinstalares a app sem eliminar antes o agente, no BolloPrint fica como Desligado. Elimina-o a partir do seu menu ⋮.

Quando alguma coisa não vai

A primeira coisa é o separador Registo da app no Home Assistant: conta o que o agente faz e, se parar, porquê.

Sintoma	O que fazer
O BolloPrint Agent não aparece na loja	Em Loja de apps, menu ⋮ → Procurar atualizações, e recarrega a página. Se em Configuração não tens Apps, o teu Home Assistant não tem apps: instala o agente com Docker.
Não te deixa instalá-la	O teu equipamento é de 32 bits, como um Raspberry Pi 3. A app precisa de 64 bits.
A instalação falha a meio	O Home Assistant descarrega o agente ao instalá-lo: confirma que tem internet e tenta outra vez.
A app para logo ao iniciá-la	Vê o Registo. Se disser `address already in use`, a porta está ocupada: muda-a como se explica acima.
Abrir a IU da Web não carrega	Estás fora da rede da oficina (acesso remoto, VPN, dados móveis). Abre-o a partir da rede local.
Ao ligar, a tua oficina não aparece	Só podes ligar o agente a oficinas de que és proprietário. Pede ao proprietário que o ligue ele.
Não encontra nenhuma impressora	O Home Assistant está na mesma rede que elas? Numa máquina virtual, a sua rede tem de estar em modo ponte. Se estão em redes separadas, adiciona-as por IP: funcionam na mesma.
Eliminaste-o no BolloPrint e a página continua a dizer «Ligado»	Espera um minuto e recarrega: o agente reinicia-se sozinho, já sem ligação a nenhuma oficina.