mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-04-10 21:03:01 +00:00

Files

Chuck 49287bdd1a docs: fix ADVANCED_FEATURES and REST_API_REFERENCE

REST_API_REFERENCE.md
- Wrong path: /fonts/delete/<font_family> -> /fonts/<font_family>
  (verified the real DELETE route in
  web_interface/blueprints/api_v3.py).
- Diffed the documented routes against the real api_v3 blueprint
  (92 routes vs the 71 documented). Added missing sections:
  - Error tracking (/errors/summary, /errors/plugin/<id>, /errors/clear)
  - Health (/health)
  - Schedule dim/power (/config/dim-schedule GET/POST)
  - Plugin-specific endpoints (calendar/list-calendars,
    of-the-day/json/upload+delete, plugins/<id>/static/<path>)
  - Starlark Apps (12 endpoints: status, install-pixlet, apps CRUD,
    repository browse/install, upload)
  - Font preview (/fonts/preview)
- Updated table of contents with the new sections.
- Added a footer note that the API blueprint mounts at /api/v3
  (app.py:144) and that SSE stream endpoints are defined directly on
  the Flask app at app.py:607-615.

ADVANCED_FEATURES.md
- Vegas Scroll Mode section was actually accurate (verified all
  config keys match src/vegas_mode/config.py:15-30).

- On-Demand Display section had multiple bugs:
  - 5 occurrences of port 5050 -> 5000
  - All API paths missing /v3 (e.g. /api/display/on-demand/start
    should be /api/v3/display/on-demand/start)
  - "Settings -> Plugin Management -> Show Now Button" UI flow doesn't
    exist. Real flow: open the plugin's tab in the second nav row,
    click Run On-Demand / Stop On-Demand.
  - "Python API Methods" section showed
    controller.show_on_demand() / clear_on_demand() /
    is_on_demand_active() / get_on_demand_info() — none of these
    methods exist on DisplayController. The on-demand machinery is
    all internal (_set_on_demand_*, _activate_on_demand, etc) and
    is driven through the cache_manager. Replaced the section with
    a note pointing to the REST API.
  - All Use Case Examples used the same fictional Python calls.
    Replaced with curl examples against the real API.

- Cache Management section claimed "On-demand display uses Redis cache
  keys". LEDMatrix doesn't use Redis — verified with grep that
  src/cache_manager.py has no redis import. The cache is file-based,
  managed by CacheManager (file at /var/cache/ledmatrix/ or fallback
  paths). Rewrote the manual recovery section:
  - Removed redis-cli commands
  - Replaced cache.delete() Python calls with cache.clear_cache()
    (the real public method per the same bug already flagged in
    PLUGIN_API_REFERENCE.md)
  - Replaced "Settings -> Cache Management" with the real Cache tab
  - Documented the actual cache directory candidates

- Background Data Service section:
  - Used "nfl_scoreboard" as the plugin id in the example.
    The real plugin is "football-scoreboard" (handles both NFL and
    NCAA). Fixed.
  - "Implementation Status: Phase 1 NFL only / Phase 2 planned"
    section was severely outdated. The background service is now
    used by all sports scoreboards (football, hockey, baseball,
    basketball, soccer, lacrosse, F1, UFC), the odds ticker, and
    the leaderboard plugin. Replaced with a current "Plugins using
    the background service" note.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-06 21:55:34 -04:00

README.md

LEDMatrix Documentation

This directory contains guides, references, and architectural notes for the LEDMatrix project. If you are setting up a Pi for the first time, start with the project root README — it covers hardware, OS imaging, and the one-shot installer. The pages here go deeper.

I'm a new user

GETTING_STARTED.md — first-time setup walkthrough
WEB_INTERFACE_GUIDE.md — using the web UI
PLUGIN_STORE_GUIDE.md — installing and managing plugins
WIFI_NETWORK_SETUP.md — WiFi and AP-mode setup
TROUBLESHOOTING.md — common issues and fixes
SSH_UNAVAILABLE_AFTER_INSTALL.md — recovering SSH after install
CONFIG_DEBUGGING.md — diagnosing config problems

I want to write a plugin

Start here:

PLUGIN_DEVELOPMENT_GUIDE.md — end-to-end workflow
PLUGIN_QUICK_REFERENCE.md — cheat sheet
PLUGIN_API_REFERENCE.md — display, cache, and plugin-manager APIs
PLUGIN_ERROR_HANDLING.md — error-handling patterns
DEV_PREVIEW.md — preview plugins on your dev machine without a Pi
EMULATOR_SETUP_GUIDE.md — running the matrix emulator

Going deeper:

ADVANCED_PLUGIN_DEVELOPMENT.md — advanced patterns
PLUGIN_ARCHITECTURE_SPEC.md — full plugin-system spec
PLUGIN_DEPENDENCY_GUIDE.md / PLUGIN_DEPENDENCY_TROUBLESHOOTING.md
PLUGIN_WEB_UI_ACTIONS.md (+ example JSON)
PLUGIN_CUSTOM_ICONS.md / PLUGIN_CUSTOM_ICONS_FEATURE.md
PLUGIN_REGISTRY_SETUP_GUIDE.md (+ registry template)
STARLARK_APPS_GUIDE.md — Starlark-based mini-apps
widget-guide.md — widget development

Configuring plugins

PLUGIN_CONFIG_QUICK_START.md — minimal config you need
PLUGIN_CONFIGURATION_GUIDE.md — schema design
PLUGIN_CONFIGURATION_TABS.md — multi-tab UI configs
PLUGIN_CONFIG_ARCHITECTURE.md — how the config system works
PLUGIN_CONFIG_CORE_PROPERTIES.md — properties every plugin honors

Advanced features

ADVANCED_FEATURES.md — Vegas scroll, on-demand display, cache management, background services, permissions
FONT_MANAGER.md — font system

Reference

REST_API_REFERENCE.md — all web-interface HTTP endpoints
PLUGIN_API_REFERENCE.md — Python APIs available to plugins
DEVELOPER_QUICK_REFERENCE.md — common dev tasks
PLUGIN_IMPLEMENTATION_SUMMARY.md — what the plugin system actually does

Contributing to LEDMatrix itself

DEVELOPMENT.md — environment setup
HOW_TO_RUN_TESTS.md — running the test suite
MULTI_ROOT_WORKSPACE_SETUP.md — multi-repo workspace
MIGRATION_GUIDE.md — breaking changes between releases

Contributing to the docs

Markdown only, professional tone, minimal emoji.
Prefer adding to an existing page over creating a new one. If you add a new page, link it from this index in the section it belongs to.
If a page becomes obsolete, move it to docs/archive/ rather than deleting it, so links don't rot.
Keep examples runnable — paths, commands, and config keys here should match what's actually in the repo.