catarrh/simple
1
0
Fork 0
Code Issues Pull Requests Actions 8 Packages Projects Releases Wiki Activity

docs: both install paths (release package / clone) + Windows notes refreshed

Browse Source 
The READMEs told users to clone the repository even though most just
want to run the app.  The Quick start now leads with the release
package (a snapshot of the tagged source: no git history, no
development files) and keeps the clone path for development or
unreleased changes; git is still required because setup installs pysim
from its upstream repository.

Windows notes refreshed against the actual tooling and PyPI:
- pyscard 2.3.1 ships cp39-cp313 wheels (no cp314) and requires
  Python >= 3.9, so the pip/pyproject floor is 3.9 now (3.8 could
  never install the dependency) and the "3.9 builds from source" note
  is gone - only 3.14 does.
- The reader sentence now describes what actually happens: start.sh
  asks for the first PC/SC reader when pcscd runs, the server
  auto-detects a PC/SC reader itself, and with none present pysim
  falls back to its serial default /dev/ttyUSB0 (use -d for a
  serial/FTDI reader).
- The manual-install block is marked Linux/macOS: on Windows pysim is
  installed via requirements-pysim.txt + --no-deps (setup.bat), since
  the plain pip route pulls the SMPP bridge and its MSVC chain.

Docs/metadata only: 953 frontend + 989 Python green.
This commit is contained in:
Антон Трошин
2026-10-20 23:23:31 +03:00
parent 27cceb0341
commit 5cea89cc66
5 changed files with 63 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+28 -9
View File
@@ -15,13 +15,28 @@ SIMple is a workbench for UICC/SIM card specialists: an offline HTML/JS PWA plus
**PWA only (client-side tools):** open `frontend/index.html` in any browser, or serve `frontend/` with any static server. No Python required.
**Full (PWA + card server):**
**Full (PWA + card server)** — two ways to get it:
**1. Download the release package (recommended).** From the
[Releases](https://github.com/anttro/simple/releases) page take the latest package
(ZIP), unzip it anywhere and run the setup script once:
```sh
./setup.sh # or setup.bat on Windows — creates .venv, installs pysim + server
./start.sh # or start.bat — starts the server (it serves the PWA too)
```
The package is built from the tagged source — no git history, no development files.
Git is still required: `setup` installs **pysim** from its upstream repository
(nothing from pysim or its dependencies is bundled).
**2. Clone the repository (for development, or changes not released yet).**
```sh
git clone https://github.com/anttro/simple.git
cd simple
./setup.sh # or setup.bat on Windows — creates .venv, installs pysim + server
./start.sh # or start.bat — starts the server (it serves the PWA too)
./setup.sh # or setup.bat on Windows
./start.sh # or start.bat
```
Then open http://127.0.0.1:8080 — the UI and API share one origin, so no CORS or browser-permission setup is needed. The server starts fine with an empty reader (no card is a normal state): insert a card and it is initialized automatically (auto-equip), or press **Equip card** in the UI.
@@ -723,29 +738,33 @@ The bundled Python server wraps [pySim](https://osmocom.org/projects/pysim/wiki)
### Prerequisites
- **Python 3.8+** with `pip`, and **Git**
- **Python 3.9+** with `pip`, and **Git**
- **Smart card reader** (PC/SC or serial/FTDI) — PC/SC is preferable (`pcsc-lite` + `ccid` on Linux)
- **Windows** — use Python 3.10–3.13 (3.13 recommended): `pyscard` ships precompiled wheels for these versions. On 3.9 / 3.14 it builds from source (needs MSVC C++ Build Tools). The SMPP bridge (`smpp.twisted3`) is intentionally skipped on Windows.
- **Windows** — use Python 3.9–3.13 (3.13 recommended): `pyscard` ships precompiled wheels for these versions. On 3.14 it builds from source (needs MSVC C++ Build Tools). The SMPP bridge (`smpp.twisted3`) is intentionally skipped on Windows.
### Scripts
| Script | What it does |
|--------|-------------|
| `setup.sh` / `setup.bat` | Creates `.venv/`, installs pysim and the server. Run once after cloning. |
| `setup.sh` / `setup.bat` | Creates `.venv/`, installs pysim and the server. Run once after cloning or after unzipping the release package. |
| `start.sh` / `start.bat` | Starts the server from the venv (serves the PWA + API on `:8080`). |
`start.sh` auto-detects the reader (PC/SC if `pcscd` is running, else `/dev/ttyUSB0`); `start.bat` always uses `-p 0` (PC/SC is built into Windows). Extra arguments are passed through to the server, e.g. `./start.sh --gsmtap` or `start.bat --gsmtap 10.0.0.5:4729`. If no reader is found the server still starts ("Reader: none") — initialize the card later via the **Equip** button.
`start.sh` asks for the first PC/SC reader when `pcscd` is running; otherwise the server still auto-detects a PC/SC reader itself, and with none present pysim falls back to its serial default `/dev/ttyUSB0` (pass `-d <device>` for a serial/FTDI reader). `start.bat` always passes `-p 0` (PC/SC is built into Windows). Extra arguments are passed through to the server, e.g. `./start.sh --gsmtap` or `start.bat --gsmtap 10.0.0.5:4729`. If no reader is found the server still starts ("Reader: none") — initialize the card later via the **Equip** button.
### Manual installation
### Manual installation (Linux/macOS)
```sh
python3 -m venv .venv
source .venv/bin/activate # Linux/macOS (Windows: .venv\Scripts\activate)
source .venv/bin/activate
pip install git+https://github.com/osmocom/pysim.git
pip install -e . # editable — serves frontend/ from the source tree
pysim-simple-server --http-port 8080
```
On Windows use `setup.bat` instead: it installs pysim's dependencies from
`requirements-pysim.txt` and pysim itself with `--no-deps`, so the SMPP bridge (and
its MSVC build chain) is not pulled in.
### CLI options
| Option | Description |
README_RUS.md
+28 -9
View File
@@ -15,13 +15,28 @@ SIMple — инструментарий для специалистов по UIC
**Только PWA (клиентские функции):** откройте `frontend/index.html` в любом браузере или раздайте `frontend/` любым статическим сервером. Python не нужен.
**Полная установка (PWA + сервер карт):**
**Полная установка (PWA + сервер карт)** — два способа:
**1. Скачать релизный пакет (рекомендуется).** На странице
[Releases](https://github.com/anttro/simple/releases) возьмите последний пакет (ZIP),
распакуйте в любое место и один раз запустите setup:
```sh
./setup.sh # или setup.bat в Windows — создаёт .venv, ставит pysim + сервер
./start.sh # или start.bat — запускает сервер (он же раздаёт PWA)
```
Пакет собран из помеченного тегом исходного кода — без истории git и без файлов для
разработки. Git всё равно нужен: `setup` ставит **pysim** из его upstream-репозитория
(ни pysim, ни его зависимости в пакет не входят).
**2. Клонировать репозиторий (для разработки или ещё не выпущенных изменений).**
```sh
git clone https://github.com/anttro/simple.git
cd simple
./setup.sh # или setup.bat в Windows — создаёт .venv, ставит pysim + сервер
./start.sh # или start.bat — запускает сервер (он же раздаёт PWA)
./setup.sh # или setup.bat в Windows
./start.sh # или start.bat
```
Затем откройте http://127.0.0.1:8080 — интерфейс и API на одном origin, поэтому CORS и разрешения браузера не нужны. Сервер запускается и с пустым картридером (отсутствие карты — нормальное состояние): вставьте карту, и она инициализируется автоматически (auto-equip), либо нажмите **Equip card** в интерфейсе.
@@ -707,29 +722,33 @@ PWA проверяет версию сервера при подключении
### Требования
- **Python 3.8+** с `pip`, и **Git**
- **Python 3.9+** с `pip`, и **Git**
- **Смарт-картридер** (PC/SC или serial/FTDI) — предпочтителен PC/SC (`pcsc-lite` + `ccid` на Linux)
- **Windows** — используйте Python 3.10–3.13 (рекомендуется 3.13): у `pyscard` есть готовые wheel. На 3.9 / 3.14 он собирается из исходников (нужны MSVC C++ Build Tools). SMPP-мост (`smpp.twisted3`) в Windows сознательно не ставится.
- **Windows** — используйте Python 3.9–3.13 (рекомендуется 3.13): у `pyscard` есть готовые wheel. На 3.14 он собирается из исходников (нужны MSVC C++ Build Tools). SMPP-мост (`smpp.twisted3`) в Windows сознательно не ставится.
### Скрипты
| Скрипт | Назначение |
|--------|-------------|
| `setup.sh` / `setup.bat` | Создаёт `.venv/`, ставит pysim и сервер. Запускать один раз после клонирования. |
| `setup.sh` / `setup.bat` | Создаёт `.venv/`, ставит pysim и сервер. Запускать один раз после клонирования или распаковки релизного пакета. |
| `start.sh` / `start.bat` | Запускает сервер из venv (раздаёт PWA + API на `:8080`). |
`start.sh` автоопределяет ридер (PC/SC при работающем `pcscd`, иначе `/dev/ttyUSB0`); `start.bat` всегда использует `-p 0`. Дополнительные аргументы передаются серверу, например `./start.sh --gsmtap` или `start.bat --gsmtap 10.0.0.5:4729`. Без ридера сервер всё равно стартует («Reader: none») — карту можно инициализировать позже кнопкой **Equip**.
`start.sh` при работающем `pcscd` запрашивает первый PC/SC-ридер; иначе сервер сам автоопределяет PC/SC-ридер, а если его нет — pysim откатывается на последовательное устройство по умолчанию `/dev/ttyUSB0` (для serial/FTDI-ридера укажите `-d <устройство>`). `start.bat` всегда передаёт `-p 0`. Дополнительные аргументы передаются серверу, например `./start.sh --gsmtap` или `start.bat --gsmtap 10.0.0.5:4729`. Без ридера сервер всё равно стартует («Reader: none») — карту можно инициализировать позже кнопкой **Equip**.
### Ручная установка
### Ручная установка (Linux/macOS)
```sh
python3 -m venv .venv
source .venv/bin/activate # Linux/macOS (Windows: .venv\Scripts\activate)
source .venv/bin/activate
pip install git+https://github.com/osmocom/pysim.git
pip install -e . # editable — раздаёт frontend/ из исходного дерева
pysim-simple-server --http-port 8080
```
В Windows используйте `setup.bat`: он ставит зависимости pysim из
`requirements-pysim.txt`, а сам pysim — с `--no-deps`, поэтому SMPP-мост (и его сборка
через MSVC) не подтягивается.
### Параметры CLI
| Параметр | Описание |
pyproject.toml
+1 -1
View File
@@ -7,7 +7,7 @@ name = "pysim-simple-server"
version = "3.31.0"
description = "HTTP REST server wrapping pysim for the SIMple PWA"
license = { text = "GPL-2.0-or-later" }
requires-python = ">=3.8"
requires-python = ">=3.9"
# pysim is a git-only dependency installed explicitly by setup.bat/setup.sh.
# Declaring it here would make pip resolve its full tree (including the SMPP
# bridge -> Twisted -> twisted-iocpsupport, which needs MSVC on Windows).
setup.bat
+5 -5
View File
@@ -13,7 +13,7 @@ REM Check Python
python --version >nul 2>&1
if %errorlevel% neq 0 (
echo Error: Python is required but not found.
echo Install Python 3.8+ from https://python.org
echo Install Python 3.9+ from https://python.org
pause
exit /b 1
)
@@ -44,10 +44,10 @@ call "%VENV_DIR%\Scripts\activate.bat"
REM Upgrade pip
python -m pip install --upgrade pip -q
REM pyscard has precompiled wheels for Python 3.10-3.13.
REM On Python 3.9 / 3.14 pip builds it from source (requires Microsoft C++ Build Tools).
echo Note: pyscard ships precompiled wheels for Python 3.10-3.13.
echo Python 3.9 / 3.14 will build pyscard from source and require
REM pyscard has precompiled wheels for Python 3.9-3.13.
REM On Python 3.14 pip builds it from source (requires Microsoft C++ Build Tools).
echo Note: pyscard ships precompiled wheels for Python 3.9-3.13.
echo Python 3.14 will build pyscard from source and require
echo Microsoft C++ Build Tools ("Desktop development with C++").
echo.
setup.sh
+1 -1
View File
@@ -8,7 +8,7 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
VENV_DIR="$SCRIPT_DIR/.venv"
# Check prerequisites
command -v python3 >/dev/null 2>&1 || { echo "Error: Python 3 is required but not found. Install Python 3.8+ from https://python.org"; exit 1; }
command -v python3 >/dev/null 2>&1 || { echo "Error: Python 3 is required but not found. Install Python 3.9+ from https://python.org"; exit 1; }
command -v git >/dev/null 2>&1 || { echo "Error: Git is required but not found. Install Git from https://git-scm.com"; exit 1; }
PY_VER=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')