kota-technician-tool/docs/INSTRUKCJA_TECHNIKA.md

KOTA Sensorbox Technician Tool – instrukcja dla technika

Program służy do sprawdzenia sensorboxa przez USB, podłączenia go do Wi-Fi bez otwierania obudowy, wgrania firmware i przygotowania karty SD. Działa na Windows 10/11 i macOS 13 lub nowszym.

⚠️ Między boxem a komputerem musi być po drodze wtyczka USB 2.0 typu A (prostokątna). Może to być kabel USB 2.0 A wpięty do komputera albo do huba – hub jest w porządku. Połączenie wyłącznie przez USB-C (kabel USB-C–USB-C, przejściówka USB-C bez odcinka USB 2.0 A) często kończy się tym, że box nie jest widoczny w systemie („Unknown USB Device”) albo restartuje się przez spadki napięcia. Kabel musi przenosić dane – kabel „tylko do ładowania” nie zadziała.

---

Spis treści

1. Instalacja (raz na komputer)
2. Aktualizacja i uruchomienie
3. Podłączenie boxa
4. Diagnoza boxa – zakładka Serial monitor
5. Sprawdzenie krok po kroku – Guided troubleshooting
6. Wi-Fi przez USB – zakładka Wi-Fi (USB)
7. Wgrywanie firmware – zakładka Flash firmware
8. Karta SD – zakładka SD card
9. Raport serwisowy
10. Co oznacza kolor diody
11. Najczęstsze problemy

---

1. Instalacja (raz na komputer)

1. Na https://gitea.kota-app.com/kkallas/kota-technician-tool otwórz Releases i przy najnowszej wersji pobierz Source Code (ZIP).
2. Rozpakuj do zwykłego folderu, np. Dokumenty\KOTA\technician-tool (macOS: ~/Documents/KOTA/technician-tool). Nie do folderu Google Drive ani OneDrive.
3. Uruchom plik aktualizacji dla swojego systemu (patrz rozdział 2). Za pierwszym razem:
   • zapyta o login do Gitea (hasło lub token) – system go zapamięta,
   • za Twoją zgodą zainstaluje brakujące narzędzia (Git, uv),
   • pobierze biblioteki (1–2 minuty, potrzebny internet).

macOS: jeśli Finder nie chce otworzyć pliku .command, otwórz Terminal, wpisz bash (ze spacją), przeciągnij plik do okna Terminala i naciśnij Enter. Po pierwszej aktualizacji dwuklik zaczyna działać.

2. Aktualizacja i uruchomienie

W folderze narzędzia potrzebujesz tylko dwóch plików:

System	Aktualizacja	Uruchomienie
Windows	update_windows.bat	run_windows.bat
macOS	update_macos.command	run_macos.command

• Aktualizacja – uruchom przed wyjazdem do klienta albo gdy zespół ogłosi nową wersję. Pobiera tylko zmiany i pokazuje ich listę. Wymaga internetu.
• Uruchomienie – otwiera program. Działa bez internetu.

Po uruchomieniu otwiera się zakładka Quick start ze skróconą instrukcją i tabelą kolorów diody:

3. Podłączenie boxa

1. Włącz box włącznikiem z tyłu obudowy (ON). Samo zasilanie z laptopa może nie wystarczyć, szczególnie przy słabej baterii.

2. Podłącz box tak, żeby po drodze była wtyczka USB 2.0 typu A – do portu USB-A komputera albo do huba (patrz ostrzeżenie na górze).

3. Na liście portów box widać jako:

   • Windows: COMx - Sensorbox (native USB) [MAC]
   • macOS: /dev/cu.usbmodemXXXX - Sensorbox (native USB) [MAC]

   MAC (np. 14:C1:9F:57:72:48) to numer identyfikacyjny boxa – zapisz go w raporcie.

Jeśli boxa nie ma na liście, zobacz Najczęstsze problemy.

4. Diagnoza boxa – zakładka Serial monitor

1. Wybierz port sensorboxa i kliknij Connect.
2. Kliknij Reset & capture – box uruchomi się ponownie, a program nagra cały start.
3. Poczekaj ok. 70 sekund – co minutę box wysyła raport stanu (health), a program uzupełnia diagnozę.

Po lewej jest log z boxa, po prawej panel Diagnosis – czytaj go od góry:

