lego-dimensions-reader/.claude-context/00-overview.md

LEGO Dimensions Portal Reader

Python module for communicating with LEGO Dimensions USB portals (PS3/PS4/Wii U versions) to detect character and vehicle disc placement/removal events.

Repository: https://gitea.hideawaygaming.com.au/jessikitty/lego-dimensions-reader

Purpose

Drives the Moonlight Drive-In video player system — placing a LEGO Dimensions character disc triggers themed video playback and LED light effects.

Architecture

• Core module: lego_dimensions_reader.py — event-driven NFC tag detection with callbacks
• Character database: character_database.json — maps IDs to character/vehicle names
• Integration: moonlight_integration.py — connects portal events to video player via POST /api/video/play {"nfc_id": "<nfc_card_id>"} (port 8547)
• CLI client: dimensions_cli_client.py — themed LED effects + Moonlight calls; sets builtin_led_effects off so the base reader doesn't override themes
• Config tools: portal_config_gui.py, tag_color_editor.py (tkinter) editing tag_colors.json

Key Features

• Tag insert/remove callbacks
• Software-driven LED effects (threads): solid, flash, pulse, and software_cycle (chase across pads, optional trail). Hardware portal effects are not used.
• tag_colors.json — 82 themed per-tag colour/effect/speed entries
• nfc_card_id — UID bytes 3–6 as decimal, matching a standard NFC reader so Moonlight mappings are shared
• TEA encryption/decryption for character ID extraction
• Built-in character (82) and vehicle (82) databases
• Cross-platform: Linux native, Windows via WinUSB/Zadig

Session Log

• 2026-02-22 — Software LED Effects and Moonlight API Integration — Replaced hardware LED effects with software threads; added nfc_card_id and the /api/video/play integration; Portal Configuration GUI
• 2026-04-06 — Cycle Effect, Tag Colour Library and Colour Editor — Added software_cycle with correct removal rules, 82-entry tag_colors.json and Tag Colour Editor
• 2026-09-23 — Windows Driver Fix — Resolved pyusb backend issues on Windows 11; requires pip install libusb and Zadig WinUSB driver

---

Created by: Jess Rogerson (yelling commands at Claude.AI)