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).

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).

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.

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.