Software LED Effects and Moonlight API Integration

Date: 2026-02-22 Project: lego-dimensions-reader Status: resolved Tags: led-effects, threading, moonlight-drive-in, nfc-card-id, api, gui, v1.3.0

Context

With the core reader working (Jan 2026), the portal's LED behaviour was unreliable — the hardware flash command didn't behave as expected and flashes kept running after a tag was removed. Separately, the reader needed to drive the Moonlight Drive-In player using the same card IDs that the existing single-tag NFC reader produces, so the existing video mappings could be reused. Work ran 2026-02-20 to 2026-02-22.

Key Decisions

Software-driven LED effects (threads in Python) instead of the portal's hardware flash/fade commands — the hardware effects weren't controllable enough and couldn't be cancelled cleanly.
Stop an effect when its tag is removed (v1.2.2) — effects are tracked per pad so removal cancels the running thread.
Remove the default LED blink on tag insert (v1.3.0) — themed colours come from tag_colors.json instead of a hardcoded response.
nfc_card_id = bytes 3–6 of the UID as decimal — matches the ID a standard NFC reader emits, so Moonlight's existing mappings work unchanged. A 10-digit zero-padded form (nfc_card_id_str) is also available.
Briefly tried sending the ID as keyboard-style plain text, then settled on the player's HTTP API — POST /api/video/play with JSON {"nfc_id": "<card id>"}.
Portal Configuration GUI (tkinter) with an effect speed control, so colours/effects can be tuned without editing JSON.

Technical Details

Portal: vendor 0x0e6f, product 0x0241.
Moonlight API (port 8547): POST /api/video/play {"nfc_id": "..."}, POST /api/video/skip, GET /api/stats.
moonlight_integration.py v1.3.0 — takes api_url (base URL of the player).
tag_colors.json — per-tag colour/effect config, now including a speed parameter.
Prefer finish states/callbacks (e.g. finish_color on flash_pad()) over sleep-based sync for background LED threads.

Code Changes

lego_dimensions_reader.py — software flash_pad (v1.2.1), stop flash on removal (v1.2.2), removed default blink + software effects (v1.3.0), nfc_card_id field.
portal_config_gui.py — new Portal Configuration GUI v1.1.0 with speed control.
moonlight_integration.py — uses nfc_card_id and the correct /api/video/play endpoint.
video_mappings.json.example, tag_colors.json.example, README.md — examples and docs.

Open Questions / Next Steps

Superseded in part by the 2026-04-06 session (cycle effect, full colour set).

Artifacts

8a9faac — Fix API to use correct Moonlight endpoint
203ea48 — Add nfc_card_id field (bytes 3-6 as decimal)
727ed71 — v1.3.0: Remove default LED blink, add software effects
13f0ae5 — Portal Configuration GUI v1.1.0

2.9 KiB Raw Blame History Unescape Escape