# 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