🏠 Agent w Home Assistant

Jeśli masz już w warsztacie Home Assistant, który działa dzień i noc, masz też gdzie postawić agenta: jest zawsze włączony, jest w twojej sieci i ma własny sklep z aplikacjami. Ta strona opisuje, jak go tam zainstalować, powiązać z twoim warsztatem i utrzymać aktualnym.

Jeśli masz inny sprzęt (NAS, komputer, serwer z Dockerem), wybierz swój w Agent lokalny. Znajdziesz tam też, co robi agent, niezależnie od sprzętu.

---

Czego potrzebujesz

• Home Assistant OS, czyli instalacji, która ma sklep z aplikacjami. Instalacje „Supervised” też go mają, ale Home Assistant już ich nie utrzymuje. Jeśli twój Home Assistant działa w Dockerze („Container”), nie ma aplikacji: zainstaluj agenta przez Dockera, jak opisuje Agent w Dockerze.
• Urządzenie 64-bitowe: mini-PC albo komputer z procesorem Intel lub AMD, Raspberry Pi 4 lub 5 albo Home Assistant Green lub Yellow. Na Raspberry Pi 3 ani w systemie 32-bitowym aplikacji nie da się zainstalować.
• Home Assistant musi być w tej samej sieci co twoje drukarki. Jeśli działa na maszynie wirtualnej, jej sieć musi być w trybie mostu (bridge), a nie NAT.
• Wolny port 8257 na tym urządzeniu. Jeśli używa go coś innego, zmienisz go w chwilę (niżej).
• Musisz być właścicielem warsztatu w BolloPrint: agenta można powiązać tylko z twoim warsztatem.

---

Instalacja

1. Na komputerze albo telefonie podłączonym do twojej sieci otwórz ten link: Dodaj BolloPrint do mojego Home Assistant. To strona Home Assistant: za pierwszym razem poprosi o adres twojego Home Assistant, na przykład http://homeassistant.local:8123.
2. Kliknij Open link. Twój Home Assistant zapyta (w oknie „Add app repository?”), czy chcesz dodać repozytorium aplikacji BolloPrint: kliknij Dodaj.
3. Otworzy się strona aplikacji BolloPrint Agent, z psem BolloPrint. Kliknij Zainstaluj. Home Assistant sam przygotuje aplikację; trwa to minutę lub dwie.
4. Kliknij Uruchom. Zostaw włączoną opcję Uruchamianie przy starcie, żeby agent wracał sam za każdym razem, gdy Home Assistant się zrestartuje.

---

Powiązanie z twoim warsztatem

1. Na stronie aplikacji kliknij Otwórz interfejs użytkownika. Strona agenta otworzy się w nowej karcie: mówi, że agent nie należy jeszcze do żadnego warsztatu, i pokazuje kod, na przykład 8054-627E.
2. Kliknij Powiąż z BolloPrint. Przeniesie cię do BolloPrint; zaloguj się na swoje konto, jeśli o to poprosi.
3. Wybierz warsztat, sprawdź, czy kod jest taki sam jak na stronie agenta, przejrzyj proponowaną nazwę (nazwę twojego Home Assistant; możesz ją zmienić) i potwierdź.
4. Wracasz na stronę agenta, która pokazuje już „Powiązano z …”. W niecałą minutę zobaczysz go jako Online w Ustawienia → Drukarki → Agent lokalny, z logo Home Assistant, i zacznie szukać twoich drukarek.

W BolloPrint nie trzeba niczego wcześniej tworzyć. Karta Home Assistant w Nowy agent tylko przypomina te kroki.

---

Port strony

Strona agenta używa portu 8257 na urządzeniu z Home Assistant. Jeśli coś innego już go używa, aplikacja zatrzymuje się zaraz po starcie, a jej zakładka Log pokazuje address already in use. Żeby go zmienić:

1. Na stronie aplikacji otwórz zakładkę Konfiguracja.
2. W sekcji Sieć wpisz inny numer (na przykład 8364) i kliknij Zapisz.
3. Home Assistant zapyta, czy zrestartować aplikację: zgódź się. Otwórz interfejs użytkownika prowadzi już do nowego portu.

Zmiana portu nie zrywa powiązania agenta: to nadal ten sam agent, z tymi samymi drukarkami.

