KrzyszurandClaude Opus 5.5
66cb804102
New guided check "Sensor data in the database (InfluxDB)", also the last step of the Quick check on the green path. It queries InfluxDB (read token) for the newest point per measurement of the box and tells apart: sensor data arrives / status arrives without sensor data / offline now / never seen / check not possible. Polls every 30 s for up to 4 minutes. With a stopped RTC in the log it concludes that sensor readings are lost (stamped 1 Jan 2000): box A4:CB:8F:C9:47:3C sent only device_status and microphone. - service/influx.py: query, CSV parsing, classification (no new deps) - guides: new step type "influx" (host answers via influx_result) - Settings > InfluxDB access (or KOTA_INFLUX_TOKEN); token never logged - service status mapping for tech.influx.* findings Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
97 lines
5.1 KiB
Markdown
97 lines
5.1 KiB
Markdown
# KOTA Sensorbox Technician Tool
|
||
|
||
Diagnoza sensorboxa przez USB, wgrywanie firmware z folderu `firmware/` i przygotowanie karty SD.
|
||
Działa na Windows 10/11 i macOS 13 (Ventura) lub nowszym, na Macach z Intelem i Apple Silicon.
|
||
|
||
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 |
|
||
|---|---|---|
|
||
| Windows | `update_windows.bat` | `run_windows.bat` |
|
||
| macOS | `update_macos.command` | `run_macos.command` |
|
||
|
||
- **Aktualizacja** sprawdza na Gitea najnowszą wydaną wersję i pobiera tylko to, co się zmieniło
|
||
(pliki programu, firmware i potrzebne biblioteki). Uruchom ją, gdy firmware team ogłosi nową wersję,
|
||
albo po prostu przed wyjazdem do klienta. Pokazuje, co się zmieniło.
|
||
- **Uruchomienie** startuje program. Nie łączy się z Gitea, działa też bez internetu (po pierwszej aktualizacji).
|
||
|
||
Nie trzymaj folderu narzędzia w Google Drive ani OneDrive.
|
||
|
||
## Pierwsza instalacja (raz na komputer)
|
||
|
||
1. Na Gitea 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`).
|
||
3. Uruchom plik aktualizacji dla swojego systemu. Za pierwszym razem:
|
||
- połączy folder z Gitea i zapyta o login do Gitea (hasło lub token); system je zapamięta,
|
||
- zainstaluje brakujące narzędzia za Twoją zgodą: Git (Windows: przez winget; macOS: Apple Command Line Tools
|
||
- po ich instalacji uruchom aktualizację jeszcze raz) oraz `uv` (menedżer Pythona, tylko dla bieżącego
|
||
użytkownika),
|
||
- pobierze biblioteki Pythona (1–2 minuty, potrzebny internet).
|
||
4. Uruchom program plikiem `run_...`.
|
||
|
||
**macOS:** jeśli Finder odpowie, że pliku nie można uruchomić (zdarza się po rozpakowaniu zip), otwórz Terminal,
|
||
wpisz `bash ` (ze spacją), przeciągnij `update_macos.command` do okna i naciśnij Enter. Po pierwszej aktualizacji
|
||
oba pliki `.command` dają się już otwierać dwuklikiem.
|
||
|
||
Zamiast zip można też zrobić `git clone https://gitea.kota-app.com/kkallas/kota-technician-tool.git` i dalej
|
||
używać tych samych dwóch plików.
|
||
|
||
Konkretna starsza wersja (np. do serwisu nietypowego boxa): w folderze narzędzia `git switch --detach v0.8`;
|
||
kolejna aktualizacja wraca do najnowszej.
|
||
|
||
Wszystkie wersje używają jednego środowiska Pythona poza folderem narzędzia:
|
||
`%LOCALAPPDATA%\KotaTechnicianTool\venv` (Windows), `~/Library/Caches/KotaTechnicianTool/venv` (macOS).
|
||
Stare środowiska `venv-0.x` z poprzednich wersji można usunąć.
|
||
|
||
Sesje, kopie zapasowe flash i ustawienia są w `~/KotaTechnicianTool` (Windows: `C:\Users\<użytkownik>\KotaTechnicianTool`).
|
||
|
||
## Dane w InfluxDB
|
||
|
||
Kontrola **Sensor data in the database (InfluxDB)** (Guided troubleshooting, także ostatni krok Quick check)
|
||
sprawdza online, czy do InfluxDB trafiają dane z czujników boxa, a nie tylko jego status. Wymaga internetu
|
||
na laptopie i jednorazowego ustawienia tokenu tylko do odczytu (od zespołu firmware):
|
||
**Settings > InfluxDB access...**. Tokenu nie zapisujemy w repozytorium.
|
||
|
||
## Port sensorboxa
|
||
|
||
- Windows: `COMx - Sensorbox (native USB) [MAC]`
|
||
- macOS: `/dev/cu.usbmodemXXXX - Sensorbox (native USB) [MAC]`
|
||
|
||
Kabel USB musi przenosić dane (nie tylko ładowanie). Przy restartach z komunikatem o brownout użyj innego portu
|
||
lub zasilacza.
|
||
|
||
## Wi-Fi przez USB (bez otwierania obudowy)
|
||
|
||
Zakładka **Wi-Fi (USB)**: podłącz box kablem USB, kliknij **Connect to the box**, wpisz nazwę sieci i hasło,
|
||
kliknij **Write to the box and connect**. Box zapisuje je na karcie SD, restartuje się i łączy z siecią
|
||
(zamiast Matter); zakładka pokazuje każdy krok aż do „Connected ... (signal -58 dBm)”.
|
||
**Read current Wi-Fi settings** pokazuje zapisaną sieć (bez hasła), **Remove Wi-Fi** wraca do Matter.
|
||
Wymaga firmware z komendami USB (plik `firmware/merged-binary-v13.bin` lub nowszy); starszy firmware
|
||
wgraj w zakładce **Flash firmware** (tryb App only zachowuje parowanie i ustawienia).
|
||
|
||
## Firmware
|
||
|
||
Wgrać można tylko pliki `.bin` z folderu `firmware/`. Lista pokazuje datę kompilacji zapisaną w pliku,
|
||
najnowszy build jest na górze. Nowy build: wrzuć plik do `firmware/` i kliknij **Refresh list**.
|
||
|
||
## Dla zespołu
|
||
|
||
- Praca nad zmianą: gałąź (`git switch -c feature/<nazwa>`) → commity z przechodzącymi testami →
|
||
`git push -u origin feature/<nazwa>` → pull request na Gitea → merge do `main`.
|
||
- Wydanie wersji: numer w `pyproject.toml`, `kota_tech/__init__.py` i `uv.lock`, tag `vX.Y`
|
||
(`git tag -a vX.Y -m "Technician tool vX.Y"`, `git push origin vX.Y`), opis w **Releases** na Gitea.
|
||
Aktualizacja techników bierze **tylko tagi `v*`** – zmiany w `main` bez tagu do nich nie trafiają.
|
||
- Nie commitujemy `ENV.TXT` z prawdziwym tokenem ani haseł Wi-Fi.
|
||
- Testy:
|
||
|
||
```
|
||
uv run --frozen pytest -q
|
||
```
|
||
|
||
Zmiany w wersjach: `docs/CHANGES-v0.*.md`; historia v0.1–v0.8 jest w tagach gita.
|