From 6e663dcdcb80bc0e97a2d2f31ede79978729c7aa 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?= Date: Wed, 28 Oct 2026 00:04:53 +0300 Subject: [PATCH] README: draw the signal path as SVG diagrams Replace the ASCII signal chain in both READMEs with a rendered diagram (resources/diagram_en.svg / resources/diagram_ru.svg): SIM card <-> reader with the passive tap on the contacts, the FX2 logic analyzer, sigrok-cli with the iso7816 decoder, GSMTAP UDP :4729, and the SIMtrace Analyser / Wireshark consumers. The SVGs are hand-authored, self-contained (no scripts, no external references), carry /<desc>, and each README embeds its own language variant with the chain repeated in the alt text. Release packaging: both diagrams are added to the archive allowlist. The shared-image equality check ignores them (the READMEs embed different files by design), while every other resources/ photo must still match across the two READMEs. AGENTS.md documents the exception. --- AGENTS.md | 12 +++++++----- README.md | 7 +------ README_RUS.md | 7 +------ resources/diagram_en.svg | 34 ++++++++++++++++++++++++++++++++++ resources/diagram_ru.svg | 34 ++++++++++++++++++++++++++++++++++ tools/build_release.sh | 15 +++++++++++++-- 6 files changed, 90 insertions(+), 19 deletions(-) create mode 100644 resources/diagram_en.svg create mode 100644 resources/diagram_ru.svg diff --git a/AGENTS.md b/AGENTS.md index 3117a33..738177c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1033,11 +1033,13 @@ pathspec, and also compared exactly against both archive listings (missing *and* unexpected entries fail): the decoder (`__init__.py`, `pd.py`, `gsmtap_stream.py`), the scripts (`setup.sh`/`start.sh`, `setup.bat`/`start.bat`), `tools/vs_reader.py`, `README.md`, `README_RUS.md`, -`LICENSE`, and every `resources/` image referenced from `README.md`. Tests, -`AGENTS.md`, the CI config, the development tools and the unreferenced -`resources/` images never enter the release. No `export-ignore` rules are -used, so GitHub's own source archives still contain the full tree. `dist/` -is gitignored. +`LICENSE`, every `resources/` photo referenced from both READMEs, and the two +language variants of the pipeline diagram (`resources/diagram_en.svg`, +`resources/diagram_ru.svg`, added explicitly because each README embeds its +own). Tests, `AGENTS.md`, the CI config, the development tools and the +unreferenced `resources/` images never enter the release. No `export-ignore` +rules are used, so GitHub's own source archives still contain the full tree. +`dist/` is gitignored. Both archives are unpacked and verified: `pd.py` VERSION, `py_compile` of the three modules, `bash -n` of the shell scripts, the tar exec bits, CRLF on the diff --git a/README.md b/README.md index 81bc2a5..16fa64d 100644 --- a/README.md +++ b/README.md @@ -8,12 +8,7 @@ Fork of [svenso/sigrok_iso7816](https://github.com/svenso/sigrok_iso7816) with **live GSMTAP UDP streaming**, making a cheap FX2 logic analyzer (Saleae clone) behave like a SIMtrace2 sniffer: -``` -SIM card ⇄ reader (passive tap on the contacts) - → FX2 logic analyzer (fx2lafw, 8ch, 24MHz max) - → sigrok-cli + iso7816 decoder - → GSMTAP UDP :4729 → [SIMtrace Analyser](https://github.com/anttro/simtrace-analyser) / Wireshark -``` +![Signal path: SIM card and reader with a passive tap on the contacts, FX2 logic analyzer (fx2lafw, 8 channels, up to 24 MHz), sigrok-cli with the iso7816 decoder, GSMTAP UDP :4729, SIMtrace Analyser and Wireshark](resources/diagram_en.svg) [SIMtrace Analyser](https://github.com/anttro/simtrace-analyser) is the recommended tool for visualising live traces and viewing saved captures — diff --git a/README_RUS.md b/README_RUS.md index e4ff767..ee9fe33 100644 --- a/README_RUS.md +++ b/README_RUS.md @@ -8,12 +8,7 @@ **живым GSMTAP-UDP-стримингом**: дешёвый логический анализатор FX2 (клон Saleae) ведёт себя как сниффер SIMtrace2: -``` -SIM-карта ⇄ ридер (пассивный съём с контактов) - → логический анализатор FX2 (fx2lafw, 8 каналов, до 24 МГц) - → sigrok-cli + декодер iso7816 - → GSMTAP UDP :4729 → [SIMtrace Analyser](https://github.com/anttro/simtrace-analyser) / Wireshark -``` +![Путь сигнала: SIM-карта и ридер с пассивным съёмом с контактов, логический анализатор FX2 (fx2lafw, 8 каналов, до 24 МГц), sigrok-cli с декодером iso7816, GSMTAP UDP :4729, SIMtrace Analyser и Wireshark](resources/diagram_ru.svg) [SIMtrace Analyser](https://github.com/anttro/simtrace-analyser) — рекомендуемый инструмент для визуализации живых трасс и просмотра diff --git a/resources/diagram_en.svg b/resources/diagram_en.svg new file mode 100644 index 0000000..e542e51 --- /dev/null +++ b/resources/diagram_en.svg @@ -0,0 +1,34 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg xmlns="http://www.w3.org/2000/svg" width="960" height="690" viewBox="0 0 960 690" role="img" aria-labelledby="diagram-title diagram-desc" font-family="'Segoe UI', 'Helvetica Neue', Arial, 'DejaVu Sans', sans-serif"> + <title id="diagram-title">sigrok_iso7816_stream: signal path + SIM card and reader with a passive tap on the contacts, FX2 logic analyzer (fx2lafw, 8 channels, up to 24 MHz), sigrok-cli with the iso7816 decoder, GSMTAP UDP :4729, SIMtrace Analyser and Wireshark + + + + + + + passive tap on the contacts + + SIM card + + Reader + + + + + FX2 logic analyzer + fx2lafw · 8 channels · up to 24 MHz + + + sigrok-cli + iso7816 decoder + + + GSMTAP UDP :4729 + + + + SIMtrace Analyser + + Wireshark + diff --git a/resources/diagram_ru.svg b/resources/diagram_ru.svg new file mode 100644 index 0000000..5f1a049 --- /dev/null +++ b/resources/diagram_ru.svg @@ -0,0 +1,34 @@ + + + sigrok_iso7816_stream: путь сигнала + SIM-карта и ридер с пассивным съёмом с контактов, логический анализатор FX2 (fx2lafw, 8 каналов, до 24 МГц), sigrok-cli с декодером iso7816, GSMTAP UDP :4729, SIMtrace Analyser и Wireshark + + + + + + + пассивный съём с контактов + + SIM-карта + + Ридер + + + + + Логический анализатор FX2 + fx2lafw · 8 каналов · до 24 МГц + + + sigrok-cli + декодер iso7816 + + + GSMTAP UDP :4729 + + + + SIMtrace Analyser + + Wireshark + diff --git a/tools/build_release.sh b/tools/build_release.sh index d59abd6..83dcf59 100755 --- a/tools/build_release.sh +++ b/tools/build_release.sh @@ -38,13 +38,23 @@ trap 'rm -rf "$STAGE"' EXIT # --- expected release contents (allowlist) ------------------------------- # The base runtime files plus every image referenced from the READMEs. +# Each README embeds its own language variant of the pipeline diagram, so the +# two diagrams are added explicitly instead of joining the shared-photo check. +LANG_RES="resources/diagram_en.svg resources/diagram_ru.svg" README_RES="$(git show "$REF:README.md" \ - | grep -oE '\]\(resources/[^)]+' | sed 's/](//' | LC_ALL=C sort -u || true)" + | grep -oE '\]\(resources/[^)]+' | sed 's/](//' \ + | grep -v -e '^resources/diagram_en\.svg$' -e '^resources/diagram_ru\.svg$' \ + | LC_ALL=C sort -u || true)" [ -n "$README_RES" ] || die "no resources/ images referenced from $REF:README.md" README_RUS_RES="$(git show "$REF:README_RUS.md" \ - | grep -oE '\]\(resources/[^)]+' | sed 's/](//' | LC_ALL=C sort -u || true)" + | grep -oE '\]\(resources/[^)]+' | sed 's/](//' \ + | grep -v -e '^resources/diagram_en\.svg$' -e '^resources/diagram_ru\.svg$' \ + | LC_ALL=C sort -u || true)" [ "$README_RES" = "$README_RUS_RES" ] || \ die "README.md and README_RUS.md reference different resources/ images" +for res in $LANG_RES; do + git cat-file -e "$REF:$res" 2>/dev/null || die "missing $res at $REF" +done EXPECTED="$STAGE/expected.list" { @@ -53,6 +63,7 @@ EXPECTED="$STAGE/expected.list" setup.sh start.sh setup.bat start.bat \ tools/vs_reader.py README.md README_RUS.md LICENSE printf '%s\n' "$README_RES" + printf '%s\n' resources/diagram_en.svg resources/diagram_ru.svg } | LC_ALL=C sort -u > "$EXPECTED" PATHS=()