A Django-based inventory management system for homelabs using NFC tags and the ACR1252U NFC reader. Track equipment, storage locations, and automate tasks with NFC cards.

• Real-time NFC Scanning: WebSocket-based live scanning interface
• Storage Location Management: Hierarchical storage locations with NFC tags
• Item Tracking: Full inventory management with categories, quantities, and locations
• NFC Tag Association: Link NFC tags to locations, items, or commands
• Command Cards: Execute predefined commands by scanning special NFC cards
• Modern UI: DaisyUI + Tailwind CSS responsive interface with 10+ themes
• Theme Switcher: Choose from dark/light themes (Dark, Dracula, Night, Coffee, Synthwave, etc.)
• Admin Panel: Full Django admin for management

• NFC Reader: ACS ACR1252U-DOT (USB NFC Reader)
• NFC Tags: MIFARE Classic 1K/4K or compatible tags
• OS: Linux (Fedora 42 tested, should work on other distros)

Install PC/SC Lite development libraries:

# Fedora/RHEL
sudo dnf install pcsc-lite-devel pcscd

# Ubuntu/Debian
sudo apt-get install libpcsclite-dev pcscd

Start the PC/SC daemon:

sudo systemctl start pcscd
sudo systemctl enable pcscd  # Optional: auto-start on boot

direnv automatically activates the virtual environment and loads environment variables when you enter the project directory.

# Install direnv
sudo dnf install direnv  # Fedora/RHEL
# or
sudo apt-get install direnv  # Ubuntu/Debian

# Add to your shell (~/.bashrc or ~/.zshrc)
eval "$(direnv hook bash)"  # for bash
# or
eval "$(direnv hook zsh)"   # for zsh

# Reload shell
source ~/.bashrc

# Allow direnv in this project
cd /home/mike/nfcinv
direnv allow

See DIRENV_SETUP.md for detailed configuration.

Benefits: Auto-activates venv, loads .env variables, no manual source venv/bin/activate needed!

# Clone the repository (if not already done)
cd /home/mike/nfcinv

# Run the setup script
./setup.sh

# Activate virtual environment
source venv/bin/activate

# Create a superuser for Django admin
python manage.py createsuperuser

# Run the development server with ASGI (for WebSockets)
daphne -b 0.0.0.0 -p 8000 config.asgi:application

Test if your NFC reader is working:

# Activate virtual environment
source venv/bin/activate

# Test NFC reader connection and scan for tags
python manage.py test_nfc --continuous

# Test reading specific blocks
python manage.py test_nfc --continuous --read-blocks 4 5 6 7

For development (with WebSocket support):

source venv/bin/activate
daphne -b 0.0.0.0 -p 8000 config.asgi:application

Access the application at: http://localhost:8001 (port configurable in .env)

Note: Port 8001 is used to avoid conflicts with other services. See PORT_CONFIG.md to change the port.

• Dashboard (/): Overview with stats and recent scans
• NFC Scanner (/nfc-scanner/): Real-time NFC tag scanning
• Locations (/locations/): Manage storage locations
• Items (/items/): View and manage inventory items
• Tags (/tags/): View registered NFC tags
• Admin (/admin/): Full management interface

Click the palette icon (🎨) in the navbar to choose from 10 themes:

• Dark Themes: Dark (default), Dracula, Night, Coffee, Synthwave, Cyberpunk, Forest, Luxury
• Light Themes: Light, Cupcake

Your theme preference is saved automatically. See THEMES.md for details.

1. Create Storage Locations

   • Go to Admin → Storage Locations → Add
   • Create location (e.g., "Server Rack", "Tool Cabinet")

2. Tag Locations with NFC

   • Go to NFC Scanner
   • Click "Start Scanning"
   • Place NFC tag on reader
   • Go to Admin → NFC Tags → find the detected UID
   • Associate it with your storage location

3. Add Items

   • Go to Admin → Items → Add
   • Fill in item details
   • Assign to a storage location
   • Optionally tag with NFC

4. Scan and Locate

   • Use NFC Scanner to scan location tags
   • Instantly see what items are in that location
   • Scan item tags to see item details and location

Command cards allow you to execute predefined commands by scanning special NFC tags.

1. Create a Command

   • Go to Admin → Commands → Add
   • Set name and description
   • Scan an NFC card and note its UID
   • Enter the UID in "Card UID" field
   • Enter the command to execute
   • Set security options (requires confirmation, etc.)

2. Execute Command

   • Go to NFC Scanner
   • Scan the command card
   • Confirm execution if required
   • View execution logs in Admin

Security Note: Commands are executed on the server. Only create commands for trusted operations and implement proper security controls.

• Hierarchical storage locations (can have parent locations)
• Optional NFC tag UID
• Tracks items in location

• Inventory items with name, description, quantity
• Category and barcode/SKU support
• Assigned to storage location
• Optional individual NFC tag

• Tag UID (unique identifier)
• Tag type: location, item, command, or other
• Association with location or item
• Scan tracking (count, last scanned)
• Flexible JSON data storage

• Command card configuration
• Card UID for triggering
• Command string to execute
• Security options (confirmation required, active/inactive)
• Execution tracking and logging

• Audit trail for command executions
• Success/failure status
• Output and error logging

• /ws/nfc-scanner/ - Real-time NFC scanning events

• /api/associate-tag/ - Associate NFC tag with location or item (POST)

The inventory/nfc_service.py module provides:

• NFCReader: PC/SC interface for ACR1252U

  • connect(): Connect to reader
  • poll(): Check for card presence
  • get_uid(): Read card UID
  • read_block(n): Read data from block
  • write_block(n, data): Write data to block

• NFCDataEncoder: Helper for encoding/decoding text to NFC blocks

nfcinv/
├── config/                 # Django project settings
│   ├── settings.py
│   ├── urls.py
│   └── asgi.py            # ASGI config for WebSockets
├── inventory/             # Main app
│   ├── models.py          # Database models
│   ├── views.py           # HTTP views
│   ├── consumers.py       # WebSocket consumers
│   ├── nfc_service.py     # NFC reader interface
│   ├── routing.py         # WebSocket routing
│   ├── admin.py           # Django admin config
│   ├── templates/         # HTML templates
│   └── management/
│       └── commands/
│           └── test_nfc.py  # NFC testing command
├── requirements.txt       # Python dependencies
├── setup.sh              # Setup script
└── README.md             # This file

# Check if pcscd is running
sudo systemctl status pcscd

# Check if reader is connected
pcsc_scan

# Check permissions (add user to plugdev group)
sudo usermod -a -G plugdev $USER

• Ensure you're running with daphne (not python manage.py runserver)
• Check browser console for WebSocket errors
• Verify firewall allows port 8000

• Default keys are used (FF FF FF FF FF FF)
• Some tags may have different authentication
• Check tag compatibility (MIFARE Classic works best)

For production use:

1. Set DEBUG = False in settings.py
2. Configure proper SECRET_KEY
3. Use PostgreSQL instead of SQLite
4. Set up Redis for channel layers
5. Use proper ASGI server (Daphne with systemd)
6. Configure nginx/Apache as reverse proxy
7. Enable HTTPS
8. Set up proper logging

This is a homelab project. Feel free to fork and customize for your needs.

MIT License - see LICENSE file

• Django + Channels for WebSocket support
• pyscard for PC/SC interface
• DaisyUI + Tailwind CSS for UI
• ACR1252U reader for NFC support