---

Aktualizacje

Aktualizują się tu dwie rzeczy i prawie nigdy nie musisz nic robić:

Co	Jak się aktualizuje
Agent, czyli to, co rozmawia z twoimi drukarkami	Sam. Gdy BolloPrint opublikuje nową wersję, agent sam ją pobiera i instaluje.
Aplikacja w Home Assistant, czyli to, co uruchamia agenta	Gdy Home Assistant powiadomi cię o aktualizacji BolloPrint Agent, kliknij Aktualizuj na stronie aplikacji. Jeśli włączysz tam Automatyczna aktualizacja, zrobi to sam.

Aktualizacja aplikacji nie zrywa powiązania agenta. Jego tożsamość jest zapisana w danych aplikacji, które trafiają też do kopii zapasowych Home Assistant.

---

Przeniesienie na inne urządzenie lub ponowna instalacja

• Jeśli zainstalujesz ponownie aplikację albo postawisz ją na innym Home Assistant, powiąż ją jeszcze raz: będzie to nowy agent. Dodaj z nim swoje drukarki (znajdzie je sam, jeśli są w jego sieci, albo po IP), a przejdą ze swoim numerem i całą historią. Potem usuń starego agenta, który zostanie bez drukarek.
• Jeśli na tym samym Home Assistant przywrócisz kopię zapasową zawierającą aplikację, agent wróci taki, jaki był, już powiązany.

---

Odinstalowanie

1. W BolloPrint przejdź do Ustawienia → Drukarki → Agent lokalny, otwórz menu ⋮ agenta i kliknij Usuń. Drukarki, które docierały tylko przez niego, znikną z listy; jeśli kiedyś dodasz je ponownie, wrócą ze swoją historią.
2. Po kilku sekundach strona agenta znów pokaże Powiąż z BolloPrint. Jeśli już go nie chcesz, na stronie aplikacji w Home Assistant otwórz menu ⋮ i kliknij Odinstaluj.
3. Jeśli chcesz, usuń też repozytorium: Sklep z aplikacjami → ⋮ → Repozytoria i ikona kosza obok BolloPrint.

Jeśli odinstalujesz aplikację, nie usuwając wcześniej agenta, w BolloPrint zostanie jako Rozłączony. Usuń go z jego menu ⋮.

---

Gdy coś nie działa

Najpierw zajrzyj do zakładki Log aplikacji w Home Assistant: widać tam, co robi agent, a jeśli się zatrzyma — dlaczego.

Objaw	Co zrobić
BolloPrint Agent nie pojawia się w sklepie	W sklepie (Sklep z aplikacjami) otwórz menu ⋮ → Sprawdź aktualizacje i odśwież stronę. Jeśli w Ustawieniach nie ma pozycji Aplikacje, twój Home Assistant nie ma aplikacji: zainstaluj agenta przez Dockera.
Nie da się jej zainstalować	Twoje urządzenie jest 32-bitowe, jak Raspberry Pi 3. Aplikacja wymaga 64 bitów.
Instalacja przerywa się w połowie	Home Assistant pobiera agenta podczas instalacji: sprawdź, czy ma dostęp do internetu, i spróbuj ponownie.
Aplikacja zatrzymuje się zaraz po uruchomieniu	Zajrzyj do zakładki Log. Jeśli widnieje address already in use, port jest zajęty: zmień go, jak opisano wyżej.
Otwórz interfejs użytkownika się nie ładuje	Jesteś poza siecią warsztatu (zdalny dostęp, VPN, dane komórkowe). Otwórz ją z sieci lokalnej.
Przy powiązywaniu nie widać twojego warsztatu	Agenta możesz powiązać tylko z warsztatami, których jesteś właścicielem. Poproś właściciela, żeby sam go powiązał.
Nie znajduje żadnej drukarki	Czy Home Assistant jest w tej samej sieci co drukarki? Na maszynie wirtualnej jej sieć musi być w trybie mostu. Jeśli są w oddzielnych sieciach, dodaj je po IP: działają tak samo.
Usunąłeś go w BolloPrint, a strona nadal pokazuje „Powiązano”	Odczekaj minutę i odśwież: agent sam się restartuje, już bez powiązania.