ske087/rdm-card-reader
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add keyboard-wedge typing and LED event support

Browse Source 
- keyboard.py: emulate a commercial USB RFID reader by typing card ids
  into the focused window via a /dev/uinput virtual keyboard
- led.py / bridge.py: drive the status LED from card events
- cli.py, card.py: wire up the new options and event flow
- deploy: harden install.sh and the systemd unit
- README: document keyboard mode, LED support, and deployment

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
scheianu
2026-10-05 21:14:58 +03:00
parent 48e800adc1
commit c0a354b98e
9 changed files with 973 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+409 -31
View File
@@ -1,9 +1,13 @@
# rdm-card-reader
Read 125 kHz RFID cards (RDM6300 reader, EM4100 cards) on a serial port and
print what happens: **card inserted** with the card data, then **card removed**.
Read 125 kHz RFID cards (RDM6300 reader, EM4100 cards) on a serial port. Two
ways to use it:
Built for a Raspberry Pi workstation, but it runs anywhere with a serial port.
* **print events** — card inserted with the card data, then card removed
* **serve an API** (`--serve`) — expose the card on the reader over HTTP so a
web app can authenticate a card tap
Built for a Raspberry Pi, but it runs anywhere with a serial port.
> Starting it on a machine with no reader attached? See **[LAUNCH.md](LAUNCH.md)**
> — it explains the startup sequence, why it exits `1` with no hardware, and how
@@ -11,6 +15,21 @@ Built for a Raspberry Pi workstation, but it runs anywhere with a serial port.
---
## Contents
- [What it does](#what-it-does)
- [Install](#install)
- [Usage](#usage)
- [Serving card data to a web app (`--serve`)](#serving-card-data-to-a-web-app---serve)
- [Running at boot (Raspberry Pi)](#running-at-boot-raspberry-pi)
- [Status LED](#status-led)
- [Wiring](#wiring)
- [The protocol](#the-protocol)
- [Troubleshooting](#troubleshooting)
- [Check it works](#check-it-works)
---
## What it does
```
@@ -99,7 +118,8 @@ wheels on first start.
```bash
rdm-card-reader # auto-detect the serial port
rdm-card-reader --port /dev/ttyUSB0 # use a specific port
rdm-card-reader --port /dev/serial0 # the Pi's on-board UART
rdm-card-reader --port /dev/ttyUSB0 # a USB adapter
rdm-card-reader --json # one JSON object per event
rdm-card-reader --heartbeat 1.5 # slower card-removed detection
rdm-card-reader --list-ports # show which ports exist, then exit
@@ -113,7 +133,7 @@ Also works as a module: `python -m rdm_card_reader`.
| --- | --- | --- |
| `--port` | auto-detect | Serial port: device path, by-id symlink, serial number or `vid:pid` |
| `--autodetect` | off | Pick the only USB adapter; refuse if there is more than one |
| `--heartbeat` | `0.5` | Seconds without a read before the card counts as removed |
| `--heartbeat` | `2.0` | Seconds without a read before the card counts as removed. Also the presence/LED window |
| `--json` | off | Machine-readable output instead of the text block |
| `--list-ports` | – | List candidate and identified ports, then exit |
| `--verbose-ports` | off | With `--list-ports`, show by-id / by-path detail |
@@ -123,15 +143,24 @@ Also works as a module: `python -m rdm_card_reader`.
| `--wheel-dir` | bundled | Install from local wheels in this DIR instead of the bundled ones |
| `--version` | – | Print the version |
With `--serve`: `--host` (`127.0.0.1`), `--bridge-port` (`8765`), `--mode`
(`login`), `--tap-ttl` (`10`), `--allow-origin` (repeatable), `--token`,
`--allow-remote`, `--verbose`.
With `--serve`:
When `--port` is omitted the ports are tried in this order, the same order the
workstation app uses:
| Option | Default | Meaning |
| --- | --- | --- |
| `--host` | `127.0.0.1` | Bind address; anything else needs `--allow-remote` |
| `--bridge-port` | `8765` | HTTP port |
| `--mode` | `login` | `login` publishes taps only; `monitor` also publishes removals |
| `--tap-ttl` | `10` | Seconds an unclaimed tap stays claimable; `0` keeps it until replaced. Keep it ≥ `--heartbeat` |
| `--claimed-ttl` | `30` | Seconds a claimed card stays readable; `0` keeps it indefinitely |
| `--allow-origin` | – | Permit this browser origin (repeatable) |
| `--token` | – | Pre-shared token for non-local callers (or `RDM_BRIDGE_TOKEN`) |
| `--allow-remote` | off | Permit binding a non-loopback address |
| `--verbose` | off | Also print each event and each HTTP request |
When `--port` is omitted the ports are tried in this order:
```
/dev/ttyS0 -> /dev/ttyAMA0 -> /dev/ttyUSB0 -> /dev/ttyACM0
/dev/ttyS0 -> /dev/ttyAMA0 -> /dev/serial0 -> /dev/ttyUSB0 -> /dev/ttyACM0
```
### Output modes
@@ -204,7 +233,7 @@ This is the mode for **authenticating a web page**: the reader runs as a service
on the device, and the page asks it for the card that was just tapped.
```bash
rdm-card-reader --serve --port /dev/rdm-reader --allow-origin https://your.web.app
rdm-card-reader --serve --port /dev/serial0 --allow-origin https://your.web.app
```
The bridge reports **card ids only**. Deciding which user a card belongs to is
@@ -222,9 +251,9 @@ sequenceDiagram
C->>B: tap
B->>B: latch the tap (tap-ttl seconds)
K->>B: GET /api/card
B-->>K: {claimable: true, card: {id: ...}}
B-->>K: {present: true, claimable: true, card: {id: ...}}
K->>B: POST /api/card/claim
B-->>K: {card: {id: ...}} (once)
B-->>K: {card: {id: ...}, consumed: true} (once, then 409)
K->>W: POST /login {card_id}
W->>W: card_id -> user
W-->>K: session
@@ -234,10 +263,52 @@ The point of the *latch* is that the tap stays available for `--tap-ttl`
seconds (default 10), **including after the card is lifted**. A quick tap
therefore cannot be lost because the page happened to poll a moment later.
`present` and `card` answer different questions, which is the part that
surprises people:
| Field | Meaning |
| --- | --- |
| `present` | the card is physically on the reader **right now** — goes `false` the moment it is lifted |
| `card` | the **latched tap** — survives the card being lifted, so you still know which card it was |
So a card that was tapped and lifted a second ago reports `present: false` with
`card` still populated. That is correct, not a bug: if the id vanished with the
card, any poll arriving after the lift could not authenticate anything.
The point of *claim* is single use. Once a tap is spent, a page reload or a
second tab gets `409 Conflict` instead of a second login, so one physical tap
can never authenticate two sessions.
Two independent windows govern how long the card stays readable:
| Window | Flag | Default | Governs |
| --- | --- | --- | --- |
| Unclaimed | `--tap-ttl` | 10 s | how long a tap can still be spent on a login |
| Claimed | `--claimed-ttl` | 30 s | how long a claimed card stays readable, so the page that claimed it can confirm which card logged in |
Put together, `/api/card` moves through these states:
| Moment | `present` | `card` | `claimable` | `consumed` |
| --- | --- | --- | --- | --- |
| Card held on the reader | `true` | id | `true` | `false` |
| Lifted, within `--tap-ttl` | `false` | id | `true` | `false` |
| Claimed, within `--claimed-ttl` | `false` | id | `false` | `true` |
| After the claimed window | `false` | `null` | `false` | `false` |
| Unclaimed and past `--tap-ttl` | `false` | `null` | `false` | `false` |
The last two rows are the point: an id that can no longer be acted on is
cleared, so it cannot be mistaken for a tap still waiting to be used.
`/api/last` and `/api/taps` keep the history either way. Setting either value to
`0` disables that expiry.
> **Set `--tap-ttl` at least as long as `--heartbeat`, or longer.**
> `--tap-ttl` applies to the tap, `--heartbeat` to presence, and they are
> independent. If the tap expires *before* the heartbeat declares the card
> removed, a card still sitting on the reader has its id cleared and reads as
> `"card": null` until the next re-read — which on a reader that reports once
> per placement may be a long time. Matching them (`--heartbeat 10 --tap-ttl 10`)
> avoids the gap for a card held in place.
### Endpoints
| Method | Path | Purpose |
@@ -247,13 +318,19 @@ can never authenticate two sessions.
| `GET` | `/api/events` | Server-Sent Events stream, pushes each event as it happens |
| `GET` | `/api/last` | Most recent card event, or `204` |
| `GET` | `/api/taps` | Recent tap history (`?limit=N`) |
| `GET` | `/api/health` | Reader state, port, uptime, tap counts — for monitoring |
| `GET` | `/api/health` | Reader state, port, uptime, tap counts, both TTLs — for monitoring |
| `POST` | `/api/mode` | `{"mode": "login"}` or `{"mode": "monitor"}` |
`login` mode (default) publishes taps only — a tap is an authentication
attempt. `monitor` mode also publishes removals, which is what you want for
watching a reader rather than logging people in.
`/api/health` is the liveness check: `status: "ok"` with a rising
`uptime_seconds` means the service is serving. It is answered **before** the
origin and token checks, so it stays readable by any client that can reach the
port — which is the intent on loopback, but means binding with `--allow-remote`
exposes the port, mode, uptime and tap counts to the network.
### Browser example
```js
@@ -271,6 +348,15 @@ if (state.claimable) {
}
```
Already claimed, and you just want to know *which* card it was? The id stays
readable for `--claimed-ttl` (default 30 s) after the claim, with
`consumed: true`:
```js
const { card, consumed } = await (await fetch("http://127.0.0.1:8765/api/card")).json();
if (consumed && card) console.log("that tap was card", card.id);
```
Or push instead of poll, so a tap logs in immediately:
```js
@@ -290,7 +376,8 @@ they do not make the card itself convincing as a sole credential.
| Origins | Cross-origin browser requests are **refused** unless `--allow-origin` lists that exact origin. Stops another site from reading your taps. |
| Token | `--token` (or `RDM_BRIDGE_TOKEN`) is required from non-loopback callers. |
| Single use | A tap can only ever produce one successful claim. |
| Expiry | A tap older than `--tap-ttl` is refused with `410`. |
| Expiry | An unclaimed tap older than `--tap-ttl` is refused with `410`. |
| Bounded retention | A claimed tap stays readable for `--claimed-ttl` (30 s), then the id is cleared — an id that can no longer be acted on is never left in the response. |
Add a second factor — a PIN after the tap — wherever a cloned card would
actually cost you something.
@@ -305,19 +392,127 @@ actually cost you something.
## Running at boot (Raspberry Pi)
The defaults already match the common wiring — **`/dev/serial0`** for the
reader on the Pi's UART and **GPIO 23** for the LED — so the LED pin and device
usually need no arguments at all:
```bash
sudo ./deploy/install.sh --origin https://your.web.app
```
To be explicit (and safe if the defaults ever change):
```bash
sudo ./deploy/install.sh --origin https://your.web.app \
--device /dev/serial0 \
--led-pin 23 \
--led-mode presence
```
| Argument | Why |
| --- | --- |
| `--device /dev/serial0` | The reader is wired to the UART pins (8 / 10). This is the default. For a USB-to-serial adapter pass `--device /dev/rdm-reader` instead — that alias is created by udev for USB adapters only, so it never exists on a UART setup |
| `--led-pin 23` | BCM GPIO 23, which is **physical pin 16**. The default |
| `--led-mode presence` | Lit while a card is on the reader, dark otherwise. The default |
> **`--led-pin` is the BCM GPIO number, not the header pin.** If your LED wire
> is on physical pin 16, pass `--led-pin 23` (the default). Passing
> `--led-pin 16` would drive **GPIO 16**, which is physical pin 36 — a different
> pin entirely. The LED is optional: with no LED, pass `--led-mode presence`
> regardless and ignore the light, or add `--no-led` to the unit if you want
> the app to stop trying.
### Standalone install
`deploy/install.sh` is the only installer — there is no `deploy.sh`.
That installs a service account, a virtualenv, a systemd unit and a udev rule,
then enables the service. Afterwards:
then enables the service. The device defaults to `/dev/rdm-reader`; if the
reader is on the Pi's UART instead, add `--device /dev/serial0` — see
**UART or USB?** above. The installer refuses to enable the service unless the
device exists and opens, so a misconfigured port fails during install rather
than as a crash-looping unit.
Useful installer options:
| Option | Default | Meaning |
| --- | --- | --- |
| `--origin URL` | – | Web app origin allowed to call the API (repeatable) |
| `--device PATH` | `/dev/serial0` | Serial device the service opens (UART; use `/dev/rdm-reader` for USB) |
| `--led-pin N` | `23` | BCM GPIO number of the status LED (physical pin 16) |
| `--led-mode M` | `presence` | `presence`: lit while a card is on the reader; `error`: lit whenever running |
| `--heartbeat S` | `2.0` | Seconds before a silent reader counts as card removed — also the presence/LED window |
| `--port PORT` | `8765` | HTTP port for the bridge |
| `--dir PATH` | `/opt/rdm-card-reader` | Install location |
| `--user NAME` | `rdmcard` | Service account |
| `--no-service` | off | Install and configure, but do not enable the service |
The unit runs the app as:
```
/opt/rdm-card-reader/.venv/bin/rdm-card-reader \
--serve --port <device> --bridge-port 8765 --mode login \
--led-pin <pin> --led-mode <mode> --heartbeat <seconds>
```
`WorkingDirectory=/opt/rdm-card-reader`, so this is equivalent to running
`.venv/bin/python -m rdm_card_reader --port <device>` there with `--serve`
added. `--serve` is what makes the API available; without it the app only
prints events, which a service sends to the journal.
Afterwards:
```bash
systemctl status rdm-card-reader # state
systemctl is-enabled rdm-card-reader # should be 'enabled' (starts at boot)
journalctl -u rdm-card-reader -f # live log
curl http://127.0.0.1:8765/api/card # tap a card, then run this
ss -ltnp | grep 8765 # confirms something is listening
curl -sS http://127.0.0.1:8765/api/card # tap a card, then run this
```
A healthy startup logs one line:
```
OK reader on /dev/serial0 ; bridge on http://127.0.0.1:8765 (mode: login)
```
### Checking the reader from the command line
```bash
# Is the reader alive? (status, port, uptime)
curl -sS http://127.0.0.1:8765/api/health | python3 -m json.tool
# Is a card on the reader right now?
curl -sS http://127.0.0.1:8765/api/card | python3 -m json.tool
```
Use `curl -sS` rather than plain `-s`: the extra `S` prints errors, so a
`Connection refused` is visible instead of an empty response that `json.tool`
then reports as `Expecting value: line 1 column 1 (char 0)`. That message means
*nothing answered*, which almost always means the service is not running —
check `ss -ltnp | grep 8765` first.
### The service gave up after a few failures
`StartLimitBurst=5` over `StartLimitIntervalSec=60` means systemd stops trying
after five failed starts — about 15 seconds. That is deliberate (an absent
reader should not restart forever), but it means fixing the wiring is not
enough on its own; the failed state has to be cleared:
```bash
sudo systemctl reset-failed rdm-card-reader
sudo systemctl restart rdm-card-reader
```
If a unit edit has no effect, you forgot `sudo systemctl daemon-reload` —
systemd caches unit files. Confirm what the service actually runs with:
```bash
systemctl cat rdm-card-reader | grep -E '^(ExecStart|DeviceAllow|After)'
```
That output, not the `.service` file on disk, is the truth the service runs.
### Identifying the right ttyUSB
`/dev/ttyUSB0` is **not** a stable identity — unplug something and the number
@@ -338,12 +533,16 @@ Identified serial ports (best candidate first):
Then pin it, most specific first:
```bash
--port /dev/rdm-reader # udev alias
--port /dev/rdm-reader # udev alias (USB adapters)
--port /dev/serial0 # on-board UART
--port /dev/serial/by-id/usb-1a86_USB_Serial-if00-port0 # by device
--port AB0XYZ12 # by serial number
--port 1a86:7523 # by chip
```
Note the two are wired differently and the udev alias only exists for one of
them — see **UART or USB?** below.
`--autodetect` picks the only USB adapter, and **refuses** when there is more
than one — silently choosing between two readers is exactly the failure this
avoids. Verify the wiring in `deploy/99-rdm-reader.rules`.
@@ -354,29 +553,41 @@ Exit codes: `0` ok, `1` no port, `2` library missing, `3` port ambiguous.
## Status LED
An LED driven by card events, on **GPIO 23** by default — the same pin the
workstation app used.
An LED driven by card events, on **GPIO 23** (physical pin **16**) by default —
the same pin the workstation app used. Optional: everything works without it.
By default the light **tracks the card**: lit while a card is on the reader,
dark otherwise.
```bash
rdm-card-reader # lit while running, blinks on a bad read
rdm-card-reader # lit only while a card is on the reader
rdm-card-reader --led-mode error # lit whenever running, blinks on a bad read
rdm-card-reader --led-pin 17 # a different pin
rdm-card-reader --led-mode presence # lit only while a card is on the reader
rdm-card-reader --no-led # no LED at all
```
| Flag | Default | Meaning |
| --- | --- | --- |
| `--no-led` | off | Do not drive a LED |
| `--led-pin` | `23` | GPIO pin (matches the workstation app) |
| `--led-mode` | `error` | See the two readings below |
| `--led-pin` | `23` | **BCM** GPIO number — not the physical header pin |
| `--led-mode` | `presence` | See the two readings below |
| `--led-no-error-blink` | off | Do not blink on a bad read |
`--led-pin` takes the **BCM GPIO number**. The two are easy to confuse, and it
is the second most common reason a LED "does not work" — the default `23` is
**physical pin 16**, not pin 23. The full mapping is under **Wiring** below.
Two modes, because the light can mean two different things:
| Mode | Behaviour | Use when |
| --- | --- | --- |
| `error` (default) | **Lit whenever the reader is running.** Dark while a card is being read, blinks on a bad read | The light should mean "the reader is alive and ready" |
| `presence` | **Lit only while a card is on the reader** | The light should mean "a card is here" |
| `presence` (default) | **Lit only while a card is on the reader**, dark otherwise | The light should mean "a card is here" — the common choice, and unambiguous |
| `error` | **Lit whenever the reader is running.** Dark while a card is being read, blinks on a bad read | The light should mean "the reader is alive and ready" |
> In `presence` mode the light is **dark at startup** and lights on the first
> valid card read, then goes dark when the card is lifted. A dark LED on a
> freshly started service is therefore correct, not a fault. Check that a card
> read lights it before concluding the LED is broken.
Wiring: LED anode to the GPIO pin through a ~330 Ω resistor, cathode to GND.
@@ -393,10 +604,11 @@ point:
refusing to run.
* **Never crashes on a dead pin.** A failed toggle is logged and ignored.
Startup reports which of the three states it is in:
Startup reports which of the three states it is in (the mode shown is
`presence` by default):
```
LED on GPIO 23 (error mode, gpiozero) # working
LED on GPIO 23 (presence mode, gpiozero) # working
LED unavailable: gpiozero not installed # library missing
LED unavailable: no usable GPIO on pin 23: ... # no pin factory / pin busy
```
@@ -405,6 +617,87 @@ That distinction matters: `BadPinFactory` subclasses `ImportError`, so a naive
check reports "not installed" when the library is present but has no usable pin
provider — which would send you to the wrong fix.
### The reader works but the light stays dark
Because a LED failure is never fatal, a misconfigured LED looks exactly like a
working reader with no light. Check the reason the app printed:
```bash
journalctl -u rdm-card-reader -n 40 --no-pager | grep -i led
```
| Message | Cause | Fix |
| --- | --- | --- |
| `LED unavailable: no usable GPIO on pin 23: ...` | gpiozero cannot reach a pin backend, or systemd/group permission is missing | See the three checks below |
| `LED unavailable: gpiozero not installed: ...` | LED extras missing from the venv | Install from the bundled wheels (below) |
| `LED on GPIO 23 (presence mode, gpiozero)` | LED is initialised — suspect wiring, or simply no card read yet | See the wiring note below |
**Check 1 — the venv must see the system pin backend.** `gpiozero` is pure
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
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
rebuild the venv:
```bash
sudo apt-get install -y python3-lgpio # Bookworm; python3-rpi.gpio on older
sudo ./deploy/install.sh --device /dev/serial0 # recreates the venv with the flag
```
**Check 2 — systemd device policy.** The unit sets `DevicePolicy=closed`, so
only devices named in `DeviceAllow=` are reachable. It must list the GPIO chip
as well as the serial port:
```
DeviceAllow=/dev/serial0 rw
DeviceAllow=/dev/gpiochip0 rw
DeviceAllow=/dev/gpiochip4 rw
```
`gpiochip0` is the header on Pi 1–4, `gpiochip4` on Pi 5. A missing entry is
denied by systemd before any group permission is even consulted. Confirm what
the service actually runs with
`systemctl cat rdm-card-reader | grep DeviceAllow`.
**Check 3 — the `gpio` group.** On modern Raspberry Pi OS (Bookworm onward)
`gpiozero` drives GPIO through `lgpio`, which opens `/dev/gpiochip0` — owned
`root:gpio`, mode `0660`. The service account must be in `gpio`:
```bash
sudo usermod -aG gpio rdmcard
```
Older releases (Bullseye, `RPi.GPIO`) use `/dev/gpiomem` and need no extra
group.
After any of these changes: `sudo systemctl daemon-reload` (systemd caches unit
files) and `sudo systemctl restart rdm-card-reader`.
**If the LED extras are missing**, install them offline from the bundled wheels
— a Pi with no internet cannot reach PyPI:
```bash
/opt/rdm-card-reader/.venv/bin/pip install --no-index \
--find-links /opt/rdm-card-reader/src/rdm_card_reader/wheels \
--no-deps gpiozero colorzero
```
**If the journal says the LED is on GPIO 23**, the software side is fine.
Tap a card: in the default `presence` mode the light comes on while the card is
held and goes dark when it is lifted. If it stays dark with a card on the
reader, the problem is electrical — see the pin numbering note under
**Wiring**. GPIO 23 is physical pin **16**, and the anode needs a series
resistor to the pin with the cathode to GND.
> **If the workstation app also runs on this device, use a different pin** — two
> processes driving GPIO 23 will fight, and the LED will flicker.
@@ -417,8 +710,29 @@ it is never imported at runtime and would add 818 KB for nothing.
## Wiring
The RDM6300 talks plain serial at **9600 baud, 8N1**. Connect it to the Pi's
UART (pins 8/10 for TXD/RXD, 5 V and GND) or through a USB-to-serial adapter.
The RDM6300 talks plain serial at **9600 baud, 8N1**.
A typical connection to the Pi's 40-pin header, using the on-board UART:
| RDM6300 | Pi pin | Function |
| --- | --- | --- |
| VCC (5 V) | 4 | power |
| GND | 6 | ground (must be common) |
| TX | **10** (GPIO 15, RXD) | card data → Pi |
| RX | 8 (GPIO 14, TXD) | not used — the reader only transmits |
The reader is **transmit-only**: it emits frames continuously and never reads,
so the Pi's TX line (pin 8) has nothing to send. Only pin 10 carries data.
> **Level warning.** The RDM6300's TX output is **5 V TTL**, while GPIO 15 is a
> **3.3 V** input. Feeding 5 V straight in often appears to work but stresses
> the pin. Use a divider (e.g. 1 kΩ in series, 2 kΩ to GND) or a level shifter
> on the reader-TX → pin-10 line. This is not a cause of "no cards read" if you
> already see data, but it is worth fixing before relying on the device.
For the status LED: **anode** → GPIO pin through a ~330 Ω resistor,
**cathode** → GND. See the pin numbering table below, and note the LED is
optional — the reader works without it.
On a Raspberry Pi you usually need to free up the primary UART first:
@@ -429,9 +743,66 @@ sudo raspi-config # Interface Options -> Serial Port
sudo usermod -aG dialout $USER # then log out and back in
```
The GPIO UART appears as `/dev/serial0` (a symlink to `/dev/ttyAMA0` or
`/dev/ttyS0`). If the serial console still owns the port the service will fail
to open it — check with:
```bash
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
the service fails with `exit 1`:
| Wiring | Device to pass | udev alias |
| --- | --- | --- |
| Pi UART pins **8 / 10** (or 10/8) | `/dev/serial0` | **never created** |
| USB-to-serial adapter | `/dev/rdm-reader` | created by the udev rule |
`deploy/99-rdm-reader.rules` matches a USB bridge chip, so it **cannot** fire
for the on-board UART — there is no USB device to match. A service pointing at
`/dev/rdm-reader` with the reader on the UART therefore finds nothing and exits
`1` on every start.
Tell the installer which one you have:
```bash
sudo ./deploy/install.sh --origin https://your.web.app --device /dev/serial0
```
It verifies the device both exists *and* opens at 9600 baud before enabling the
service, so this class of failure is caught at install time rather than as a
crash-looping unit:
```
/dev/serial0 opened at 9600 baud
```
If the LED is not on GPIO 23, say so at the same time (`--led-pin` takes the
**BCM GPIO number**, not the physical header pin):
```bash
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** 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.
---
## The protocol
@@ -478,6 +849,13 @@ problem with the following card.
| Reader opens but no cards | Card must be EM4100 / 125 kHz; hold it ~2 cm from the coil |
| `INVALID CARD` repeatedly | Noisy supply or long/unshielded wiring; shorten it |
| Every card reported twice | Lower `--heartbeat` if the card is lifted quickly |
| Card reported as **removed while still on the reader** | Raise `--heartbeat` — the reader reports a card once per placement, so a short window expires while the card sits still |
| LED blinks on and off instead of staying lit | Same cause: the LED follows `present`. Raise `--heartbeat` |
| Service `exit 1`, `no port matched '/dev/rdm-reader'` | Reader is on the UART — re-install with `--device /dev/serial0` |
| Service `exit 1`, `Could not open /dev/serial0` | UART held by the serial console, or the user is not in `dialout` |
| Service stuck in `failed`, restarts refused | `sudo systemctl reset-failed rdm-card-reader` |
| `curl` returns nothing, `Expecting value: line 1 column 1` | Nothing is listening — the service is not running; check `ss -ltnp \| grep 8765` |
| Reader works but the LED is dark | See **The reader works but the light stays dark** |
---