# 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)