diff --git a/README.md b/README.md index d0e843d..bf69946 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,9 @@ Działa na Windows 10/11 i macOS 13 (Ventura) lub nowszym, na Macach z Intelem i Repozytorium: https://gitea.kota-app.com/kkallas/kota-technician-tool (dostęp nadaje właściciel repozytorium). +**Instrukcja krok po kroku ze zrzutami ekranu: [docs/INSTRUKCJA_TECHNIKA.md](docs/INSTRUKCJA_TECHNIKA.md) (do druku: [PDF](docs/INSTRUKCJA_TECHNIKA.pdf)).** +Box podłączaj tak, żeby po drodze była wtyczka USB 2.0 typu A (do komputera albo do huba). + ## Dla technika: dwa pliki | System | Aktualizacja | Uruchomienie | diff --git a/docs/INSTRUKCJA_TECHNIKA.md b/docs/INSTRUKCJA_TECHNIKA.md new file mode 100644 index 0000000..4e61b35 --- /dev/null +++ b/docs/INSTRUKCJA_TECHNIKA.md @@ -0,0 +1,204 @@ +# 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)](#1-instalacja-raz-na-komputer) +2. [Aktualizacja i uruchomienie](#2-aktualizacja-i-uruchomienie) +3. [Podłączenie boxa](#3-podłączenie-boxa) +4. [Diagnoza boxa – zakładka Serial monitor](#4-diagnoza-boxa--zakładka-serial-monitor) +5. [Sprawdzenie krok po kroku – Guided troubleshooting](#5-sprawdzenie-krok-po-kroku--guided-troubleshooting) +6. [Wi-Fi przez USB – zakładka Wi-Fi (USB)](#6-wi-fi-przez-usb--zakładka-wi-fi-usb) +7. [Wgrywanie firmware – zakładka Flash firmware](#7-wgrywanie-firmware--zakładka-flash-firmware) +8. [Karta SD – zakładka SD card](#8-karta-sd--zakładka-sd-card) +9. [Raport serwisowy](#9-raport-serwisowy) +10. [Co oznacza kolor diody](#10-co-oznacza-kolor-diody) +11. [Najczęstsze problemy](#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: + +![Quick start](img/01_quick_start.png) + +## 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](#11-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ę. + +![Serial monitor i diagnoza](img/02_serial_diagnosis.png) + +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**: + +![Lista sprawdzeń](img/03_guided_list.png) + +Program zadaje pytania (np. jaki kolor ma dioda) i na bieżąco sprawdza log boxa. Odpowiedzi trafiają do raportu: + +![Pytanie o kolor diody](img/04_guided_led_question.png) + +## 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)”**: + +![Wi-Fi przez USB](img/06_wifi_usb.png) + +- 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 + +![Wgrywanie firmware](img/05_flash.png) + +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. + +![Karta SD](img/07_sd_card.png) + +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. diff --git a/docs/INSTRUKCJA_TECHNIKA.pdf b/docs/INSTRUKCJA_TECHNIKA.pdf new file mode 100644 index 0000000..a2ae846 Binary files /dev/null and b/docs/INSTRUKCJA_TECHNIKA.pdf differ diff --git a/docs/img/01_quick_start.png b/docs/img/01_quick_start.png new file mode 100644 index 0000000..73029c1 Binary files /dev/null and b/docs/img/01_quick_start.png differ diff --git a/docs/img/02_serial_diagnosis.png b/docs/img/02_serial_diagnosis.png new file mode 100644 index 0000000..d17f80c Binary files /dev/null and b/docs/img/02_serial_diagnosis.png differ diff --git a/docs/img/03_guided_list.png b/docs/img/03_guided_list.png new file mode 100644 index 0000000..336a88b Binary files /dev/null and b/docs/img/03_guided_list.png differ diff --git a/docs/img/04_guided_led_question.png b/docs/img/04_guided_led_question.png new file mode 100644 index 0000000..1982d33 Binary files /dev/null and b/docs/img/04_guided_led_question.png differ diff --git a/docs/img/05_flash.png b/docs/img/05_flash.png new file mode 100644 index 0000000..f99aa54 Binary files /dev/null and b/docs/img/05_flash.png differ diff --git a/docs/img/06_wifi_usb.png b/docs/img/06_wifi_usb.png new file mode 100644 index 0000000..3d8cd1b Binary files /dev/null and b/docs/img/06_wifi_usb.png differ diff --git a/docs/img/07_sd_card.png b/docs/img/07_sd_card.png new file mode 100644 index 0000000..60ca25d Binary files /dev/null and b/docs/img/07_sd_card.png differ diff --git a/kota_tech/flash/runner.py b/kota_tech/flash/runner.py index ae596f6..1abd04b 100644 --- a/kota_tech/flash/runner.py +++ b/kota_tech/flash/runner.py @@ -26,7 +26,7 @@ HINTS = [ "The box did not enter flashing mode by itself. Open the case, hold the BOOT button, press and release RESET, " "release BOOT, then press Start again."), (re.compile(r"device reports readiness to read but returned no data|The port disappeared|device disconnected", re.I), - "The USB connection dropped. Use a short data-capable USB cable directly on the laptop (no hub) and try again."), + "The USB connection dropped. Use a data-capable cable with a USB 2.0 type-A plug on the way to the laptop (not USB-C only) and try again."), (re.compile(r"Invalid head of packet|timed out", re.I), "Communication errors. Try another USB cable or port."), ] diff --git a/kota_tech/ui/cheatsheet.py b/kota_tech/ui/cheatsheet.py index b42d389..7928b5f 100644 --- a/kota_tech/ui/cheatsheet.py +++ b/kota_tech/ui/cheatsheet.py @@ -54,7 +54,8 @@ HINTS = [ STEPS = [ "Switch the sensorbox power switch ON.", - "Connect the laptop to the box's native USB port with a data-capable cable.", + "Connect the box so that a USB 2.0 type-A plug is on the way to the laptop (into the laptop or a " + "hub; USB-C only often fails). The cable must carry data.", "Open the Serial monitor tab, choose the sensorbox port, press " "Connect.", "Press Reset & capture to record a full boot log from the first line.", diff --git a/kota_tech/ui/flash_tab.py b/kota_tech/ui/flash_tab.py index 1accf88..0ae4e7b 100644 --- a/kota_tech/ui/flash_tab.py +++ b/kota_tech/ui/flash_tab.py @@ -36,7 +36,7 @@ BACKUP_DIR = SESSIONS_DIR.parent / "backups" VERIFY_TIMEOUT_MS = 45_000 HELP = ( - "If flashing cannot connect: use a data-capable USB cable directly on the laptop, close " + "If flashing cannot connect: use a data-capable cable with a USB 2.0 type-A plug on the way, close " "other programs using the port, then retry. Last resort (case must be opened): hold BOOT, " "press and release RESET, release BOOT, and press Start again." )