nfcink

Vibe-coded, reverse-engineered driver for a 4-colour e-ink NFC display badge (240 × 416 px, black / white / red / yellow). The CLI reads the device configuration, writes images, composes name/photo badges, and triggers the e-ink refresh.

Layout

nfcink/             -- Python package (DeviceCfg, NfcInkDevice, transports, …)
nfcink.py           -- CLI entry point
requirements.txt

Quick start

Requires Python 3.10+ and a CCID-compliant contactless NFC reader (see NFC reader below).

Using uv (recommended)

uv venv
uv pip install -r requirements.txt
uv run nfcink.py read

Using pip

python -m venv .venv
# Linux / macOS:
source .venv/bin/activate
# Windows (PowerShell):
.venv\Scripts\Activate.ps1

pip install -r requirements.txt
python nfcink.py read

CLI

python nfcink.py [-v] [--reader N] <command> ...

Commands:

Command	Description
read	Print the parsed device configuration
current-slot	Print the index of the image slot currently shown
read-user-data	Read N bytes from the chip's 20 KB user data area
write-user-data	Write N bytes to the user data area (destructive)
write <image>	Quantise, dither and write an image, then refresh
badge <photo> --name "Jane Doe"	Compose and write a name badge
refresh	Trigger a screen refresh without rewriting image data
clear	Write a blank white screen
factory-reset	Re-upload the canonical driver flow

Options:

• --section N (write / refresh) — image slot index (default 0; badge has 3 slots: 0..2)
• --bw (write / badge) — force 2-colour palette (black + white only)
• --compression {lzo,none} (write) — upload mode: LZO-compressed F0D3 (default) or raw F0D2
• --reader N — PC/SC reader index (default: 0; PICC interface auto-preferred)
• -v — verbose APDU logging

NFC reader

Uses pyscard to talk to any CCID-compliant contactless NFC reader through the OS smart-card stack. SCardTransmit has no built-in timeout, so the 15-second e-ink waveform computation (F0D4850000) completes without the reader dropping the session.

Recommended hardware

Any ISO 14443-4 compliant CCID reader works. The ACS ACR1552U has been tested and works well.

Note — ACR122U compatibility: the ACR122U reader driven via nfcpy (direct USB / WinUSB) cannot sustain the ~15-second F0D4850000 response wait. The reader's firmware imposes a hard ~5-second NFC operation timeout that cannot be overridden in software, causing the session to drop before the device responds. Use a CCID reader with pyscard instead.

Reader setup

Windows (if needed)

The generic Windows CCID driver only exposes the SAM slot. If the PICC interface does not appear (see verification below), install the ACS CCID driver from acs.com.hk, then unplug and re-plug the reader.

Linux

sudo apt install pcscd libpcsclite-dev swig
sudo systemctl enable --now pcscd

Verify

Re-plug the reader, then run:

python -c "from smartcard.System import readers; print(list(readers()))"
# Should show: ACS ACR1552 1S CL Reader PICC 0

No reader? Alternative app

If you don't have a compatible NFC reader, the vendor's own Android app can write to the badge directly from a phone: NetMePro.

Use at your own risk. This is a closed-source third-party application. Review its permissions before installing and do not use it with sensitive data.

---

Protocol notes

• Refresh sequence. Send F0D4050000; on 68C6 resend once; on a second 68C6 send F0D4850000 (blocks ~14.5 s while the e-ink waveform is computed); then poll once with F0DE000001. Any of 9000, 009000 or 019000 counts as success — the device completes the waveform autonomously after the NFC session ends.
• Restore the 4_color Screen marker if write-user-data --force overwrote offset 0..13. The marker is a 14-byte ASCII string that the config parser reads to enable 4-color mode; without it write will produce wrong byte encodings:

  python nfcink.py write-user-data --offset 0 --force \
    --data 345F636F6C6F722053637265656E

See nfcink/runner.py and nfcink/protocol.py for the full state machine.