Merge branch 'docs/technician-guide' into main

Technician guide (Markdown + PDF) with screenshots; USB 2.0 type-A plug requirement in the guide, README and the app's hints.

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 |

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.

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."),
 ]

kota_tech/ui/cheatsheet.py

@@ -54,7 +54,8 @@ HINTS = [
 
 STEPS = [
     "Switch the sensorbox <b>power switch ON</b>.",
-    "Connect the laptop to the box's <b>native USB</b> port with a data-capable cable.",
+    "Connect the box so that a <b>USB 2.0 type-A plug</b> 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 <b>Serial monitor</b> tab, choose the sensorbox port, press "
     "<b>Connect</b>.",
     "Press <b>Reset &amp; capture</b> to record a full boot log from the first line.",

kota_tech/ui/flash_tab.py

@@ -36,7 +36,7 @@ BACKUP_DIR = SESSIONS_DIR.parent / "backups"
 VERIFY_TIMEOUT_MS = 45_000
 
 HELP = (
-    "<b>If flashing cannot connect:</b> use a data-capable USB cable directly on the laptop, close "
+    "<b>If flashing cannot connect:</b> 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 <b>BOOT</b>, "
     "press and release <b>RESET</b>, release <b>BOOT</b>, and press Start again."
 )