docs: add session log for Windows driver troubleshooting

.claude-context/sessions/2026-09-23-windows-driver-fix.md

@@ -0,0 +1,63 @@
+# Windows 11 USB Driver Troubleshooting for LEGO Portal
+
+**Date:** 2026-09-23
+**Project:** lego-dimensions-reader
+**Status:** resolved
+**Tags:** windows, usb, pyusb, libusb, drivers, zadig
+
+## Context
+The LEGO Dimensions WiiU portal was not being detected on Windows 11 when running the `lego_dimensions_reader.py` module. Initial error was "Portal not found" despite the device being connected, followed by "Operation not supported or unimplemented on this platform" errors.
+
+## Key Decisions
+- **Install `libusb` Python package** — pyusb needs a backend DLL on Windows. The `pip install libusb` package bundles the DLL in a Python-accessible location, avoiding manual DLL placement.
+- **Use Zadig to install WinUSB driver** — The portal ships with HID drivers which don't support raw USB access. WinUSB (via Zadig) enables pyusb communication.
+- **Keep existing kernel driver detach code** — The `connect()` method already wraps `is_kernel_driver_active()` / `detach_kernel_driver()` in `try/except (AttributeError, usb.core.USBError): pass`, making it Windows-safe. No code change needed.
+
+## Technical Details
+**Portal USB identifiers:**
+- VID: `0x0E6F`
+- PID: `0x0241`
+- Product string: "LEGO READER V2.10"
+- Manufacturer: "PDP LIMITED"
+- Interface: HID (Class 0x03)
+- Endpoints: 0x81 (IN), 0x01 (OUT) — 32-byte interrupt packets
+
+**Required packages:**
+```
+pip install pyusb libusb
+```
+
+**Zadig setup:**
+1. Options → List All Devices
+2. Select "LEGO READER V2.10"
+3. Target driver: WinUSB
+4. Click "Replace Driver"
+
+**USB operations verified working:**
+- `set_configuration()` ✓
+- `get_interface()` ✓
+- `claim_interface()` ✓
+- `write(1, data)` ✓
+- `read(0x81, 32, timeout=100)` ✓ — returned init response with "(c) LEGO 2014" signature
+
+**Tag event parsing (from `_poll_events`):**
+- Packet byte 0: `0x56` = NFC tag event
+- Packet byte 2: pad number (1=CENTER, 2=LEFT, 3=RIGHT)
+- Packet byte 5: action (0=INSERTED, 1=REMOVED)
+- Packet bytes 6-12: 7-byte UID
+
+## Code Changes
+No code changes required. The existing `lego_dimensions_reader.py` already handles Windows gracefully:
+
+- `connect()` lines 248-252: kernel driver detach wrapped in try/except
+- All USB operations use standard pyusb calls compatible with WinUSB backend
+
+## Open Questions / Next Steps
+- **Test full tag reading** — Run `python lego_dimensions_reader.py` with a character disc to verify end-to-end tag detection
+- **Character ID decryption** — May need to implement tag memory read commands (0xB2) to read pages 0x24-0x25 for TEA-encrypted character ID
+- **Integration testing** — Connect to Moonlight Drive-In video player system
+
+## Artifacts
+- Repository: https://gitea.hideawaygaming.com.au/jessikitty/lego-dimensions-reader
+- File: `lego_dimensions_reader.py` (SHA: 000981b09d078e1777229b7d8f748d3a6da8762b)
+- Diagnostic script used: `test_connect.py` (created during session, not committed)