147 lines
4.5 KiB
Markdown
147 lines
4.5 KiB
Markdown
# Global Input Capture Implementation Summary
|
|
|
|
## Problem Solved
|
|
The NFC Network Client was losing NFC scans when the window lost focus. Users had to keep the window focused for it to detect scans, which was inconvenient.
|
|
|
|
## Solution Implemented
|
|
Implemented **global keyboard capture** using the `pynput` library, allowing the client to capture NFC scans regardless of window focus state.
|
|
|
|
## Changes Made
|
|
|
|
### 1. Updated `nfc_network_client.py` (v1.1.0)
|
|
**Key Changes:**
|
|
- Added `pynput.keyboard` integration for system-wide input capture
|
|
- Implemented `keyboard.Listener` that runs in a background thread
|
|
- Added `start_keyboard_listener()` and `stop_keyboard_listener()` methods
|
|
- Modified `on_key_press()` to handle global keyboard events
|
|
- Added UI status panel showing "Global Input Capture" state
|
|
- Proper cleanup on application shutdown
|
|
|
|
**Technical Implementation:**
|
|
```python
|
|
self.keyboard_listener = keyboard.Listener(on_press=self.on_key_press)
|
|
self.keyboard_listener.start()
|
|
```
|
|
|
|
The listener captures all keyboard input system-wide and filters for NFC scan patterns (character accumulation followed by Enter key).
|
|
|
|
### 2. Created `client_requirements.txt`
|
|
New dependency file specifically for the client:
|
|
- `pynput>=1.7.6` (required for global input capture)
|
|
- `requests>=2.31.0` (HTTP client)
|
|
- `tkinter-tooltip>=2.2.0` (optional GUI enhancement)
|
|
- `typing-extensions>=4.5.0` (type hints support)
|
|
|
|
### 3. Updated `start_nfc_client.bat`
|
|
Enhanced launcher with:
|
|
- Automatic dependency checking for `pynput`
|
|
- Auto-installation if missing
|
|
- Clear messaging about global input capture capability
|
|
- Graceful error handling
|
|
|
|
### 4. Created `UPDATE_GUIDE.md`
|
|
Comprehensive documentation including:
|
|
- Feature explanation
|
|
- Installation instructions
|
|
- Technical details
|
|
- Troubleshooting guide
|
|
- Compatibility information
|
|
|
|
## User Experience Improvements
|
|
|
|
### Before (v1.0.0)
|
|
❌ Had to keep client window focused
|
|
❌ Scans lost when clicking other windows
|
|
❌ Couldn't minimize the client
|
|
❌ Annoying to keep on top
|
|
|
|
### After (v1.1.0)
|
|
✅ Works when minimized
|
|
✅ Works when using other programs
|
|
✅ Works when browsing/gaming
|
|
✅ Can run quietly in background
|
|
✅ Visual indicator of capture state
|
|
|
|
## Installation Steps for Users
|
|
|
|
1. **Pull latest from Gitea**
|
|
2. **Install new dependency:**
|
|
```
|
|
pip install pynput
|
|
```
|
|
Or use the requirements file:
|
|
```
|
|
cd clients
|
|
pip install -r client_requirements.txt
|
|
```
|
|
3. **Run the updated client:**
|
|
```
|
|
start_nfc_client.bat
|
|
```
|
|
|
|
The launcher automatically checks for and installs `pynput` if needed.
|
|
|
|
## Technical Architecture
|
|
|
|
```
|
|
User Scans NFC Tag
|
|
↓
|
|
NFC Reader (keyboard emulation)
|
|
↓
|
|
pynput.keyboard.Listener (global capture)
|
|
↓
|
|
on_key_press() event handler
|
|
↓
|
|
Character accumulation + Enter detection
|
|
↓
|
|
complete_scan() validates and sends
|
|
↓
|
|
HTTP POST to server /api/nfc_scan
|
|
↓
|
|
Server plays content
|
|
```
|
|
|
|
## Platform Compatibility
|
|
|
|
| Platform | Status | Notes |
|
|
|----------|--------|-------|
|
|
| Windows 10/11 | ✅ Full Support | Works out of the box |
|
|
| Linux (X11) | ✅ Full Support | Works out of the box |
|
|
| Linux (Wayland) | ⚠️ May Need Setup | Accessibility permissions may be required |
|
|
| macOS | ✅ Full Support | Requires accessibility permissions |
|
|
|
|
## Testing Recommendations
|
|
|
|
1. **Focus Test**: Start client, click another window, scan NFC tag
|
|
2. **Minimize Test**: Minimize client, scan NFC tag
|
|
3. **Background Test**: Open browser/game, scan NFC tag
|
|
4. **Multiple Scan Test**: Perform rapid sequential scans
|
|
5. **Connection Test**: Ensure scans still forward to server
|
|
|
|
## Known Considerations
|
|
|
|
- **Privacy**: Global keyboard capture is powerful - code is open source for transparency
|
|
- **Permissions**: Some systems may prompt for accessibility permissions (macOS, some Linux)
|
|
- **Performance**: Minimal overhead - listener only processes keyboard events
|
|
- **Security**: Listener is isolated to the client process and only processes during active scans
|
|
|
|
## Files Modified/Created in Gitea
|
|
|
|
✅ `clients/nfc_network_client.py` (updated)
|
|
✅ `clients/client_requirements.txt` (new)
|
|
✅ `clients/start_nfc_client.bat` (updated)
|
|
✅ `clients/UPDATE_GUIDE.md` (new)
|
|
|
|
## Version Bump
|
|
- Previous: v1.0.0
|
|
- Current: **v1.1.0**
|
|
|
|
## Maintenance Notes
|
|
|
|
- The `pynput` library is actively maintained and stable
|
|
- No additional system dependencies required on Windows
|
|
- Linux may need `python3-xlib` for X11 (usually pre-installed)
|
|
- Global listener automatically stops when application closes
|
|
|
|
Enjoy hassle-free NFC scanning! 🎬
|