Blippstation turns a Raspberry Pi and a USB RFID/NFC reader into a card-scan station. Every card tap is decoded on the Pi and posted as a JSON request to your HTTP endpoint (for example a ServiceNow Scripted REST API), authenticated with OAuth2 client credentials.
card tap → reader (USB HID keyboard) → blippstation daemon on the Pi
→ OAuth token (cached) → POST {"uid","station","scanned_at"} → your endpoint
The downloads on this page are Blippstation Flasher, the desktop app that writes a ready-to-boot SD card for the Pi. The card carries the operating system, the network settings you enter and the Blippstation software itself — nothing has to be installed on the Pi by hand.
What you need
- A Raspberry Pi (tested on a Pi 5) with a microSD card and a power supply.
- A card reader in HID keyboard mode — it enumerates as a USB keyboard and "types" the card ID followed by Enter. Built and tested with an ELATEC TWN4.
- A Windows, macOS or Linux computer with an SD-card slot or USB card reader to run the flasher on.
- Network for the Pi: Ethernet or Wi-Fi, with internet access at least during the first boot.
- An endpoint that accepts the scan, and an OAuth2 client (ID and secret) for the client-credentials grant.
Reader firmware
A new TWN4 reader must be flashed with ELATEC's Standard Keyboard firmware before it works with Blippstation; out of the box it may emit a different UID format and no trailing Enter. Flash it with AppBlaster from the ELATEC TWN4 DevPack (Windows only), using TWN4_xKx520_STD207_Multi_Keyboard_Standard.bix from the DevPack's firmware/ directory.
Install the flasher
| Platform |
Install |
| Windows 10/11 (x64) |
Run Blippstation.Flasher_<version>_x64_en-US.msi and accept the licence. It installs for all users and asks for administrator rights; if you have 0.3.x, uninstall that first |
| macOS (Apple Silicon) |
Open Blippstation.Flasher_<version>_aarch64.dmg, agree to the licence and drag the app to Applications |
| Ubuntu / Debian |
sudo apt install ./Blippstation.Flasher_<version>_amd64.deb |
| Arch Linux |
sudo pacman -U blippstation-flasher-<version>-1-x86_64.pkg.tar.zst |
The installers are signed by Devolent AB (since 0.4.0):
- macOS: the app is notarized by Apple and opens without a warning.
- Windows: the MSI and the app are signed, so the administrator prompt (writing a raw disk needs it) names Devolent AB. While an installer is new, SmartScreen may still ask once: choose More info → Run anyway. Coming from 0.3.x, uninstall it first (Settings → Apps → Blippstation Flasher → Uninstall), then run the MSI. IT can deploy the MSI with
msiexec /i <file>.msi /qn.
- macOS and Linux: the app runs unprivileged and asks for authorization only when the write starts (macOS: the system dialog; Linux: a PolicyKit prompt).
Prefer the terminal? The command-line flasher is the same wizard without a window, packaged for Ubuntu/Debian and Arch as blippstation-flasher-cli; it installs next to the desktop app and is started as blippstation-flash. --list prints the available image versions, --device and --image skip the menus. No sudo needed: opening the target disk prompts for authorization by itself (on a system without polkit, set BLIPPSTATION_ELEVATOR=sudo).
Make a card
- Start the flasher and pick an Ubuntu Server image version for the Pi.
- Pick the target SD card. Only removable disks are offered, the disk holding your running system is never listed, and the write starts only after you type the device name back.
- Enter a hostname, and optionally Wi-Fi (the flasher scans nearby networks where the OS allows it, checks the passphrase against the WPA rules, and on Linux can verify it by briefly joining the network), a static IP (DHCP is the default) and SSH public keys.
- The flasher downloads the image (cached per user, checksum-verified), writes it, and drops the first-boot configuration and the Blippstation binary on the boot partition.
Before the Pi ever boots, the flasher shows the setup URL with its access token and saves the same information on the card as blippstation-info.txt. Keep it — you need the URL in the next step.
First boot and setup
Put the card in the Pi, attach the reader and power it on. On first boot the Pi installs Blippstation and starts the setup console, reachable as http://<hostname>.local:8787 (.local discovery needs internet once during the first boot; without it, look the Pi's IP up in your router). Open the URL from the flasher — the ?k= access token is required — and:
- Confirm the reader shows detected.
- Tap a card to test and check the decoded UID looks right.
- Fill in Endpoint URL, OAuth token URL, Client ID / Secret and Station ID (and Scope if your provider needs one).
- Test token — confirms the OAuth credentials work.
- Install / update service — installs and starts the daemon, enabled on boot. The setup console shuts down and never starts again.
- Tap a card and confirm it arrives at your endpoint.
Rescue login on the Pi: ubuntu / blippstation. The first login (on the console, or over SSH with one of the embedded keys) prompts for a new password. SSH password login is disabled — only an embedded key works.
What gets sent
Each scan is one POST with Content-Type: application/json and an Authorization: Bearer <token> header:
{ "uid": "0123456789", "station": "reception-1", "scanned_at": "2026-05-27T17:24:49Z" }
The three keys can be renamed under Advanced in the setup console; the timestamp is RFC 3339 UTC. The token comes from the OAuth2 client-credentials grant, is cached in memory and refreshed about 30 seconds before it expires; a 401 from the endpoint triggers one retry with a fresh token.
Delivery is best-effort: each scan is attempted once and, on failure, logged and dropped. A scan during a network or endpoint outage is lost.
Operating the station
On the Pi, over SSH or on the console:
systemctl status blippstation
journalctl -u blippstation -f # one `posted uid="..."` line per scan, or the error
sudo blippstation uninstall # stop and purge service, config, binary and user
The service runs as the unprivileged blippstation user, the configuration including the client secret lives in /etc/blippstation/config.json readable only by root and the service, and the daemon holds the reader exclusively so card data cannot leak into any other program.
Troubleshooting
- Reader not detected — confirm it is in HID keyboard mode (
lsusb shows 09d8:0410). For a different reader, set its USB vendor and product ID under Advanced.
- Test scan fails while the service is running — expected; the daemon holds the reader exclusively. Stop it with
sudo systemctl stop blippstation, or test before installing.
- UID decodes incorrectly — the decoder assumes a US keyboard layout. Use Debug — raw key dump in the console and send the output to support@devolent.com.
