lego-dimensions-reader/.claude-context/01-architecture.md

Architecture

Module Structure

lego-dimensions-reader/
├── lego_dimensions_reader.py   # Core portal communication
├── moonlight_integration.py    # Video player integration
├── character_database.json     # Character/vehicle ID mappings
├── requirements.txt            # Python dependencies
└── .claude-context/            # Session history

Core Classes

LegoDimensionsReader

Event-driven portal interface with callbacks:

• on_tag_insert(TagInfo) — fired when disc placed
• on_tag_remove(TagInfo) — fired when disc removed
• on_connect() / on_disconnect() — portal connection state
• on_error(Exception) — error handling

TagInfo (dataclass)

• uid: bytes — 7-byte NFC tag UID
• pad: Pad — CENTER, LEFT, or RIGHT
• event: TagEvent — INSERTED or REMOVED
• character_id: Optional[int] — decrypted ID (if available)
• character_name: Optional[str] — looked up from database

USB Protocol

Endpoints:

• OUT: 0x01 — commands to portal
• IN: 0x81 — events from portal (32-byte interrupt packets)

Command structure:

[0x55, length, cmd_type, cmd_id, ...payload, checksum, ...padding]

Tag event packet (0x56):

[0x56, ??, pad_num, ??, ??, action, uid[0:7], ...]

Platform Support

Platform	Backend	Driver Setup
Linux	libusb (native)	udev rules for non-root access
Windows	libusb-win32 via WinUSB	Zadig to replace HID driver
macOS	libusb (homebrew)	Should work, untested

Dependencies

• pyusb — USB device communication
• libusb (on Windows) — provides backend DLL

---

Last updated: 2026-09-23