NFC GUI - Reader/Writer for ACS ACR1252

A modern PyQt5-based GUI application for reading and writing NFC tags using the ACS ACR1252U USB NFC Reader on Linux systems.

Features

• Modern PyQt5 GUI: Beautiful, responsive interface with material design styling
• Read Mode: Continuously scan NFC tags and automatically open URLs in browser
• Write Mode: Write URLs to NFC tags with optional permanent locking
• Batch Writing: Write the same URL to multiple tags sequentially
• Safety Features: Optional overwrite protection to prevent accidental data loss
• Clipboard Integration: Easy paste from clipboard and copy read URLs
• Real-time Logging: Activity log with timestamps for all operations
• System Tray Integration: Minimize to system tray for background operation
• Background Read Mode: Continuous tag reading while minimized - perfect for always-on inventory management

Screenshots

Main Application Window

The main interface showing Read/Write/Update mode controls, URL entry, batch writing options, and activity log.

URL Rewrite Settings

Configure regex patterns to automatically rewrite URLs when updating NFC tags (useful for migrating from local to public URLs).

System Tray Integration

Right-click menu for background operation with continuous NFC reading.

Application Launcher

The application integrates with your desktop environment's application menu after installation.

Hardware Requirements

• ACS ACR1252U USB NFC Reader/Writer (tested)
• NTAG213/215/216 NFC tags (recommended)
• Linux system with USB support

Validated Hardware

• Reader: ACS ACR1252U
• Tags: NXP NTAG213 (validated)

Installation

Quick Install (Recommended)

Run the install script which builds and installs the Debian package:

./install.sh

This will:

• Build the .deb package
• Optionally install it
• Set up all dependencies
• Configure system permissions

Manual Installation

Build the package:

./build-deb.sh

Install the package:

sudo dpkg -i dist/nfc-gui_1.0.0_amd64.deb
sudo apt-get install -f

Development Mode

For development without installing:

./run-gui.sh

Or manually:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m nfc_gui.gui

Usage

Read Mode

1. Click "Read Mode" button (green)
2. Present NFC tag to reader
3. URL will be automatically:
   • Displayed in the activity log
   • Copied to clipboard
   • Opened in your default browser

Write Mode

1. Click "Write Mode" button (blue)
2. Enter or paste the URL to write
3. Configure options:
   • Lock tag after writing: Permanently locks the tag (irreversible)
   • Allow overwrite: Permits overwriting existing tag data
4. Set batch count (1 for single tag, >1 for multiple tags)
5. Click "Write Tag(s)" (orange button)
6. Present tag(s) to the reader

GUI Controls

• Read Mode (Green): Switch to continuous tag reading
• Write Mode (Blue): Switch to tag writing mode
• URL Entry: Enter or paste URL to write to tags
• Paste Button: Paste URL from clipboard
• Lock tag after writing: Checkbox to enable permanent tag locking
• Allow overwrite: Checkbox to enable overwriting existing tags
• Batch count: Spinbox to set number of tags to write (1-100)
• Write Tag(s) (Orange): Execute write operation
• Clear Log: Clear the activity log
• Copy Last URL: Copy the last read URL to clipboard
• Open Last URL: Open the last read URL in browser
• Background Read Mode: Minimize to tray and enable continuous background reading

Background Read Mode

The application can run minimized in the system tray with continuous NFC tag reading:

1. Click "Background Read Mode" button in the main window, OR
2. Right-click the system tray icon and select "Background Read Mode"

When enabled:

• Application minimizes to system tray (blue circle icon)
• NFC reader stays active in read mode
• Present any NFC tag and the URL will automatically open in your browser
• Desktop notifications confirm mode changes
• Perfect for always-on inventory scanning at your desk

To restore the window:

• Double-click the tray icon, OR
• Right-click tray icon → "Show Window"

To quit completely:

• Right-click tray icon → "Quit"

Safety Features

Overwrite Protection

By default, the application will not overwrite tags that already contain data. To intentionally replace existing content, enable the "Allow overwrite" checkbox.

Tag Locking

When "Lock tag after writing" is enabled, tags will be permanently locked after writing. This is irreversible - locked tags cannot be rewritten.

URL Rewriting

The application includes configurable URL rewriting for migrating NFC tags from local to public URLs. This is useful when:

• You run a local service (like Homebox) that you later expose publicly
• You have old tags pointing to internal IPs that need updating

Settings Dialog: Click the "Settings" button to configure:

• Source URL Pattern: A regex pattern to match URLs that need rewriting
• Target Base URL: The new base URL to use

Example: Homebox Asset Tags

If you have NFC tags pointing to a local Homebox instance and want to migrate them to a public URL:

Field	Value
Source Pattern	^https?://10\.0\.0\.1:3100/item/(.+)$
Target Base URL	https://homebox.example.com/item/

This pattern:

• ^https?:// - Matches both http:// and https://
• 10\.0\.0\.1:3100 - Matches your local Homebox IP and port (dots escaped with \)
• /item/(.+)$ - Captures the item ID to append to the target URL

Result: http://10.0.0.1:3100/item/abc123 → https://homebox.example.com/item/abc123

Update Mode: Use "Update Mode" to automatically:

1. Read the existing URL from a tag
2. Apply the rewrite rule
3. Write the new URL back
4. Lock the tag

Project Structure

NFC-GUI-1025/
├── nfc_gui/
│   ├── __init__.py
│   ├── gui.py           # PyQt5 GUI implementation
│   └── nfc_handler.py   # Core NFC operations
├── install.sh           # Build & install Debian package (recommended)
├── build-deb.sh         # Build Debian package only
├── run-gui.sh           # Launch in development mode
├── requirements.txt     # Python dependencies
├── CHANGELOG.md         # Version history
└── README.md            # This file

Build Scripts

• install.sh - Interactive installer (builds and optionally installs)
• build-deb.sh - Build Debian package only (no installation)
• build.sh - Legacy build script (supports multiple formats, not recommended)
• run-gui.sh - Development mode launcher

Troubleshooting

Reader Not Found

• Ensure the ACS ACR1252 is connected via USB
• Check that pcscd daemon is running: sudo systemctl status pcscd
• Verify reader is detected: pcsc_scan

Permission Issues

• Add your user to the scard group: sudo usermod -a -G scard $USER
• Log out and back in for group changes to take effect

Tag Read/Write Failures

• Ensure tag is NDEF-compatible
• Try different tag positioning on the reader
• Check that the tag isn't locked or damaged
• Keep tag steady on reader during write operations

Tested Tags

• NXP NTAG213: ~144 bytes usable NDEF capacity (recommended)

Dependencies

• PyQt5: Modern GUI framework
• pyscard: PC/SC smartcard library interface
• ndeflib: NDEF message encoding/decoding
• pyperclip: Clipboard operations

Credits

Core NFC functionality based on VladoPortos's ACR1252 implementation

License

MIT License - see LICENSE for details.