mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-10-10 09:06:36 +00:00
Merge remote-tracking branch 'origin/main' into claude/frame-timing-harness
# Conflicts: # CHANGELOG.md
This commit is contained in:
Chuck
+55
-74
@@ -185,63 +185,53 @@ their config section to control how oversized content is handled (see
|
||||
|
||||
### Plugin Integration (Developer Guide)
|
||||
|
||||
All of these have defaults in
|
||||
[`BasePlugin`](../src/plugin_system/base_plugin.py); override only what you
|
||||
need.
|
||||
|
||||
**1. Implement Content Method:**
|
||||
|
||||
```python
|
||||
def get_vegas_content(self):
|
||||
"""
|
||||
Return PIL Image or list of Images for Vegas mode.
|
||||
|
||||
Returns:
|
||||
PIL.Image or list[PIL.Image]: Content to display
|
||||
- Single image: fixed-width content
|
||||
- List of images: multiple segments
|
||||
- None: skip this cycle
|
||||
"""
|
||||
# Example: Return single wide image
|
||||
img = Image.new('RGB', (256, 32))
|
||||
# ... render your content ...
|
||||
return img
|
||||
|
||||
# Example: Return multiple segments
|
||||
return [image1, image2, image3]
|
||||
# Return a PIL Image, a list of Images, or None.
|
||||
# A single image is one block; a list becomes one item per image.
|
||||
return [self._render_game(game) for game in self.games]
|
||||
```
|
||||
|
||||
If it returns `None` (the default), Vegas falls back to the plugin's
|
||||
`scroll_helper` image, then to capturing `display()` output
|
||||
(`PluginAdapter.get_content()` in
|
||||
[`src/vegas_mode/plugin_adapter.py`](../src/vegas_mode/plugin_adapter.py)).
|
||||
|
||||
**2. Specify Content Type:**
|
||||
|
||||
```python
|
||||
def get_vegas_content_type(self):
|
||||
"""
|
||||
Specify how content should be handled.
|
||||
|
||||
Returns:
|
||||
str: 'multi' | 'static' | 'none'
|
||||
"""
|
||||
return 'multi' # Default for most plugins
|
||||
# 'multi' | 'static' | 'none' -- default is 'static'
|
||||
return 'multi'
|
||||
```
|
||||
|
||||
`'none'` excludes the plugin from Vegas mode.
|
||||
|
||||
**3. Optionally Specify Display Mode:**
|
||||
|
||||
```python
|
||||
def get_vegas_display_mode(self):
|
||||
"""
|
||||
Preferred display mode for this plugin.
|
||||
These return `VegasDisplayMode` members, not strings:
|
||||
|
||||
Returns:
|
||||
str: 'scroll' | 'fixed' | 'static'
|
||||
"""
|
||||
return 'scroll'
|
||||
```python
|
||||
from src.plugin_system.base_plugin import VegasDisplayMode
|
||||
|
||||
def get_vegas_display_mode(self):
|
||||
return VegasDisplayMode.SCROLL
|
||||
|
||||
def get_supported_vegas_modes(self):
|
||||
"""
|
||||
List of supported modes.
|
||||
|
||||
Returns:
|
||||
list: ['scroll', 'fixed', 'static']
|
||||
"""
|
||||
return ['scroll', 'static']
|
||||
return [VegasDisplayMode.SCROLL, VegasDisplayMode.STATIC]
|
||||
```
|
||||
|
||||
`VegasDisplayMode` has `SCROLL` (`"scroll"`), `FIXED_SEGMENT` (`"fixed"`) and
|
||||
`STATIC` (`"static"`). The default `get_vegas_display_mode()` uses the
|
||||
plugin's `vegas_mode` config value if set, otherwise maps the content type
|
||||
(`multi` to `SCROLL`, anything else to `FIXED_SEGMENT`).
|
||||
|
||||
### Content Rendering Guidelines
|
||||
|
||||
**Image Dimensions:**
|
||||
@@ -966,11 +956,16 @@ from src.cache_manager import CacheManager
|
||||
|
||||
service = get_background_service(CacheManager())
|
||||
stats = service.get_statistics()
|
||||
print(f"Active tasks: {stats['active_tasks']}")
|
||||
print(f"Completed: {stats['completed']}")
|
||||
print(f"Failed: {stats['failed']}")
|
||||
print(f"Active: {stats['active_requests']}")
|
||||
print(f"Completed: {stats['completed_requests']}")
|
||||
print(f"Failed: {stats['failed_requests']}")
|
||||
```
|
||||
|
||||
Other keys: `total_requests`, `cached_hits`, `cache_misses`,
|
||||
`average_fetch_time`, `completed_requests_count` (results currently held in
|
||||
memory) — see `BackgroundDataService.get_statistics()` in
|
||||
[`src/background_data_service.py`](../src/background_data_service.py).
|
||||
|
||||
**Enable Debug Logging:**
|
||||
```python
|
||||
import logging
|
||||
@@ -981,6 +976,10 @@ logging.getLogger('src.background_data_service').setLevel(logging.DEBUG)
|
||||
|
||||
## 5. Permission Management
|
||||
|
||||
Ownership, modes, sudo rules and the repair scripts are listed in
|
||||
[PERMISSIONS.md](PERMISSIONS.md). This section covers the helpers code uses
|
||||
to keep files shareable.
|
||||
|
||||
### Overview
|
||||
|
||||
LEDMatrix uses a dual-user architecture: the display service runs as root (hardware access), while the web interface runs as a non-privileged user. Centralized permission management ensures both can access necessary files.
|
||||
@@ -1044,7 +1043,7 @@ ensure_file_permissions(config_path, get_config_file_mode(config_path))
|
||||
| Config (secrets) | `rw-r-----` | `0o640` | Owner write, group read |
|
||||
| Assets | `rw-rw-r--` | `0o664` | Owner/group write, all read |
|
||||
| Plugins | `rw-rw-r--` | `0o664` | Owner/group write, all read |
|
||||
| Cache files | `rw-rw-r--` | `0o664` | Owner/group write, all read |
|
||||
| Cache files | `rw-rw----` | `0o660` | Owner/group write, no world access (`_CACHE_FILE_MODE` in `src/cache/disk_cache.py`) |
|
||||
|
||||
**Directory Permissions:**
|
||||
|
||||
@@ -1115,40 +1114,22 @@ These core utilities **already handle permissions** - you don't need to call per
|
||||
|
||||
### Manual Fixes
|
||||
|
||||
If you encounter permission issues:
|
||||
[PERMISSIONS.md](PERMISSIONS.md) lists who owns what on an installed system,
|
||||
the expected modes, and which `scripts/fix_perms/` script to run as which
|
||||
user. In short:
|
||||
|
||||
```bash
|
||||
# Targeted permission fixes (see scripts/fix_perms/README.md)
|
||||
sudo ./scripts/fix_perms/fix_assets_permissions.sh # assets/ tree (logos, fonts)
|
||||
sudo ./scripts/fix_perms/fix_cache_permissions.sh # all cache directories
|
||||
sudo ./scripts/fix_perms/fix_plugin_permissions.sh # plugin directories
|
||||
sudo ./scripts/fix_perms/fix_web_permissions.sh # web interface files
|
||||
- `fix_assets_permissions.sh`, `fix_cache_permissions.sh` and
|
||||
`fix_plugin_permissions.sh` are run with `sudo`.
|
||||
- `fix_web_permissions.sh` is run as the web interface user, without
|
||||
`sudo` (it refuses to run as root and calls `sudo` itself where needed).
|
||||
It resets project file ownership for that user, then makes the two
|
||||
helper scripts the web user may run as root (`safe_plugin_rm.sh`,
|
||||
`safe_pip_install.sh`) root-owned again and restores `config_secrets.json`
|
||||
to its owner, the `ledmatrix` group and mode `640`. It does not write
|
||||
sudoers rules; `scripts/install/configure_web_sudo.sh` does that.
|
||||
|
||||
# Fix specific directory
|
||||
sudo chown -R ledpi:ledpi /home/ledpi/LEDMatrix/config
|
||||
sudo chmod -R 2775 /home/ledpi/LEDMatrix/config
|
||||
sudo find /home/ledpi/LEDMatrix/config -type f -exec chmod 664 {} \;
|
||||
|
||||
# Verify permissions
|
||||
ls -la config/
|
||||
ls -la assets/
|
||||
```
|
||||
|
||||
### Verification
|
||||
|
||||
```bash
|
||||
# Check directory has setgid bit
|
||||
ls -ld assets/
|
||||
# Should show: drwxrwsr-x (note the 's')
|
||||
|
||||
# Check file has correct group
|
||||
ls -l assets/logo.png
|
||||
# Should show group 'ledpi'
|
||||
|
||||
# Check file permissions
|
||||
stat -c "%a %n" config/config.json
|
||||
# Should show: 644 config/config.json
|
||||
```
|
||||
Do not `chmod` the whole `config/` directory: `config_secrets.json` must stay
|
||||
`640`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ Advanced patterns, examples, and best practices for developing LEDMatrix plugins
|
||||
- [Using Weather Icons](#using-weather-icons)
|
||||
- [Implementing Scrolling with Deferred Updates](#implementing-scrolling-with-deferred-updates)
|
||||
- [Cache Strategy Patterns](#cache-strategy-patterns)
|
||||
- [Font Management and Overrides](#font-management-and-overrides)
|
||||
- [Font Management](#font-management)
|
||||
- [Error Handling Best Practices](#error-handling-best-practices)
|
||||
- [Performance Optimization](#performance-optimization)
|
||||
- [Testing Plugins with Mocks](#testing-plugins-with-mocks)
|
||||
@@ -25,69 +25,12 @@ Advanced patterns, examples, and best practices for developing LEDMatrix plugins
|
||||
|
||||
## Using Weather Icons
|
||||
|
||||
The Display Manager provides built-in weather icon drawing methods for easy visual representation of weather conditions.
|
||||
|
||||
### Basic Weather Icon Usage
|
||||
|
||||
```python
|
||||
def display(self, force_clear=False):
|
||||
if force_clear:
|
||||
self.display_manager.clear()
|
||||
|
||||
# Draw weather icon based on condition
|
||||
condition = self.data.get('condition', 'clear')
|
||||
self.display_manager.draw_weather_icon(condition, x=5, y=5, size=16)
|
||||
|
||||
# Draw temperature next to icon
|
||||
temp = self.data.get('temp', 72)
|
||||
self.display_manager.draw_text(
|
||||
f"{temp}°F",
|
||||
x=25, y=10,
|
||||
color=(255, 255, 255)
|
||||
)
|
||||
|
||||
self.display_manager.update_display()
|
||||
```
|
||||
|
||||
### Supported Weather Conditions
|
||||
|
||||
The `draw_weather_icon()` method automatically maps condition strings to appropriate icons:
|
||||
|
||||
- `"clear"`, `"sunny"` → Sun icon
|
||||
- `"clouds"`, `"cloudy"`, `"partly cloudy"` → Cloud icon
|
||||
- `"rain"`, `"drizzle"`, `"shower"` → Rain icon
|
||||
- `"snow"`, `"sleet"`, `"hail"` → Snow icon
|
||||
- `"thunderstorm"`, `"storm"` → Storm icon
|
||||
|
||||
### Custom Weather Icons
|
||||
|
||||
For more control, use individual icon methods:
|
||||
|
||||
```python
|
||||
# Draw specific icons
|
||||
self.display_manager.draw_sun(x=10, y=10, size=16)
|
||||
self.display_manager.draw_cloud(x=10, y=10, size=16, color=(150, 150, 150))
|
||||
self.display_manager.draw_rain(x=10, y=10, size=16)
|
||||
self.display_manager.draw_snow(x=10, y=10, size=16)
|
||||
```
|
||||
|
||||
### Text with Weather Icons
|
||||
|
||||
Use `draw_text_with_icons()` to combine text and icons:
|
||||
|
||||
```python
|
||||
icons = [
|
||||
("sun", 5, 5), # Sun icon at (5, 5)
|
||||
("cloud", 100, 5) # Cloud icon at (100, 5)
|
||||
]
|
||||
|
||||
self.display_manager.draw_text_with_icons(
|
||||
"Weather: Sunny, Cloudy",
|
||||
icons=icons,
|
||||
x=10, y=20,
|
||||
color=(255, 255, 255)
|
||||
)
|
||||
```
|
||||
The Display Manager's icon methods — `draw_weather_icon()`, `draw_sun()`,
|
||||
`draw_cloud()`, `draw_rain()`, `draw_snow()` and `draw_text_with_icons()` —
|
||||
are deprecated, removed in 3.7.0. Draw your own icons instead: render them
|
||||
onto a PIL image and paste it onto `self.display_manager.image`, or ship
|
||||
icon images with the plugin. The weather plugin's `WeatherIcons` class is an
|
||||
example. See [Deprecated APIs](PLUGIN_API_REFERENCE.md#deprecated-apis).
|
||||
|
||||
---
|
||||
|
||||
@@ -251,11 +194,8 @@ def update(self):
|
||||
sport_key = "nhl"
|
||||
cache_key = f"{self.plugin_id}_{sport_key}_games"
|
||||
|
||||
# Uses sport-specific live_update_interval from config
|
||||
cached = self.cache_manager.get_background_cached_data(
|
||||
cache_key,
|
||||
sport_key=sport_key
|
||||
)
|
||||
# get_background_cached_data() is deprecated, removed in 3.7.0 — use get()
|
||||
cached = self.cache_manager.get(cache_key, max_age=60)
|
||||
|
||||
if cached:
|
||||
self.games = cached
|
||||
@@ -282,9 +222,9 @@ def on_config_change(self, new_config):
|
||||
|
||||
---
|
||||
|
||||
## Font Management and Overrides
|
||||
## Font Management
|
||||
|
||||
Use the Font Manager for advanced font handling and user customization.
|
||||
The display manager's built-in fonts and text measurement. For fonts shipped with a plugin, see [FONT_MANAGER.md](FONT_MANAGER.md).
|
||||
|
||||
### Using Different Fonts
|
||||
|
||||
@@ -656,14 +596,12 @@ def update(self):
|
||||
|
||||
```python
|
||||
def update(self):
|
||||
# Check if another plugin is enabled
|
||||
enabled_plugins = self.plugin_manager.get_enabled_plugins()
|
||||
if "weather" in enabled_plugins:
|
||||
# Weather plugin is available
|
||||
weather_plugin = self.plugin_manager.get_plugin("weather")
|
||||
if weather_plugin:
|
||||
# Use weather data
|
||||
pass
|
||||
# get_enabled_plugins() is deprecated, removed in 3.7.0 — check the
|
||||
# instance's `enabled` flag instead
|
||||
weather_plugin = self.plugin_manager.get_plugin("weather")
|
||||
if weather_plugin is not None and weather_plugin.enabled:
|
||||
# Use weather data
|
||||
pass
|
||||
```
|
||||
|
||||
### Sharing Data Between Plugins
|
||||
|
||||
@@ -0,0 +1,215 @@
|
||||
# Architecture
|
||||
|
||||
A map of the codebase for a new contributor: which process does what, how
|
||||
they talk to each other, and where to start reading for common changes.
|
||||
|
||||
## Processes
|
||||
|
||||
| systemd unit | Runs as | Runs | Installed by |
|
||||
|---|---|---|---|
|
||||
| `ledmatrix.service` | root | [`run.py`](../run.py) → `DisplayController` | [`install_service.sh`](../scripts/install/install_service.sh) |
|
||||
| `ledmatrix-web.service` | the installing user | [`start_web_conditionally.py`](../scripts/utils/start_web_conditionally.py) → [`web_interface/start.py`](../web_interface/start.py) (Flask, port 5000) | `install_service.sh`, [`install_web_service.sh`](../scripts/install/install_web_service.sh) |
|
||||
| `ledmatrix-update-verify.path` / `.service` | the web user | Health check after an automatic update | the same installers, or [`src/auto_update_setup.py`](../src/auto_update_setup.py) at runtime |
|
||||
| `ledmatrix-wifi-monitor.service` | root | [`wifi_monitor_daemon.py`](../scripts/utils/wifi_monitor_daemon.py) | [`install_wifi_monitor.sh`](../scripts/install/install_wifi_monitor.sh) |
|
||||
| `ledmatrix-mqtt-bridge.service` | root | [MQTT bridge](../integrations/mqtt_bridge/README.md) (optional) | [`install_mqtt_bridge.sh`](../scripts/install/install_mqtt_bridge.sh) |
|
||||
| `ledmatrix-dns-fix.service` | root | DNS workaround (optional) | [`install_dns_fix.sh`](../scripts/install/install_dns_fix.sh) |
|
||||
|
||||
Unit templates are in [`systemd/`](../systemd/README.md). The display runs as
|
||||
root because the LED matrix library needs direct GPIO access. The web
|
||||
interface runs unprivileged and uses a fixed list of `sudo` rules for the
|
||||
few privileged things it does; see [PERMISSIONS.md](PERMISSIONS.md).
|
||||
|
||||
`start_web_conditionally.py` exits without starting Flask when
|
||||
`web_display_autostart` is explicitly false in `config.json`.
|
||||
|
||||
## How the two main processes share state
|
||||
|
||||
The display and the web interface are separate processes that never call
|
||||
each other. They share three things:
|
||||
|
||||
1. **`config/config.json` and `config/config_secrets.json`.** The web
|
||||
interface writes them through `ConfigManager`
|
||||
([`src/config_manager.py`](../src/config_manager.py)); the display
|
||||
notices through `ConfigService` (below).
|
||||
2. **The disk cache**, `/var/cache/ledmatrix` (owned `root:ledmatrix`,
|
||||
setgid, files `0660`), read and written through `CacheManager`
|
||||
([`src/cache_manager.py`](../src/cache_manager.py),
|
||||
[`src/cache/disk_cache.py`](../src/cache/disk_cache.py)). Readers in the
|
||||
other process pass `memory_ttl=0` so they do not serve a stale in-memory
|
||||
copy.
|
||||
3. **A few files in `/tmp`.**
|
||||
|
||||
| State | Where | Written by | Read by |
|
||||
|---|---|---|---|
|
||||
| On-demand request | cache `display_on_demand_request` | web: `start_on_demand_display()` / `stop_on_demand_display()` in [`api_v3/display.py`](../web_interface/blueprints/api_v3/display.py) | display: `_poll_on_demand_requests()` |
|
||||
| On-demand state | cache `display_on_demand_state` | display: `_publish_on_demand_state()` | web: `/api/v3/display/on-demand/status` |
|
||||
| Current screen | cache `display_current_state` | display | web: `/api/v3/display/current-status` |
|
||||
| Plugin errors | cache `plugin_error_snapshot` | display: `ErrorSnapshotPublisher` ([`src/error_aggregator.py`](../src/error_aggregator.py)) | web: `read_error_report()` for `/api/v3/errors/*` |
|
||||
| Error clear | cache `plugin_error_clear_request` | web | display |
|
||||
| Font usage | cache `font_usage_snapshot` | display: `FontUsagePublisher` ([`src/font_usage.py`](../src/font_usage.py)) | web: Fonts tab |
|
||||
| Plugin health | cache `plugin_health:<id>` | display (web writes on reset) | web: `/api/v3/plugins/health` |
|
||||
| Preview frame | `/tmp/led_matrix_preview.png` | display: `DisplayManager`, gated by [`snapshot_policy`](../src/common/snapshot_policy.py) | web: display SSE stream, `/api/v3/health` (file age) |
|
||||
| Preview viewer marker | `/tmp/led_matrix_preview_viewer` | web, while a preview is open | display: writes full-rate snapshots only while it is fresh |
|
||||
| Hardware init status | `/tmp/led_matrix_hw_status.json` | display | web: `/api/v3/hardware/status` |
|
||||
|
||||
The on-demand start route also restarts `ledmatrix.service` by default so the
|
||||
request takes effect straight away.
|
||||
|
||||
## Display loop
|
||||
|
||||
[`src/display_controller.py`](../src/display_controller.py), class
|
||||
`DisplayController`. `__init__` loads config, starts the cache and the
|
||||
error-snapshot publisher, runs the startup validator, creates the
|
||||
`DisplayManager` ([`src/display_manager.py`](../src/display_manager.py)),
|
||||
`FontManager` and `PluginManager`, loads the enabled plugins in parallel,
|
||||
runs an initial `update()` pass within a 20-second budget
|
||||
(`_INITIAL_UPDATE_BUDGET_SECONDS`; a plugin that misses it is deferred to
|
||||
the scheduler), and sets up Vegas mode.
|
||||
|
||||
`run()` is the main loop. Each pass, in order: apply a pending plugin
|
||||
enable/disable, poll on-demand requests, run scheduled plugin updates, check
|
||||
the on/off schedule and brightness, then show one screen. Priority is
|
||||
on-demand, then WiFi status messages, then live priority, then Vegas mode,
|
||||
then normal rotation.
|
||||
|
||||
- **Rotation.** `available_modes` is the ordered list of display modes;
|
||||
`current_mode_index` advances after each screen.
|
||||
`_apply_plugin_rotation_order()` applies `display.plugin_rotation_order`.
|
||||
- **Durations.** `_get_display_duration()`: `display.display_durations[mode]`,
|
||||
else the plugin's `get_display_duration()`, else 30 s. Plugins that
|
||||
support dynamic duration run until `is_cycle_complete()`, capped by
|
||||
`display.dynamic_duration.max_duration_seconds` (default 180 s).
|
||||
- **On-demand.** A request from the web interface pins one plugin (or mode)
|
||||
for a duration. `_activate_on_demand()` / `_clear_on_demand()`; the
|
||||
session is saved under `display_on_demand_config` so it survives a
|
||||
restart. It also keeps the display on during scheduled off hours.
|
||||
- **Live priority.** `_check_live_priority()` looks for a plugin whose
|
||||
`has_live_priority()` and `has_live_content()` are both true and switches
|
||||
to it, rotating between several live games.
|
||||
- **Schedule and dim schedule.** `_check_schedule()` reads `schedule`;
|
||||
`_check_dim_schedule()` reads `dim_schedule` and
|
||||
`display.hardware.brightness`. Both are re-evaluated once a minute.
|
||||
- **Long screens.** While a screen is showing (a dwell, a scroll, a Vegas
|
||||
iteration), `_service_pending_changes()` repeats the on-demand, schedule
|
||||
and brightness checks every 0.25 s, so a change does not wait for the
|
||||
screen to end.
|
||||
- **Config hot reload.** `ConfigService`
|
||||
([`src/config_service.py`](../src/config_service.py)) polls the config and
|
||||
secrets files' mtimes every 2 s and notifies subscribers when the content
|
||||
changes. The controller refreshes its cached settings; enabling or
|
||||
disabling a plugin queues `_reconcile_enabled_plugins()`, which loads or
|
||||
unloads it on the display thread; each plugin gets `on_config_change()`
|
||||
for its own section. Set `LEDMATRIX_HOT_RELOAD=false` to turn this off.
|
||||
Matrix hardware settings are only read at start-up.
|
||||
- **Vegas mode.** [`src/vegas_mode/`](../src/vegas_mode/): the display loop
|
||||
calls `VegasModeCoordinator.run_iteration()`
|
||||
([`coordinator.py`](../src/vegas_mode/coordinator.py)) when
|
||||
`display.vegas_scroll.enabled` is set. `PluginAdapter` gets each plugin's
|
||||
content (`get_vegas_content()`, else its `scroll_helper` image, else a
|
||||
capture of `display()`), `StreamManager` orders it and `RenderPipeline`
|
||||
scrolls it. See [ADVANCED_FEATURES.md](ADVANCED_FEATURES.md).
|
||||
- **Multi-display sync.** `DisplaySyncManager`
|
||||
([`src/common/sync_manager.py`](../src/common/sync_manager.py)), enabled by
|
||||
`sync.role`: a leader sends a follower its share of each frame over UDP
|
||||
(port 5765).
|
||||
|
||||
## Plugin system
|
||||
|
||||
[`src/plugin_system/`](../src/plugin_system/):
|
||||
|
||||
| Area | Where |
|
||||
|---|---|
|
||||
| Base class plugins implement | [`base_plugin.py`](../src/plugin_system/base_plugin.py) (`BasePlugin`, `VegasDisplayMode`) |
|
||||
| Finding a plugin's directory | [`plugin_dirs.py`](../src/plugin_system/plugin_dirs.py): manifest `id` first, then directory `<id>` or `ledmatrix-<id>` |
|
||||
| Discovery, load, unload, scheduled updates | [`plugin_manager.py`](../src/plugin_system/plugin_manager.py) (`PluginManager`) |
|
||||
| Import and instantiate | [`plugin_loader.py`](../src/plugin_system/plugin_loader.py) (`PluginLoader.load_plugin()`: dependencies, module, class) |
|
||||
| Timeouts | [`plugin_executor.py`](../src/plugin_system/plugin_executor.py) (`PluginExecutor`, 30 s default; a timed-out thread is abandoned, not killed) |
|
||||
| Circuit breaker | [`plugin_health.py`](../src/plugin_system/plugin_health.py) (`PluginHealthTracker`: 3 consecutive failures open the circuit for 300 s) |
|
||||
| Resource metrics | [`resource_monitor.py`](../src/plugin_system/resource_monitor.py) |
|
||||
| Config schemas and defaults | [`schema_manager.py`](../src/plugin_system/schema_manager.py) |
|
||||
| Install, update, uninstall | [`store_manager.py`](../src/plugin_system/store_manager.py) (`PluginStoreManager`) |
|
||||
| Core-version gate | [`compatibility.py`](../src/plugin_system/compatibility.py) |
|
||||
|
||||
Discovery scans only `plugin_system.plugins_directory` (default
|
||||
`plugin-repos/`). Scheduled `update()` calls run on one background worker
|
||||
thread; a per-plugin lock keeps `display()` from running during an update.
|
||||
|
||||
**Store flow.** `install_plugin()` renames any existing copy aside
|
||||
(`<id>.standalone-backup-preinstall`), installs the new one, and puts the old
|
||||
copy back if the install fails. Monorepo plugins come from the GitHub Trees
|
||||
API, falling back to the repository ZIP; other plugins by `git clone` or
|
||||
download. The manifest is checked (see
|
||||
[required fields](PLUGIN_API_REFERENCE.md#manifest-required-fields)), the core
|
||||
version gate runs, then dependencies are installed as root through
|
||||
`scripts/fix_perms/safe_pip_install.sh`. `update_plugin()` pulls git
|
||||
installs, undoing a pull whose new version is incompatible, and reinstalls
|
||||
everything else through `_reinstall_with_rollback()`.
|
||||
|
||||
## Web interface
|
||||
|
||||
- **App.** [`web_interface/app.py`](../web_interface/app.py) builds the
|
||||
Flask `app` at import time, creates the managers, and registers two
|
||||
blueprints. `web_interface/start.py` runs it on port 5000.
|
||||
- **Pages.** [`blueprints/pages_v3.py`](../web_interface/blueprints/pages_v3.py)
|
||||
serves the shell `templates/v3/base.html` at `/` and each tab as a
|
||||
partial at `/partials/<name>` (templates in
|
||||
`web_interface/templates/v3/partials/`). Plugin configuration tabs are
|
||||
rendered from the plugin's schema by `plugin_config.html`.
|
||||
- **API.** [`blueprints/api_v3/`](../web_interface/blueprints/api_v3/) is one
|
||||
blueprint at `/api/v3`, split by area: `backup.py`, `config.py`,
|
||||
`display.py`, `fonts.py`, `misc.py` (health, logs, errors, cache, sync),
|
||||
`plugins.py`, `starlark.py`, `system.py` (service actions, updates, git),
|
||||
`wifi.py`. `__init__.py` defines the blueprint and shared helpers and
|
||||
imports the modules so their routes register. Endpoints are listed in
|
||||
[REST_API_REFERENCE.md](REST_API_REFERENCE.md).
|
||||
- **Front end.** HTMX loads each tab's partial on first open
|
||||
(`hx-trigger="loadtab"`); Alpine.js holds page state. Scripts are in
|
||||
`web_interface/static/v3/js/`; form widgets are bundled from
|
||||
[`js/widgets/`](../web_interface/static/v3/js/widgets/README.md).
|
||||
- **Server-sent events** (`app.py`): `/api/v3/stream/stats` (CPU, memory,
|
||||
temperature, service state, every 10 s), `/api/v3/stream/display` (preview
|
||||
frames when the PNG changes) and `/api/v3/stream/logs` (journal of both
|
||||
services). One generator thread per stream is shared by all clients.
|
||||
|
||||
## Updates
|
||||
|
||||
- **Update Code** on the Overview tab and the automatic updater both call
|
||||
`perform_core_update()` in
|
||||
[`api_v3/system.py`](../web_interface/blueprints/api_v3/system.py):
|
||||
`git pull --rebase`, reinstall changed requirement files, report whether a
|
||||
restart is needed.
|
||||
- **Automatic updates** (`auto_update.enabled`, off by default):
|
||||
`AutoUpdater` in [`web_interface/auto_update.py`](../web_interface/auto_update.py)
|
||||
runs in the web process, checks every 30 minutes, and updates at most
|
||||
weekly between 02:00 and 05:00. Before pulling it copies
|
||||
[`scripts/utils/auto_update_verify.py`](../scripts/utils/auto_update_verify.py)
|
||||
to `data/auto_update_verifier.py`, then writes
|
||||
`data/auto_update_verify.request`. That file triggers
|
||||
`ledmatrix-update-verify.path`, which runs the verifier as a separate unit
|
||||
(so restarting the web service does not kill it). The verifier restarts
|
||||
both services, waits for the web API to answer and the display service to
|
||||
stay up, and on failure resets to the previous commit and restarts again.
|
||||
Plugin updates run only after a verified core update. State is in
|
||||
`data/auto_update_state.json` and `data/auto_update_pending.json`.
|
||||
- **Startup validator.** `StartupValidator`
|
||||
([`src/startup_validator.py`](../src/startup_validator.py)) runs twice in
|
||||
`DisplayController.__init__`: config and cache directory first, then
|
||||
enabled plugins once the plugin manager exists. It also warns when an
|
||||
installed systemd unit differs from its template in `systemd/`. Results
|
||||
are logged; startup continues either way.
|
||||
|
||||
## Where to start reading
|
||||
|
||||
| Task | Start with |
|
||||
|---|---|
|
||||
| Change rotation, durations or priorities | `DisplayController.run()` and `_get_display_duration()` in [`display_controller.py`](../src/display_controller.py) |
|
||||
| Add a config key | [CONFIG_REFERENCE.md](CONFIG_REFERENCE.md), [`config/config.template.json`](../config/config.template.json), the tab's partial and `api_v3/config.py` |
|
||||
| Change drawing or fonts | [`display_manager.py`](../src/display_manager.py), [`font_manager.py`](../src/font_manager.py), [`src/common/bdf_font.py`](../src/common/bdf_font.py) |
|
||||
| Add a plugin-facing API | [`base_plugin.py`](../src/plugin_system/base_plugin.py) or [`src/common/`](../src/common/README.md); document it in [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) |
|
||||
| Plugin install/update bugs | `PluginStoreManager` in [`store_manager.py`](../src/plugin_system/store_manager.py) |
|
||||
| A plugin that won't load | `PluginManager.load_plugin()` and `PluginLoader.load_plugin()`; `python3 scripts/check_plugin.py --plugin <id>` |
|
||||
| Add an API endpoint | the matching module in [`api_v3/`](../web_interface/blueprints/api_v3/) |
|
||||
| Add a web UI tab or control | `templates/v3/base.html`, the tab's partial, `pages_v3.py` |
|
||||
| Vegas scroll | [`src/vegas_mode/coordinator.py`](../src/vegas_mode/coordinator.py) |
|
||||
| Installer or permissions | [`first_time_install.sh`](../first_time_install.sh), [`scripts/install/`](../scripts/install/), [PERMISSIONS.md](PERMISSIONS.md) |
|
||||
| Work without a Pi | [DEV_PREVIEW.md](DEV_PREVIEW.md), [EMULATOR_SETUP_GUIDE.md](EMULATOR_SETUP_GUIDE.md), [HOW_TO_RUN_TESTS.md](HOW_TO_RUN_TESTS.md) |
|
||||
@@ -172,10 +172,14 @@ ERROR - Plugin football-scoreboard configuration validation failed: 'api_key' is
|
||||
|
||||
### Enable Debug Logging
|
||||
|
||||
Set environment variable:
|
||||
Run the display in the foreground with `-d`, or set `LEDMATRIX_DEBUG=true`
|
||||
(the value must be `true`; `1` is ignored — see `setup_logging()` in
|
||||
[`src/logging_config.py`](../src/logging_config.py)):
|
||||
```bash
|
||||
export LEDMATRIX_DEBUG=1
|
||||
python run.py
|
||||
sudo systemctl stop ledmatrix.service
|
||||
sudo python3 run.py -d
|
||||
# or
|
||||
sudo LEDMATRIX_DEBUG=true python3 run.py
|
||||
```
|
||||
|
||||
### Check Merged Configuration
|
||||
@@ -321,8 +325,10 @@ cp config/backups/config.json.backup.20240115_120000_000000 config/config.json
|
||||
|
||||
## Getting Help
|
||||
|
||||
1. Check logs: `tail -f logs/ledmatrix.log`
|
||||
2. Enable debug: `LEDMATRIX_DEBUG=1`
|
||||
1. Check logs. Both services log to journald, not to a file:
|
||||
`sudo journalctl -u ledmatrix.service -f` (display) and
|
||||
`sudo journalctl -u ledmatrix-web.service -f` (web interface)
|
||||
2. Enable debug: `LEDMATRIX_DEBUG=true` or `python3 run.py -d`
|
||||
3. Check error dashboard: `/api/v3/errors/summary`
|
||||
4. Validate JSON: https://jsonlint.com/
|
||||
5. File an issue: https://github.com/ChuckBuilds/LEDMatrix/issues
|
||||
|
||||
@@ -54,8 +54,8 @@ rows = self.layout.bounds.inset(1).split_v(3, 1, gap=1)
|
||||
self.draw_fit("12:34", rows[0]) # largest crisp font that fits
|
||||
self.draw_image(logo, rows[1], mode="fill_height", crop_to_ink=True)
|
||||
|
||||
# Weather icons
|
||||
display_manager.draw_weather_icon("rain", x=10, y=10, size=16)
|
||||
# Weather icons: draw_weather_icon() is deprecated, removed in 3.7.0 —
|
||||
# draw your own icons (the weather plugin ships WeatherIcons)
|
||||
|
||||
# Scrolling state
|
||||
display_manager.set_scrolling_state(True)
|
||||
@@ -72,20 +72,23 @@ cache_manager.delete("key") # alias for clear_cache(key)
|
||||
|
||||
# Advanced caching
|
||||
data = cache_manager.get_cached_data_with_strategy("key", data_type="weather")
|
||||
data = cache_manager.get_background_cached_data("key", sport_key="nhl")
|
||||
|
||||
# Strategy
|
||||
strategy = cache_manager.get_cache_strategy("weather")
|
||||
interval = cache_manager.get_sport_live_interval("nhl")
|
||||
```
|
||||
|
||||
`get_background_cached_data()` (use `get()`) and `get_sport_live_interval()`
|
||||
are deprecated, removed in 3.7.0. See
|
||||
[Deprecated APIs](PLUGIN_API_REFERENCE.md#deprecated-apis).
|
||||
|
||||
## Plugin Manager Quick Methods
|
||||
|
||||
```python
|
||||
# Get plugins
|
||||
plugin = plugin_manager.get_plugin("plugin-id")
|
||||
all_plugins = plugin_manager.get_all_plugins()
|
||||
enabled = plugin_manager.get_enabled_plugins()
|
||||
# get_enabled_plugins() is deprecated, removed in 3.7.0 — check `enabled`
|
||||
# on the entries in plugin_manager.plugins
|
||||
|
||||
# Get info
|
||||
info = plugin_manager.get_plugin_info("plugin-id")
|
||||
@@ -168,7 +171,7 @@ def display(self, force_clear=False):
|
||||
|
||||
- [ ] Plugin inherits from `BasePlugin`
|
||||
- [ ] Implements `update()` and `display()` methods
|
||||
- [ ] `manifest.json` with required fields
|
||||
- [ ] `manifest.json` with the [required fields](PLUGIN_API_REFERENCE.md#manifest-required-fields)
|
||||
- [ ] `config_schema.json` for web UI (recommended)
|
||||
- [ ] `README.md` with documentation
|
||||
- [ ] Error handling implemented
|
||||
|
||||
+123
-326
@@ -9,12 +9,14 @@
|
||||
|
||||
## Overview
|
||||
|
||||
The enhanced FontManager provides comprehensive font management for the LEDMatrix application with support for:
|
||||
- Manager font registration and detection
|
||||
- Plugin font management
|
||||
- Programmatic per-element font overrides
|
||||
- Performance monitoring and caching
|
||||
- Dynamic font discovery
|
||||
[`src/font_manager.py`](../src/font_manager.py) loads and caches the TTF and
|
||||
BDF fonts in `assets/fonts/`, registers fonts that plugins ship, and records
|
||||
which plugin uses which font so the web UI can show it.
|
||||
|
||||
Several methods are deprecated and will be removed in LEDMatrix 3.7.0; they
|
||||
log a warning on first call. They are listed in
|
||||
[Deprecated methods](#deprecated-methods) below, and the full set is pinned in
|
||||
[`test/test_deprecation.py`](../test/test_deprecation.py).
|
||||
|
||||
## Getting the FontManager
|
||||
|
||||
@@ -34,157 +36,60 @@ standalone FontManager when none is available (test harnesses, mocks).
|
||||
`DisplayManager` has **no** `font_manager` attribute —
|
||||
`display_manager.font_manager` raises `AttributeError`.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Manager-Centric Design
|
||||
|
||||
Managers define their own fonts, but the FontManager:
|
||||
1. **Loads and caches fonts** for performance
|
||||
2. **Detects font usage** for visibility
|
||||
3. **Allows manual overrides** when needed
|
||||
4. **Supports plugin fonts** with namespacing
|
||||
|
||||
### Font Resolution Flow
|
||||
|
||||
```
|
||||
Manager requests font → Check manual overrides → Apply manager choice → Cache & return
|
||||
```
|
||||
|
||||
## For Manager Developers
|
||||
|
||||
### Basic Font Usage
|
||||
## Resolving a font
|
||||
|
||||
```python
|
||||
from src.font_manager import FontManager
|
||||
element_key = f"{self.plugin_id}.title"
|
||||
|
||||
class MyManager:
|
||||
def __init__(self, config, display_manager, cache_manager, plugin_manager):
|
||||
self.display_manager = display_manager
|
||||
self.font_manager = plugin_manager.font_manager # Shared FontManager
|
||||
self.manager_id = "my_manager"
|
||||
|
||||
def display(self):
|
||||
# Define your font choices
|
||||
element_key = "my_manager.title"
|
||||
font_family = "press_start"
|
||||
font_size_px = 10
|
||||
color = (255, 255, 255) # RGB white
|
||||
|
||||
# Register your font choice (for detection and future overrides)
|
||||
self.font_manager.register_manager_font(
|
||||
manager_id=self.manager_id,
|
||||
element_key=element_key,
|
||||
family=font_family,
|
||||
size_px=font_size_px,
|
||||
color=color
|
||||
)
|
||||
|
||||
# Get the font (checks for manual overrides automatically)
|
||||
font = self.font_manager.resolve_font(
|
||||
element_key=element_key,
|
||||
family=font_family,
|
||||
size_px=font_size_px
|
||||
)
|
||||
|
||||
# Use the font for rendering
|
||||
self.display_manager.draw_text(
|
||||
"Hello World",
|
||||
x=10, y=10,
|
||||
color=color,
|
||||
font=font
|
||||
)
|
||||
```
|
||||
|
||||
### Advanced Font Usage
|
||||
|
||||
```python
|
||||
class AdvancedManager:
|
||||
def __init__(self, config, display_manager, cache_manager, plugin_manager):
|
||||
self.display_manager = display_manager
|
||||
self.font_manager = plugin_manager.font_manager
|
||||
self.manager_id = "advanced_manager"
|
||||
|
||||
# Define your font specifications
|
||||
self.font_specs = {
|
||||
"title": {"family": "press_start", "size_px": 12, "color": (255, 255, 0)},
|
||||
"body": {"family": "four_by_six", "size_px": 8, "color": (255, 255, 255)},
|
||||
"footer": {"family": "five_by_seven", "size_px": 7, "color": (128, 128, 128)}
|
||||
}
|
||||
|
||||
# Register all font specs
|
||||
for element_type, spec in self.font_specs.items():
|
||||
element_key = f"{self.manager_id}.{element_type}"
|
||||
self.font_manager.register_manager_font(
|
||||
manager_id=self.manager_id,
|
||||
element_key=element_key,
|
||||
family=spec["family"],
|
||||
size_px=spec["size_px"],
|
||||
color=spec["color"]
|
||||
)
|
||||
|
||||
def get_font(self, element_type: str):
|
||||
"""Helper method to get fonts with override support."""
|
||||
spec = self.font_specs[element_type]
|
||||
element_key = f"{self.manager_id}.{element_type}"
|
||||
|
||||
return self.font_manager.resolve_font(
|
||||
element_key=element_key,
|
||||
family=spec["family"],
|
||||
size_px=spec["size_px"]
|
||||
)
|
||||
|
||||
def display(self):
|
||||
# Get fonts (automatically checks for overrides)
|
||||
title_font = self.get_font("title")
|
||||
body_font = self.get_font("body")
|
||||
footer_font = self.get_font("footer")
|
||||
|
||||
# Render with fonts
|
||||
self.display_manager.draw_text("Title", font=title_font, color=self.font_specs["title"]["color"])
|
||||
self.display_manager.draw_text("Body Text", font=body_font, color=self.font_specs["body"]["color"])
|
||||
self.display_manager.draw_text("Footer", font=footer_font, color=self.font_specs["footer"]["color"])
|
||||
```
|
||||
|
||||
### Using Size Tokens
|
||||
|
||||
```python
|
||||
# Get available size tokens
|
||||
tokens = self.font_manager.get_size_tokens()
|
||||
# Returns: {'xs': 6, 'sm': 8, 'md': 10, 'lg': 12, 'xl': 14, 'xxl': 16}
|
||||
|
||||
# Use token to get size
|
||||
size_px = tokens.get('md', 10) # 10px
|
||||
|
||||
# Then use in font resolution
|
||||
font = self.font_manager.resolve_font(
|
||||
element_key="my_manager.text",
|
||||
# Register the choice so the web UI's Fonts tab can list it.
|
||||
self.font_manager.register_manager_font(
|
||||
manager_id=self.plugin_id,
|
||||
element_key=element_key,
|
||||
family="press_start",
|
||||
size_px=size_px
|
||||
size_px=10,
|
||||
color=(255, 255, 255),
|
||||
)
|
||||
|
||||
font = self.font_manager.resolve_font(
|
||||
element_key=element_key,
|
||||
family="press_start",
|
||||
size_px=10,
|
||||
)
|
||||
self.display_manager.draw_text("Hello", x=10, y=10, font=font)
|
||||
```
|
||||
|
||||
## For Plugin Developers
|
||||
`resolve_font()` applies any entry for `element_key` in
|
||||
`config/font_overrides.json`, maps a plugin-local family to its namespaced
|
||||
name when `plugin_id` is passed, and then calls `get_font(family, size_px)`.
|
||||
On error it returns a fallback font rather than raising.
|
||||
|
||||
> **Note**: plugins that ship their own fonts via a `"fonts"` block
|
||||
> in `manifest.json` are registered automatically during plugin load
|
||||
> (`src/plugin_system/plugin_manager.py` calls
|
||||
> `FontManager.register_plugin_fonts()`). The `plugin://…` source
|
||||
> URIs documented below are resolved relative to the plugin's
|
||||
> install directory.
|
||||
>
|
||||
> The web UI's **Fonts** tab lists, uploads, previews and deletes the
|
||||
> font files in `assets/fonts/`. Its **Used by** column shows which
|
||||
> loaded plugins registered each file through `register_manager_font()`
|
||||
> (see [Font usage in the web UI](#font-usage-in-the-web-ui)), and it
|
||||
> warns before deleting one of them. It has no override editor (the
|
||||
> override panels and `/api/v3/fonts/overrides` endpoints were removed).
|
||||
> The programmatic override workflow in
|
||||
> [Manual Font Overrides](#manual-font-overrides) below still works.
|
||||
> Let users pick fonts through your plugin's own config schema.
|
||||
`get_font(family, size_px)` looks the family up in `font_catalog` and loads
|
||||
it (cached per family and size).
|
||||
|
||||
### Plugin Font Registration
|
||||
## Font families
|
||||
|
||||
In your plugin's `manifest.json`:
|
||||
At start-up the FontManager scans `assets/fonts/` for `.ttf` and `.bdf`
|
||||
files. Each becomes a family named after the file, lower-cased and without
|
||||
the extension (`PressStart2P-Regular.ttf` → `pressstart2p-regular`). Four
|
||||
aliases are added on top:
|
||||
|
||||
| Alias | File |
|
||||
|---|---|
|
||||
| `press_start` | `assets/fonts/PressStart2P-Regular.ttf` |
|
||||
| `four_by_six` | `assets/fonts/4x6-font.ttf` |
|
||||
| `five_by_seven` | `assets/fonts/5x7.bdf` |
|
||||
| `tom_thumb` | `assets/fonts/tom-thumb.bdf` |
|
||||
|
||||
Read the catalog directly: `font_manager.font_catalog` is a dict of family
|
||||
name to file path. Files added later are picked up on the next start of the
|
||||
display service.
|
||||
|
||||
## Plugin fonts
|
||||
|
||||
Plugins that ship their own fonts declare them in a `"fonts"` block in
|
||||
`manifest.json`. The plugin manager calls
|
||||
`FontManager.register_plugin_fonts()` during plugin load. `plugin://…`
|
||||
sources are resolved relative to the plugin's install directory.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -195,231 +100,123 @@ In your plugin's `manifest.json`:
|
||||
{
|
||||
"family": "custom_font",
|
||||
"source": "plugin://fonts/custom.ttf",
|
||||
"metadata": {
|
||||
"description": "Custom plugin font",
|
||||
"license": "MIT"
|
||||
}
|
||||
"metadata": {"description": "Custom plugin font", "license": "MIT"}
|
||||
},
|
||||
{
|
||||
"family": "web_font",
|
||||
"source": "https://example.com/fonts/font.ttf",
|
||||
"metadata": {
|
||||
"description": "Downloaded font",
|
||||
"checksum": "sha256:abc123..."
|
||||
}
|
||||
"metadata": {"checksum": "sha256:abc123..."}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Using Plugin Fonts
|
||||
Registered families are namespaced as `<plugin_id>::<family>`. Pass
|
||||
`plugin_id` to `resolve_font()` to use the short name:
|
||||
|
||||
```python
|
||||
class MyPlugin(BasePlugin):
|
||||
def __init__(self, plugin_id, config, display_manager, cache_manager, plugin_manager):
|
||||
super().__init__(plugin_id, config, display_manager, cache_manager, plugin_manager)
|
||||
self.font_manager = self._get_font_manager()
|
||||
|
||||
def display(self):
|
||||
# Use plugin font (automatically namespaced)
|
||||
font = self.font_manager.resolve_font(
|
||||
element_key=f"{self.plugin_id}.text",
|
||||
family="custom_font", # Will be resolved as "my-plugin::custom_font"
|
||||
size_px=10,
|
||||
plugin_id=self.plugin_id
|
||||
)
|
||||
|
||||
self.display_manager.draw_text("Plugin Text", font=font)
|
||||
```
|
||||
|
||||
## Manual Font Overrides
|
||||
|
||||
Overrides are set in code (there is no web UI or REST endpoint for them).
|
||||
They are stored in `config/font_overrides.json` and persist across restarts.
|
||||
|
||||
### Programmatic Overrides
|
||||
|
||||
```python
|
||||
# Set override
|
||||
font_manager.set_override(
|
||||
element_key="nfl.live.score",
|
||||
family="four_by_six",
|
||||
size_px=8
|
||||
font = self.font_manager.resolve_font(
|
||||
element_key=f"{self.plugin_id}.text",
|
||||
family="custom_font", # resolved as "my-plugin::custom_font"
|
||||
size_px=10,
|
||||
plugin_id=self.plugin_id,
|
||||
)
|
||||
|
||||
# Remove override
|
||||
font_manager.remove_override("nfl.live.score")
|
||||
|
||||
# Get all overrides
|
||||
overrides = font_manager.get_overrides()
|
||||
```
|
||||
|
||||
## Font Discovery
|
||||
## Overrides
|
||||
|
||||
### Available Fonts
|
||||
|
||||
The FontManager automatically scans `assets/fonts/` for TTF and BDF fonts:
|
||||
|
||||
```python
|
||||
# Get all available fonts
|
||||
fonts = font_manager.get_available_fonts()
|
||||
# Returns: {'press_start': 'assets/fonts/PressStart2P-Regular.ttf', ...}
|
||||
|
||||
# Check if font exists
|
||||
if "my_font" in fonts:
|
||||
font = font_manager.get_font("my_font", 10)
|
||||
```
|
||||
|
||||
### Adding Custom Fonts
|
||||
|
||||
Place font files in `assets/fonts/` directory:
|
||||
- Supported formats: `.ttf`, `.bdf`
|
||||
- Font family name is derived from filename (without extension)
|
||||
- Will be automatically discovered on next initialization
|
||||
`resolve_font()` still honours `config/font_overrides.json` (a map of
|
||||
element key to `family` and/or `size_px`), which is read once at start-up.
|
||||
The methods that edit it — `set_override()`, `remove_override()`,
|
||||
`get_overrides()` — are deprecated, and there is no web UI or REST endpoint
|
||||
for overrides (the override editor and `/api/v3/fonts/overrides` were
|
||||
removed). To let users choose a font, add a field to your plugin's config
|
||||
schema.
|
||||
|
||||
## Font usage in the web UI
|
||||
|
||||
The web interface runs in its own process and has no FontManager, so the
|
||||
display service publishes which plugin uses which font
|
||||
(`src/font_usage.py`), and the Fonts tab's **Used by** column reads it:
|
||||
The web UI's **Fonts** tab lists, uploads, previews and deletes the font
|
||||
files in `assets/fonts/`. The web interface runs in its own process and has
|
||||
no FontManager, so the display service publishes which plugin uses which
|
||||
font ([`src/font_usage.py`](../src/font_usage.py)), and the tab's **Used by**
|
||||
column reads it:
|
||||
|
||||
- **Source**: `register_manager_font()` registrations of the loaded
|
||||
plugins. `get_font()` and `resolve_font()` do not know the calling plugin
|
||||
and are not counted, and neither is a plugin that opens a font file
|
||||
directly with PIL — register the fonts your plugin draws with if you want
|
||||
them listed.
|
||||
- **Names**: a family, alias (`press_start`, `four_by_six`,
|
||||
`five_by_seven`, `tom_thumb`) or path is resolved through
|
||||
`font_catalog` to the file it loads and reported under that file's name
|
||||
without extension (`PressStart2P-Regular`, `4x6-font`, `5x7`,
|
||||
`tom-thumb`), which is how the Fonts tab keys its rows. Fonts outside
|
||||
`assets/fonts/` (a plugin's own `plugin_id::family` fonts) and families
|
||||
that resolve to nothing are left out.
|
||||
- **Names**: a family, alias or path is resolved through `font_catalog` to
|
||||
the file it loads and reported under that file's name without extension
|
||||
(`PressStart2P-Regular`, `4x6-font`, `5x7`, `tom-thumb`), which is how the
|
||||
Fonts tab keys its rows. Fonts outside `assets/fonts/` (a plugin's own
|
||||
`plugin_id::family` fonts) and families that resolve to nothing are left
|
||||
out.
|
||||
- **When**: a daemon thread started once plugins have loaded checks every
|
||||
10 seconds and writes the `font_usage_snapshot` cache key only when the
|
||||
usage changed (and once a day, so the cache's cleanup never expires it).
|
||||
Unloading a plugin drops its registrations (`forget_manager_fonts`).
|
||||
- **Unknown**: until the display service has published, the column reads
|
||||
"unknown" and `GET /api/v3/fonts/catalog` returns `used_by: null`.
|
||||
- The tab warns before deleting a font that a loaded plugin registered.
|
||||
|
||||
## Performance Monitoring
|
||||
## Text measurement
|
||||
|
||||
```python
|
||||
# Get performance stats
|
||||
stats = font_manager.get_performance_stats()
|
||||
|
||||
print(f"Cache hit rate: {stats['cache_hit_rate']*100:.1f}%")
|
||||
print(f"Total fonts cached: {stats['total_fonts_cached']}")
|
||||
print(f"Failed loads: {stats['failed_loads']}")
|
||||
print(f"Manager fonts: {stats['manager_fonts']}")
|
||||
print(f"Plugin fonts: {stats['plugin_fonts']}")
|
||||
```
|
||||
|
||||
## Text Measurement
|
||||
|
||||
```python
|
||||
# Measure text dimensions
|
||||
width, height, baseline = font_manager.measure_text("Hello", font)
|
||||
|
||||
# Get font height
|
||||
font_height = font_manager.get_font_height(font)
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
## Tips
|
||||
|
||||
### For Managers
|
||||
|
||||
1. **Register all fonts** you use for visibility
|
||||
2. **Use consistent element keys** (e.g., `{manager_id}.{element_type}`)
|
||||
3. **Cache font references** if using same font multiple times
|
||||
4. **Use `resolve_font()`** not `get_font()` directly to support overrides
|
||||
5. **Define sensible defaults** that work well on LED matrix
|
||||
|
||||
### For Plugins
|
||||
|
||||
1. **Use plugin-relative paths** (`plugin://fonts/...`)
|
||||
2. **Include font metadata** (license, description)
|
||||
3. **Provide fallback** fonts if custom fonts fail to load
|
||||
4. **Test with different display sizes**
|
||||
|
||||
### General
|
||||
|
||||
1. **BDF fonts** are often better for small sizes on LED matrices
|
||||
2. **TTF fonts** work well for larger sizes
|
||||
3. **Monospace fonts** are easier to align
|
||||
4. **Test on actual hardware** - what looks good on screen may not work on LED matrix
|
||||
|
||||
## Migration from Old System
|
||||
|
||||
### Old Way (Direct Font Loading)
|
||||
```python
|
||||
self.font = ImageFont.truetype("assets/fonts/PressStart2P-Regular.ttf", 8)
|
||||
```
|
||||
|
||||
### New Way (FontManager)
|
||||
```python
|
||||
element_key = f"{self.manager_id}.text"
|
||||
self.font_manager.register_manager_font(
|
||||
manager_id=self.manager_id,
|
||||
element_key=element_key,
|
||||
family="pressstart2p-regular",
|
||||
size_px=8
|
||||
)
|
||||
self.font = self.font_manager.resolve_font(
|
||||
element_key=element_key,
|
||||
family="pressstart2p-regular",
|
||||
size_px=8
|
||||
)
|
||||
```
|
||||
- BDF fonts usually look better than TTF at small sizes on LED panels.
|
||||
- Use `{plugin_id}.{element}` element keys.
|
||||
- Register the fonts you draw with, so the Fonts tab can warn before one is
|
||||
deleted.
|
||||
- Replace direct `ImageFont.truetype("assets/fonts/...", 8)` calls with
|
||||
`resolve_font()`: it caches, resolves paths against the install directory,
|
||||
and handles BDF files.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Font Not Found
|
||||
- Check font file exists in `assets/fonts/`
|
||||
- Verify font family name matches filename (without extension, lowercase)
|
||||
- Check logs for font discovery errors
|
||||
**Font not found**
|
||||
- Check the file exists in `assets/fonts/`.
|
||||
- The family name is the filename without extension, lower-cased.
|
||||
- Check the display service log for font discovery errors.
|
||||
|
||||
### Override Not Working
|
||||
- Verify element key matches exactly what manager registered
|
||||
- Check `config/font_overrides.json` for correct syntax
|
||||
- Restart application to ensure overrides are loaded
|
||||
**Plugin fonts not loading**
|
||||
- Check the manifest's `"fonts"` block.
|
||||
- Check the log for download or registration errors, and that font URLs are
|
||||
reachable.
|
||||
|
||||
### Performance Issues
|
||||
- Check cache hit rate in performance stats
|
||||
- Reduce number of unique font/size combinations
|
||||
- Clear cache if it grows too large: `font_manager.clear_cache()`
|
||||
## API reference
|
||||
|
||||
### Plugin Fonts Not Loading
|
||||
- Verify plugin manifest syntax
|
||||
- Check plugin directory structure
|
||||
- Review logs for download/registration errors
|
||||
- Ensure font URLs are accessible
|
||||
Current methods:
|
||||
|
||||
## API Reference
|
||||
| Method | Purpose |
|
||||
|---|---|
|
||||
| `register_manager_font(manager_id, element_key, family, size_px, color=None)` | Record a font choice (feeds the Fonts tab) |
|
||||
| `forget_manager_fonts(manager_id)` | Drop a manager's registrations (core calls it when a plugin unloads) |
|
||||
| `resolve_font(element_key, family, size_px, plugin_id=None)` | Get a font, applying overrides and plugin namespacing |
|
||||
| `get_font(family, size_px)` | Get a font directly |
|
||||
| `get_native_bdf_size(family)` | Native pixel size of a BDF family, or `None` |
|
||||
| `measure_text(text, font)` | `(width, height, baseline)` |
|
||||
| `get_font_height(font)` | Line height |
|
||||
| `register_plugin_fonts(plugin_id, font_manifest)` | Register a plugin's fonts (core calls it at load) |
|
||||
| `clear_cache()` | Drop cached fonts and metrics |
|
||||
| `font_catalog` (attribute) | Family name → file path |
|
||||
|
||||
### FontManager Methods
|
||||
### Deprecated methods
|
||||
|
||||
- `register_manager_font(manager_id, element_key, family, size_px, color=None)` - Register font usage
|
||||
- `forget_manager_fonts(manager_id)` - Drop a manager's registrations (core calls it when a plugin unloads)
|
||||
- `resolve_font(element_key, family, size_px, plugin_id=None)` - Get font with override support
|
||||
- `get_font(family, size_px)` - Get font directly (bypasses overrides)
|
||||
- `measure_text(text, font)` - Measure text dimensions
|
||||
- `get_font_height(font)` - Get font height
|
||||
- `set_override(element_key, family=None, size_px=None)` - Set manual override
|
||||
- `remove_override(element_key)` - Remove override
|
||||
- `get_overrides()` - Get all overrides
|
||||
- `get_detected_fonts()` - Get all detected font usage
|
||||
- `get_manager_fonts(manager_id=None)` - Get fonts by manager
|
||||
- `get_available_fonts()` - Get font catalog
|
||||
- `get_size_tokens()` - Get size token definitions
|
||||
- `get_performance_stats()` - Get performance metrics
|
||||
- `clear_cache()` - Clear font cache
|
||||
- `register_plugin_fonts(plugin_id, font_manifest)` - Register plugin fonts
|
||||
- `unregister_plugin_fonts(plugin_id)` - Unregister plugin fonts
|
||||
|
||||
## Example: Complete Manager Implementation
|
||||
|
||||
For a working example of the font manager API in use, see
|
||||
`src/font_manager.py` itself.
|
||||
Removed in 3.7.0. Each logs a warning on first call.
|
||||
|
||||
| Method | Use instead |
|
||||
|---|---|
|
||||
| `get_available_fonts()`, `get_font_catalog()` | read `font_catalog` |
|
||||
| `get_size_tokens()` | pass a pixel size |
|
||||
| `get_performance_stats()` | — |
|
||||
| `set_override()`, `remove_override()`, `get_overrides()` | a font field in your plugin's config schema |
|
||||
| `get_manager_fonts()`, `get_detected_fonts()` | — |
|
||||
| `get_plugin_fonts()`, `unregister_plugin_fonts()` | — |
|
||||
| `add_font()`, `remove_font()`, `validate_font()` | the web UI's Fonts tab |
|
||||
|
||||
+11
-10
@@ -116,8 +116,8 @@ weather and other location-aware plugins.
|
||||
4. Wait for installation to finish — installed plugins appear in the
|
||||
**Installed Plugins** section above and get their own tab in the second
|
||||
nav row
|
||||
5. Toggle the plugin to enabled
|
||||
6. From **Overview**, click **Restart Display Service**
|
||||
5. Toggle the plugin to enabled. The running display loads it within a
|
||||
few seconds; no restart is needed
|
||||
|
||||
You can also install community plugins straight from a GitHub URL using the
|
||||
**Install from GitHub** section further down the same tab — see
|
||||
@@ -128,9 +128,9 @@ You can also install community plugins straight from a GitHub URL using the
|
||||
1. Each installed plugin gets its own tab in the second navigation row
|
||||
2. Open that plugin's tab to edit its settings (favorite teams, API keys,
|
||||
update intervals, etc.)
|
||||
3. Click **Save**
|
||||
4. Restart the display service from **Overview** so the new settings take
|
||||
effect
|
||||
3. Click **Save**. The display service watches `config.json` and hands the
|
||||
new settings to the running plugin, so no restart is needed. If a plugin
|
||||
still shows old settings, restart the display service from **Overview**
|
||||
|
||||
**Note:** how long each plugin stays on screen is not set in the
|
||||
plugin's own tab — use the **Rotation** tab's **Screen Durations**
|
||||
@@ -197,14 +197,15 @@ The fastest way to verify a plugin works without waiting for the rotation:
|
||||
|
||||
**Check:**
|
||||
1. Plugin is enabled (toggle on the **Plugin Manager** tab)
|
||||
2. Display service was restarted after enabling
|
||||
3. Plugin's display duration is non-zero
|
||||
4. No errors in the **Logs** tab for that plugin
|
||||
2. Plugin's display duration is non-zero
|
||||
3. No errors in the **Logs** tab for that plugin. A plugin whose
|
||||
`validate_config()` fails is not loaded until its settings are fixed
|
||||
|
||||
**Fix:**
|
||||
1. Enable the plugin from **Plugin Manager**
|
||||
2. Click **Restart Display Service** on **Overview**
|
||||
3. Check the **Logs** tab for plugin-specific errors
|
||||
2. Check the **Logs** tab for plugin-specific errors
|
||||
3. If it still does not appear, click **Restart Display Service** on
|
||||
**Overview**
|
||||
|
||||
### Weather Plugin Shows "No Data"
|
||||
|
||||
|
||||
@@ -52,10 +52,10 @@ pytest test/test_display_controller.py test/test_plugin_system.py
|
||||
|
||||
```bash
|
||||
# Run a specific test class
|
||||
pytest test/test_display_controller.py::TestDisplayControllerModeRotation
|
||||
pytest test/test_display_controller.py::TestDisplayControllerLivePriority
|
||||
|
||||
# Run a specific test function
|
||||
pytest test/test_display_controller.py::TestDisplayControllerModeRotation::test_basic_rotation
|
||||
pytest test/test_display_controller.py::TestDisplayControllerSchedule::test_active_hours
|
||||
```
|
||||
|
||||
### Run Tests by Marker
|
||||
@@ -98,7 +98,7 @@ When you run `pytest`, you'll see:
|
||||
|
||||
```
|
||||
test/test_display_controller.py::TestDisplayControllerInitialization::test_init_success PASSED
|
||||
test/test_display_controller.py::TestDisplayControllerModeRotation::test_basic_rotation PASSED
|
||||
test/test_display_controller.py::TestDisplayControllerOnDemand::test_activate_on_demand PASSED
|
||||
...
|
||||
```
|
||||
|
||||
@@ -174,10 +174,10 @@ pytest
|
||||
|
||||
```bash
|
||||
# Run with maximum verbosity and show print statements
|
||||
pytest -vv -s test/test_display_controller.py::TestDisplayControllerModeRotation::test_basic_rotation
|
||||
pytest -vv -s test/test_display_controller.py::TestDisplayControllerSchedule::test_active_hours
|
||||
|
||||
# Run with Python debugger (pdb)
|
||||
pytest --pdb test/test_display_controller.py::TestDisplayControllerModeRotation::test_basic_rotation
|
||||
pytest --pdb test/test_display_controller.py::TestDisplayControllerSchedule::test_active_hours
|
||||
```
|
||||
|
||||
### Run Tests in Parallel (Faster)
|
||||
|
||||
@@ -0,0 +1,154 @@
|
||||
# Permissions
|
||||
|
||||
Who owns what on an installed system, which privileged commands the web
|
||||
interface may run, and how to repair ownership when it goes wrong. The
|
||||
installer, [`first_time_install.sh`](../first_time_install.sh), sets all of
|
||||
this up; this page describes the result.
|
||||
|
||||
## Users and groups
|
||||
|
||||
| Account | Used by | Why |
|
||||
|---|---|---|
|
||||
| `root` | `ledmatrix.service` (the display) | The LED matrix library needs direct GPIO access |
|
||||
| The installing user (e.g. `ledpi`) | `ledmatrix-web.service`, `ledmatrix-update-verify.service` | A web server should not run as root |
|
||||
| `ledmatrix` group | shared files | Members: the installing user, `root`, and `daemon` if it exists. Created by [`setup_cache.sh`](../scripts/install/setup_cache.sh) and the installer |
|
||||
|
||||
The installer also adds the web user to `systemd-journal` and `adm` so the
|
||||
**Logs** tab can read the journal. Group changes apply after the user logs
|
||||
in again (services pick them up on restart).
|
||||
|
||||
## Files and directories
|
||||
|
||||
| Path | Owner | Mode | Notes |
|
||||
|---|---|---|---|
|
||||
| Project directory | web user | dirs `755`, files `644`, `*.sh` `755` | Set in the installer's "Normalize project file permissions" step |
|
||||
| `config/` | web user | `2775` | |
|
||||
| `config/config.json` | web user | `644` | Written by the web interface |
|
||||
| `config/config_secrets.json` | web user : `ledmatrix` | `640` | Owned by the web user because the web interface writes it; root reads it regardless of mode |
|
||||
| `plugin-repos/`, `plugins/` | web user | dirs `2775`, files `664` | The web interface installs and removes plugins |
|
||||
| `assets/` | web user | dirs `755`, files `644` | Root writes downloaded logos regardless |
|
||||
| `/var/cache/ledmatrix/` | `root:ledmatrix` | `2775` (setgid) | Shared cache: see below |
|
||||
| Cache files | creator : `ledmatrix` | `660` | |
|
||||
| `scripts/fix_perms/safe_plugin_rm.sh`, `safe_pip_install.sh` | `root:root` | `755` | Run as root through sudo, so the web user must not be able to edit them |
|
||||
| `/etc/sudoers.d/ledmatrix_web`, `ledmatrix_wifi` | `root` | `440` | |
|
||||
|
||||
What keeps it that way at runtime:
|
||||
|
||||
- **Config files.** Saves go through
|
||||
[`src/config_manager_atomic.py`](../src/config_manager_atomic.py), which
|
||||
applies `get_config_file_mode()` (`640` for secrets, `644` otherwise) and,
|
||||
when running as root, moves the file's group to the project directory's
|
||||
group (`ensure_shared_group_ownership()` in
|
||||
[`src/common/permission_utils.py`](../src/common/permission_utils.py)).
|
||||
- **Cache files.** [`src/cache/disk_cache.py`](../src/cache/disk_cache.py)
|
||||
sets every file it writes to `0660` and gives it the cache directory's
|
||||
group, without relying on the setgid bit. So a file root writes stays
|
||||
readable by the web user.
|
||||
- **Plugin directories.** [`run.py`](../run.py) sets
|
||||
`sys.dont_write_bytecode`, because root-owned `__pycache__` directories
|
||||
inside a plugin stop the web user updating or removing it.
|
||||
|
||||
`ledmatrix-web.service` deliberately has no `CacheDirectory=`: systemd would
|
||||
re-own `/var/cache/ledmatrix` to the web user and its primary group, and the
|
||||
web interface could no longer read what the display writes (see the comment
|
||||
in [`systemd/ledmatrix-web.service`](../systemd/ledmatrix-web.service)).
|
||||
|
||||
If `/var/cache/ledmatrix` is not usable, `CacheManager` falls back to
|
||||
`~/.ledmatrix_cache`, `/opt/ledmatrix/cache` or a temp directory
|
||||
([`src/cache_manager.py`](../src/cache_manager.py)). The two services then
|
||||
may not share a cache, and the web UI shows stale or empty display status,
|
||||
on-demand state and plugin health. Fix the directory rather than living
|
||||
with the fallback.
|
||||
|
||||
## sudo rules
|
||||
|
||||
### `/etc/sudoers.d/ledmatrix_web`
|
||||
|
||||
Generated by `web_sudoers_rules()` in
|
||||
[`scripts/install/lib_sudoers.sh`](../scripts/install/lib_sudoers.sh), the
|
||||
only place these rules are defined. Installed by the installer and by
|
||||
[`configure_web_sudo.sh`](../scripts/install/configure_web_sudo.sh), both of
|
||||
which check them with `visudo -c` first. The web user may run, without a
|
||||
password:
|
||||
|
||||
- `reboot`, `poweroff`
|
||||
- `systemctl start|stop|restart|enable|disable|status ledmatrix.service`,
|
||||
`systemctl is-active ledmatrix[.service]`
|
||||
- `systemctl start|stop|restart ledmatrix-web.service`
|
||||
- `bash <project>/scripts/fix_perms/safe_plugin_rm.sh *` — removes a
|
||||
directory only if it resolves to a child of `plugin-repos/` or `plugins/`
|
||||
- `bash <project>/scripts/fix_perms/safe_pip_install.sh *` — installs a
|
||||
`requirements.txt` only if it is the project's own or one under
|
||||
`plugin-repos/` or `plugins/`, so the root display service can import the
|
||||
packages
|
||||
- `journalctl -u ledmatrix.service *`, `-u ledmatrix *`, `-t ledmatrix *`,
|
||||
tagged `NOEXEC`: journalctl opens a pager on a terminal, and a shell
|
||||
escape from that pager would be a root shell
|
||||
|
||||
### `/etc/sudoers.d/ledmatrix_wifi`
|
||||
|
||||
Written by
|
||||
[`scripts/install/configure_wifi_permissions.sh`](../scripts/install/configure_wifi_permissions.sh)
|
||||
(run as the web user; the installer calls it). It refuses to grant a binary
|
||||
that is not root-owned or is group/world-writable. The rules cover:
|
||||
|
||||
- `nmcli device wifi connect|disconnect *`, `nmcli device connect|disconnect *`,
|
||||
`nmcli radio wifi on|off`
|
||||
- `systemctl start|stop|restart hostapd`, `... dnsmasq`,
|
||||
`systemctl restart NetworkManager`
|
||||
- `sysctl -w net.ipv4.ip_forward=0|1`
|
||||
- `nft add|delete table ip ledmatrix`
|
||||
- `rfkill unblock wifi`
|
||||
- `mkdir -p /etc/NetworkManager/dnsmasq-shared.d`
|
||||
- `cp` of `/tmp/hostapd.conf` and `/tmp/dnsmasq.conf` to their fixed
|
||||
destinations, and `rm -f /etc/dnsmasq.d/ledmatrix-captive.conf`
|
||||
- `cp /tmp/ledmatrix-nm-dnsmasq.conf` to
|
||||
`/etc/NetworkManager/dnsmasq-shared.d/ledmatrix-captive.conf`, and
|
||||
`rm -f` of that file
|
||||
|
||||
**`iptables` is deliberately not granted.** The captive portal's rules are
|
||||
built from the interface name and port, so a rule covering them would need a
|
||||
trailing wildcard, and `iptables --modprobe=<path>` runs `<path>` as root: a
|
||||
wildcard grant is a root shell for the web user. Doing it safely needs a
|
||||
wrapper script that builds the rules itself, like `safe_plugin_rm.sh`. On a
|
||||
stock Raspberry Pi OS image the default user's blanket `NOPASSWD` rule
|
||||
(`/etc/sudoers.d/010_pi-nopasswd`) hides this gap.
|
||||
|
||||
### polkit
|
||||
|
||||
The same script installs `/etc/polkit-1/rules.d/10-ledmatrix-wifi.rules`,
|
||||
which lets the web user perform any `org.freedesktop.NetworkManager.*`
|
||||
action without authentication.
|
||||
|
||||
## Repair scripts
|
||||
|
||||
In [`scripts/fix_perms/`](../scripts/fix_perms/). Run them from the project
|
||||
directory.
|
||||
|
||||
| Script | Run as | What it does | Notes |
|
||||
|---|---|---|---|
|
||||
| `fix_plugin_permissions.sh` | `sudo` | `plugins/` and `plugin-repos/` to `root:<user>`, dirs `2775`, files `664`; makes a `700` home directory `755` so root can traverse it | Safe. Group-writable, so the web user keeps write access |
|
||||
| `fix_assets_permissions.sh` | `sudo` | `assets/` to `<user>:<group>`, mode `777` recursively | Works, but looser than the installer's `755`/`644` |
|
||||
| `fix_cache_permissions.sh` | `sudo` | Runs [`setup_cache.sh`](../scripts/install/setup_cache.sh) for `/var/cache/ledmatrix` (`root:ledmatrix`, `2775`, files `660`), then makes `~/.ledmatrix_cache` (the fallback cache) `<user>:<group>` mode `777` | Safe. The `~/.ledmatrix_cache` mode is still `777` |
|
||||
| `fix_web_permissions.sh` | the web user, **without** `sudo` | Resets project file ownership for the web user (it calls `sudo` itself), then makes `safe_plugin_rm.sh` and `safe_pip_install.sh` `root:root` `755` again and restores `config_secrets.json` to its owner, group `ledmatrix`, mode `640` | Refuses to run as root. It does not write sudoers rules |
|
||||
| `safe_plugin_rm.sh`, `safe_pip_install.sh` | — | Called by the web interface through sudo | Not for manual use |
|
||||
|
||||
To reinstall the sudoers rules, run
|
||||
`./scripts/install/configure_web_sudo.sh` (web rules) or
|
||||
`./scripts/install/configure_wifi_permissions.sh` (WiFi rules and polkit) as
|
||||
the web user, not with `sudo`.
|
||||
|
||||
After any of these, restart both services:
|
||||
|
||||
```bash
|
||||
sudo systemctl restart ledmatrix.service ledmatrix-web.service
|
||||
```
|
||||
|
||||
## Checking
|
||||
|
||||
```bash
|
||||
ls -ld /var/cache/ledmatrix # drwxrwsr-x root ledmatrix
|
||||
stat -c '%U:%G %a %n' config/config.json config/config_secrets.json
|
||||
id # web user should list ledmatrix
|
||||
sudo -l # lists the NOPASSWD rules
|
||||
```
|
||||
@@ -9,6 +9,7 @@ Complete API reference for plugin developers. This document describes all method
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Manifest Required Fields](#manifest-required-fields)
|
||||
- [BasePlugin](#baseplugin)
|
||||
- [Display Manager](#display-manager)
|
||||
- [Cache Manager](#cache-manager)
|
||||
@@ -17,6 +18,50 @@ Complete API reference for plugin developers. This document describes all method
|
||||
|
||||
---
|
||||
|
||||
## Manifest Required Fields
|
||||
|
||||
Three parts of core check `manifest.json`, each for a different set of
|
||||
fields:
|
||||
|
||||
| Check | Fields | What happens when one is missing |
|
||||
|---|---|---|
|
||||
| JSON schema, [`schema/manifest_schema.json`](../schema/manifest_schema.json) | `id`, `name`, `version`, `author`, `entry_point`, `class_name`, `compatible_versions` | Install from URL logs a warning (`PluginStoreManager._validate_manifest_schema()`); nothing is refused |
|
||||
| Plugin Store install, [`src/plugin_system/store_manager.py`](../src/plugin_system/store_manager.py) | `id`, `name`, `class_name`, `display_modes` | Install is refused. A registry install first tries to detect a missing `class_name` from the entry-point file |
|
||||
| Plugin loader, [`src/plugin_system/plugin_loader.py`](../src/plugin_system/plugin_loader.py) | `class_name` | The plugin fails to load |
|
||||
|
||||
Defaults and other uses:
|
||||
|
||||
- `entry_point` defaults to `manager.py`; the store writes the default back
|
||||
into the manifest on install.
|
||||
- `compatible_versions` (a list of semver ranges such as `">=2.0.0"`) is how
|
||||
the store decides whether a plugin can run on this core. An install is
|
||||
refused only when the field excludes the running version
|
||||
(`compatibility.check()` in
|
||||
[`src/plugin_system/compatibility.py`](../src/plugin_system/compatibility.py)).
|
||||
- `version` is compared with the registry's `latest_version` to decide
|
||||
whether an update is available.
|
||||
- If `display_modes` is empty at load time, the display controller uses the
|
||||
plugin id as the only mode.
|
||||
|
||||
**Set all eight:** `id`, `name`, `version`, `author`, `entry_point`,
|
||||
`class_name`, `display_modes`, `compatible_versions`. That satisfies every
|
||||
check. The schema lists the optional fields.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "my-plugin",
|
||||
"name": "My Plugin",
|
||||
"version": "1.0.0",
|
||||
"author": "YourName",
|
||||
"entry_point": "manager.py",
|
||||
"class_name": "MyPlugin",
|
||||
"display_modes": ["my-plugin"],
|
||||
"compatible_versions": [">=2.0.0"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## BasePlugin
|
||||
|
||||
All plugins must inherit from `BasePlugin` and implement the required methods. The base class provides access to managers and common functionality.
|
||||
@@ -432,82 +477,17 @@ self.display_manager.update_display()
|
||||
|
||||
This is the canonical way to render arbitrary images.
|
||||
|
||||
### Weather Icons
|
||||
### Weather Icons (deprecated)
|
||||
|
||||
#### `draw_weather_icon(condition: str, x: int, y: int, size: int = 16) -> None`
|
||||
> Deprecated, removed in 3.7.0 — draw your own icons (the weather plugin
|
||||
> ships `WeatherIcons`). See [Deprecated APIs](#deprecated-apis).
|
||||
|
||||
Draw a weather icon based on the condition string.
|
||||
|
||||
**Parameters**:
|
||||
- `condition` (str): Weather condition (e.g., "clear", "cloudy", "rain", "snow", "storm")
|
||||
- `x` (int): X position
|
||||
- `y` (int): Y position
|
||||
- `size` (int): Icon size in pixels (default: 16)
|
||||
|
||||
**Supported Conditions**:
|
||||
- `"clear"`, `"sunny"` → Sun icon
|
||||
- `"clouds"`, `"cloudy"`, `"partly cloudy"` → Cloud icon
|
||||
- `"rain"`, `"drizzle"`, `"shower"` → Rain icon
|
||||
- `"snow"`, `"sleet"`, `"hail"` → Snow icon
|
||||
- `"thunderstorm"`, `"storm"` → Storm icon
|
||||
|
||||
**Example**:
|
||||
```python
|
||||
self.display_manager.draw_weather_icon("rain", x=10, y=10, size=16)
|
||||
```
|
||||
|
||||
#### `draw_sun(x: int, y: int, size: int = 16) -> None`
|
||||
|
||||
Draw a sun icon with rays.
|
||||
|
||||
**Parameters**:
|
||||
- `x` (int): X position
|
||||
- `y` (int): Y position
|
||||
- `size` (int): Icon size (default: 16)
|
||||
|
||||
#### `draw_cloud(x: int, y: int, size: int = 16, color: tuple = (200, 200, 200)) -> None`
|
||||
|
||||
Draw a cloud icon.
|
||||
|
||||
**Parameters**:
|
||||
- `x` (int): X position
|
||||
- `y` (int): Y position
|
||||
- `size` (int): Icon size (default: 16)
|
||||
- `color` (tuple): RGB color (default: light gray)
|
||||
|
||||
#### `draw_rain(x: int, y: int, size: int = 16) -> None`
|
||||
|
||||
Draw rain icon with cloud and droplets.
|
||||
|
||||
#### `draw_snow(x: int, y: int, size: int = 16) -> None`
|
||||
|
||||
Draw snow icon with cloud and snowflakes.
|
||||
|
||||
#### `draw_text_with_icons(text: str, icons: List[tuple] = None, x: int = None, y: int = None, color: tuple = (255, 255, 255)) -> None`
|
||||
|
||||
Draw text with weather icons at specified positions.
|
||||
|
||||
**Parameters**:
|
||||
- `text` (str): Text to display
|
||||
- `icons` (List[tuple], optional): List of (icon_type, x, y) tuples
|
||||
- `x` (int, optional): X position for text
|
||||
- `y` (int, optional): Y position for text
|
||||
- `color` (tuple): Text color
|
||||
|
||||
**Note**: Automatically calls `update_display()` after drawing.
|
||||
|
||||
**Example**:
|
||||
```python
|
||||
icons = [
|
||||
("sun", 5, 5),
|
||||
("cloud", 100, 5)
|
||||
]
|
||||
self.display_manager.draw_text_with_icons(
|
||||
"Weather: Sunny, Cloudy",
|
||||
icons=icons,
|
||||
x=10, y=20
|
||||
)
|
||||
```
|
||||
- `draw_weather_icon(condition, x, y, size=16)` — icon for a condition
|
||||
string such as `"clear"`, `"clouds"`, `"rain"`, `"snow"`, `"storm"`
|
||||
- `draw_sun(x, y, size=16)`, `draw_cloud(x, y, size=16, color=(200, 200, 200))`,
|
||||
`draw_rain(x, y, size=16)`, `draw_snow(x, y, size=16)`
|
||||
- `draw_text_with_icons(text, icons=None, x=None, y=None, color=(255, 255, 255))`
|
||||
— text plus a list of `(icon_type, x, y)` icons; calls `update_display()`
|
||||
|
||||
### Scrolling State Management
|
||||
|
||||
@@ -601,6 +581,8 @@ Process any deferred updates if not currently scrolling. Called automatically by
|
||||
|
||||
#### `get_scrolling_stats() -> dict`
|
||||
|
||||
> Deprecated, removed in 3.7.0. See [Deprecated APIs](#deprecated-apis).
|
||||
|
||||
Get current scrolling statistics for debugging.
|
||||
|
||||
**Returns**: Dictionary with scrolling state information
|
||||
@@ -742,6 +724,8 @@ data = self.cache_manager.get_with_auto_strategy("nhl_live_scores")
|
||||
|
||||
#### `get_background_cached_data(key: str, sport_key: Optional[str] = None) -> Optional[Dict[str, Any]]`
|
||||
|
||||
> Deprecated, removed in 3.7.0 — use `get()`. See [Deprecated APIs](#deprecated-apis).
|
||||
|
||||
Get background service cached data with sport-specific intervals.
|
||||
|
||||
**Parameters**:
|
||||
@@ -779,6 +763,8 @@ max_age = strategy['max_age'] # Get configured max age
|
||||
|
||||
#### `get_sport_live_interval(sport_key: str) -> int`
|
||||
|
||||
> Deprecated, removed in 3.7.0. See [Deprecated APIs](#deprecated-apis).
|
||||
|
||||
Get the live_update_interval for a specific sport from config.
|
||||
|
||||
**Parameters**:
|
||||
@@ -803,6 +789,8 @@ Extract data type from cache key to determine appropriate cache strategy.
|
||||
|
||||
#### `get_sport_key_from_cache_key(key: str) -> Optional[str]`
|
||||
|
||||
> Deprecated, removed in 3.7.0. See [Deprecated APIs](#deprecated-apis).
|
||||
|
||||
Extract sport key from cache key for sport-specific strategies.
|
||||
|
||||
**Parameters**:
|
||||
@@ -847,10 +835,12 @@ for file_info in files:
|
||||
self.logger.info(f"Cache: {file_info['key']}, Age: {file_info['age_display']}")
|
||||
```
|
||||
|
||||
### Metrics Methods
|
||||
### Metrics Methods (deprecated)
|
||||
|
||||
#### `get_cache_metrics() -> Dict[str, Any]`
|
||||
|
||||
> Deprecated, removed in 3.7.0. See [Deprecated APIs](#deprecated-apis).
|
||||
|
||||
Get cache performance metrics.
|
||||
|
||||
**Returns**: Dictionary with cache statistics (`total_requests`, `cache_hit_rate`, `background_hit_rate`, `api_calls_saved`, `average_fetch_time`, etc.)
|
||||
@@ -863,6 +853,8 @@ self.logger.info(f"Cache hit rate: {metrics['cache_hit_rate']:.2%}")
|
||||
|
||||
#### `get_memory_cache_stats() -> Dict[str, Any]`
|
||||
|
||||
> Deprecated, removed in 3.7.0. See [Deprecated APIs](#deprecated-apis).
|
||||
|
||||
Get memory cache statistics.
|
||||
|
||||
**Returns**: Dictionary with memory cache stats (size, max_size, etc.)
|
||||
@@ -907,6 +899,8 @@ for plugin_id, plugin in all_plugins.items():
|
||||
|
||||
#### `get_enabled_plugins() -> List[str]`
|
||||
|
||||
> Deprecated, removed in 3.7.0 — check `enabled` on the instances in `plugin_manager.plugins`. See [Deprecated APIs](#deprecated-apis).
|
||||
|
||||
Get list of enabled plugin IDs.
|
||||
|
||||
**Returns**: List of plugin identifier strings
|
||||
@@ -985,9 +979,8 @@ def update(self):
|
||||
|
||||
**Example - Checking if another plugin is enabled**:
|
||||
```python
|
||||
enabled_plugins = self.plugin_manager.get_enabled_plugins()
|
||||
if "weather" in enabled_plugins:
|
||||
# Weather plugin is enabled
|
||||
weather = self.plugin_manager.plugins.get("weather")
|
||||
if weather is not None and weather.enabled:
|
||||
pass
|
||||
```
|
||||
|
||||
|
||||
@@ -155,9 +155,9 @@ deep-merged back into the plugin's config at load time
|
||||
### Custom input widgets
|
||||
|
||||
Set `"x-widget": "<name>"` on a property. Core widgets are in
|
||||
`web_interface/static/v3/js/widgets/` (see its README); a plugin can ship its
|
||||
own widget script, served from `/static/plugin-widgets/<plugin_id>/<name>.js`.
|
||||
See [widget-guide.md](widget-guide.md).
|
||||
`web_interface/static/v3/js/widgets/`; a plugin can ship its own widget
|
||||
script, served from `/static/plugin-widgets/<plugin_id>/<name>.js`. See the
|
||||
[widget guide](../web_interface/static/v3/js/widgets/README.md).
|
||||
|
||||
### Custom actions
|
||||
|
||||
|
||||
@@ -520,19 +520,22 @@ When developing plugins, you'll need to use the APIs provided by the LEDMatrix s
|
||||
`display_manager.image` (a PIL Image) and call `update_display()`;
|
||||
there is no `draw_image()` helper method.
|
||||
- `draw_weather_icon()`, `draw_sun()`, `draw_cloud()` - Weather icons
|
||||
(deprecated, removed in 3.7.0 — draw your own icons)
|
||||
- `get_text_width()`, `get_font_height()` - Text utilities
|
||||
- `set_scrolling_state()`, `defer_update()` - Scrolling state management
|
||||
|
||||
**Cache Manager** (`self.cache_manager`):
|
||||
- `get()`, `set()`, `delete()` - Basic caching
|
||||
- `get_cached_data_with_strategy()` - Advanced caching with strategies
|
||||
- `get_background_cached_data()` - Background service caching
|
||||
- `get_background_cached_data()` - deprecated, removed in 3.7.0 — use `get()`
|
||||
|
||||
**Plugin Manager** (`self.plugin_manager`):
|
||||
- `get_plugin()`, `get_all_plugins()` - Access other plugins
|
||||
- `get_plugin_info()` - Get plugin information
|
||||
|
||||
See [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) for complete documentation.
|
||||
See [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) for complete
|
||||
documentation, and its [Deprecated APIs](PLUGIN_API_REFERENCE.md#deprecated-apis)
|
||||
table for everything removed in 3.7.0.
|
||||
|
||||
## 3rd Party Plugin Development
|
||||
|
||||
@@ -577,12 +580,14 @@ Your plugin must:
|
||||
pass
|
||||
```
|
||||
|
||||
2. **Include manifest.json** with required fields:
|
||||
2. **Include manifest.json** with the required fields listed in
|
||||
[PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md#manifest-required-fields):
|
||||
```json
|
||||
{
|
||||
"id": "my-plugin",
|
||||
"name": "My Plugin",
|
||||
"version": "1.0.0",
|
||||
"author": "YourName",
|
||||
"class_name": "MyPlugin",
|
||||
"entry_point": "manager.py",
|
||||
"display_modes": ["my_plugin"],
|
||||
@@ -658,7 +663,7 @@ For your plugin to work well in the plugin store:
|
||||
with the registry's `latest_version`; releases and tags are not read
|
||||
- **README.md**: Clear installation and configuration instructions
|
||||
- **config_schema.json**: Recommended for web UI configuration
|
||||
- **manifest.json**: Required with all required fields
|
||||
- **manifest.json**: Required, with the [required fields](PLUGIN_API_REFERENCE.md#manifest-required-fields)
|
||||
- **requirements.txt**: If your plugin has Python dependencies
|
||||
|
||||
### Distribution Options
|
||||
|
||||
@@ -45,7 +45,8 @@ LEDMatrix/
|
||||
|
||||
### 1. Minimal Plugin Structure
|
||||
|
||||
**manifest.json**:
|
||||
**manifest.json** (the required fields are explained in
|
||||
[PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md#manifest-required-fields)):
|
||||
```json
|
||||
{
|
||||
"id": "my-plugin",
|
||||
@@ -54,6 +55,8 @@ LEDMatrix/
|
||||
"author": "YourName",
|
||||
"entry_point": "manager.py",
|
||||
"class_name": "MyPlugin",
|
||||
"display_modes": ["my-plugin"],
|
||||
"compatible_versions": [">=2.0.0"],
|
||||
"category": "custom"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -67,9 +67,9 @@ Don't edit `latest_version` or `last_updated` by hand for monorepo plugins:
|
||||
|
||||
## Adding or changing an official plugin
|
||||
|
||||
1. Add or edit `plugins/<your-plugin-id>/` in the monorepo. The store refuses
|
||||
a manifest without `id`, `name`, `class_name` and `display_modes`; also
|
||||
set `version`.
|
||||
1. Add or edit `plugins/<your-plugin-id>/` in the monorepo, with the
|
||||
manifest fields listed in
|
||||
[PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md#manifest-required-fields).
|
||||
2. Bump `version` in the plugin's `manifest.json` for every change, or users
|
||||
won't be offered the update.
|
||||
3. Run `python update_registry.py` in ledmatrix-plugins and commit the
|
||||
|
||||
+7
-3
@@ -11,7 +11,7 @@ the one-shot installer. The pages here go deeper.
|
||||
2. [WEB_INTERFACE_GUIDE.md](WEB_INTERFACE_GUIDE.md) — using the web UI
|
||||
3. [PLUGIN_STORE_GUIDE.md](PLUGIN_STORE_GUIDE.md) — installing and managing plugins
|
||||
4. [WIFI_NETWORK_SETUP.md](WIFI_NETWORK_SETUP.md) — WiFi and AP-mode setup
|
||||
5. [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — common issues and fixes
|
||||
5. [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — common issues and fixes ([PERMISSIONS.md](PERMISSIONS.md) for "Permission denied")
|
||||
6. [SSH_UNAVAILABLE_AFTER_INSTALL.md](SSH_UNAVAILABLE_AFTER_INSTALL.md) — recovering SSH after install
|
||||
7. [CONFIG_DEBUGGING.md](CONFIG_DEBUGGING.md) — diagnosing config problems
|
||||
8. [LOW_MEMORY_BOARDS.md](LOW_MEMORY_BOARDS.md) — Pi Zero 2 W / 3B+ / 1GB Pi 4 memory limits
|
||||
@@ -37,7 +37,7 @@ Going deeper:
|
||||
- [PLUGIN_CUSTOM_ICONS.md](PLUGIN_CUSTOM_ICONS.md)
|
||||
- [PLUGIN_REGISTRY_SETUP_GUIDE.md](PLUGIN_REGISTRY_SETUP_GUIDE.md) (+ [registry template](plugin_registry_template.json))
|
||||
- [STARLARK_APPS_GUIDE.md](STARLARK_APPS_GUIDE.md) — Starlark-based mini-apps
|
||||
- [widget-guide.md](widget-guide.md) — widget development
|
||||
- [Widget guide](../web_interface/static/v3/js/widgets/README.md) — built-in `x-widget`s and custom widgets
|
||||
- [ADAPTIVE_LAYOUT.md](ADAPTIVE_LAYOUT.md) — render legibly on any panel size (opt-in font/layout scaling)
|
||||
- [plugin-safety-harness.md](plugin-safety-harness.md) — test a plugin across every screen and matrix size
|
||||
|
||||
@@ -56,21 +56,25 @@ Going deeper:
|
||||
- [ADVANCED_FEATURES.md](ADVANCED_FEATURES.md) — Vegas scroll, on-demand display,
|
||||
cache management, background services, permissions
|
||||
- [FONT_MANAGER.md](FONT_MANAGER.md) — font system
|
||||
- [PERMISSIONS.md](PERMISSIONS.md) — file ownership, sudo rules, repair scripts
|
||||
- [MQTT bridge](../integrations/mqtt_bridge/README.md) — control the display from Home Assistant over MQTT
|
||||
|
||||
## Reference
|
||||
|
||||
- [CONFIG_REFERENCE.md](CONFIG_REFERENCE.md) — every key in config.json and config_secrets.json
|
||||
- [REST_API_REFERENCE.md](REST_API_REFERENCE.md) — all web-interface HTTP endpoints
|
||||
- [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) — Python APIs available to plugins
|
||||
- [src/common/README.md](../src/common/README.md) — shared helper modules plugins can import
|
||||
- [DEVELOPER_QUICK_REFERENCE.md](DEVELOPER_QUICK_REFERENCE.md) — common dev tasks
|
||||
|
||||
## Contributing to LEDMatrix itself
|
||||
|
||||
- [ARCHITECTURE.md](ARCHITECTURE.md) — processes, display loop, plugin system, web UI; where to start reading
|
||||
- [DEVELOPMENT.md](DEVELOPMENT.md) — environment setup
|
||||
- [HOW_TO_RUN_TESTS.md](HOW_TO_RUN_TESTS.md) — running the test suite
|
||||
- [MULTI_ROOT_WORKSPACE_SETUP.md](MULTI_ROOT_WORKSPACE_SETUP.md) — multi-repo workspace
|
||||
- [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) — breaking changes between releases
|
||||
- [SPORTS_UNIFICATION.md](SPORTS_UNIFICATION.md) — how the sports scoreboard base classes are organized
|
||||
- [SPORTS_UNIFICATION.md](SPORTS_UNIFICATION.md) — how shared sports scoreboard code moves into `src/common`
|
||||
|
||||
## Audits
|
||||
|
||||
|
||||
@@ -73,14 +73,16 @@ B2 below promoted code into it (`SportsCore`, the mode classes,
|
||||
capabilities sections record that design, but none of it ships in core any
|
||||
more. Shared sports code lives in `src/common`:
|
||||
|
||||
```
|
||||
src/common/
|
||||
sports_scroll.py SportsScrollDisplay / …Manager — scroll orchestration
|
||||
(content building stays in the plugins)
|
||||
sports_helpers.py clamp/logo/rotation free functions + SportsHelpersMixin
|
||||
(3.5.0) — the helpers byte-identical in the
|
||||
plugins' sports.py, and the _favorite_key seam
|
||||
```
|
||||
| Module | Since | Holds |
|
||||
|---|---|---|
|
||||
| `sports_scroll.py` | 3.2.0 | `SportsScrollDisplay` / `SportsScrollDisplayManager` — scroll orchestration (content building stays in the plugins) |
|
||||
| `sports_card.py` | 3.3.0 | Free functions for card settings, colours, favourite-team rules, dates and font sizes |
|
||||
| `sports_game_renderer.py` | 3.3.0 | `SportsGameRendererMixin` — scroll/Vegas card geometry |
|
||||
| `sports_shared.py` | 3.3.0 | `SportsCoreSharedMixin`, `SportsLiveSharedMixin`, `SportsRecentSharedMixin` — the sport-independent `sports.py` methods |
|
||||
| `sports_helpers.py` | 3.5.0 | clamp/logo/rotation free functions and `SportsHelpersMixin`, plus the `_favorite_key` seam |
|
||||
| `espn_dates.py` | 3.5.0 | ESPN date-range and `limit` workarounds |
|
||||
|
||||
Each is described in [src/common/README.md](../src/common/README.md).
|
||||
|
||||
### Converging on `src/common`
|
||||
|
||||
@@ -90,7 +92,7 @@ modules taken from the plugin copies, each a **new module** rather than growth
|
||||
on an existing one: a plugin that deletes a method copy and relies on an older
|
||||
module having gained it fails at runtime with an `AttributeError`, while a
|
||||
missing module fails at load, where the version checks can see it.
|
||||
`sports_helpers.py` is the first (it holds `_favorite_key`, the override point
|
||||
`sports_helpers.py` is the newest (it holds `_favorite_key`, the override point
|
||||
listed below, for later phases); its parity test compares every body against
|
||||
the plugin copies when `LEDMATRIX_PLUGINS` points at a checkout, and
|
||||
`test/test_common_is_hardware_free.py` keeps `src/common` free of
|
||||
|
||||
@@ -102,9 +102,16 @@ cd /path/to/LEDMatrix
|
||||
bash scripts/download_pixlet.sh
|
||||
```
|
||||
|
||||
The script downloads only the Linux ARM64 build (Raspberry Pi OS 64-bit),
|
||||
from the `tronbyt/pixlet` releases, to `bin/pixlet/pixlet-linux-arm64`. On
|
||||
any other platform (32-bit Pi OS, x86_64, macOS), put a `pixlet` binary on
|
||||
your `PATH`, or set the plugin's `pixlet_path`, or place it in `bin/pixlet/`
|
||||
under the name `_find_pixlet_binary()` looks for
|
||||
([`web_interface/blueprints/api_v3/__init__.py`](../web_interface/blueprints/api_v3/__init__.py)).
|
||||
|
||||
Verify installation:
|
||||
```bash
|
||||
./bin/pixlet/pixlet-linux-amd64 version
|
||||
./bin/pixlet/pixlet-linux-arm64 version
|
||||
# Pixlet 0.50.2 (or later)
|
||||
```
|
||||
|
||||
@@ -276,10 +283,8 @@ LEDMatrix/
|
||||
│ ├── hour_hand.png
|
||||
│ └── minute_hand.png
|
||||
│
|
||||
├── bin/pixlet/ # Pixlet binaries
|
||||
│ ├── pixlet-linux-amd64
|
||||
│ ├── pixlet-linux-arm64
|
||||
│ └── pixlet-darwin-arm64
|
||||
├── bin/pixlet/ # Pixlet binary
|
||||
│ └── pixlet-linux-arm64 # the only one download_pixlet.sh fetches
|
||||
│
|
||||
└── scripts/
|
||||
└── download_pixlet.sh # Pixlet installer
|
||||
@@ -324,7 +329,7 @@ Many apps require API keys for external services:
|
||||
**Solutions**:
|
||||
1. Check logs: `journalctl -u ledmatrix | grep -i pixlet`
|
||||
2. Verify config: Ensure all required fields are filled
|
||||
3. Test manually: `./bin/pixlet/pixlet-linux-amd64 render starlark-apps/{app-id}/{app-id}.star`
|
||||
3. Test manually: `./bin/pixlet/pixlet-linux-arm64 render starlark-apps/{app-id}/{app-id}.star`
|
||||
4. Missing assets: Some apps need images/fonts that may fail to download
|
||||
5. API issues: Check API keys and rate limits
|
||||
|
||||
|
||||
+32
-27
@@ -201,10 +201,11 @@ sudo systemctl restart ledmatrix-web
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Install dependencies:**
|
||||
1. **Install dependencies** as root, so the root display service can import
|
||||
them:
|
||||
```bash
|
||||
pip3 install --break-system-packages -r requirements.txt
|
||||
pip3 install --break-system-packages -r web_interface/requirements.txt
|
||||
sudo python3 -m pip install --break-system-packages --no-cache-dir -r requirements.txt
|
||||
sudo python3 -m pip install --break-system-packages --no-cache-dir -r web_interface/requirements.txt
|
||||
```
|
||||
|
||||
2. **Test imports step-by-step:**
|
||||
@@ -250,15 +251,18 @@ sudo systemctl restart ledmatrix-web
|
||||
|
||||
**Solutions:**
|
||||
|
||||
```bash
|
||||
# Fix ownership of LEDMatrix directory
|
||||
sudo chown -R ledpi:ledpi /home/ledpi/LEDMatrix
|
||||
[PERMISSIONS.md](PERMISSIONS.md) lists the expected owner and mode of every
|
||||
file and directory, and which `scripts/fix_perms/` script to run as which
|
||||
user. Don't `chown -R` the whole project: the two sudo helper scripts in
|
||||
`scripts/fix_perms/` must stay owned by root.
|
||||
|
||||
# Fix config file permissions
|
||||
```bash
|
||||
# Config files: web user owns both; secrets must stay 640
|
||||
stat -c '%U:%G %a %n' config/config.json config/config_secrets.json
|
||||
sudo chmod 644 config/config.json
|
||||
sudo chmod 640 config/config_secrets.json
|
||||
|
||||
# Verify service runs as correct user
|
||||
# Which user the web interface runs as
|
||||
sudo systemctl cat ledmatrix-web | grep User
|
||||
```
|
||||
|
||||
@@ -462,15 +466,17 @@ sudo systemctl cat ledmatrix-web | grep User
|
||||
}
|
||||
```
|
||||
|
||||
2. **Restart display:**
|
||||
```bash
|
||||
sudo systemctl restart ledmatrix
|
||||
```
|
||||
Or toggle the plugin on in the **Plugin Manager** tab, which writes the
|
||||
same flag.
|
||||
|
||||
3. **Verify in web interface:**
|
||||
- Open the **Plugin Manager** tab
|
||||
- Toggle the plugin switch to enable
|
||||
- From **Overview**, click **Restart Display Service**
|
||||
2. **Wait a few seconds.** The display service watches `config.json` and
|
||||
loads a newly enabled plugin without a restart
|
||||
(`DisplayController._reconcile_enabled_plugins()` in
|
||||
[`src/display_controller.py`](../src/display_controller.py)). This
|
||||
needs hot reload, which is on unless `LEDMATRIX_HOT_RELOAD=false` is set.
|
||||
|
||||
3. **If it still does not appear**, check the logs for a config validation
|
||||
error, then restart: `sudo systemctl restart ledmatrix`
|
||||
|
||||
#### Plugin Not Loading
|
||||
|
||||
@@ -491,10 +497,12 @@ sudo systemctl cat ledmatrix-web | grep User
|
||||
# Verify all required fields present
|
||||
```
|
||||
|
||||
3. **Check dependencies installed:**
|
||||
3. **Check dependencies installed.** Install them with `sudo`: the display
|
||||
service runs as root and does not see packages pip put in your user's
|
||||
`~/.local` (see [PLUGIN_DEPENDENCY_GUIDE.md](PLUGIN_DEPENDENCY_GUIDE.md)):
|
||||
```bash
|
||||
if [ -f plugin-repos/plugin-id/requirements.txt ]; then
|
||||
pip3 install --break-system-packages -r plugin-repos/plugin-id/requirements.txt
|
||||
sudo python3 -m pip install --break-system-packages --no-cache-dir -r plugin-repos/plugin-id/requirements.txt
|
||||
fi
|
||||
```
|
||||
|
||||
@@ -503,14 +511,9 @@ sudo systemctl cat ledmatrix-web | grep User
|
||||
sudo journalctl -u ledmatrix -f | grep plugin-id
|
||||
```
|
||||
|
||||
5. **Test plugin import:**
|
||||
5. **Load and render the plugin headlessly:**
|
||||
```bash
|
||||
python3 -c "
|
||||
import sys
|
||||
sys.path.insert(0, 'plugin-repos/plugin-id')
|
||||
from manager import PluginClass
|
||||
print('Plugin imports successfully')
|
||||
"
|
||||
python3 scripts/check_plugin.py --plugin plugin-id
|
||||
```
|
||||
|
||||
#### Stale Cache Data
|
||||
@@ -540,10 +543,12 @@ sudo systemctl cat ledmatrix-web | grep User
|
||||
sudo systemctl restart ledmatrix
|
||||
```
|
||||
|
||||
2. **Check cache permissions:**
|
||||
2. **Check cache permissions.** Expected: `root:ledmatrix`, `drwxrwsr-x`.
|
||||
`setup_cache.sh` restores that layout (see
|
||||
[PERMISSIONS.md](PERMISSIONS.md#repair-scripts)):
|
||||
```bash
|
||||
ls -ld /var/cache/ledmatrix
|
||||
sudo ./scripts/fix_perms/fix_cache_permissions.sh
|
||||
sudo bash scripts/install/setup_cache.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -161,7 +161,11 @@ duration, and related settings — so you can configure Vegas mode
|
||||
entirely from the web UI without hand-editing JSON. See
|
||||
[ADVANCED_FEATURES.md](ADVANCED_FEATURES.md) for what the options do.
|
||||
|
||||
Changes require **Restart Display Service** from the Overview tab.
|
||||
Brightness and the Vegas Scroll settings apply to the running display
|
||||
within a few seconds. Matrix hardware settings (rows, columns, chain length,
|
||||
mapping, GPIO slowdown, PWM and refresh settings) are only read when the
|
||||
display starts, so those need **Restart Display Service** from the Overview
|
||||
tab.
|
||||
|
||||
### Plugin Manager Tab
|
||||
|
||||
@@ -248,16 +252,16 @@ View real-time system logs:
|
||||
|
||||
1. Open the **Display** tab
|
||||
2. Adjust the **Brightness** slider (1–100)
|
||||
3. Click **Save**
|
||||
4. Click **Restart Display Service** on the **Overview** tab
|
||||
3. Click **Save**. The panel picks up the new brightness within a few
|
||||
seconds; no restart is needed
|
||||
|
||||
### Installing a New Plugin
|
||||
|
||||
1. Open the **Plugin Manager** tab
|
||||
2. Scroll to the **Plugin Store** section and browse or search
|
||||
3. Click **Install** next to the plugin
|
||||
4. Toggle the plugin on in **Installed Plugins**
|
||||
5. Click **Restart Display Service** on **Overview**
|
||||
4. Toggle the plugin on in **Installed Plugins**. The running display
|
||||
loads it within a few seconds; no restart is needed
|
||||
|
||||
### Configuring a Plugin
|
||||
|
||||
|
||||
+5
-588
@@ -1,590 +1,7 @@
|
||||
# Widget Development Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The LEDMatrix Widget Registry system allows plugins to use reusable UI components for configuration forms. This enables:
|
||||
|
||||
- **Reusable Components**: Use existing widgets (file upload, checkboxes, etc.) without custom code
|
||||
- **Custom Widgets**: Create plugin-specific widgets without modifying the LEDMatrix codebase
|
||||
- **Backwards Compatibility**: Existing plugins continue to work without changes
|
||||
|
||||
## Available Core Widgets
|
||||
|
||||
### Plugin File Manager Widget (`plugin-file-manager`)
|
||||
|
||||
Full inline file management UI for plugins that manage files via the `web_ui_actions` system. Renders a card grid, upload zone, create/delete modals, and an entry table editor — entirely inline, no iframe.
|
||||
|
||||
`plugin_id` is **automatically injected** from template context. File operations call `/api/v3/plugins/action` immediately on user action; no Save Configuration needed.
|
||||
|
||||
**Schema Configuration:**
|
||||
```json
|
||||
{
|
||||
"file_manager": {
|
||||
"type": "null",
|
||||
"title": "Data Files",
|
||||
"x-widget": "plugin-file-manager",
|
||||
"x-widget-config": {
|
||||
"actions": {
|
||||
"list": "list-files",
|
||||
"get": "get-file",
|
||||
"save": "save-file",
|
||||
"upload": "upload-file",
|
||||
"delete": "delete-file",
|
||||
"create": "create-file",
|
||||
"toggle": "toggle-category"
|
||||
},
|
||||
"upload_hint": "JSON files with day numbers 1–365 as keys",
|
||||
"directory_label": "my_data/",
|
||||
"create_fields": [
|
||||
{ "key": "category_name", "label": "Category Name",
|
||||
"placeholder": "e.g., my_words", "pattern": "^[a-z0-9_]+$",
|
||||
"hint": "Lowercase letters, numbers, underscores" },
|
||||
{ "key": "display_name", "label": "Display Name",
|
||||
"placeholder": "e.g., My Words", "hint": "Optional" }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**`list` is required** — the widget calls it on render to populate the file grid; omitting it leaves the widget stuck in a loading state. All other actions are optional — omit any key to hide its UI element (e.g., no `create` = no New File button, no `toggle` = no enable/disable switch).
|
||||
|
||||
The edit view auto-detects whether file content is tabular (object-of-objects with uniform keys) and shows a paginated table editor with inline cells. Otherwise falls back to a JSON textarea.
|
||||
|
||||
**Used by:** of-the-day
|
||||
|
||||
---
|
||||
|
||||
### Time Picker Widget (`time-picker`)
|
||||
|
||||
Single time selection using the browser's native time input. Returns a string in `HH:MM` (24-hour) format. Generic — works in any plugin without configuration.
|
||||
|
||||
**Schema Configuration:**
|
||||
```json
|
||||
{
|
||||
"target_time": {
|
||||
"type": "string",
|
||||
"x-widget": "time-picker",
|
||||
"default": "00:00",
|
||||
"x-options": {
|
||||
"placeholder": "Select time",
|
||||
"clearable": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Used by:** countdown
|
||||
|
||||
---
|
||||
|
||||
### File Upload Single Widget (`file-upload-single`)
|
||||
|
||||
Single-image upload for string fields. Uploads to the plugin's asset folder (`assets/plugins/<plugin_id>/uploads/`) and sets the string field value to the returned relative path. Shows a thumbnail preview and a clear button. The `plugin_id` is **automatically injected** from the template context — no need to specify it in the schema.
|
||||
|
||||
**Schema Configuration:**
|
||||
```json
|
||||
{
|
||||
"image_path": {
|
||||
"type": "string",
|
||||
"x-widget": "file-upload-single",
|
||||
"x-upload-config": {
|
||||
"allowed_types": ["image/png", "image/jpeg", "image/bmp", "image/gif"],
|
||||
"max_size_mb": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Note: Unlike `file-upload` (array-level), this widget is for a single `string` field. It is ideal for per-item images inside `array-table` rows.
|
||||
|
||||
**Used by:** countdown
|
||||
|
||||
---
|
||||
|
||||
### File Upload Widget (`file-upload`)
|
||||
|
||||
Upload and manage image files with drag-and-drop support, preview, delete, and scheduling.
|
||||
|
||||
**Schema Configuration:**
|
||||
```json
|
||||
{
|
||||
"type": "array",
|
||||
"x-widget": "file-upload",
|
||||
"x-upload-config": {
|
||||
"plugin_id": "my-plugin",
|
||||
"max_files": 10,
|
||||
"max_size_mb": 5,
|
||||
"allowed_types": ["image/png", "image/jpeg", "image/bmp", "image/gif"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Used by:** static-image, news plugins
|
||||
|
||||
### Checkbox Group Widget (`checkbox-group`)
|
||||
|
||||
Multi-select checkboxes for array fields with enum items.
|
||||
|
||||
**Schema Configuration:**
|
||||
```json
|
||||
{
|
||||
"type": "array",
|
||||
"x-widget": "checkbox-group",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"enum": ["option1", "option2", "option3"]
|
||||
},
|
||||
"x-options": {
|
||||
"labels": {
|
||||
"option1": "Option 1 Label",
|
||||
"option2": "Option 2 Label"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Used by:** odds-ticker, news plugins
|
||||
|
||||
### Custom Feeds Widget (`custom-feeds`)
|
||||
|
||||
Table-based RSS feed editor with logo uploads.
|
||||
|
||||
**Schema Configuration:**
|
||||
```json
|
||||
{
|
||||
"type": "array",
|
||||
"x-widget": "custom-feeds",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": { "type": "string" },
|
||||
"url": { "type": "string", "format": "uri" },
|
||||
"enabled": { "type": "boolean" },
|
||||
"logo": { "type": "object" }
|
||||
}
|
||||
},
|
||||
"maxItems": 50
|
||||
}
|
||||
```
|
||||
|
||||
**Used by:** news plugin (for custom RSS feeds)
|
||||
|
||||
## Using Existing Widgets
|
||||
|
||||
To use an existing widget in your plugin's `config_schema.json`, simply add the `x-widget` property:
|
||||
|
||||
```json
|
||||
{
|
||||
"properties": {
|
||||
"my_images": {
|
||||
"type": "array",
|
||||
"x-widget": "file-upload",
|
||||
"x-upload-config": {
|
||||
"plugin_id": "my-plugin",
|
||||
"max_files": 5
|
||||
}
|
||||
},
|
||||
"enabled_leagues": {
|
||||
"type": "array",
|
||||
"x-widget": "checkbox-group",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"enum": ["nfl", "nba", "mlb"]
|
||||
},
|
||||
"x-options": {
|
||||
"labels": {
|
||||
"nfl": "NFL",
|
||||
"nba": "NBA",
|
||||
"mlb": "MLB"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The widget will be automatically rendered when the plugin configuration form is loaded.
|
||||
|
||||
## Labelling Enum Options (`x-options.labels`)
|
||||
|
||||
A plain `enum` renders as a dropdown whose option text is the value with
|
||||
underscores replaced and title case applied — `day_first` becomes "Day First".
|
||||
That is fine for values that read as their own label, and wrong for values that
|
||||
do not: `vs` becomes "Vs", and `abbrev` says nothing about the `Sep 19` it
|
||||
actually produces.
|
||||
|
||||
Supply `x-options.labels` to set the visible text. This is the same convention
|
||||
the `checkbox-group` widget uses:
|
||||
|
||||
```json
|
||||
{
|
||||
"date_format": {
|
||||
"type": "string",
|
||||
"enum": ["abbrev", "numeric", "day_first"],
|
||||
"default": "abbrev",
|
||||
"x-options": {
|
||||
"labels": {
|
||||
"abbrev": "Sep 19",
|
||||
"numeric": "9/19",
|
||||
"day_first": "19 Sep"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Labels are **display only** — the stored value is still the enum value, so
|
||||
adding them never changes a saved config. The map may be partial: any value
|
||||
without a label keeps the humanised fallback. Older cores that predate this
|
||||
support ignore `x-options` and render the fallback for every option, so a
|
||||
plugin can ship labels without requiring a core upgrade.
|
||||
|
||||
Array-table columns (`x-widget: array-table`) accept the same
|
||||
`x-options.labels` on a column definition, but their fallback is the **raw
|
||||
value** rather than the humanised one, because those columns hold values such
|
||||
as ticker symbols where `aapl` → "Aapl" would be wrong. Rows added in the
|
||||
browser use the labels too (`array-table.js`), so a column reads the same
|
||||
before and after a page reload.
|
||||
|
||||
## Marking Fields as Advanced (`x-advanced`)
|
||||
|
||||
Add `"x-advanced": true` to any top-level, non-object property to move it out
|
||||
of the main form and into a single collapsed **Advanced Settings** section at
|
||||
the bottom of the plugin's configuration page:
|
||||
|
||||
```json
|
||||
{
|
||||
"properties": {
|
||||
"city": {
|
||||
"type": "string",
|
||||
"title": "City"
|
||||
},
|
||||
"request_timeout": {
|
||||
"type": "integer",
|
||||
"default": 10,
|
||||
"description": "HTTP timeout in seconds",
|
||||
"x-advanced": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Guidelines:
|
||||
|
||||
- Use it for fine-tuning knobs most users never touch (timeouts, retry
|
||||
behavior, cache TTLs, styling overrides). Anything a first-time user must
|
||||
set to get the plugin working should stay basic.
|
||||
- Nothing is hidden permanently — the section expands on click, and the
|
||||
settings search finds and auto-expands advanced fields like any others.
|
||||
- The flag is ignored on `object`-type properties (they already render as
|
||||
their own collapsible sections) and is safely ignored by older cores, so
|
||||
adding it never breaks compatibility.
|
||||
|
||||
## Hiding Fields From the Form (`x-display: "hidden"`)
|
||||
|
||||
Add `"x-display": "hidden"` to a property that must stay in the schema but
|
||||
should not appear as a control: a deprecated key kept so existing configs keep
|
||||
validating, or an internal value such as an auto-generated row id.
|
||||
|
||||
```json
|
||||
{
|
||||
"properties": {
|
||||
"radar_zoom": {
|
||||
"type": "integer",
|
||||
"default": 6,
|
||||
"title": "Radar Zoom Level (deprecated)",
|
||||
"x-display": "hidden"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
What the core does with it:
|
||||
|
||||
- **Not rendered** at any depth: top-level fields, children of an object
|
||||
section, and properties of array-of-object items (never a table column, even
|
||||
if `x-columns` names it, and never in the row editor). A hidden field flagged
|
||||
`x-advanced` is not listed or counted in Advanced Settings, and an object
|
||||
whose children are all hidden draws no empty section. Hidden fields don't
|
||||
show up in the settings search either, since it indexes the rendered form.
|
||||
- **Stored value preserved on save.** Saving the form never changes a hidden
|
||||
value. The unchecked-checkbox rule ignores a hidden boolean. Array rows carry
|
||||
a hidden property's stored value through the form, so the value survives the
|
||||
row being posted back; a new row gets no value (the plugin fills it in).
|
||||
- **The API is unaffected.** A JSON save to `POST /api/v3/plugins/config` can
|
||||
still set a hidden field.
|
||||
|
||||
Older cores ignore the flag and render the field as a normal control.
|
||||
|
||||
## Creating Custom Widgets
|
||||
|
||||
### Step 1: Create Widget File
|
||||
|
||||
Create a JavaScript file in your plugin's `widgets/` directory, named
|
||||
`widgets/[widget-name].js`. The directory is not optional: it is the only
|
||||
place the core will serve a widget from.
|
||||
|
||||
```javascript
|
||||
// Ensure LEDMatrixWidgets registry is available
|
||||
if (typeof window.LEDMatrixWidgets === 'undefined') {
|
||||
console.error('LEDMatrixWidgets registry not found');
|
||||
return;
|
||||
}
|
||||
|
||||
// Register your widget
|
||||
window.LEDMatrixWidgets.register('my-custom-widget', {
|
||||
name: 'My Custom Widget',
|
||||
version: '1.0.0',
|
||||
|
||||
/**
|
||||
* Render the widget HTML
|
||||
* @param {HTMLElement} container - Container element to render into
|
||||
* @param {Object} config - Widget configuration from schema
|
||||
* @param {*} value - Current value
|
||||
* @param {Object} options - Additional options (fieldId, pluginId, etc.)
|
||||
*/
|
||||
render: function(container, config, value, options) {
|
||||
const fieldId = options.fieldId || container.id;
|
||||
|
||||
// Always escape HTML to prevent XSS
|
||||
const escapeHtml = (text) => {
|
||||
const div = document.createElement('div');
|
||||
div.textContent = text;
|
||||
return div.innerHTML;
|
||||
};
|
||||
|
||||
container.innerHTML = `
|
||||
<div class="my-custom-widget">
|
||||
<input type="text"
|
||||
id="${fieldId}_input"
|
||||
value="${escapeHtml(value || '')}"
|
||||
class="w-full px-3 py-2 border border-gray-300 rounded">
|
||||
</div>
|
||||
`;
|
||||
|
||||
// Attach event listeners
|
||||
const input = container.querySelector('input');
|
||||
input.addEventListener('change', (e) => {
|
||||
this.handlers.onChange(fieldId, e.target.value);
|
||||
});
|
||||
},
|
||||
|
||||
/**
|
||||
* Get current value from widget
|
||||
*/
|
||||
getValue: function(fieldId) {
|
||||
const input = document.querySelector(`#${fieldId}_input`);
|
||||
return input ? input.value : null;
|
||||
},
|
||||
|
||||
/**
|
||||
* Set value programmatically
|
||||
*/
|
||||
setValue: function(fieldId, value) {
|
||||
const input = document.querySelector(`#${fieldId}_input`);
|
||||
if (input) {
|
||||
input.value = value || '';
|
||||
}
|
||||
},
|
||||
|
||||
/**
|
||||
* Event handlers
|
||||
*/
|
||||
handlers: {
|
||||
onChange: function(fieldId, value) {
|
||||
// Trigger form change event
|
||||
const event = new CustomEvent('widget-change', {
|
||||
detail: { fieldId, value },
|
||||
bubbles: true
|
||||
});
|
||||
document.dispatchEvent(event);
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Step 2: Declare the Widget in `manifest.json`
|
||||
|
||||
The manifest is the allowlist. A widget is served only if the plugin declares
|
||||
it, so shipping a file under `widgets/` does not by itself publish it:
|
||||
|
||||
```json
|
||||
{
|
||||
"widgets": [
|
||||
{
|
||||
"name": "my-custom-widget",
|
||||
"script": "my-custom-widget.js",
|
||||
"description": "What this widget is for"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`name` is what you use in `x-widget` and in the URL. `script` is optional and
|
||||
defaults to `[name].js`; it must be a plain filename directly inside
|
||||
`widgets/` (no paths). Both are validated against
|
||||
`schema/manifest_schema.json`.
|
||||
|
||||
### Step 3: Reference Widget in Schema
|
||||
|
||||
In your plugin's `config_schema.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"properties": {
|
||||
"my_field": {
|
||||
"type": "string",
|
||||
"description": "My custom field",
|
||||
"x-widget": "my-custom-widget",
|
||||
"default": ""
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Widget Loading
|
||||
|
||||
The widget is loaded on demand when the plugin's configuration form renders a
|
||||
field that references it. The system will:
|
||||
|
||||
1. Check whether the widget is already registered in the core registry.
|
||||
2. If not, fetch it from `/static/plugin-widgets/[plugin-id]/[widget-name].js`.
|
||||
That route serves the declared `script` from your plugin's `widgets/`
|
||||
directory, as `text/javascript`.
|
||||
3. Render it by calling the `render` function your script registered.
|
||||
|
||||
The fetch uses a dynamic `import()`, so the file must parse as an ES module.
|
||||
A plain IIFE does — modules are strict mode, so avoid sloppy-mode constructs.
|
||||
|
||||
**If the widget fails to load** (not declared, file missing, script throws, or
|
||||
it never calls `register`), the field falls back to a plain text input holding
|
||||
the current value. This is deliberate: a broken widget costs the user an
|
||||
editor, not their configured value.
|
||||
|
||||
**Limitation:** the on-demand path applies to `string`-typed fields (the
|
||||
default branch of the config-form renderer). Fields typed `object`, `array`,
|
||||
`boolean`, `integer` or `number`, and fields whose `enum` is set, are
|
||||
dispatched by the server-side template to its own built-in renderers, so a
|
||||
plugin-supplied `x-widget` on one of those is ignored today.
|
||||
|
||||
## Widget API Reference
|
||||
|
||||
### Widget Definition Object
|
||||
|
||||
```javascript
|
||||
{
|
||||
name: string, // Human-readable widget name
|
||||
version: string, // Widget version
|
||||
render: function, // Required: Render function
|
||||
getValue: function, // Optional: Get current value
|
||||
setValue: function, // Optional: Set value programmatically
|
||||
handlers: object // Optional: Event handlers
|
||||
}
|
||||
```
|
||||
|
||||
### Render Function
|
||||
|
||||
```javascript
|
||||
render(container, config, value, options)
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `container` (HTMLElement): Container element to render into
|
||||
- `config` (Object): Widget configuration from schema
|
||||
- `value` (*): Current field value
|
||||
- `options` (Object): Additional options
|
||||
- `fieldId` (string): Field ID
|
||||
- `pluginId` (string): Plugin ID
|
||||
- `fullKey` (string): Full field key path
|
||||
|
||||
### Get Value Function
|
||||
|
||||
```javascript
|
||||
getValue(fieldId)
|
||||
```
|
||||
|
||||
**Returns:** Current widget value
|
||||
|
||||
### Set Value Function
|
||||
|
||||
```javascript
|
||||
setValue(fieldId, value)
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `fieldId` (string): Field ID
|
||||
- `value` (*): Value to set
|
||||
|
||||
## Examples
|
||||
|
||||
See [`web_interface/static/v3/js/widgets/example-color-picker.js`](../web_interface/static/v3/js/widgets/example-color-picker.js) for a complete example of a custom color picker widget.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Security
|
||||
|
||||
1. **Always escape HTML**: Use `escapeHtml()` or `textContent` to prevent XSS
|
||||
2. **Validate inputs**: Validate user input before processing
|
||||
3. **Sanitize values**: Clean values before storing
|
||||
|
||||
### Performance
|
||||
|
||||
1. **Lazy loading**: Load widget scripts only when needed
|
||||
2. **Event delegation**: Use event delegation for dynamic content
|
||||
3. **Debounce**: Debounce frequent events (e.g., input changes)
|
||||
|
||||
### Accessibility
|
||||
|
||||
1. **Labels**: Always associate labels with inputs
|
||||
2. **ARIA attributes**: Use appropriate ARIA attributes
|
||||
3. **Keyboard navigation**: Ensure keyboard accessibility
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Widget Not Loading
|
||||
|
||||
1. Check browser console for errors
|
||||
2. Verify widget file path is correct
|
||||
3. Ensure `LEDMatrixWidgets.register()` is called
|
||||
4. Check that widget name matches schema `x-widget` value
|
||||
|
||||
### Widget Not Rendering
|
||||
|
||||
1. Verify `render` function is defined
|
||||
2. Check container element exists
|
||||
3. Ensure widget is registered before form loads
|
||||
4. Check for JavaScript errors in console
|
||||
|
||||
### Value Not Saving
|
||||
|
||||
1. Ensure widget triggers `widget-change` event
|
||||
2. Verify form submission includes widget value
|
||||
3. Check `getValue` function returns correct type
|
||||
4. Verify field name matches schema property
|
||||
|
||||
## Current Implementation Status
|
||||
|
||||
**Phase 1 Complete:**
|
||||
- ✅ Widget registry system created
|
||||
- ✅ Core widgets extracted to separate files
|
||||
- ✅ Widget handlers available globally (backwards compatible)
|
||||
- ✅ Plugin widget loading system implemented
|
||||
|
||||
**Current Behavior:**
|
||||
- Core widgets are server-side rendered via Jinja2 templates (existing behavior preserved)
|
||||
- Widget handlers are registered and available globally
|
||||
- Custom widgets can be created, declared in `manifest.json`, and are served
|
||||
and rendered on demand for `string`-typed fields
|
||||
- Plugin widgets on non-string fields are not dispatched yet (see Step 4)
|
||||
|
||||
**Backwards Compatibility:**
|
||||
- All existing plugins using widgets continue to work without changes
|
||||
- Server-side rendering remains the primary method
|
||||
- Widget registry provides foundation for future enhancements
|
||||
|
||||
## See Also
|
||||
|
||||
- [Widget README](../web_interface/static/v3/js/widgets/README.md) - Complete widget development guide with examples
|
||||
- [Plugin Development Guide](PLUGIN_DEVELOPMENT_GUIDE.md) - General plugin development
|
||||
- [Plugin Configuration Guide](PLUGIN_CONFIGURATION_GUIDE.md) - Configuration setup
|
||||
The widget guide lives next to the widgets, in
|
||||
[web_interface/static/v3/js/widgets/README.md](../web_interface/static/v3/js/widgets/README.md).
|
||||
It lists every built-in `x-widget`, the schema keywords the config form
|
||||
understands (`x-options.labels`, `x-advanced`, `x-display: "hidden"`), and how
|
||||
to ship a custom widget with a plugin.
|
||||
|
||||
Reference in New Issue
Block a user