kkallasandClaude Opus 5.5
43f4c51aa4
Describes the zip from Releases and git clone/pull, the macOS executable-bit note for zips, and the branch/PR/tag workflow for the team. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
77 lines
3.2 KiB
Markdown
77 lines
3.2 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).
|
||
|
||
## 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.
|