From 65c8ab215b8d41f30040bb076335ed0267e5228f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=D0=90=D0=BD=D1=82=D0=BE=D0=BD=20=D0=A2=D1=80=D0=BE=D1=88?=
 =?UTF-8?q?=D0=B8=D0=BD?= <i@atroshin.ru>
Date: Tue, 20 Oct 2026 23:15:54 +0300
Subject: [PATCH] README: two explicit install paths; Windows launchers pass
 --db and quote paths

- the Install section now leads with the release artifacts (the wheel via
  pipx/pip, the direct release URL, `gh release download` for the
  version-agnostic case, and the source archive) and keeps the git clone as
  the development path.  It finally names the launchers (./start.sh,
  start.bat): a clone needs no install, but the README never said how to start
  it while the Running section only showed the console script that an install
  provides.
- Windows: the USB section now says the .bat launchers mirror the shell ones
  and call the `python` command (Python 3 must be on PATH); the Install section
  carries the same note.
- start.bat: --db/DB was parsed and then never passed to the server; it is
  passed now, and --gsmtap-port is sent only for gsmtap capture (as start.sh
  already did).  Both .bat files passed values unquoted and stripped the
  quotes of pass-through options, so paths with spaces broke
  (--db "C:\My Data\...", --web-dir, --pcap, --output); values are quoted now
  and pass-through keeps the original quoting (argument assembly through
  delayed expansion).
- the launcher usage comments include the `disabled` capture mode.
- verified the argument assembly with Wine cmd.exe and an echo harness: the
  quoted paths survive, --db arrives, --gsmtap-port appears only for gsmtap;
  547 Python + 80 Node tests.
---
 README.md       | 68 +++++++++++++++++++++++++++++++++-------------
 README_RUS.md   | 71 ++++++++++++++++++++++++++++++++++++-------------
 sniff-start.bat | 14 +++++-----
 start.bat       | 11 +++++---
 start.sh        |  2 +-
 5 files changed, 119 insertions(+), 47 deletions(-)

diff --git a/README.md b/README.md
index 0b41fc9..d23f646 100644
--- a/README.md
+++ b/README.md
@@ -94,26 +94,15 @@ No other dependencies. PCAP, GSMTAP, and hex dump output use only Python stdlib.
 
 ## Install
 
-```sh
-git clone https://github.com/anttro/simtrace-analyser.git
-cd simtrace-analyser
-pip install pyusb
-```
+There are two ways to get the analyser: install a release artifact (no git
+history), or clone the repository for development.  Both bundle the same PWA.
 
-Or install the package into your environment:
+### From a release (no git history)
 
