40 lines
2.9 KiB
Markdown
40 lines
2.9 KiB
Markdown
# 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
|