Element	Co oznacza
Pasek na górze	Werdykt: zielony = wszystko działa, żółty/czerwony = główny problem.
Status LED should be	Jaki kolor i wzór powinna mieć dioda. Porównaj z boxem – jeśli jest inaczej, zanotuj to.
Firmware	Wersja i build firmware na boxie.
Box self-report	Co box sam o sobie zgłasza: czujniki (I2C), karta SD, zegar, Matter, mikrofon, Wi-Fi, stan co minutę. ✔ = OK, ! = uwaga, ✖ = błąd.
Start-up progress	Kolejne etapy startu z czasem w sekundach. Szare kółko = etap jeszcze nieosiągnięty.
Findings	Znalezione problemy – najpierw przyczyny, pod nimi (↳) ich skutki. Kliknij, by zobaczyć, co to znaczy i co zrobić.

Przydatne przyciski:

• Show: KOTA diagnostics + errors – pokazuje w logu tylko najważniejsze linie.
• Copy report – kopiuje diagnozę jako tekst (np. do maila).
• Open logs folder – pełne logi każdej sesji (do wysłania zespołowi firmware).

5. Sprawdzenie krok po kroku – Guided troubleshooting

Obok zakładki Diagnosis jest Guided troubleshooting. Program proponuje sprawdzenia pasujące do znalezionych problemów. Zacznij od Quick check – start here:

Program zadaje pytania (np. jaki kolor ma dioda) i na bieżąco sprawdza log boxa. Odpowiedzi trafiają do raportu:

6. Wi-Fi przez USB – zakładka Wi-Fi (USB)

Pozwala podłączyć box do sieci Wi-Fi bez otwierania obudowy i wyjmowania karty SD. Wymaga firmware z komendami USB – jeśli program zgłosi „The box does not answer USB commands”, najpierw wgraj najnowszy firmware (rozdział 7).

1. Kliknij Connect to the box (jeśli box nie jest już połączony w Serial monitor).
2. Opcjonalnie Read current Wi-Fi settings – pokazuje zapisaną sieć (hasła nigdy nie pokazuje).
3. Wpisz nazwę sieci (SSID) dokładnie jak na routerze i hasło (8–63 znaki). Sieć musi być 2,4 GHz i mieć hasło.
4. Kliknij Write to the box and connect i potwierdź.
5. Obserwuj listę kroków. Box zapisuje ustawienia, restartuje się i łączy z siecią. Na końcu zobaczysz „Connected to '…' (signal … dBm)”:

• Siła sygnału: powyżej −70 dBm jest dobrze, poniżej −75 dBm połączenie może się zrywać – przestaw box lub router.
• Po zapisaniu Wi-Fi box nie używa Matter. Powrót do Matter: Remove Wi-Fi (back to Matter).
• Jeśli box nie połączy się w 90 s, sprawdź nazwę sieci, hasło i czy to sieć 2,4 GHz. Ustawienia zostają na boxie, a box sam próbuje dalej.

7. Wgrywanie firmware – zakładka Flash firmware

1. Sensorbox – wybierz port. Program pokazuje, jaki firmware jest teraz na boxie i czy wybrany plik jest nowszy.
2. Firmware – wybierz plik. Lista pokazuje datę kompilacji, najnowszy jest na górze. Dostępne są tylko pliki z folderu firmware narzędzia (aktualizuje je update_…).
3. Co wgrać:
   • App only (zalecane przy naprawach) – wymienia tylko program. Parowanie Matter, rejestracja aktualizacji i ustawienia zostają.
   • Full image – tylko dla nowych lub całkowicie wyczyszczonych płytek. Kasuje parowanie Matter – box trzeba potem sparować od nowa. Wymaga zaznaczenia potwierdzenia.
   • Back up… – kopia całej pamięci boxa przed wgraniem (ok. 3 minuty). Zalecane przy Full image.
4. Kliknij Start flashing. Nie odłączaj kabla, dopóki nie pojawi się „Success” – program sam uruchomi box ponownie i sprawdzi, czy działa nowy firmware.

Jeśli wgrywanie nie może się połączyć: inny port/kabel (z wtyczką USB 2.0 A po drodze), zamknij inne programy używające portu. Ostateczność (trzeba otworzyć obudowę): przytrzymaj BOOT, naciśnij i puść RESET, puść BOOT, kliknij Start jeszcze raz.

8. Karta SD – zakładka SD card

Karta SD jest wewnątrz obudowy. Ta zakładka służy do przygotowania nowej karty albo naprawy uszkodzonej. Do zmiany samego Wi-Fi używaj zakładki Wi-Fi (USB) – nie trzeba wtedy otwierać obudowy.

