🧩 O agente local
O agente local é um programa pequeno que corre num equipamento da tua oficina. Fala com as tuas impressoras pela rede local e conta ao BolloPrint o que vê.
É a única coisa que é preciso instalar para ligar impressoras por rede local e, com um só, chega para toda a frota.
Precisas dele?
| A tua situação | Precisas do agente? |
|---|---|
| Tens Bambu Lab e chega-te vê-las pela nuvem | Não, mas com o agente ganhas câmara. Pausar e cancelar, não: a Bambu não aceita ordens de programas alheios, vá por onde for |
| Tens Prusa | Sim. É a única forma de as ligar |
| Tens Elegoo de resina ou Centauri | Sim. Não há outra via |
| Tens QIDI, Sovol, Voron, RatRig, Two Trees, Artillery, uma Creality K1 com Moonraker acessível ou qualquer máquina com Klipper | Sim |
| Tens FlashForge Adventurer 5M, AD5X ou Creator 5 | Sim |
| Não queres que as tuas impressoras saiam para a internet | Sim. O agente fala com elas dentro da tua rede |
Instalá-lo e mantê-lo atualizado
Duas páginas à parte, porque são dois momentos diferentes:
- 🚀 Instalar o agente — onde o pôr, como o criar no BolloPrint e como o arrancar no teu equipamento com Docker Compose, Portainer ou Kubernetes.
- 🔄 Atualizar o agente — o que fazer quando o BolloPrint te avisa de que há uma versão nova. É mudar um número e voltar a instalar.
Como se liga
O agente liga-se ao BolloPrint, não ao contrário. É isso que faz com que funcione sem mexer no router: não é preciso abrir portas, nem pedir IP fixo, nem tocar na firewall. Funciona atrás de um router doméstico normal, e até com as ligações de fibra que não dão IP público.
Uma vez ligado:
- pergunta que impressoras tem de atender,
- liga-se a cada uma pelo seu protocolo,
- e vai enviando o que vê.
Quando registas uma impressora nova a partir do BolloPrint, o agente dá por isso sozinho, em segundos. Não é preciso reiniciá-lo.
Autorizar instalações
A instalação do manifesto que copiaste entra logo. Qualquer outra instalação que use esse mesmo código espera pelo teu aval: vais ver um aviso vermelho por cima dos separadores e, dentro do agente, em Estado, a instalação em Instalações a aguardar autorização, com o nome do equipamento a partir do qual se liga.
Com um manifesto atual isto quase não acontece: a identidade vai escrita no próprio manifesto, por isso podes mudar o agente de máquina ou reinstalá-lo e continua a ser o mesmo. É normal que aconteça com um agente anterior, instalado com um manifesto sem identidade, quando:
- o mudas para outra máquina,
- apagas o seu volume de dados e o voltas a criar,
- o reinstalas de raiz.
Prime Autorizar se reconheces o equipamento. Ao autorizar um, o anterior deixa de ter acesso.
Se aparecer uma instalação pendente que não foste tu a pôr, não a autorizes: significa que mais alguém tem o teu código. Abre o agente, usa Regenerar chaves em Instalação e volta a instalá-lo com o manifesto novo.
O ecrã de estado
O separador Agente local tem duas partes:
- Os agentes, um por linha, com o seu estado e a sua versão. No menu ⋮ de cada um tens Editar, que abre a sua janela, e Eliminar.
- Impressoras na rede local, por baixo: as de todos os teus agentes juntas, cada uma com o agente que a conduz. Em cima estão Procurar agora e Adicionar por IP, e no final o que cada agente encontrou na tua rede e os endereços que ainda está a procurar.
A janela de um agente tem dois separadores:
- Estado — aquilo que o próprio agente reporta (a tabela abaixo), as instalações pendentes e a ligação a cada impressora. Também é aqui que lhe mudas o nome.
- Instalação — o manifesto com a versão atual e Regenerar chaves.
O que pode aparecer em Estado:
| O que vês | O que significa |
|---|---|
| Online | Está ligado e a trabalhar. |
| Sem sinal recente | Já vai um bocado sem dar sinal. Costuma ser o equipamento desligado ou sem internet. |
| Desligado | Não está. |
| Modo seguro | Arrancou e ligou-se, mas não está a gerir impressoras. Diz-te o motivo. |
| Buffer | O que guardou enquanto não o conseguia enviar. Se aparecer «mensagens descartadas», houve um corte tão longo que não coube tudo. |
| Atualiza o teu agente | Há uma versão mais recente. Faz-se no teu equipamento, não a partir do BolloPrint: muda a versão da imagem no teu ficheiro e volta a instalar. Passo a passo em Atualizar o agente. |
Por baixo, Ligação a cada impressora: máquina a máquina, se o agente chega a ela e, se não chega, porquê.
O agente procura impressoras novas na tua rede sozinho a cada 15 minutos. Se acabaste de ligar uma e não queres esperar, prime Procurar agora em Impressoras na rede local.
Particularidades que convém conhecer
O agente lembra-se de quem é. A sua identidade vai escrita no manifesto (BP_AGENT_INSTANCE_ID), por isso o mesmo manifesto arrancado noutra máquina continua a ser o mesmo agente. Não a alteres nem a copies para outra instalação: é a sua palavra-passe. Os agentes instalados com um manifesto anterior guardam a identidade no seu volume de dados; se o apagares, terás de o autorizar outra vez (não se perde nada).
Um agente aguenta uma frota inteira. Não é preciso um por impressora nem um por sala. Dito isto, podes ter vários agentes na mesma conta, e há três motivos para o fazer:
- Redes separadas: uma VLAN para produção e outra para escritório, por exemplo. Um agente em cada uma deteta as suas sem que tenhas de acrescentar nada à mão.
- Locais diferentes: dois pavilhões, duas oficinas, duas casas. Cada sítio com o seu, e vê-se tudo junto no BolloPrint.
- Um agente saturado: se a frota crescer muito e notares que está no limite, reparte as impressoras por dois.
Cada agente cria-se da mesma forma, com o seu nome e o seu próprio código. No separador Agente local vê-los-ás uns por baixo dos outros, e em Impressoras na rede local cada máquina diz por que agente chega. Para mudares uma impressora de um agente para outro, abre-a com Editar no seu menu ⋮ e muda o agente na lista pendente. Ao Adicionar por IP com vários agentes, pergunta-te qual é o que a vai conduzir.
⚠️ Um código por equipamento
O que não deves fazer é usar o mesmo código em duas máquinas: a segunda fica à espera de autorização e, se a autorizares, a primeira perde o acesso. Para dois equipamentos, dois agentes.
Sobrevive aos cortes. Se a tua internet cair, o agente continua a ler as impressoras e a guardar o que se passa. Quando a ligação volta, manda tudo. As horas do corte não se perdem do histórico.
Regenerar as chaves desliga o agente no momento. O código e a identidade anteriores deixam de valer assim que premes o botão, por isso o agente fica desligado até o voltares a instalar com o manifesto novo. Usa-o quando achares que alguém tem as tuas chaves ou se perdeste o manifesto. Para atualizar o agente não é preciso: basta mudar a versão da imagem (Atualizar o agente).
Eliminar um agente leva as suas impressoras. Faz-se a partir do menu ⋮ da sua linha. Deixa de se ligar no momento, e as impressoras que só chegavam por ele desaparecem da lista e deixam de contar para o teu plano. As que também chegam pela Bambu Cloud ficam. Não se perde nada: se voltares a adicionar uma dessas impressoras — com outro agente, por deteção ou por IP —, ela volta com o seu número e todo o seu histórico. O contentor que corre no teu equipamento não se apaga a partir do BolloPrint: para-o e elimina-o tu (docker compose down na sua pasta, ou apaga o stack no Portainer).
Quando alguma coisa não vai
Quando o agente não aparece ou se porta de forma estranha, a primeira coisa é ver o seu registo no equipamento onde corre:
docker logs bolloprint_agent --tail 50
| Sintoma | O que ver |
|---|---|
| O agente nunca aparece | O código foi bem colado, inteiro e sem espaços à frente ou atrás? O equipamento chega à internet? Há alguma firewall a bloquear a saída? |
| Pede autorização em cada reinício | O manifesto não leva BP_AGENT_INSTANCE_ID (é antigo ou foi editado à mão). Regenera as chaves e instala o manifesto novo tal como está. |
| Não deteta nenhuma impressora | O agente e as impressoras estão na mesma rede? Se não estão, ou se usas o Docker Desktop, é o esperado: acrescenta-as por IP e funcionarão na mesma. |
| Uma impressora aparece como «ligada mas sem enviar dados» | Fecha a app do telemóvel ou o fatiador que a tenha aberta. Algumas máquinas só admitem uma ligação de cada vez. |
| Uma impressora «responde mas recusa a ligação» | Código de acesso errado, ou modo LAN desativado no ecrã da máquina. Atenção: nas Bambu, o código muda sempre que ativas ou desativas o modo LAN. |
| Todas as impressoras de um agente desligadas de repente | Não é a frota, é o agente. Abre-o com Editar e vê o seu Estado. |
Perguntas frequentes
Posso pausar ou cancelar uma impressão a partir do BolloPrint? Sim, nas máquinas ligadas pelo agente que o permitem (hoje, Klipper, PrusaLink e as Elegoo que vão por SDCP: as de resina e a Centauri Carbon). Nas Bambu não, nem pelo agente nem pela nuvem: o seu firmware ignora as ordens que não vêm dos seus próprios programas. O que não se pode em nenhuma é enviar trabalhos: o ficheiro continua a ser mandado a partir do teu fatiador.
O que acontece se a internet cair na oficina? O agente continua a falar com as tuas impressoras e guarda o que acontece. Quando a ligação volta, envia tudo. Se o corte for longuíssimo, pode não lhe caber o detalhe todo e, nesse caso, ele diz-to.
Guarda alguma coisa no meu disco? Não guarda dados de impressão. No seu volume guarda o seu próprio registo de atividade dos últimos dias, que se vai apagando sozinho (e, nos agentes instalados com um manifesto anterior, o seu ficheiro de identidade). Esse registo só sai do teu equipamento se o suporte do BolloPrint o pedir para investigar um problema.
Quanto consome? Muito pouco: entre 10 e 20 MB de memória com várias impressoras ligadas.
E se desligar o equipamento? Não acontece nada. Ao ligá-lo, o agente volta sozinho e sem te pedir nada.
Tenho de abrir portas no router? Não. Nem portas, nem IP fixo, nem regras de firewall. A ligação sai da tua rede para fora, como quando abres uma página web.