moonlight-drive-in/clients/UPDATE_GUIDE.md

NFC Network Client Update - Global Input Capture

What's New in v1.1.0

MAJOR IMPROVEMENT: The NFC client now uses global input capture - it will capture NFC scans even when the window is NOT focused!

The Problem (Fixed)

Previously, the client only captured keyboard input when its window had focus. If you clicked on another window or minimized it, NFC scans wouldn't be detected.

The Solution

The new version uses the pynput library to capture keyboard input globally, regardless of which window has focus. This means:

✅ NFC scans work when the client is minimized ✅ NFC scans work when you're using other programs ✅ NFC scans work when you're browsing the web ✅ The client can run in the background without being annoying

Installation

For New Installations

1. Navigate to the clients directory
2. Install dependencies:

   pip install -r client_requirements.txt
   

3. Run the client:

   start_nfc_client.bat
   

For Existing Installations

1. Pull the latest version from Gitea
2. Install the new dependency:

   pip install pynput
   

3. Run the updated client:

   start_nfc_client.bat
   

The launcher will automatically check for pynput and install it if missing.

Technical Details

How It Works

• Uses pynput.keyboard.Listener for system-wide keyboard capture
• Monitors all keyboard input regardless of focus
• Maintains the same scan detection logic (character accumulation + Enter key)
• Automatically starts the global listener on launch

UI Indicators

The client window now shows:

• "Global Input Capture" status panel
• Green "Active - Capturing NFC scans globally" when running
• Clear indication that scans work without window focus

Requirements

• Python 3.7+
• pynput (new requirement)
• requests (existing)
• tkinter (usually included with Python)

Compatibility

• ✅ Windows 10/11
• ✅ Linux (requires X11 or accessibility permissions)
• ✅ macOS (may require accessibility permissions)

Troubleshooting

"Permission denied" errors on Linux/macOS

The system may require accessibility permissions for global input capture.

Linux (X11):

# Should work out of the box with X11
# Wayland may require additional setup

macOS:

1. Go to System Preferences → Security & Privacy → Privacy
2. Add Python/Terminal to "Accessibility" list
3. Restart the client

"pynput not found" error

Run:

pip install pynput

Or use the requirements file:

pip install -r client_requirements.txt

Version History

v1.1.0 (Current)

• ✨ NEW: Global input capture - works without window focus
• ✨ NEW: Background operation capability
• ✨ NEW: Visual status indicators for capture state
• 🐛 FIX: No longer loses scans when window is unfocused
• 📦 NEW: Added pynput dependency

v1.0.0

• Initial release with window-focus-dependent input capture

Need Help?

If you have issues:

1. Check that pynput is installed: pip show pynput
2. Check the Activity Log in the client window
3. Test with a simple keyboard input when window is unfocused

Enjoy seamless NFC scanning! 🎬