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

Instalacja

Wybierz jeden sposób. Nie trzymaj narzędzia w folderze Google Drive ani OneDrive.

A. Paczka zip (najprościej)

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.
3. Nowa wersja: pobierz nowy zip i rozpakuj obok (albo w miejsce starego folderu).

B. Git (aktualizacja jednym poleceniem)

Wymaga zainstalowanego gita (Windows: https://git-scm.com, macOS: xcode-select --install).

git clone https://gitea.kota-app.com/kkallas/kota-technician-tool.git

Przy pierwszym połączeniu podaj login i hasło (lub token) do Gitea; system je zapamięta. Aktualizacja do najnowszej wersji, w folderze kota-technician-tool:

git pull

Konkretna wersja, np. na potrzeby serwisu starszego boxa: git switch --detach v0.8, powrót: git switch main.

Uruchomienie

Windows: dwuklik run_windows.bat.

macOS: dwuklik run_macos.command. Jeśli Finder odpowie, że pliku nie można uruchomić (zdarza się po rozpakowaniu zip), otwórz Terminal, wpisz bash (ze spacją), przeciągnij plik do okna i naciśnij Enter. Na stałe naprawia to chmod +x run_macos.command. Przy instalacji przez git ten problem nie występuje.

Przy pierwszym uruchomieniu skrypt proponuje instalację uv (menedżer Pythona, tylko dla bieżącego użytkownika) i pobiera biblioteki. Potrzebny jest internet, trwa to 1–2 minuty. Kolejne starty są natychmiastowe. Środowisko Pythona jest poza folderem narzędzia: %LOCALAPPDATA%\KotaTechnicianTool\venv-<wersja> (Windows), ~/Library/Caches/KotaTechnicianTool/venv-<wersja> (macOS).

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 skryptach run_*, tag vX.Y (git tag -a vX.Y -m "Technician tool vX.Y", git push origin vX.Y), opis w Releases na Gitea.
• Nie commitujemy ENV.TXT z prawdziwym tokenem ani haseł Wi-Fi.
• Testy:

uv run --frozen pytest -q

Zmiany w wersjach: docs/CHANGES-v0.7.md, docs/CHANGES-v0.8.md; historia v0.1–v0.8 jest w tagach gita.