diff --git a/.claude-context/sessions/2026-09-23-windows-driver-fix.md b/.claude-context/sessions/2026-09-23-windows-driver-fix.md new file mode 100644 index 0000000..1d93900 --- /dev/null +++ b/.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)