mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-10-04 06:15:09 +00:00
ChuckandClaude Opus 5.5
9a1f94f793
* fix(starlark): blank app locations use the device location, not San Francisco A Starlark (Tidbyt) app whose Location field is blank rendered at its author's hard-coded DEFAULT_LOCATION -- usually San Francisco -- even with the device city set under General settings. A user in Charlotte, NC got San Francisco weather and radar with nothing in config.json to explain it. src/device_location.py fills unset location fields at render time (display plugin and the web standalone render): the device city is geocoded once via Open-Meteo, preferring a match in the configured state/country, and cached permanently. A saved location always wins; if the lookup fails the field is dropped so the app uses its own default, and the failure is not retried for 30 minutes. Also fixes the config form: clearing a location omitted the key, and the save merges, so the old value could never be removed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(starlark): say what happens when the device location can't be used A blank app Location only renders at the device's city when one is set and the Open-Meteo lookup finds it. With no city, no match, or the geocoder unreachable (retried after 30 minutes), the app gets no location and keeps its author's default. The guide, the config page hint, CONFIG_REFERENCE and the CHANGELOG entry now say so. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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
- LOW_MEMORY_BOARDS.md — Pi Zero 2 W / 3B+ / 1GB Pi 4 memory limits
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 — original plugin-system design spec (historical; see its banner for what has drifted)
- PLUGIN_DEPENDENCY_GUIDE.md / PLUGIN_DEPENDENCY_TROUBLESHOOTING.md
- PLUGIN_WEB_UI_ACTIONS.md (+ example JSON)
- PLUGIN_CUSTOM_ICONS.md
- PLUGIN_REGISTRY_SETUP_GUIDE.md (+ registry template)
- STARLARK_APPS_GUIDE.md — Starlark-based mini-apps
- widget-guide.md — widget development
- ADAPTIVE_LAYOUT.md — render legibly on any panel size (opt-in font/layout scaling)
- plugin-safety-harness.md — test a plugin across every screen and matrix size
Configuring plugins
- PLUGIN_CONFIG_QUICK_START.md — minimal config you need
- PLUGIN_CONFIGURATION_GUIDE.md — schema design
- PLUGIN_ELEMENT_STYLING.md — let users restyle, move, hide and scale individual elements (per display mode, if you have them)
- 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
- CONFIG_REFERENCE.md — every key in config.json and config_secrets.json
- 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
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
- SPORTS_UNIFICATION.md — how the sports scoreboard base classes are organized
Audits
- audits/WEB_UI_AUDIT_2026-09.md — web UI audit (September 2026)
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, delete it (it stays in the repository
history) and fix the links to it;
test/test_doc_links.pyfails on broken relative links. - Keep examples runnable — paths, commands, and config keys here should match what's actually in the repo.