Install the GPIO pin backend, and add the Word guide

install.sh created the virtualenv with --system-site-packages so it could
see the pin backend, but never installed one. On a Pi OS image whose
python3-gpiozero does not pull it in, gpiozero then raised BadPinFactory,
the app fell back to a no-op LED, and the reader ran with the light dark
and nothing failing - the failure that is easiest to miss. Install
python3-lgpio (Bookworm and later) or python3-rpi.gpio (older releases)
when neither backend is importable, best-effort like the packages above.

Adds the installation and API guide (DOCX, 36 pages, 4 figures, 25
tables) covering enabling the serial port, wiring, mounting, installing on
Raspberry Pi OS and the complete HTTP API, plus the header diagrams it
references.

.gitignore now excludes the release build outputs: they are generated from
the source tree, and committing them would duplicate the code.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.gitignore

@@ -7,3 +7,7 @@ dist/
 venv/
 .idea/
 .vscode/
+
+# Release build outputs: generated from the source tree, not source
+rdm-card-reader-release/
+rdm-card-reader-release-*.zip

README.md

@@ -889,16 +889,23 @@ Python, but the library it uses to talk to the pins (`lgpio` on Bookworm,
 `RPi.GPIO` on older releases) is an **apt package in the system Python**. A
 plain venv cannot see it, so gpiozero raises `BadPinFactory` and the app
 quietly falls back to a no-op LED. This is why `install.sh` creates the venv
-with `--system-site-packages`; if you built the venv by hand, that is the most
+with `--system-site-packages` and installs a backend. If you built the venv by
-likely cause:
+hand, that is the most likely cause:
 
 ```bash
 grep system-site-packages /opt/rdm-card-reader/.venv/pyvenv.cfg   # want: true
 /opt/rdm-card-reader/.venv/bin/python -c 'import lgpio; print("lgpio OK")'
 ```
 
-If the first line is missing or the import fails, install the backend and
+If either line is wrong, let the installer set both up at once:
-rebuild the venv:
+
+```bash
+sudo ./deploy/install.sh --device /dev/serial0
+```
+
+It installs `python3-lgpio` (Bookworm and later) or `python3-rpi.gpio` (older
+releases) when neither backend is importable, and recreates the venv with the
+flag. To do it yourself instead:
 
 ```bash
 sudo apt-get install -y python3-lgpio        # Bookworm; python3-rpi.gpio on older

deploy/install.sh

@@ -119,6 +119,29 @@ apt-get update -qq 2>/dev/null || warn "apt-get update failed (no network?) - co
 apt-get install -y --no-install-recommends python3 python3-venv python3-pip \
     || warn "could not install system packages - continuing with what is present"
 
+# The pin backend gpiozero needs to drive the LED is an apt package in the
+# *system* Python (lgpio on Bookworm and later, RPi.GPIO on older releases).
+# gpiozero itself comes from the bundled wheels, but without a backend it
+# raises BadPinFactory, the app falls back to a no-op LED, and the reader works
+# with the light dark and nothing failing - the failure that is easiest to
+# miss. Best-effort, like the packages above: a full Raspberry Pi OS image
+# ships python3-gpiozero, which already pulls the right backend in, so only
+# install one when neither is importable.
+if ! python3 -c 'import lgpio' 2>/dev/null \
+   && ! python3 -c 'import RPi.GPIO' 2>/dev/null; then
+    echo "   no GPIO backend found - installing one for the status LED"
+    if apt-get install -y --no-install-recommends python3-lgpio 2>/dev/null; then
+        echo "   installed python3-lgpio (Bookworm and later)"
+    elif apt-get install -y --no-install-recommends python3-rpi.gpio 2>/dev/null; then
+        echo "   installed python3-rpi.gpio (Bullseye and older)"
+    else
+        warn "could not install a GPIO pin backend (python3-lgpio or"
+        warn "python3-rpi.gpio). The reader will work, but the status LED will"
+        warn "stay dark. Install it on the Pi with:"
+        warn "    sudo apt-get install -y python3-lgpio   # or python3-rpi.gpio"
+    fi
+fi
+
 # ---------------------------------------------------------------------------
 # 2. Install the application
 # ---------------------------------------------------------------------------