From 04f0ab9efa90a7f8b10be4f9d886bc4b30b514de Mon Sep 17 00:00:00 2001
From: scheianu <scheianuionut@gmail.com>
Date: Mon, 5 Oct 2026 22:06:03 +0300
Subject: [PATCH] Expand the LED pin numbering table

--led-pin is the BCM GPIO number, not the physical header pin, and
getting it wrong produces a dark LED with no error at all: the app
still reports "LED on GPIO 23" and looks healthy. The three-row table
did not cover most of the header, so the fix for a wire on any other
pin was left as guesswork.

Lists all 22 usable pins both ways round, gives the concrete
"physical pin 23 needs --led-pin 11" case, names the pins that must
not be used (the reader's own UART on 8/10, reserved ID_SD/ID_SC on
27/28, and the power pins), and adds a blink-each-candidate script
that finds the pin by experiment. Verified the table against the
standard 40-pin pinout.

Also drops a duplicated sentence about /dev/serial0 in Wiring.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 49 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 370af29..32821af 100644
--- a/README.md
+++ b/README.md
@@ -864,9 +864,6 @@ sudo systemctl is-active serial-getty@ttyAMA0.service   # must not be active
 grep -o 'console=[^ ]*' /boot/firmware/cmdline.txt      # must not say serial0
 ```
 
-The GPIO UART appears as `/dev/serial0` (a symlink to `/dev/ttyAMA0` or
-`/dev/ttyS0`).
-
 ### UART or USB? The service must be told which
 
 The two are not interchangeable, and getting it wrong is the most common reason
@@ -905,15 +902,56 @@ sudo ./deploy/install.sh --device /dev/serial0 --led-pin 18   # LED on GPIO 18
 
 ### LED pin numbering
 
-| `--led-pin` | BCM GPIO | Physical header pin |
-| --- | --- | --- |
-| `23` (the default) | GPIO 23 | **16** |
-| `18` | GPIO 18 | 12 |
-| `17` | GPIO 17 | 11 |
+`--led-pin` is the **BCM GPIO number** — what the app uses and what GPIO
+libraries use — **not** the physical header pin number. This is the single most
+common way to get a dark LED with no error: the app reports
+`LED on GPIO <n>` and looks healthy, while the wire is on a different pin.
 
-`--led-pin` is the **BCM** number, which is what the app uses and what GPIO
-libraries use. Putting the LED on physical pin 23 would drive **GPIO 11**, not
-GPIO 23 — the wire must go to physical pin **16** for the default to be right.
+Look up the pin your wire is actually on, and pass the BCM number:
+
+| Physical pin | `--led-pin` (BCM) | | Physical pin | `--led-pin` (BCM) |
+| --- | --- | --- | --- | --- |
+| 7 | `4` | | 24 | `8` |
+| 11 | `17` | | 26 | `7` |
+| 12 | `18` | | 29 | `5` |
+| 13 | `27` | | 31 | `6` |
+| 15 | `22` | | 32 | `12` |
+| **16** | **`23`** (the default) | | 33 | `13` |
+| 18 | `24` | | 35 | `19` |
+| 19 | `10` | | 36 | `16` |
+| 21 | `9` | | 37 | `26` |
+| 22 | `25` | | 38 | `20` |
+| **23** | **`11`** | | 40 | `21` |
+
+So an LED wired to **physical pin 23** needs `--led-pin 11`, and the default
+`--led-pin 23` requires the wire on **physical pin 16**.
+
+```bash
+sudo ./deploy/install.sh --device /dev/serial0 --led-pin 11   # wire on physical pin 23
+```
+
+Do **not** use physical pin 8 or 10 (GPIO 14 / 15 — the reader's own UART),
+physical pin 27 or 28 (ID_SD / ID_SC, reserved), or pins 1 / 17 (3.3 V) and
+2 / 4 (5 V), which are power rather than GPIO.
+
+If you would rather find the pin by experiment, stop the service first — two
+processes driving one pin fight each other — then blink each candidate and note
+which one lights:
+
+```bash
+sudo systemctl stop rdm-card-reader
+sudo /opt/rdm-card-reader/.venv/bin/python - <<'PY'
+from gpiozero import LED
+import time
+# (physical pin, BCM GPIO)
+for physical, bcm in [(23, 11), (16, 23), (12, 18), (11, 17), (22, 25)]:
+    print(f"physical pin {physical}  (GPIO {bcm})", flush=True)
+    led = LED(bcm)
+    led.on(); time.sleep(1.0); led.off(); led.close()
+    time.sleep(0.5)
+PY
+sudo systemctl start rdm-card-reader
+```
 
 ---