1. Settings – ustawienia wczytują się z pliku od zespołu (INFLUX_URL, INFLUX_TOKEN). Nie zmieniaj ich bez potrzeby. Opcjonalnie możesz wpisać Wi-Fi (sieć i hasło).
2. Włóż kartę do czytnika w komputerze. Na liście pojawiają się tylko karty wymienne – dyski komputera nie są pokazywane.
3. Check card – sprawdza kartę bez zmieniania czegokolwiek. Write ENV.TXT only – zapisuje ustawienia, zostawia pomiary na karcie. Format card and write ENV.TXT – kasuje całą kartę (FAT32) i zapisuje ustawienia.
4. Program sam wysuwa kartę – dopiero wtedy ją wyjmij.

9. Raport serwisowy

Kliknij Service report… w zakładce Serial monitor. Otworzy się strona boxa w systemie KOTA Serwis z wpisaną diagnozą (werdykt, stan boxa, etapy startu, problemy z liczbą wystąpień i czasem). Sprawdź treść, dopisz lokalizację i uwagi, kliknij Zapisz.

Zaznaczenie Open service report on disconnect otwiera raport automatycznie po rozłączeniu boxa.

10. Co oznacza kolor diody

Kolor	Wzór	Znaczenie	Co zrobić
Zielony	ciągły	Wszystko OK	Nic
Cyan (turkusowy)	pulsuje / szybko miga	Nie sparowany w Matter / telefon łączy się	Sparuj w aplikacji Matter albo ustaw Wi-Fi przez USB
Biały	szybko miga / ciągły / pulsuje	Błąd karty SD lub ENV.TXT / reset fabryczny / tryb konfiguracji Wi-Fi	Sprawdź kartę SD (zakładka SD card)
Czerwony	1–6 błysków	Awaria czujnika: 1 BME688, 2 SEN66, 3 AS7341, 4 mikrofon, 5 flicker, 6 test po aktualizacji	Policz błyski, sprawdź przewód tego czujnika
Czerwony	ciągły	Inny błąd wewnętrzny / brak pamięci	Zapisz log, wyślij zespołowi
Niebieski	1 / 2 błyski	Zegar RTC nie odpowiada / zablokowana magistrala I2C	Sprawdź przewód I2C między płytkami
Fioletowy	ciągły / miga	Brak sieci / serwer odrzuca box (złe ENV.TXT)	Sprawdź Wi-Fi / wgraj poprawne ENV.TXT
Żółty	miga coraz szybciej	Pobiera aktualizację	Nie wyłączaj, poczekaj
Pomarańczowy	ciągły	Test po aktualizacji (~2,5 min)	Poczekaj
Zgaszona	–	Firmware nie działa lub brak zasilania	Sprawdź włącznik i kabel; wgraj firmware

Mała dioda obok (heartbeat): miga raz na sekundę = online, podwójnie = offline, nie miga = firmware stoi.

11. Najczęstsze problemy

Objaw	Przyczyna	Co zrobić
Boxa nie ma na liście portów	Brak wtyczki USB 2.0 A po drodze (samo USB-C), kabel tylko do ładowania, box wyłączony	Połączenie z wtyczką USB 2.0 typu A (do komputera lub huba), kabel z transmisją danych, włącznik ON, odłącz i podłącz ponownie. W Windows sprawdź Menedżer urządzeń – „Unknown USB Device” oznacza problem z kablem/portem/zasilaniem.
Diagnoza: „Power supply voltage drops (brown-out)”, box się restartuje	Za słabe zasilanie	Włącznik boxa ON, inny port USB-A, zasilacz; naładuj baterię
„The box does not answer USB commands” (Wi-Fi USB)	Stary firmware	Wgraj najnowszy firmware (App only)
„Clock chip was stopped at start-up”	Pusta bateria zegara RTC	Zegar ustawi się sam po połączeniu z internetem; przy powtórce wymień baterię pastylkową
„Box is not connected to Wi-Fi (not commissioned in Matter)”	Box nie jest sparowany	Sparuj w Matter (przycisk Matter pairing QR code…) albo ustaw Wi-Fi przez USB
Wgrywanie nie może połączyć się z boxem	Port zajęty lub zły kabel	Zamknij inne programy, inny kabel/port; ostatecznie BOOT + RESET (rozdział 7)

Jeśli problem się powtarza: Open logs folder → wyślij plik sesji zespołowi firmware razem z MAC boxa.