-```sh
-pip install -e .
-# then run: simtrace-analyser-server [opts]
-# or:       simtrace2-pysniff [opts]
-```
+Everything is on the
+[latest release](https://github.com/anttro/simtrace-analyser/releases/latest).
 
-### From a release (no git checkout)
-
-The release artifacts bundle the PWA, so an installed server serves the same UI
-as a clone.  Download the wheel from the
-[latest release](https://github.com/anttro/simtrace-analyser/releases/latest)
-and install it:
+**Wheel** (recommended — an isolated install, the PWA is inside the package):
 
 ```sh
 pipx install ./simtrace_analyser-2.7.10-py3-none-any.whl
@@ -123,12 +112,49 @@ pipx install ./simtrace_analyser-2.7.10-py3-none-any.whl
 simtrace-analyser-server --capture gsmtap
 ```
 
-`pip` can also fetch the wheel straight from the release page:
+`pip` can also fetch the wheel straight from the release page (use the version
+shown there):
 
 ```sh
 pip install https://github.com/anttro/simtrace-analyser/releases/download/v2.7.10/simtrace_analyser-2.7.10-py3-none-any.whl
 ```
 
+With the GitHub CLI, download the latest wheel without knowing the version:
+
+```sh
+gh release download --pattern '*.whl'
+pipx install ./simtrace_analyser-*.whl
+```
+
+**Source archive** — the *Source code (zip / tar.gz)* assets are the full tree
+without the git history: unzip, `cd` into it and use the launchers below
+(`./start.sh` on Linux/macOS, `start.bat` on Windows).
+
+### From a git clone (development)
+
+```sh
+git clone https://github.com/anttro/simtrace-analyser.git
+cd simtrace-analyser
+./start.sh                  # Linux/macOS; on Windows: start.bat
+```
+
+The launchers add the checkout to `PYTHONPATH` and run
+`python -m simtrace_analyser`, so no install step is needed for browsing and
+GSMTAP capture; they accept the server's options (`./start.sh --capture direct
+--port 8080`).  Direct hardware capture needs **PyUSB** (`pip install pyusb`).
+
+To get the console scripts (`simtrace-analyser-server`, `simtrace2-pysniff`)
+install the package instead:
+
+```sh
+pip install -e .
+simtrace-analyser-server --capture gsmtap
+```
+
+On Windows the `.bat` launchers run the `python` command, so Python 3 has to be
+on `PATH` (check with `python --version`); direct USB capture additionally
+needs the driver swap described in [USB Device Access](#usb-device-access).
+
 ## Running
 
 ### Analysis server + PWA (`simtrace-analyser-server`)
@@ -397,6 +423,12 @@ Windows does not ship a libusb-compatible driver for SIMtrace2. Use
 
 After that, `python -m simtrace2_pysniff` works identically to Linux.
 
+The Windows launchers match their shell counterparts and pass every option
+through: `start.bat --capture direct` starts the analyser server and
+`sniff-start.bat` the capture utility.  Both call the `python` command, so
+Python 3 must be on `PATH` (verify with `python --version` in a new command
+prompt).
+
 ## Utility CLI Options
 
 ```
diff --git a/README_RUS.md b/README_RUS.md
index 6fab958..6c9b3b7 100644
--- a/README_RUS.md
+++ b/README_RUS.md
@@ -99,26 +99,16 @@ SIM/UICC из UDP-потока GSMTAP (или импортирует файлы
 
 ## Установка
 
-```sh
-git clone https://github.com/anttro/simtrace-analyser.git
-cd simtrace-analyser
-pip install pyusb
-```
+Есть два способа получить анализатор: установить артефакт релиза (без истории
+git) или склонировать репозиторий для разработки. В обоих случаях в комплекте
+одна и та же PWA.
 
-Или установите пакет в своё окружение:
+### Из релиза (без истории git)
 
-```sh
-pip install -e .
-# затем запуск: simtrace-analyser-server [opts]
-# или:          simtrace2-pysniff [opts]
-```
+Всё находится на странице
+[последнего релиза](https://github.com/anttro/simtrace-analyser/releases/latest).
 
-### Из релиза (без клонирования репозитория)
-
-Релизные артефакты содержат PWA внутри пакета, поэтому установленный сервер
-отдаёт тот же интерфейс, что и при запуске из клона. Скачайте wheel со
-страницы [последнего релиза](https://github.com/anttro/simtrace-analyser/releases/latest)
-и установите его:
+**Wheel** (рекомендуется — изолированная установка, PWA внутри пакета):
 
 ```sh
 pipx install ./simtrace_analyser-2.7.10-py3-none-any.whl
@@ -128,12 +118,51 @@ pipx install ./simtrace_analyser-2.7.10-py3-none-any.whl
 simtrace-analyser-server --capture gsmtap
 ```
 
-`pip` также может скачать wheel прямо со страницы релиза:
+`pip` также может скачать wheel прямо со страницы релиза (подставьте версию,
+указанную там):
 
 ```sh
 pip install https://github.com/anttro/simtrace-analyser/releases/download/v2.7.10/simtrace_analyser-2.7.10-py3-none-any.whl
 ```
 
+С GitHub CLI можно скачать wheel последнего релиза, не зная версии:
+
+```sh
+gh release download --pattern '*.whl'
+pipx install ./simtrace_analyser-*.whl
+```
+
+**Архив исходников** — ассеты *Source code (zip / tar.gz)* содержат полное
+дерево без истории git: распакуйте, перейдите в каталог и используйте скрипты
+запуска ниже (`./start.sh` в Linux/macOS, `start.bat` в Windows).
+
+### Из клона репозитория (для разработки)
+
+```sh
+git clone https://github.com/anttro/simtrace-analyser.git
+cd simtrace-analyser
+./start.sh                  # Linux/macOS; в Windows: start.bat
+```
+
+Скрипты запуска добавляют каталог в `PYTHONPATH` и запускают
+`python -m simtrace_analyser`, поэтому для просмотра и захвата GSMTAP
+установка не нужна; они принимают параметры сервера
+(`./start.sh --capture direct --port 8080`). Для прямого захвата с
+оборудования нужен **PyUSB** (`pip install pyusb`).
+
+Чтобы получить консольные команды (`simtrace-analyser-server`,
+`simtrace2-pysniff`), установите пакет:
+
+```sh
+pip install -e .
+simtrace-analyser-server --capture gsmtap
+```
+
+В Windows скрипты `.bat` вызывают команду `python`, поэтому Python 3 должен
+быть в `PATH` (проверьте `python --version`); для прямого захвата по USB
+дополнительно нужна замена драйвера, описанная в разделе
+[Доступ к USB-устройству](#доступ-к-usb-устройству).
+
 ## Запуск
 
 ### Анализирующий сервер + PWA (`simtrace-analyser-server`)
@@ -407,6 +436,12 @@ sudo udevadm trigger
 
 После этого `python -m simtrace2_pysniff` работает так же, как в Linux.
 
+Скрипты запуска для Windows соответствуют shell-версиям и передают все
+параметры: `start.bat --capture direct` запускает сервер анализатора, а
+`sniff-start.bat` — утилиту захвата. Оба вызывают команду `python`, поэтому
+Python 3 должен быть в `PATH` (проверьте `python --version` в новом окне
+команды).
+
 ## Параметры CLI утилиты
 
 ```
diff --git a/sniff-start.bat b/sniff-start.bat
index d27c379..13ade78 100644
--- a/sniff-start.bat
+++ b/sniff-start.bat
@@ -59,7 +59,7 @@ if "%~1"=="--inactivity-timeout" (
     shift
     goto :parse_args
 )
-set "EXTRA_ARGS=!EXTRA_ARGS! %~1"
+set "EXTRA_ARGS=!EXTRA_ARGS! %1"
 shift
 goto :parse_args
 
@@ -67,11 +67,11 @@ goto :parse_args
 echo Starting simtrace2-pysniff...
 
 set "ARGS="
-if not "%GSMTAP%"=="" set "ARGS=!ARGS! --gsmtap %GSMTAP%"
-if not "%PCAP%"=="" set "ARGS=!ARGS! --pcap %PCAP%"
-if not "%OUTPUT%"=="" set "ARGS=!ARGS! --output %OUTPUT%"
-if not "%FORMAT%"=="" set "ARGS=!ARGS! --format %FORMAT%"
-if not "%INACTIVITY_TIMEOUT%"=="0" set "ARGS=!ARGS! --inactivity-timeout %INACTIVITY_TIMEOUT%"
+if not "%GSMTAP%"=="" set "ARGS=!ARGS! --gsmtap "%GSMTAP%""
+if not "%PCAP%"=="" set "ARGS=!ARGS! --pcap "%PCAP%""
+if not "%OUTPUT%"=="" set "ARGS=!ARGS! --output "%OUTPUT%""
+if not "%FORMAT%"=="" set "ARGS=!ARGS! --format "%FORMAT%""
+if not "%INACTIVITY_TIMEOUT%"=="0" set "ARGS=!ARGS! --inactivity-timeout "%INACTIVITY_TIMEOUT%""
 
 set "PYTHONPATH=%~dp0"
-python -m simtrace2_pysniff %ARGS% %EXTRA_ARGS%
+python -m simtrace2_pysniff !ARGS! !EXTRA_ARGS!
diff --git a/start.bat b/start.bat
index 78704fb..35ed309 100644
--- a/start.bat
+++ b/start.bat
@@ -3,7 +3,7 @@ setlocal enabledelayedexpansion
 
 :: simtrace-analyser-server startup script for Windows
 ::
-:: Usage: start.bat [--capture gsmtap|direct] [--port PORT] [--db PATH] [--gsmtap-port PORT]
+:: Usage: start.bat [--capture gsmtap|direct|disabled] [--port PORT] [--db PATH] [--gsmtap-port PORT]
 ::
 :: Options set via environment variables act as defaults; CLI flags override them.
 
@@ -42,7 +42,7 @@ if "%~1"=="--gsmtap-port" (
     shift
     goto :parse_args
 )
-set "EXTRA_ARGS=!EXTRA_ARGS! %~1"
+set "EXTRA_ARGS=!EXTRA_ARGS! %1"
 shift
 goto :parse_args
 
@@ -50,5 +50,10 @@ goto :parse_args
 echo Starting simtrace-analyser-server...
 echo PWA (simtrace-analyser) will be served at http://127.0.0.1:%PORT%/
 
+set "ARGS=--capture "%CAPTURE%" --port "%PORT%""
+if not "%DB%"=="" set "ARGS=!ARGS! --db "%DB%""
+if /i "%CAPTURE%"=="gsmtap" set "ARGS=!ARGS! --gsmtap-port "%GSMTAP_PORT%""
+set "ARGS=!ARGS! !EXTRA_ARGS!"
+
 set "PYTHONPATH=%~dp0"
-python -m simtrace_analyser --capture %CAPTURE% --port %PORT% --gsmtap-port %GSMTAP_PORT% %EXTRA_ARGS%
+python -m simtrace_analyser !ARGS!
diff --git a/start.sh b/start.sh
index f4671aa..422feb2 100755
--- a/start.sh
+++ b/start.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # simtrace-analyser-server startup script
 #
-# Usage: ./start.sh [--capture gsmtap|direct] [--port PORT] [--db PATH] [--gsmtap-port PORT]
+# Usage: ./start.sh [--capture gsmtap|direct|disabled] [--port PORT] [--db PATH] [--gsmtap-port PORT]
 #
 # Options set via environment variables act as defaults; CLI flags override them.