diff --git a/README.md b/README.md index 5723379..cf65845 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,77 @@ -# 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-` (Windows), `~/Library/Caches/KotaTechnicianTool/venv-` (macOS). - -Sesje, kopie zapasowe flash i ustawienia są w `~/KotaTechnicianTool` (Windows: `C:\Users\\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/`) → commity z przechodzącymi testami → - `git push -u origin feature/` → 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. +# 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 echnician-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 env` (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\\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/`) → commity z przechodzącymi testami → + `git push -u origin feature/` → 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. diff --git a/docs/CHANGES-v0.9.md b/docs/CHANGES-v0.9.md new file mode 100644 index 0000000..e0b4023 --- /dev/null +++ b/docs/CHANGES-v0.9.md @@ -0,0 +1,9 @@ +# Technician tool v0.9 - changes + +- Two files per system for technicians: `update_windows.bat` / `update_macos.command` (update) and + `run_windows.bat` / `run_macos.command` (start). +- Update: checks Gitea for the newest release tag `vX.Y`, downloads only what changed (git), shows the list of + changes, protects files edited by hand (asks first), connects a folder unpacked from a release zip on first + run, installs git / uv when missing (asks first) and brings the Python libraries up to date. +- One shared Python environment for all versions: `KotaTechnicianTool/venv` (was `venv-0.x` per version). +- A developer copy on a branch is left alone by the update script (use `git pull`). diff --git a/update_windows.bat b/update_windows.bat index e0de997..0e12c49 100644 --- a/update_windows.bat +++ b/update_windows.bat @@ -19,7 +19,7 @@ if errorlevel 1 ( winget install --id Git.Git -e --source winget --accept-package-agreements where git >nul 2>nul if errorlevel 1 ( - echo [!] Git installation failed. Install it from https://git-scm.com and run this again. + echo ERROR: Git installation failed. Install it from https://git-scm.com and run this again. goto :fail ) ) @@ -43,7 +43,7 @@ if not errorlevel 1 ( echo Checking for a new version... git fetch --quiet --force --tags origin if errorlevel 1 ( - echo [!] Cannot reach %KOTA_REPO_URL%. + echo ERROR: Cannot reach %KOTA_REPO_URL%. echo Check the Internet connection and your Gitea login, then try again. goto :fail ) @@ -51,7 +51,7 @@ if errorlevel 1 ( set "LATEST=" for /f "delims=" %%t in ('git tag -l "v*" --sort^=-v:refname') do if not defined LATEST set "LATEST=%%t" if not defined LATEST ( - echo [!] No released version found on the server. + echo ERROR: No released version found on the server. goto :fail ) set "CURRENT=" @@ -87,7 +87,7 @@ if errorlevel 1 ( ) where uv >nul 2>nul if errorlevel 1 ( - echo [!] uv installation failed. Ask the firmware team for help. + echo ERROR: uv installation failed. Ask the firmware team for help. goto :fail ) echo Checking Python libraries... @@ -102,6 +102,6 @@ exit /b 0 :fail echo. -echo [!] Update did not finish. +echo ERROR: Update did not finish. if not defined KOTA_NO_PAUSE pause exit /b 1