From 7b40bf7014a1df225581c02a364fc7d48e1e1100 Mon Sep 17 00:00:00 2001
From: jessikitty <jess.rogerson.29@outlook.com>
Date: Wed, 24 Dec 2025 02:18:44 +1100
Subject: [PATCH] Add update guide for global input capture feature

---
 clients/UPDATE_GUIDE.md | 115 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 clients/UPDATE_GUIDE.md

diff --git a/clients/UPDATE_GUIDE.md b/clients/UPDATE_GUIDE.md
new file mode 100644
index 0000000..3cf4d01
--- /dev/null
+++ b/clients/UPDATE_GUIDE.md
@@ -0,0 +1,115 @@
+# 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):**
+```bash
+# 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! 🎬