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