Kiwy-Signage/documentation/dev-notes/CARD_READER_AUTHENTICATION.md

USB Card Reader Authentication

This document describes the USB card reader authentication feature for the Kiwy Signage Player.

Overview

The player now supports user authentication via USB card readers when accessing the edit/drawing interface. When a user clicks the edit button (pencil icon), they must swipe their card to authenticate before being allowed to edit the image.

How It Works

1. Edit Button Click: User clicks the pencil icon to edit the current image
2. Validation Checks:
   • Verify current media is an image (not video)
   • Check if editing is allowed for this media (edit_on_player permission from server)
3. Card Reader Prompt:
   • Display "Please swipe your card..." message
   • Wait for card swipe (5 second timeout)
   • Read card data from USB card reader
   • Store the card data (no validation required)
4. Open Edit Interface: Edit interface opens with card data stored
5. Save & Upload: When user saves the edited image:
   • Card data is included in the metadata JSON
   • Both image and metadata (with card data) are uploaded to server
   • Server receives user_card_data field for tracking who edited the image

Card Reader Setup

Hardware Requirements

• USB card reader (HID/keyboard emulation type)
• Compatible cards (magnetic stripe or RFID depending on reader)

Software Requirements

The player requires the evdev Python library to interface with USB input devices:

# Install via apt (recommended for Raspberry Pi)
sudo apt-get install python3-evdev

# Or via pip
pip3 install evdev

Fallback Mode

If evdev is not available, the player will:

• Log a warning message
• Use a default card value (DEFAULT_USER_12345) for testing
• This allows development and testing without hardware

Card Data Storage

The card data is captured as a raw string and stored without validation or mapping:

• No preprocessing: Card data is stored exactly as received from the reader
• Format: Whatever the card reader sends (typically numeric or alphanumeric)
• Sent to server: Raw card data is included in the user_card_data field of the metadata JSON
• Server-side processing: The server can validate, map, or process the card data as needed

Metadata JSON Format

When an image is saved, the metadata includes:

{
  "time_of_modification": "2025-12-08T10:30:00",
  "original_name": "image.jpg",
  "new_name": "image_e_v1.jpg",
  "original_path": "/path/to/image.jpg",
  "version": 1,
  "user_card_data": "123456789"
}

If no card is swiped (timeout), user_card_data will be null.

Testing the Card Reader

A test utility is provided to verify card reader functionality:

cd /home/pi/Desktop/Kiwy-Signage/dev/tests
python3 test_card_reader.py

The test tool will:

1. List all available input devices
2. Auto-detect the card reader (or let you select manually)
3. Listen for card swipes and display the data received
4. Show how the data will be processed

Test Output Example

✓ Card data received: '123456789'
  Length: 9 characters
  Processed ID: card_123456789

Implementation Details

Main Components

1. CardReader Class (main.py)

   • Handles USB device detection
   • Reads input events from card reader
   • Provides async callback interface
   • Includes timeout handling (5 seconds)

2. Card Read Flow (show_edit_interface() method)

   • Validates media type and permissions
   • Initiates card read
   • Stores raw card data
   • Opens edit popup

3. Metadata Creation (_save_metadata() method)

   • Includes card data in metadata JSON
   • No processing or validation of card data
   • Sent to server as-is

Card Data Format

Card readers typically send data as keyboard input:

• Each character is sent as a key press event
• Data ends with an ENTER key press
• Reader format: [CARD_DATA][ENTER]

The CardReader class:

• Captures key press events
• Builds the card data string character by character
• Completes reading when ENTER is detected
• Returns the complete card data to the callback

Security Considerations

1. Server-Side Validation: Card validation should be implemented on the server
2. Timeout: 5-second timeout prevents infinite waiting for card swipe
3. Logging: All card reads are logged with the raw card data
4. Permissions: Edit permission must be enabled on the server (edit_on_player)
5. Raw Data: Card data is sent as-is; server is responsible for validation and authorization

Troubleshooting

Card Reader Not Detected

• Check USB connection
• Run ls /dev/input/ to see available devices
• Run the test script to verify detection
• Check evdev is installed: python3 -c "import evdev"

Card Swipes Not Recognized

• Verify card reader sends keyboard events
• Test with the test_card_reader.py utility
• Check card format is compatible with reader
• Ensure card is swiped smoothly at proper speed

Card Data Not Captured

• Check card data format in logs
• Enable debug logging to see raw card data
• Test in fallback mode (without evdev) to isolate hardware issues
• Verify card swipe completes within 5-second timeout

Permission Denied Errors

• User may need to be in the input group:

  sudo usermod -a -G input $USER
  

• Reboot after adding user to group

Future Enhancements

Potential improvements for the card reader system:

1. Server Validation: Server validates cards against database and returns authorization
2. Card Enrollment: Server-side UI for registering new cards
3. Multiple Card Types: Support for different card formats (barcode, RFID, magnetic)
4. Client-side Validation: Add optional local card validation before opening edit
5. Audit Trail: Server tracks all card usage with timestamps
6. RFID Support: Test and optimize for RFID readers
7. Barcode Scanners: Support USB barcode scanners as alternative
8. Retry Logic: Allow re-swipe if card read fails

Related Files

• /src/main.py - Main implementation (CardReader class, authentication flow)
• /src/edit_drowing.py - Drawing/editing interface (uses authenticated user)
• /dev/tests/test_card_reader.py - Card reader test utility
• /requirements.txt - Dependencies (includes evdev)