mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-04-12 13:42:59 +00:00
Compare commits
1 Commits
fix/lacros
...
a0873806db
| Author | SHA1 | Date | |
|---|---|---|---|
|
a0873806db |
@@ -43,48 +43,39 @@ cp ../../.cursor/plugin_templates/*.template .
|
||||
2. **Using dev_plugin_setup.sh**:
|
||||
```bash
|
||||
# Link from GitHub
|
||||
./scripts/dev/dev_plugin_setup.sh link-github my-plugin
|
||||
./dev_plugin_setup.sh link-github my-plugin
|
||||
|
||||
# Link local repo
|
||||
./scripts/dev/dev_plugin_setup.sh link my-plugin /path/to/repo
|
||||
./dev_plugin_setup.sh link my-plugin /path/to/repo
|
||||
```
|
||||
|
||||
### Running the Display
|
||||
### Running Plugins
|
||||
|
||||
```bash
|
||||
# Emulator mode (development, no hardware required)
|
||||
python3 run.py --emulator
|
||||
# (equivalent: EMULATOR=true python3 run.py)
|
||||
# Emulator (development)
|
||||
python run.py --emulator
|
||||
|
||||
# Hardware (production, requires the rpi-rgb-led-matrix submodule built)
|
||||
python3 run.py
|
||||
# Hardware (production)
|
||||
python run.py
|
||||
|
||||
# As a systemd service
|
||||
# As service
|
||||
sudo systemctl start ledmatrix
|
||||
|
||||
# Dev preview server (renders plugins to a browser without running run.py)
|
||||
python3 scripts/dev_server.py # then open http://localhost:5001
|
||||
```
|
||||
|
||||
The `-e`/`--emulator` CLI flag is defined in `run.py:19-20` and
|
||||
sets `os.environ["EMULATOR"] = "true"` before any display imports,
|
||||
which `src/display_manager.py:2` then reads to switch between the
|
||||
hardware and emulator backends.
|
||||
|
||||
### Managing Plugins
|
||||
|
||||
```bash
|
||||
# List plugins
|
||||
./scripts/dev/dev_plugin_setup.sh list
|
||||
./dev_plugin_setup.sh list
|
||||
|
||||
# Check status
|
||||
./scripts/dev/dev_plugin_setup.sh status
|
||||
./dev_plugin_setup.sh status
|
||||
|
||||
# Update plugin(s)
|
||||
./scripts/dev/dev_plugin_setup.sh update [plugin-name]
|
||||
./dev_plugin_setup.sh update [plugin-name]
|
||||
|
||||
# Unlink plugin
|
||||
./scripts/dev/dev_plugin_setup.sh unlink <plugin-name>
|
||||
./dev_plugin_setup.sh unlink <plugin-name>
|
||||
```
|
||||
|
||||
## Using These Files with Cursor
|
||||
@@ -127,13 +118,9 @@ Refer to `plugins_guide.md` for:
|
||||
- **Plugin System**: `src/plugin_system/`
|
||||
- **Base Plugin**: `src/plugin_system/base_plugin.py`
|
||||
- **Plugin Manager**: `src/plugin_system/plugin_manager.py`
|
||||
- **Example Plugins**: see the
|
||||
[`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins)
|
||||
repo for canonical sources (e.g. `plugins/hockey-scoreboard/`,
|
||||
`plugins/football-scoreboard/`). Installed plugins land in
|
||||
`plugin-repos/` (default) or `plugins/` (dev fallback).
|
||||
- **Example Plugins**: `plugins/hockey-scoreboard/`, `plugins/football-scoreboard/`
|
||||
- **Architecture Docs**: `docs/PLUGIN_ARCHITECTURE_SPEC.md`
|
||||
- **Development Setup**: `scripts/dev/dev_plugin_setup.sh`
|
||||
- **Development Setup**: `dev_plugin_setup.sh`
|
||||
|
||||
## Getting Help
|
||||
|
||||
|
||||
@@ -156,34 +156,20 @@ def _fetch_data(self):
|
||||
|
||||
### Adding Image Rendering
|
||||
|
||||
There is no `draw_image()` helper on `DisplayManager`. To render an
|
||||
image, paste it directly onto the underlying PIL `Image`
|
||||
(`display_manager.image`) and then call `update_display()`:
|
||||
|
||||
```python
|
||||
def _render_content(self):
|
||||
# Load and paste image onto the display canvas
|
||||
image = Image.open("assets/logo.png").convert("RGB")
|
||||
self.display_manager.image.paste(image, (0, 0))
|
||||
|
||||
# Load and render image
|
||||
image = Image.open("assets/logo.png")
|
||||
self.display_manager.draw_image(image, x=0, y=0)
|
||||
|
||||
# Draw text overlay
|
||||
self.display_manager.draw_text(
|
||||
"Text",
|
||||
x=10, y=20,
|
||||
color=(255, 255, 255)
|
||||
)
|
||||
|
||||
self.display_manager.update_display()
|
||||
```
|
||||
|
||||
For transparency, paste with a mask:
|
||||
|
||||
```python
|
||||
icon = Image.open("assets/icon.png").convert("RGBA")
|
||||
self.display_manager.image.paste(icon, (5, 5), icon)
|
||||
```
|
||||
|
||||
|
||||
### Adding Live Priority
|
||||
|
||||
1. Enable in config:
|
||||
|
||||
@@ -53,13 +53,13 @@ This method is best for plugins stored in separate Git repositories.
|
||||
|
||||
```bash
|
||||
# Link a plugin from GitHub (auto-detects URL)
|
||||
./scripts/dev/dev_plugin_setup.sh link-github <plugin-name>
|
||||
./dev_plugin_setup.sh link-github <plugin-name>
|
||||
|
||||
# Example: Link hockey-scoreboard plugin
|
||||
./scripts/dev/dev_plugin_setup.sh link-github hockey-scoreboard
|
||||
./dev_plugin_setup.sh link-github hockey-scoreboard
|
||||
|
||||
# With custom URL
|
||||
./scripts/dev/dev_plugin_setup.sh link-github <plugin-name> https://github.com/user/repo.git
|
||||
./dev_plugin_setup.sh link-github <plugin-name> https://github.com/user/repo.git
|
||||
```
|
||||
|
||||
The script will:
|
||||
@@ -71,10 +71,10 @@ The script will:
|
||||
|
||||
```bash
|
||||
# Link a local plugin repository
|
||||
./scripts/dev/dev_plugin_setup.sh link <plugin-name> <path-to-repo>
|
||||
./dev_plugin_setup.sh link <plugin-name> <path-to-repo>
|
||||
|
||||
# Example: Link a local plugin
|
||||
./scripts/dev/dev_plugin_setup.sh link my-plugin ../ledmatrix-my-plugin
|
||||
./dev_plugin_setup.sh link my-plugin ../ledmatrix-my-plugin
|
||||
```
|
||||
|
||||
### Method 2: Manual Plugin Creation
|
||||
@@ -321,8 +321,7 @@ Each plugin has its own section in `config/config.json`:
|
||||
|
||||
### Secrets Management
|
||||
|
||||
Store sensitive data (API keys, tokens) in `config/config_secrets.json`
|
||||
under the same plugin id you use in `config/config.json`:
|
||||
Store sensitive data (API keys, tokens) in `config/config_secrets.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -332,21 +331,19 @@ under the same plugin id you use in `config/config.json`:
|
||||
}
|
||||
```
|
||||
|
||||
At load time, the config manager deep-merges `config_secrets.json` into
|
||||
the main config (verified at `src/config_manager.py:162-172`). So in
|
||||
your plugin's code:
|
||||
Reference secrets in main config:
|
||||
|
||||
```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.api_key = config.get("api_key") # already merged from secrets
|
||||
```json
|
||||
{
|
||||
"my-plugin": {
|
||||
"enabled": true,
|
||||
"config_secrets": {
|
||||
"api_key": "my-plugin.api_key"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
There is no separate `config_secrets` reference field — just put the
|
||||
secret value under the same plugin namespace and read it from the
|
||||
merged config.
|
||||
|
||||
### Plugin Discovery
|
||||
|
||||
Plugins are automatically discovered when:
|
||||
@@ -358,7 +355,7 @@ Check discovered plugins:
|
||||
|
||||
```bash
|
||||
# Using dev_plugin_setup.sh
|
||||
./scripts/dev/dev_plugin_setup.sh list
|
||||
./dev_plugin_setup.sh list
|
||||
|
||||
# Output shows:
|
||||
# ✓ plugin-name (symlink)
|
||||
@@ -371,7 +368,7 @@ Check discovered plugins:
|
||||
Check plugin status and git information:
|
||||
|
||||
```bash
|
||||
./scripts/dev/dev_plugin_setup.sh status
|
||||
./dev_plugin_setup.sh status
|
||||
|
||||
# Output shows:
|
||||
# ✓ plugin-name
|
||||
@@ -394,19 +391,13 @@ cd ledmatrix-my-plugin
|
||||
|
||||
# Link to LEDMatrix project
|
||||
cd /path/to/LEDMatrix
|
||||
./scripts/dev/dev_plugin_setup.sh link my-plugin ../ledmatrix-my-plugin
|
||||
./dev_plugin_setup.sh link my-plugin ../ledmatrix-my-plugin
|
||||
```
|
||||
|
||||
### 2. Development Cycle
|
||||
|
||||
1. **Edit plugin code** in linked repository
|
||||
2. **Test with the dev preview server**:
|
||||
`python3 scripts/dev_server.py` (then open `http://localhost:5001`).
|
||||
Or run the full display in emulator mode with
|
||||
`python3 run.py --emulator` (or equivalently
|
||||
`EMULATOR=true python3 run.py`). The `-e`/`--emulator` CLI flag is
|
||||
defined in `run.py:19-20` and sets the same `EMULATOR` environment
|
||||
variable internally.
|
||||
2. **Test with emulator**: `python run.py --emulator`
|
||||
3. **Check logs** for errors or warnings
|
||||
4. **Update configuration** in `config/config.json` if needed
|
||||
5. **Iterate** until plugin works correctly
|
||||
@@ -415,30 +406,30 @@ cd /path/to/LEDMatrix
|
||||
|
||||
```bash
|
||||
# Deploy to Raspberry Pi
|
||||
rsync -avz plugins/my-plugin/ ledpi@your-pi-ip:/path/to/LEDMatrix/plugins/my-plugin/
|
||||
rsync -avz plugins/my-plugin/ pi@raspberrypi:/path/to/LEDMatrix/plugins/my-plugin/
|
||||
|
||||
# Or if using git, pull on Pi
|
||||
ssh ledpi@your-pi-ip "cd /path/to/LEDMatrix/plugins/my-plugin && git pull"
|
||||
ssh pi@raspberrypi "cd /path/to/LEDMatrix/plugins/my-plugin && git pull"
|
||||
|
||||
# Restart service
|
||||
ssh ledpi@your-pi-ip "sudo systemctl restart ledmatrix"
|
||||
ssh pi@raspberrypi "sudo systemctl restart ledmatrix"
|
||||
```
|
||||
|
||||
### 4. Updating Plugins
|
||||
|
||||
```bash
|
||||
# Update single plugin from git
|
||||
./scripts/dev/dev_plugin_setup.sh update my-plugin
|
||||
./dev_plugin_setup.sh update my-plugin
|
||||
|
||||
# Update all linked plugins
|
||||
./scripts/dev/dev_plugin_setup.sh update
|
||||
./dev_plugin_setup.sh update
|
||||
```
|
||||
|
||||
### 5. Unlinking Plugins
|
||||
|
||||
```bash
|
||||
# Remove symlink (preserves repository)
|
||||
./scripts/dev/dev_plugin_setup.sh unlink my-plugin
|
||||
./dev_plugin_setup.sh unlink my-plugin
|
||||
```
|
||||
|
||||
---
|
||||
@@ -634,8 +625,8 @@ python run.py --emulator
|
||||
**Solutions**:
|
||||
1. Check symlink: `ls -la plugins/my-plugin`
|
||||
2. Verify target exists: `readlink -f plugins/my-plugin`
|
||||
3. Update plugin: `./scripts/dev/dev_plugin_setup.sh update my-plugin`
|
||||
4. Re-link plugin if needed: `./scripts/dev/dev_plugin_setup.sh unlink my-plugin && ./scripts/dev/dev_plugin_setup.sh link my-plugin <path>`
|
||||
3. Update plugin: `./dev_plugin_setup.sh update my-plugin`
|
||||
4. Re-link plugin if needed: `./dev_plugin_setup.sh unlink my-plugin && ./dev_plugin_setup.sh link my-plugin <path>`
|
||||
5. Check git status: `cd plugins/my-plugin && git status`
|
||||
|
||||
---
|
||||
@@ -706,22 +697,22 @@ python run.py --emulator
|
||||
|
||||
```bash
|
||||
# Link plugin from GitHub
|
||||
./scripts/dev/dev_plugin_setup.sh link-github <name>
|
||||
./dev_plugin_setup.sh link-github <name>
|
||||
|
||||
# Link local plugin
|
||||
./scripts/dev/dev_plugin_setup.sh link <name> <path>
|
||||
./dev_plugin_setup.sh link <name> <path>
|
||||
|
||||
# List all plugins
|
||||
./scripts/dev/dev_plugin_setup.sh list
|
||||
./dev_plugin_setup.sh list
|
||||
|
||||
# Check plugin status
|
||||
./scripts/dev/dev_plugin_setup.sh status
|
||||
./dev_plugin_setup.sh status
|
||||
|
||||
# Update plugin(s)
|
||||
./scripts/dev/dev_plugin_setup.sh update [name]
|
||||
./dev_plugin_setup.sh update [name]
|
||||
|
||||
# Unlink plugin
|
||||
./scripts/dev/dev_plugin_setup.sh unlink <name>
|
||||
./dev_plugin_setup.sh unlink <name>
|
||||
|
||||
# Run with emulator
|
||||
python run.py --emulator
|
||||
|
||||
79
.cursorrules
79
.cursorrules
@@ -2,31 +2,7 @@
|
||||
|
||||
## Plugin System Overview
|
||||
|
||||
The LEDMatrix project uses a plugin-based architecture. All display
|
||||
functionality (except core calendar) is implemented as plugins that are
|
||||
dynamically loaded from the directory configured by
|
||||
`plugin_system.plugins_directory` in `config.json` — the default is
|
||||
`plugin-repos/` (per `config/config.template.json:130`).
|
||||
|
||||
> **Fallback note (scoped):** `PluginManager.discover_plugins()`
|
||||
> (`src/plugin_system/plugin_manager.py:154`) only scans the
|
||||
> configured directory — there is no fallback to `plugins/` in the
|
||||
> main discovery path. A fallback to `plugins/` does exist in two
|
||||
> narrower places:
|
||||
> - `store_manager.py:1700-1718` — store operations (install/update/
|
||||
> uninstall) check `plugins/` if the plugin isn't found in the
|
||||
> configured directory, so plugin-store flows work even when your
|
||||
> dev symlinks live in `plugins/`.
|
||||
> - `schema_manager.py:70-80` — `get_schema_path()` probes both
|
||||
> `plugins/` and `plugin-repos/` for `config_schema.json` so the
|
||||
> web UI form generation finds the schema regardless of where the
|
||||
> plugin lives.
|
||||
>
|
||||
> The dev workflow in `scripts/dev/dev_plugin_setup.sh` creates
|
||||
> symlinks under `plugins/`, which is why the store and schema
|
||||
> fallbacks exist. For day-to-day development, set
|
||||
> `plugin_system.plugins_directory` to `plugins` so the main
|
||||
> discovery path picks up your symlinks.
|
||||
The LEDMatrix project uses a plugin-based architecture. All display functionality (except core calendar) is implemented as plugins that are dynamically loaded from the `plugins/` directory.
|
||||
|
||||
## Plugin Structure
|
||||
|
||||
@@ -51,15 +27,14 @@ dynamically loaded from the directory configured by
|
||||
**Option A: Use dev_plugin_setup.sh (Recommended)**
|
||||
```bash
|
||||
# Link from GitHub
|
||||
./scripts/dev/dev_plugin_setup.sh link-github <plugin-name>
|
||||
./dev_plugin_setup.sh link-github <plugin-name>
|
||||
|
||||
# Link local repository
|
||||
./scripts/dev/dev_plugin_setup.sh link <plugin-name> <path-to-repo>
|
||||
./dev_plugin_setup.sh link <plugin-name> <path-to-repo>
|
||||
```
|
||||
|
||||
**Option B: Manual Setup**
|
||||
1. Create directory in `plugin-repos/<plugin-id>/` (or `plugins/<plugin-id>/`
|
||||
if you're using the dev fallback location)
|
||||
1. Create directory in `plugins/<plugin-id>/`
|
||||
2. Add `manifest.json` with required fields
|
||||
3. Create `manager.py` with plugin class
|
||||
4. Add `config_schema.json` for configuration
|
||||
@@ -88,13 +63,7 @@ Plugins are configured in `config/config.json`:
|
||||
### 3. Testing Plugins
|
||||
|
||||
**On Development Machine:**
|
||||
- Run the dev preview server: `python3 scripts/dev_server.py` (then
|
||||
open `http://localhost:5001`) — renders plugins in the browser
|
||||
without running the full display loop
|
||||
- Or run the full display in emulator mode:
|
||||
`python3 run.py --emulator` (or equivalently
|
||||
`EMULATOR=true python3 run.py`, or `./scripts/dev/run_emulator.sh`).
|
||||
The `-e`/`--emulator` CLI flag is defined in `run.py:19-20`.
|
||||
- Use emulator: `python run.py --emulator` or `./run_emulator.sh`
|
||||
- Test plugin loading: Check logs for plugin discovery and loading
|
||||
- Validate configuration: Ensure config matches `config_schema.json`
|
||||
|
||||
@@ -106,22 +75,15 @@ Plugins are configured in `config/config.json`:
|
||||
### 4. Plugin Development Best Practices
|
||||
|
||||
**Code Organization:**
|
||||
- Keep plugin code in `plugin-repos/<plugin-id>/` (or its dev-time
|
||||
symlink in `plugins/<plugin-id>/`)
|
||||
- Keep plugin code in `plugins/<plugin-id>/`
|
||||
- Use shared assets from `assets/` directory when possible
|
||||
- Follow existing plugin patterns — canonical sources live in the
|
||||
[`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins)
|
||||
repo (`plugins/hockey-scoreboard/`, `plugins/football-scoreboard/`,
|
||||
`plugins/clock-simple/`, etc.)
|
||||
- Follow existing plugin patterns (see `plugins/hockey-scoreboard/` as reference)
|
||||
- Place shared utilities in `src/common/` if reusable across plugins
|
||||
|
||||
**Configuration Management:**
|
||||
- Use `config_schema.json` for validation
|
||||
- Store secrets in `config/config_secrets.json` under the same plugin
|
||||
id namespace as the main config — they're deep-merged into the main
|
||||
config at load time (`src/config_manager.py:162-172`), so plugin
|
||||
code reads them directly from `config.get(...)` like any other key
|
||||
- There is no separate `config_secrets` reference field
|
||||
- Store secrets in `config/config_secrets.json` (not in main config)
|
||||
- Reference secrets via `config_secrets` key in main config
|
||||
- Validate all required fields in `validate_config()`
|
||||
|
||||
**Error Handling:**
|
||||
@@ -176,31 +138,18 @@ Located in: `src/display_manager.py`
|
||||
|
||||
**Key Methods:**
|
||||
- `clear()`: Clear the display
|
||||
- `draw_text(text, x, y, color, font, small_font, centered)`: Draw text
|
||||
- `update_display()`: Push the buffer to the physical display
|
||||
- `draw_weather_icon(condition, x, y, size)`: Draw a weather icon
|
||||
- `draw_text(text, x, y, color, font)`: Draw text
|
||||
- `draw_image(image, x, y)`: Draw PIL Image
|
||||
- `update_display()`: Update physical display
|
||||
- `width`, `height`: Display dimensions
|
||||
|
||||
**Image rendering**: there is no `draw_image()` helper. Paste directly
|
||||
onto the underlying PIL Image:
|
||||
```python
|
||||
self.display_manager.image.paste(pil_image, (x, y))
|
||||
self.display_manager.update_display()
|
||||
```
|
||||
For transparency, paste with a mask: `image.paste(rgba, (x, y), rgba)`.
|
||||
|
||||
### Cache Manager
|
||||
Located in: `src/cache_manager.py`
|
||||
|
||||
**Key Methods:**
|
||||
- `get(key, max_age=300)`: Get cached value (returns None if missing/stale)
|
||||
- `get(key, max_age=None)`: Get cached value
|
||||
- `set(key, value, ttl=None)`: Cache a value
|
||||
- `clear_cache(key=None)`: Remove a cache entry, or all entries if `key`
|
||||
is omitted. There is no `delete()` method.
|
||||
- `get_cached_data_with_strategy(key, data_type)`: Cache get with
|
||||
data-type-aware TTL strategy
|
||||
- `get_background_cached_data(key, sport_key)`: Cache get for the
|
||||
background-fetch service path
|
||||
- `delete(key)`: Remove cached value
|
||||
|
||||
## Plugin Manifest Schema
|
||||
|
||||
|
||||
96
.github/ISSUE_TEMPLATE/bug_report.md
vendored
96
.github/ISSUE_TEMPLATE/bug_report.md
vendored
@@ -1,84 +1,38 @@
|
||||
---
|
||||
name: Bug report
|
||||
about: Report a problem with LEDMatrix
|
||||
about: Create a report to help us improve
|
||||
title: ''
|
||||
labels: bug
|
||||
labels: ''
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
<!--
|
||||
Before filing: please check existing issues to see if this is already
|
||||
reported. For security issues, see SECURITY.md and report privately.
|
||||
-->
|
||||
**Describe the bug**
|
||||
A clear and concise description of what the bug is.
|
||||
|
||||
## Describe the bug
|
||||
**To Reproduce**
|
||||
Steps to reproduce the behavior:
|
||||
1. Go to '...'
|
||||
2. Click on '....'
|
||||
3. Scroll down to '....'
|
||||
4. See error
|
||||
|
||||
<!-- A clear and concise description of what the bug is. -->
|
||||
**Expected behavior**
|
||||
A clear and concise description of what you expected to happen.
|
||||
|
||||
## Steps to reproduce
|
||||
**Screenshots**
|
||||
If applicable, add screenshots to help explain your problem.
|
||||
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
**Desktop (please complete the following information):**
|
||||
- OS: [e.g. iOS]
|
||||
- Browser [e.g. chrome, safari]
|
||||
- Version [e.g. 22]
|
||||
|
||||
## Expected behavior
|
||||
**Smartphone (please complete the following information):**
|
||||
- Device: [e.g. iPhone6]
|
||||
- OS: [e.g. iOS8.1]
|
||||
- Browser [e.g. stock browser, safari]
|
||||
- Version [e.g. 22]
|
||||
|
||||
<!-- What you expected to happen. -->
|
||||
|
||||
## Actual behavior
|
||||
|
||||
<!-- What actually happened. Include any error messages. -->
|
||||
|
||||
## Hardware
|
||||
|
||||
- **Raspberry Pi model**: <!-- e.g. Pi 3B+, Pi 4 8GB, Pi Zero 2W -->
|
||||
- **OS / kernel**: <!-- output of `cat /etc/os-release` and `uname -a` -->
|
||||
- **LED matrix panels**: <!-- e.g. 2x Adafruit 64x32, 1x Waveshare 96x48 -->
|
||||
- **HAT / Bonnet**: <!-- e.g. Adafruit RGB Matrix Bonnet, Electrodragon HAT -->
|
||||
- **PWM jumper mod soldered?**: <!-- yes / no -->
|
||||
- **Display chain**: <!-- chain_length × parallel, e.g. "2x1" -->
|
||||
|
||||
## LEDMatrix version
|
||||
|
||||
<!-- Run `git rev-parse HEAD` in the LEDMatrix directory, or paste the
|
||||
release tag if you installed from a release. -->
|
||||
|
||||
```
|
||||
git commit:
|
||||
```
|
||||
|
||||
## Plugin involved (if any)
|
||||
|
||||
- **Plugin id**:
|
||||
- **Plugin version** (from `manifest.json`):
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- Paste the relevant section from config/config.json. Redact any
|
||||
API keys before pasting. For display issues, the `display.hardware`
|
||||
block is most relevant. For plugin issues, paste that plugin's section. -->
|
||||
|
||||
```json
|
||||
```
|
||||
|
||||
## Logs
|
||||
|
||||
<!-- The first 50 lines of the relevant log are usually enough. Run:
|
||||
sudo journalctl -u ledmatrix -n 100 --no-pager
|
||||
or for the web service:
|
||||
sudo journalctl -u ledmatrix-web -n 100 --no-pager
|
||||
-->
|
||||
|
||||
```
|
||||
```
|
||||
|
||||
## Screenshots / video (optional)
|
||||
|
||||
<!-- A photo of the actual display, or a screenshot of the web UI,
|
||||
helps a lot for visual issues. -->
|
||||
|
||||
## Additional context
|
||||
|
||||
<!-- Anything else that might be relevant: when did this start happening,
|
||||
what's different about your setup, what have you already tried, etc. -->
|
||||
**Additional context**
|
||||
Add any other context about the problem here.
|
||||
|
||||
62
.github/PULL_REQUEST_TEMPLATE.md
vendored
62
.github/PULL_REQUEST_TEMPLATE.md
vendored
@@ -1,62 +0,0 @@
|
||||
# Pull Request
|
||||
|
||||
## Summary
|
||||
|
||||
<!-- 1-3 sentences describing what this PR does and why. -->
|
||||
|
||||
## Type of change
|
||||
|
||||
<!-- Check all that apply. -->
|
||||
|
||||
- [ ] Bug fix
|
||||
- [ ] New feature
|
||||
- [ ] Documentation
|
||||
- [ ] Refactor (no functional change)
|
||||
- [ ] Build / CI
|
||||
- [ ] Plugin work (link to the plugin)
|
||||
|
||||
## Related issues
|
||||
|
||||
<!-- "Fixes #123" or "Refs #123". Use "Fixes" for bug PRs so the issue
|
||||
auto-closes when this merges. -->
|
||||
|
||||
## Test plan
|
||||
|
||||
<!-- How did you test this? Check all that apply. Add details for any
|
||||
checked box. -->
|
||||
|
||||
- [ ] Ran on a real Raspberry Pi with hardware
|
||||
- [ ] Ran in emulator mode (`EMULATOR=true python3 run.py`)
|
||||
- [ ] Ran the dev preview server (`scripts/dev_server.py`)
|
||||
- [ ] Ran the test suite (`pytest`)
|
||||
- [ ] Manually verified the affected code path in the web UI
|
||||
- [ ] N/A — documentation-only change
|
||||
|
||||
## Documentation
|
||||
|
||||
- [ ] I updated `README.md` if user-facing behavior changed
|
||||
- [ ] I updated the relevant doc in `docs/` if developer behavior changed
|
||||
- [ ] I added/updated docstrings on new public functions
|
||||
- [ ] N/A — no docs needed
|
||||
|
||||
## Plugin compatibility
|
||||
|
||||
<!-- For changes to BasePlugin, the plugin loader, the web UI, or the
|
||||
config schema. -->
|
||||
|
||||
- [ ] No plugin breakage expected
|
||||
- [ ] Some plugins will need updates — listed below
|
||||
- [ ] N/A — change doesn't touch the plugin system
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] My commits follow the message convention in `CONTRIBUTING.md`
|
||||
- [ ] I read `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md`
|
||||
- [ ] I've not committed any secrets or hardcoded API keys
|
||||
- [ ] If this adds a new config key, the form in the web UI was
|
||||
verified (the form is generated from `config_schema.json`)
|
||||
|
||||
## Notes for reviewer
|
||||
|
||||
<!-- Anything reviewers should know — gotchas, things you weren't
|
||||
sure about, decisions you'd like a second opinion on. -->
|
||||
10
CLAUDE.md
10
CLAUDE.md
@@ -4,14 +4,8 @@
|
||||
- `src/plugin_system/` — Plugin loader, manager, store manager, base plugin class
|
||||
- `web_interface/` — Flask web UI (blueprints, templates, static JS)
|
||||
- `config/config.json` — User plugin configuration (persists across plugin reinstalls)
|
||||
- `plugin-repos/` — **Default** plugin install directory used by the
|
||||
Plugin Store, set by `plugin_system.plugins_directory` in
|
||||
`config.json` (default per `config/config.template.json:130`).
|
||||
Not gitignored.
|
||||
- `plugins/` — Legacy/dev plugin location. Gitignored (`plugins/*`).
|
||||
Used by `scripts/dev/dev_plugin_setup.sh` for symlinks. The plugin
|
||||
loader falls back to it when something isn't found in `plugin-repos/`
|
||||
(`src/plugin_system/schema_manager.py:77`).
|
||||
- `plugins/` — Installed plugins directory (gitignored)
|
||||
- `plugin-repos/` — Development symlinks to monorepo plugin dirs
|
||||
|
||||
## Plugin System
|
||||
- Plugins inherit from `BasePlugin` in `src/plugin_system/base_plugin.py`
|
||||
|
||||
@@ -1,137 +0,0 @@
|
||||
# Contributor Covenant Code of Conduct
|
||||
|
||||
## Our Pledge
|
||||
|
||||
We as members, contributors, and leaders pledge to make participation in our
|
||||
community a harassment-free experience for everyone, regardless of age, body
|
||||
size, visible or invisible disability, ethnicity, sex characteristics, gender
|
||||
identity and expression, level of experience, education, socio-economic status,
|
||||
nationality, personal appearance, race, religion, or sexual identity
|
||||
and orientation.
|
||||
|
||||
We pledge to act and interact in ways that contribute to an open, welcoming,
|
||||
diverse, inclusive, and healthy community.
|
||||
|
||||
## Our Standards
|
||||
|
||||
Examples of behavior that contributes to a positive environment for our
|
||||
community include:
|
||||
|
||||
* Demonstrating empathy and kindness toward other people
|
||||
* Being respectful of differing opinions, viewpoints, and experiences
|
||||
* Giving and gracefully accepting constructive feedback
|
||||
* Accepting responsibility and apologizing to those affected by our mistakes,
|
||||
and learning from the experience
|
||||
* Focusing on what is best not just for us as individuals, but for the
|
||||
overall community
|
||||
|
||||
Examples of unacceptable behavior include:
|
||||
|
||||
* The use of sexualized language or imagery, and sexual attention or
|
||||
advances of any kind
|
||||
* Trolling, insulting or derogatory comments, and personal or political attacks
|
||||
* Public or private harassment
|
||||
* Publishing others' private information, such as a physical or email
|
||||
address, without their explicit permission
|
||||
* Other conduct which could reasonably be considered inappropriate in a
|
||||
professional setting
|
||||
|
||||
## Enforcement Responsibilities
|
||||
|
||||
Community leaders are responsible for clarifying and enforcing our standards of
|
||||
acceptable behavior and will take appropriate and fair corrective action in
|
||||
response to any behavior that they deem inappropriate, threatening, offensive,
|
||||
or harmful.
|
||||
|
||||
Community leaders have the right and responsibility to remove, edit, or reject
|
||||
comments, commits, code, wiki edits, issues, and other contributions that are
|
||||
not aligned to this Code of Conduct, and will communicate reasons for moderation
|
||||
decisions when appropriate.
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies within all community spaces, and also applies when
|
||||
an individual is officially representing the community in public spaces.
|
||||
Examples of representing our community include using an official email address,
|
||||
posting via an official social media account, or acting as an appointed
|
||||
representative at an online or offline event.
|
||||
|
||||
This includes the LEDMatrix Discord server, GitHub repositories owned by
|
||||
ChuckBuilds, and any other forums hosted by or affiliated with the project.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
||||
reported to the community leaders responsible for enforcement on the
|
||||
[LEDMatrix Discord](https://discord.gg/uW36dVAtcT) (DM a moderator or
|
||||
ChuckBuilds directly) or by opening a private GitHub Security Advisory if
|
||||
the issue involves account safety. All complaints will be reviewed and
|
||||
investigated promptly and fairly.
|
||||
|
||||
All community leaders are obligated to respect the privacy and security of the
|
||||
reporter of any incident.
|
||||
|
||||
## Enforcement Guidelines
|
||||
|
||||
Community leaders will follow these Community Impact Guidelines in determining
|
||||
the consequences for any action they deem in violation of this Code of Conduct:
|
||||
|
||||
### 1. Correction
|
||||
|
||||
**Community Impact**: Use of inappropriate language or other behavior deemed
|
||||
unprofessional or unwelcome in the community.
|
||||
|
||||
**Consequence**: A private, written warning from community leaders, providing
|
||||
clarity around the nature of the violation and an explanation of why the
|
||||
behavior was inappropriate. A public apology may be requested.
|
||||
|
||||
### 2. Warning
|
||||
|
||||
**Community Impact**: A violation through a single incident or series
|
||||
of actions.
|
||||
|
||||
**Consequence**: A warning with consequences for continued behavior. No
|
||||
interaction with the people involved, including unsolicited interaction with
|
||||
those enforcing the Code of Conduct, for a specified period of time. This
|
||||
includes avoiding interactions in community spaces as well as external channels
|
||||
like social media. Violating these terms may lead to a temporary or
|
||||
permanent ban.
|
||||
|
||||
### 3. Temporary Ban
|
||||
|
||||
**Community Impact**: A serious violation of community standards, including
|
||||
sustained inappropriate behavior.
|
||||
|
||||
**Consequence**: A temporary ban from any sort of interaction or public
|
||||
communication with the community for a specified period of time. No public or
|
||||
private interaction with the people involved, including unsolicited interaction
|
||||
with those enforcing the Code of Conduct, is allowed during this period.
|
||||
Violating these terms may lead to a permanent ban.
|
||||
|
||||
### 4. Permanent Ban
|
||||
|
||||
**Community Impact**: Demonstrating a pattern of violation of community
|
||||
standards, including sustained inappropriate behavior, harassment of an
|
||||
individual, or aggression toward or disparagement of classes of individuals.
|
||||
|
||||
**Consequence**: A permanent ban from any sort of public interaction within
|
||||
the community.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
|
||||
version 2.1, available at
|
||||
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
|
||||
|
||||
Community Impact Guidelines were inspired by
|
||||
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
|
||||
|
||||
For answers to common questions about this code of conduct, see the FAQ at
|
||||
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available
|
||||
at [https://www.contributor-covenant.org/translations][translations].
|
||||
|
||||
[homepage]: https://www.contributor-covenant.org
|
||||
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
|
||||
[Mozilla CoC]: https://github.com/mozilla/diversity
|
||||
[FAQ]: https://www.contributor-covenant.org/faq
|
||||
[translations]: https://www.contributor-covenant.org/translations
|
||||
113
CONTRIBUTING.md
113
CONTRIBUTING.md
@@ -1,113 +0,0 @@
|
||||
# Contributing to LEDMatrix
|
||||
|
||||
Thanks for considering a contribution! LEDMatrix is built with help from
|
||||
the community and we welcome bug reports, plugins, documentation
|
||||
improvements, and code changes.
|
||||
|
||||
## Quick links
|
||||
|
||||
- **Bugs / feature requests**: open an issue using one of the templates
|
||||
in [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/).
|
||||
- **Real-time discussion**: the
|
||||
[LEDMatrix Discord](https://discord.gg/uW36dVAtcT).
|
||||
- **Plugin development**:
|
||||
[`docs/PLUGIN_DEVELOPMENT_GUIDE.md`](docs/PLUGIN_DEVELOPMENT_GUIDE.md)
|
||||
and the [`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins)
|
||||
repository.
|
||||
- **Security issues**: see [`SECURITY.md`](SECURITY.md). Please don't
|
||||
open public issues for vulnerabilities.
|
||||
|
||||
## Setting up a development environment
|
||||
|
||||
1. Clone with submodules:
|
||||
```bash
|
||||
git clone --recurse-submodules https://github.com/ChuckBuilds/LEDMatrix.git
|
||||
cd LEDMatrix
|
||||
```
|
||||
2. For development without hardware, run the dev preview server:
|
||||
```bash
|
||||
python3 scripts/dev_server.py
|
||||
# then open http://localhost:5001
|
||||
```
|
||||
See [`docs/DEV_PREVIEW.md`](docs/DEV_PREVIEW.md) for details.
|
||||
3. To run the full display in emulator mode:
|
||||
```bash
|
||||
EMULATOR=true python3 run.py
|
||||
```
|
||||
4. To target real hardware on a Raspberry Pi, follow the install
|
||||
instructions in the root [`README.md`](README.md).
|
||||
|
||||
## Running the tests
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
pytest
|
||||
```
|
||||
|
||||
See [`docs/HOW_TO_RUN_TESTS.md`](docs/HOW_TO_RUN_TESTS.md) for details
|
||||
on test markers, the per-plugin tests, and the web-interface
|
||||
integration tests.
|
||||
|
||||
## Submitting changes
|
||||
|
||||
1. **Open an issue first** for non-trivial changes. This avoids
|
||||
wasted work on PRs that don't fit the project direction.
|
||||
2. **Create a topic branch** off `main`:
|
||||
`feat/<short-description>`, `fix/<short-description>`,
|
||||
`docs/<short-description>`.
|
||||
3. **Keep PRs focused.** One conceptual change per PR. If you find
|
||||
adjacent bugs while working, fix them in a separate PR.
|
||||
4. **Follow the existing code style.** Python code uses standard
|
||||
`black`/`ruff` conventions; HTML/JS in `web_interface/` follows the
|
||||
patterns already in `templates/v3/` and `static/v3/`.
|
||||
5. **Update documentation** alongside code changes. If you add a
|
||||
config key, document it in the relevant `*.md` file (or, for
|
||||
plugins, in `config_schema.json` so the form is auto-generated).
|
||||
6. **Run the tests** locally before opening the PR.
|
||||
7. **Use the PR template** — `.github/PULL_REQUEST_TEMPLATE.md` will
|
||||
prompt you for what we need.
|
||||
|
||||
## Commit message convention
|
||||
|
||||
Conventional Commits is encouraged but not strictly enforced:
|
||||
|
||||
- `feat: add NHL playoff bracket display`
|
||||
- `fix(plugin-loader): handle missing class_name in manifest`
|
||||
- `docs: correct web UI port in TROUBLESHOOTING.md`
|
||||
- `refactor(cache): consolidate strategy lookup`
|
||||
|
||||
Keep the subject under 72 characters; put the why in the body.
|
||||
|
||||
## Contributing a plugin
|
||||
|
||||
LEDMatrix plugins live in their own repository:
|
||||
[`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins).
|
||||
Plugin contributions go through that repo's
|
||||
[`SUBMISSION.md`](https://github.com/ChuckBuilds/ledmatrix-plugins/blob/main/SUBMISSION.md)
|
||||
process. The
|
||||
[`hello-world` plugin](https://github.com/ChuckBuilds/ledmatrix-plugins/tree/main/plugins/hello-world)
|
||||
is the canonical starter template.
|
||||
|
||||
## Reviewing pull requests
|
||||
|
||||
Maintainer review is by [@ChuckBuilds](https://github.com/ChuckBuilds).
|
||||
Community review is welcome on any open PR — leave constructive
|
||||
comments, test on your hardware if applicable, and call out anything
|
||||
unclear.
|
||||
|
||||
## Code of conduct
|
||||
|
||||
This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). By
|
||||
participating you agree to abide by its terms.
|
||||
|
||||
## License
|
||||
|
||||
LEDMatrix is licensed under the [GNU General Public License v3.0 or
|
||||
later](LICENSE). By submitting a contribution you agree to license it
|
||||
under the same terms (the standard "inbound = outbound" rule that
|
||||
GitHub applies by default).
|
||||
|
||||
LEDMatrix builds on
|
||||
[`rpi-rgb-led-matrix`](https://github.com/hzeller/rpi-rgb-led-matrix),
|
||||
which is GPL-2.0-or-later. The "or later" clause makes it compatible
|
||||
with GPL-3.0 distribution.
|
||||
674
LICENSE
674
LICENSE
@@ -1,674 +0,0 @@
|
||||
GNU GENERAL PUBLIC LICENSE
|
||||
Version 3, 29 June 2007
|
||||
|
||||
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
|
||||
Everyone is permitted to copy and distribute verbatim copies
|
||||
of this license document, but changing it is not allowed.
|
||||
|
||||
Preamble
|
||||
|
||||
The GNU General Public License is a free, copyleft license for
|
||||
software and other kinds of works.
|
||||
|
||||
The licenses for most software and other practical works are designed
|
||||
to take away your freedom to share and change the works. By contrast,
|
||||
the GNU General Public License is intended to guarantee your freedom to
|
||||
share and change all versions of a program--to make sure it remains free
|
||||
software for all its users. We, the Free Software Foundation, use the
|
||||
GNU General Public License for most of our software; it applies also to
|
||||
any other work released this way by its authors. You can apply it to
|
||||
your programs, too.
|
||||
|
||||
When we speak of free software, we are referring to freedom, not
|
||||
price. Our General Public Licenses are designed to make sure that you
|
||||
have the freedom to distribute copies of free software (and charge for
|
||||
them if you wish), that you receive source code or can get it if you
|
||||
want it, that you can change the software or use pieces of it in new
|
||||
free programs, and that you know you can do these things.
|
||||
|
||||
To protect your rights, we need to prevent others from denying you
|
||||
these rights or asking you to surrender the rights. Therefore, you have
|
||||
certain responsibilities if you distribute copies of the software, or if
|
||||
you modify it: responsibilities to respect the freedom of others.
|
||||
|
||||
For example, if you distribute copies of such a program, whether
|
||||
gratis or for a fee, you must pass on to the recipients the same
|
||||
freedoms that you received. You must make sure that they, too, receive
|
||||
or can get the source code. And you must show them these terms so they
|
||||
know their rights.
|
||||
|
||||
Developers that use the GNU GPL protect your rights with two steps:
|
||||
(1) assert copyright on the software, and (2) offer you this License
|
||||
giving you legal permission to copy, distribute and/or modify it.
|
||||
|
||||
For the developers' and authors' protection, the GPL clearly explains
|
||||
that there is no warranty for this free software. For both users' and
|
||||
authors' sake, the GPL requires that modified versions be marked as
|
||||
changed, so that their problems will not be attributed erroneously to
|
||||
authors of previous versions.
|
||||
|
||||
Some devices are designed to deny users access to install or run
|
||||
modified versions of the software inside them, although the manufacturer
|
||||
can do so. This is fundamentally incompatible with the aim of
|
||||
protecting users' freedom to change the software. The systematic
|
||||
pattern of such abuse occurs in the area of products for individuals to
|
||||
use, which is precisely where it is most unacceptable. Therefore, we
|
||||
have designed this version of the GPL to prohibit the practice for those
|
||||
products. If such problems arise substantially in other domains, we
|
||||
stand ready to extend this provision to those domains in future versions
|
||||
of the GPL, as needed to protect the freedom of users.
|
||||
|
||||
Finally, every program is threatened constantly by software patents.
|
||||
States should not allow patents to restrict development and use of
|
||||
software on general-purpose computers, but in those that do, we wish to
|
||||
avoid the special danger that patents applied to a free program could
|
||||
make it effectively proprietary. To prevent this, the GPL assures that
|
||||
patents cannot be used to render the program non-free.
|
||||
|
||||
The precise terms and conditions for copying, distribution and
|
||||
modification follow.
|
||||
|
||||
TERMS AND CONDITIONS
|
||||
|
||||
0. Definitions.
|
||||
|
||||
"This License" refers to version 3 of the GNU General Public License.
|
||||
|
||||
"Copyright" also means copyright-like laws that apply to other kinds of
|
||||
works, such as semiconductor masks.
|
||||
|
||||
"The Program" refers to any copyrightable work licensed under this
|
||||
License. Each licensee is addressed as "you". "Licensees" and
|
||||
"recipients" may be individuals or organizations.
|
||||
|
||||
To "modify" a work means to copy from or adapt all or part of the work
|
||||
in a fashion requiring copyright permission, other than the making of an
|
||||
exact copy. The resulting work is called a "modified version" of the
|
||||
earlier work or a work "based on" the earlier work.
|
||||
|
||||
A "covered work" means either the unmodified Program or a work based
|
||||
on the Program.
|
||||
|
||||
To "propagate" a work means to do anything with it that, without
|
||||
permission, would make you directly or secondarily liable for
|
||||
infringement under applicable copyright law, except executing it on a
|
||||
computer or modifying a private copy. Propagation includes copying,
|
||||
distribution (with or without modification), making available to the
|
||||
public, and in some countries other activities as well.
|
||||
|
||||
To "convey" a work means any kind of propagation that enables other
|
||||
parties to make or receive copies. Mere interaction with a user through
|
||||
a computer network, with no transfer of a copy, is not conveying.
|
||||
|
||||
An interactive user interface displays "Appropriate Legal Notices"
|
||||
to the extent that it includes a convenient and prominently visible
|
||||
feature that (1) displays an appropriate copyright notice, and (2)
|
||||
tells the user that there is no warranty for the work (except to the
|
||||
extent that warranties are provided), that licensees may convey the
|
||||
work under this License, and how to view a copy of this License. If
|
||||
the interface presents a list of user commands or options, such as a
|
||||
menu, a prominent item in the list meets this criterion.
|
||||
|
||||
1. Source Code.
|
||||
|
||||
The "source code" for a work means the preferred form of the work
|
||||
for making modifications to it. "Object code" means any non-source
|
||||
form of a work.
|
||||
|
||||
A "Standard Interface" means an interface that either is an official
|
||||
standard defined by a recognized standards body, or, in the case of
|
||||
interfaces specified for a particular programming language, one that
|
||||
is widely used among developers working in that language.
|
||||
|
||||
The "System Libraries" of an executable work include anything, other
|
||||
than the work as a whole, that (a) is included in the normal form of
|
||||
packaging a Major Component, but which is not part of that Major
|
||||
Component, and (b) serves only to enable use of the work with that
|
||||
Major Component, or to implement a Standard Interface for which an
|
||||
implementation is available to the public in source code form. A
|
||||
"Major Component", in this context, means a major essential component
|
||||
(kernel, window system, and so on) of the specific operating system
|
||||
(if any) on which the executable work runs, or a compiler used to
|
||||
produce the work, or an object code interpreter used to run it.
|
||||
|
||||
The "Corresponding Source" for a work in object code form means all
|
||||
the source code needed to generate, install, and (for an executable
|
||||
work) run the object code and to modify the work, including scripts to
|
||||
control those activities. However, it does not include the work's
|
||||
System Libraries, or general-purpose tools or generally available free
|
||||
programs which are used unmodified in performing those activities but
|
||||
which are not part of the work. For example, Corresponding Source
|
||||
includes interface definition files associated with source files for
|
||||
the work, and the source code for shared libraries and dynamically
|
||||
linked subprograms that the work is specifically designed to require,
|
||||
such as by intimate data communication or control flow between those
|
||||
subprograms and other parts of the work.
|
||||
|
||||
The Corresponding Source need not include anything that users
|
||||
can regenerate automatically from other parts of the Corresponding
|
||||
Source.
|
||||
|
||||
The Corresponding Source for a work in source code form is that
|
||||
same work.
|
||||
|
||||
2. Basic Permissions.
|
||||
|
||||
All rights granted under this License are granted for the term of
|
||||
copyright on the Program, and are irrevocable provided the stated
|
||||
conditions are met. This License explicitly affirms your unlimited
|
||||
permission to run the unmodified Program. The output from running a
|
||||
covered work is covered by this License only if the output, given its
|
||||
content, constitutes a covered work. This License acknowledges your
|
||||
rights of fair use or other equivalent, as provided by copyright law.
|
||||
|
||||
You may make, run and propagate covered works that you do not
|
||||
convey, without conditions so long as your license otherwise remains
|
||||
in force. You may convey covered works to others for the sole purpose
|
||||
of having them make modifications exclusively for you, or provide you
|
||||
with facilities for running those works, provided that you comply with
|
||||
the terms of this License in conveying all material for which you do
|
||||
not control copyright. Those thus making or running the covered works
|
||||
for you must do so exclusively on your behalf, under your direction
|
||||
and control, on terms that prohibit them from making any copies of
|
||||
your copyrighted material outside their relationship with you.
|
||||
|
||||
Conveying under any other circumstances is permitted solely under
|
||||
the conditions stated below. Sublicensing is not allowed; section 10
|
||||
makes it unnecessary.
|
||||
|
||||
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
|
||||
|
||||
No covered work shall be deemed part of an effective technological
|
||||
measure under any applicable law fulfilling obligations under article
|
||||
11 of the WIPO copyright treaty adopted on 20 December 1996, or
|
||||
similar laws prohibiting or restricting circumvention of such
|
||||
measures.
|
||||
|
||||
When you convey a covered work, you waive any legal power to forbid
|
||||
circumvention of technological measures to the extent such circumvention
|
||||
is effected by exercising rights under this License with respect to
|
||||
the covered work, and you disclaim any intention to limit operation or
|
||||
modification of the work as a means of enforcing, against the work's
|
||||
users, your or third parties' legal rights to forbid circumvention of
|
||||
technological measures.
|
||||
|
||||
4. Conveying Verbatim Copies.
|
||||
|
||||
You may convey verbatim copies of the Program's source code as you
|
||||
receive it, in any medium, provided that you conspicuously and
|
||||
appropriately publish on each copy an appropriate copyright notice;
|
||||
keep intact all notices stating that this License and any
|
||||
non-permissive terms added in accord with section 7 apply to the code;
|
||||
keep intact all notices of the absence of any warranty; and give all
|
||||
recipients a copy of this License along with the Program.
|
||||
|
||||
You may charge any price or no price for each copy that you convey,
|
||||
and you may offer support or warranty protection for a fee.
|
||||
|
||||
5. Conveying Modified Source Versions.
|
||||
|
||||
You may convey a work based on the Program, or the modifications to
|
||||
produce it from the Program, in the form of source code under the
|
||||
terms of section 4, provided that you also meet all of these conditions:
|
||||
|
||||
a) The work must carry prominent notices stating that you modified
|
||||
it, and giving a relevant date.
|
||||
|
||||
b) The work must carry prominent notices stating that it is
|
||||
released under this License and any conditions added under section
|
||||
7. This requirement modifies the requirement in section 4 to
|
||||
"keep intact all notices".
|
||||
|
||||
c) You must license the entire work, as a whole, under this
|
||||
License to anyone who comes into possession of a copy. This
|
||||
License will therefore apply, along with any applicable section 7
|
||||
additional terms, to the whole of the work, and all its parts,
|
||||
regardless of how they are packaged. This License gives no
|
||||
permission to license the work in any other way, but it does not
|
||||
invalidate such permission if you have separately received it.
|
||||
|
||||
d) If the work has interactive user interfaces, each must display
|
||||
Appropriate Legal Notices; however, if the Program has interactive
|
||||
interfaces that do not display Appropriate Legal Notices, your
|
||||
work need not make them do so.
|
||||
|
||||
A compilation of a covered work with other separate and independent
|
||||
works, which are not by their nature extensions of the covered work,
|
||||
and which are not combined with it such as to form a larger program,
|
||||
in or on a volume of a storage or distribution medium, is called an
|
||||
"aggregate" if the compilation and its resulting copyright are not
|
||||
used to limit the access or legal rights of the compilation's users
|
||||
beyond what the individual works permit. Inclusion of a covered work
|
||||
in an aggregate does not cause this License to apply to the other
|
||||
parts of the aggregate.
|
||||
|
||||
6. Conveying Non-Source Forms.
|
||||
|
||||
You may convey a covered work in object code form under the terms
|
||||
of sections 4 and 5, provided that you also convey the
|
||||
machine-readable Corresponding Source under the terms of this License,
|
||||
in one of these ways:
|
||||
|
||||
a) Convey the object code in, or embodied in, a physical product
|
||||
(including a physical distribution medium), accompanied by the
|
||||
Corresponding Source fixed on a durable physical medium
|
||||
customarily used for software interchange.
|
||||
|
||||
b) Convey the object code in, or embodied in, a physical product
|
||||
(including a physical distribution medium), accompanied by a
|
||||
written offer, valid for at least three years and valid for as
|
||||
long as you offer spare parts or customer support for that product
|
||||
model, to give anyone who possesses the object code either (1) a
|
||||
copy of the Corresponding Source for all the software in the
|
||||
product that is covered by this License, on a durable physical
|
||||
medium customarily used for software interchange, for a price no
|
||||
more than your reasonable cost of physically performing this
|
||||
conveying of source, or (2) access to copy the
|
||||
Corresponding Source from a network server at no charge.
|
||||
|
||||
c) Convey individual copies of the object code with a copy of the
|
||||
written offer to provide the Corresponding Source. This
|
||||
alternative is allowed only occasionally and noncommercially, and
|
||||
only if you received the object code with such an offer, in accord
|
||||
with subsection 6b.
|
||||
|
||||
d) Convey the object code by offering access from a designated
|
||||
place (gratis or for a charge), and offer equivalent access to the
|
||||
Corresponding Source in the same way through the same place at no
|
||||
further charge. You need not require recipients to copy the
|
||||
Corresponding Source along with the object code. If the place to
|
||||
copy the object code is a network server, the Corresponding Source
|
||||
may be on a different server (operated by you or a third party)
|
||||
that supports equivalent copying facilities, provided you maintain
|
||||
clear directions next to the object code saying where to find the
|
||||
Corresponding Source. Regardless of what server hosts the
|
||||
Corresponding Source, you remain obligated to ensure that it is
|
||||
available for as long as needed to satisfy these requirements.
|
||||
|
||||
e) Convey the object code using peer-to-peer transmission, provided
|
||||
you inform other peers where the object code and Corresponding
|
||||
Source of the work are being offered to the general public at no
|
||||
charge under subsection 6d.
|
||||
|
||||
A separable portion of the object code, whose source code is excluded
|
||||
from the Corresponding Source as a System Library, need not be
|
||||
included in conveying the object code work.
|
||||
|
||||
A "User Product" is either (1) a "consumer product", which means any
|
||||
tangible personal property which is normally used for personal, family,
|
||||
or household purposes, or (2) anything designed or sold for incorporation
|
||||
into a dwelling. In determining whether a product is a consumer product,
|
||||
doubtful cases shall be resolved in favor of coverage. For a particular
|
||||
product received by a particular user, "normally used" refers to a
|
||||
typical or common use of that class of product, regardless of the status
|
||||
of the particular user or of the way in which the particular user
|
||||
actually uses, or expects or is expected to use, the product. A product
|
||||
is a consumer product regardless of whether the product has substantial
|
||||
commercial, industrial or non-consumer uses, unless such uses represent
|
||||
the only significant mode of use of the product.
|
||||
|
||||
"Installation Information" for a User Product means any methods,
|
||||
procedures, authorization keys, or other information required to install
|
||||
and execute modified versions of a covered work in that User Product from
|
||||
a modified version of its Corresponding Source. The information must
|
||||
suffice to ensure that the continued functioning of the modified object
|
||||
code is in no case prevented or interfered with solely because
|
||||
modification has been made.
|
||||
|
||||
If you convey an object code work under this section in, or with, or
|
||||
specifically for use in, a User Product, and the conveying occurs as
|
||||
part of a transaction in which the right of possession and use of the
|
||||
User Product is transferred to the recipient in perpetuity or for a
|
||||
fixed term (regardless of how the transaction is characterized), the
|
||||
Corresponding Source conveyed under this section must be accompanied
|
||||
by the Installation Information. But this requirement does not apply
|
||||
if neither you nor any third party retains the ability to install
|
||||
modified object code on the User Product (for example, the work has
|
||||
been installed in ROM).
|
||||
|
||||
The requirement to provide Installation Information does not include a
|
||||
requirement to continue to provide support service, warranty, or updates
|
||||
for a work that has been modified or installed by the recipient, or for
|
||||
the User Product in which it has been modified or installed. Access to a
|
||||
network may be denied when the modification itself materially and
|
||||
adversely affects the operation of the network or violates the rules and
|
||||
protocols for communication across the network.
|
||||
|
||||
Corresponding Source conveyed, and Installation Information provided,
|
||||
in accord with this section must be in a format that is publicly
|
||||
documented (and with an implementation available to the public in
|
||||
source code form), and must require no special password or key for
|
||||
unpacking, reading or copying.
|
||||
|
||||
7. Additional Terms.
|
||||
|
||||
"Additional permissions" are terms that supplement the terms of this
|
||||
License by making exceptions from one or more of its conditions.
|
||||
Additional permissions that are applicable to the entire Program shall
|
||||
be treated as though they were included in this License, to the extent
|
||||
that they are valid under applicable law. If additional permissions
|
||||
apply only to part of the Program, that part may be used separately
|
||||
under those permissions, but the entire Program remains governed by
|
||||
this License without regard to the additional permissions.
|
||||
|
||||
When you convey a copy of a covered work, you may at your option
|
||||
remove any additional permissions from that copy, or from any part of
|
||||
it. (Additional permissions may be written to require their own
|
||||
removal in certain cases when you modify the work.) You may place
|
||||
additional permissions on material, added by you to a covered work,
|
||||
for which you have or can give appropriate copyright permission.
|
||||
|
||||
Notwithstanding any other provision of this License, for material you
|
||||
add to a covered work, you may (if authorized by the copyright holders of
|
||||
that material) supplement the terms of this License with terms:
|
||||
|
||||
a) Disclaiming warranty or limiting liability differently from the
|
||||
terms of sections 15 and 16 of this License; or
|
||||
|
||||
b) Requiring preservation of specified reasonable legal notices or
|
||||
author attributions in that material or in the Appropriate Legal
|
||||
Notices displayed by works containing it; or
|
||||
|
||||
c) Prohibiting misrepresentation of the origin of that material, or
|
||||
requiring that modified versions of such material be marked in
|
||||
reasonable ways as different from the original version; or
|
||||
|
||||
d) Limiting the use for publicity purposes of names of licensors or
|
||||
authors of the material; or
|
||||
|
||||
e) Declining to grant rights under trademark law for use of some
|
||||
trade names, trademarks, or service marks; or
|
||||
|
||||
f) Requiring indemnification of licensors and authors of that
|
||||
material by anyone who conveys the material (or modified versions of
|
||||
it) with contractual assumptions of liability to the recipient, for
|
||||
any liability that these contractual assumptions directly impose on
|
||||
those licensors and authors.
|
||||
|
||||
All other non-permissive additional terms are considered "further
|
||||
restrictions" within the meaning of section 10. If the Program as you
|
||||
received it, or any part of it, contains a notice stating that it is
|
||||
governed by this License along with a term that is a further
|
||||
restriction, you may remove that term. If a license document contains
|
||||
a further restriction but permits relicensing or conveying under this
|
||||
License, you may add to a covered work material governed by the terms
|
||||
of that license document, provided that the further restriction does
|
||||
not survive such relicensing or conveying.
|
||||
|
||||
If you add terms to a covered work in accord with this section, you
|
||||
must place, in the relevant source files, a statement of the
|
||||
additional terms that apply to those files, or a notice indicating
|
||||
where to find the applicable terms.
|
||||
|
||||
Additional terms, permissive or non-permissive, may be stated in the
|
||||
form of a separately written license, or stated as exceptions;
|
||||
the above requirements apply either way.
|
||||
|
||||
8. Termination.
|
||||
|
||||
You may not propagate or modify a covered work except as expressly
|
||||
provided under this License. Any attempt otherwise to propagate or
|
||||
modify it is void, and will automatically terminate your rights under
|
||||
this License (including any patent licenses granted under the third
|
||||
paragraph of section 11).
|
||||
|
||||
However, if you cease all violation of this License, then your
|
||||
license from a particular copyright holder is reinstated (a)
|
||||
provisionally, unless and until the copyright holder explicitly and
|
||||
finally terminates your license, and (b) permanently, if the copyright
|
||||
holder fails to notify you of the violation by some reasonable means
|
||||
prior to 60 days after the cessation.
|
||||
|
||||
Moreover, your license from a particular copyright holder is
|
||||
reinstated permanently if the copyright holder notifies you of the
|
||||
violation by some reasonable means, this is the first time you have
|
||||
received notice of violation of this License (for any work) from that
|
||||
copyright holder, and you cure the violation prior to 30 days after
|
||||
your receipt of the notice.
|
||||
|
||||
Termination of your rights under this section does not terminate the
|
||||
licenses of parties who have received copies or rights from you under
|
||||
this License. If your rights have been terminated and not permanently
|
||||
reinstated, you do not qualify to receive new licenses for the same
|
||||
material under section 10.
|
||||
|
||||
9. Acceptance Not Required for Having Copies.
|
||||
|
||||
You are not required to accept this License in order to receive or
|
||||
run a copy of the Program. Ancillary propagation of a covered work
|
||||
occurring solely as a consequence of using peer-to-peer transmission
|
||||
to receive a copy likewise does not require acceptance. However,
|
||||
nothing other than this License grants you permission to propagate or
|
||||
modify any covered work. These actions infringe copyright if you do
|
||||
not accept this License. Therefore, by modifying or propagating a
|
||||
covered work, you indicate your acceptance of this License to do so.
|
||||
|
||||
10. Automatic Licensing of Downstream Recipients.
|
||||
|
||||
Each time you convey a covered work, the recipient automatically
|
||||
receives a license from the original licensors, to run, modify and
|
||||
propagate that work, subject to this License. You are not responsible
|
||||
for enforcing compliance by third parties with this License.
|
||||
|
||||
An "entity transaction" is a transaction transferring control of an
|
||||
organization, or substantially all assets of one, or subdividing an
|
||||
organization, or merging organizations. If propagation of a covered
|
||||
work results from an entity transaction, each party to that
|
||||
transaction who receives a copy of the work also receives whatever
|
||||
licenses to the work the party's predecessor in interest had or could
|
||||
give under the previous paragraph, plus a right to possession of the
|
||||
Corresponding Source of the work from the predecessor in interest, if
|
||||
the predecessor has it or can get it with reasonable efforts.
|
||||
|
||||
You may not impose any further restrictions on the exercise of the
|
||||
rights granted or affirmed under this License. For example, you may
|
||||
not impose a license fee, royalty, or other charge for exercise of
|
||||
rights granted under this License, and you may not initiate litigation
|
||||
(including a cross-claim or counterclaim in a lawsuit) alleging that
|
||||
any patent claim is infringed by making, using, selling, offering for
|
||||
sale, or importing the Program or any portion of it.
|
||||
|
||||
11. Patents.
|
||||
|
||||
A "contributor" is a copyright holder who authorizes use under this
|
||||
License of the Program or a work on which the Program is based. The
|
||||
work thus licensed is called the contributor's "contributor version".
|
||||
|
||||
A contributor's "essential patent claims" are all patent claims
|
||||
owned or controlled by the contributor, whether already acquired or
|
||||
hereafter acquired, that would be infringed by some manner, permitted
|
||||
by this License, of making, using, or selling its contributor version,
|
||||
but do not include claims that would be infringed only as a
|
||||
consequence of further modification of the contributor version. For
|
||||
purposes of this definition, "control" includes the right to grant
|
||||
patent sublicenses in a manner consistent with the requirements of
|
||||
this License.
|
||||
|
||||
Each contributor grants you a non-exclusive, worldwide, royalty-free
|
||||
patent license under the contributor's essential patent claims, to
|
||||
make, use, sell, offer for sale, import and otherwise run, modify and
|
||||
propagate the contents of its contributor version.
|
||||
|
||||
In the following three paragraphs, a "patent license" is any express
|
||||
agreement or commitment, however denominated, not to enforce a patent
|
||||
(such as an express permission to practice a patent or covenant not to
|
||||
sue for patent infringement). To "grant" such a patent license to a
|
||||
party means to make such an agreement or commitment not to enforce a
|
||||
patent against the party.
|
||||
|
||||
If you convey a covered work, knowingly relying on a patent license,
|
||||
and the Corresponding Source of the work is not available for anyone
|
||||
to copy, free of charge and under the terms of this License, through a
|
||||
publicly available network server or other readily accessible means,
|
||||
then you must either (1) cause the Corresponding Source to be so
|
||||
available, or (2) arrange to deprive yourself of the benefit of the
|
||||
patent license for this particular work, or (3) arrange, in a manner
|
||||
consistent with the requirements of this License, to extend the patent
|
||||
license to downstream recipients. "Knowingly relying" means you have
|
||||
actual knowledge that, but for the patent license, your conveying the
|
||||
covered work in a country, or your recipient's use of the covered work
|
||||
in a country, would infringe one or more identifiable patents in that
|
||||
country that you have reason to believe are valid.
|
||||
|
||||
If, pursuant to or in connection with a single transaction or
|
||||
arrangement, you convey, or propagate by procuring conveyance of, a
|
||||
covered work, and grant a patent license to some of the parties
|
||||
receiving the covered work authorizing them to use, propagate, modify
|
||||
or convey a specific copy of the covered work, then the patent license
|
||||
you grant is automatically extended to all recipients of the covered
|
||||
work and works based on it.
|
||||
|
||||
A patent license is "discriminatory" if it does not include within
|
||||
the scope of its coverage, prohibits the exercise of, or is
|
||||
conditioned on the non-exercise of one or more of the rights that are
|
||||
specifically granted under this License. You may not convey a covered
|
||||
work if you are a party to an arrangement with a third party that is
|
||||
in the business of distributing software, under which you make payment
|
||||
to the third party based on the extent of your activity of conveying
|
||||
the work, and under which the third party grants, to any of the
|
||||
parties who would receive the covered work from you, a discriminatory
|
||||
patent license (a) in connection with copies of the covered work
|
||||
conveyed by you (or copies made from those copies), or (b) primarily
|
||||
for and in connection with specific products or compilations that
|
||||
contain the covered work, unless you entered into that arrangement,
|
||||
or that patent license was granted, prior to 28 March 2007.
|
||||
|
||||
Nothing in this License shall be construed as excluding or limiting
|
||||
any implied license or other defenses to infringement that may
|
||||
otherwise be available to you under applicable patent law.
|
||||
|
||||
12. No Surrender of Others' Freedom.
|
||||
|
||||
If conditions are imposed on you (whether by court order, agreement or
|
||||
otherwise) that contradict the conditions of this License, they do not
|
||||
excuse you from the conditions of this License. If you cannot convey a
|
||||
covered work so as to satisfy simultaneously your obligations under this
|
||||
License and any other pertinent obligations, then as a consequence you may
|
||||
not convey it at all. For example, if you agree to terms that obligate you
|
||||
to collect a royalty for further conveying from those to whom you convey
|
||||
the Program, the only way you could satisfy both those terms and this
|
||||
License would be to refrain entirely from conveying the Program.
|
||||
|
||||
13. Use with the GNU Affero General Public License.
|
||||
|
||||
Notwithstanding any other provision of this License, you have
|
||||
permission to link or combine any covered work with a work licensed
|
||||
under version 3 of the GNU Affero General Public License into a single
|
||||
combined work, and to convey the resulting work. The terms of this
|
||||
License will continue to apply to the part which is the covered work,
|
||||
but the special requirements of the GNU Affero General Public License,
|
||||
section 13, concerning interaction through a network will apply to the
|
||||
combination as such.
|
||||
|
||||
14. Revised Versions of this License.
|
||||
|
||||
The Free Software Foundation may publish revised and/or new versions of
|
||||
the GNU General Public License from time to time. Such new versions will
|
||||
be similar in spirit to the present version, but may differ in detail to
|
||||
address new problems or concerns.
|
||||
|
||||
Each version is given a distinguishing version number. If the
|
||||
Program specifies that a certain numbered version of the GNU General
|
||||
Public License "or any later version" applies to it, you have the
|
||||
option of following the terms and conditions either of that numbered
|
||||
version or of any later version published by the Free Software
|
||||
Foundation. If the Program does not specify a version number of the
|
||||
GNU General Public License, you may choose any version ever published
|
||||
by the Free Software Foundation.
|
||||
|
||||
If the Program specifies that a proxy can decide which future
|
||||
versions of the GNU General Public License can be used, that proxy's
|
||||
public statement of acceptance of a version permanently authorizes you
|
||||
to choose that version for the Program.
|
||||
|
||||
Later license versions may give you additional or different
|
||||
permissions. However, no additional obligations are imposed on any
|
||||
author or copyright holder as a result of your choosing to follow a
|
||||
later version.
|
||||
|
||||
15. Disclaimer of Warranty.
|
||||
|
||||
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
|
||||
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
|
||||
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
|
||||
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
|
||||
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
||||
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
|
||||
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
|
||||
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
|
||||
|
||||
16. Limitation of Liability.
|
||||
|
||||
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
|
||||
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
|
||||
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
|
||||
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
|
||||
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
|
||||
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
|
||||
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
|
||||
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
|
||||
SUCH DAMAGES.
|
||||
|
||||
17. Interpretation of Sections 15 and 16.
|
||||
|
||||
If the disclaimer of warranty and limitation of liability provided
|
||||
above cannot be given local legal effect according to their terms,
|
||||
reviewing courts shall apply local law that most closely approximates
|
||||
an absolute waiver of all civil liability in connection with the
|
||||
Program, unless a warranty or assumption of liability accompanies a
|
||||
copy of the Program in return for a fee.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
How to Apply These Terms to Your New Programs
|
||||
|
||||
If you develop a new program, and you want it to be of the greatest
|
||||
possible use to the public, the best way to achieve this is to make it
|
||||
free software which everyone can redistribute and change under these terms.
|
||||
|
||||
To do so, attach the following notices to the program. It is safest
|
||||
to attach them to the start of each source file to most effectively
|
||||
state the exclusion of warranty; and each file should have at least
|
||||
the "copyright" line and a pointer to where the full notice is found.
|
||||
|
||||
<one line to give the program's name and a brief idea of what it does.>
|
||||
Copyright (C) <year> <name of author>
|
||||
|
||||
This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation, either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||
|
||||
Also add information on how to contact you by electronic and paper mail.
|
||||
|
||||
If the program does terminal interaction, make it output a short
|
||||
notice like this when it starts in an interactive mode:
|
||||
|
||||
<program> Copyright (C) <year> <name of author>
|
||||
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
|
||||
This is free software, and you are welcome to redistribute it
|
||||
under certain conditions; type `show c' for details.
|
||||
|
||||
The hypothetical commands `show w' and `show c' should show the appropriate
|
||||
parts of the General Public License. Of course, your program's commands
|
||||
might be different; for a GUI interface, you would use an "about box".
|
||||
|
||||
You should also get your employer (if you work as a programmer) or school,
|
||||
if any, to sign a "copyright disclaimer" for the program, if necessary.
|
||||
For more information on this, and how to apply and follow the GNU GPL, see
|
||||
<https://www.gnu.org/licenses/>.
|
||||
|
||||
The GNU General Public License does not permit incorporating your program
|
||||
into proprietary programs. If your program is a subroutine library, you
|
||||
may consider it more useful to permit linking proprietary applications with
|
||||
the library. If this is what you want to do, use the GNU Lesser General
|
||||
Public License instead of this License. But first, please read
|
||||
<https://www.gnu.org/licenses/why-not-lgpl.html>.
|
||||
32
README.md
32
README.md
@@ -782,18 +782,14 @@ The LEDMatrix system includes Web Interface that runs on port 5000 and provides
|
||||
|
||||
### Installing the Web Interface Service
|
||||
|
||||
> The first-time installer (`first_time_install.sh`) already installs the
|
||||
> web service. The steps below only apply if you need to (re)install it
|
||||
> manually.
|
||||
|
||||
1. Make the install script executable:
|
||||
```bash
|
||||
chmod +x scripts/install/install_web_service.sh
|
||||
chmod +x install_web_service.sh
|
||||
```
|
||||
|
||||
2. Run the install script with sudo:
|
||||
```bash
|
||||
sudo ./scripts/install/install_web_service.sh
|
||||
sudo ./install_web_service.sh
|
||||
```
|
||||
|
||||
The script will:
|
||||
@@ -878,27 +874,3 @@ sudo systemctl enable ledmatrix-web.service
|
||||
|
||||
|
||||
### If you've read this far — thanks!
|
||||
|
||||
-----------------------------------------------------------------------------------
|
||||
|
||||
## License
|
||||
|
||||
LEDMatrix is licensed under the
|
||||
[GNU General Public License v3.0 or later](LICENSE).
|
||||
|
||||
LEDMatrix builds on
|
||||
[`rpi-rgb-led-matrix`](https://github.com/hzeller/rpi-rgb-led-matrix),
|
||||
which is GPL-2.0-or-later. The "or later" clause makes it compatible
|
||||
with GPL-3.0 distribution.
|
||||
|
||||
Plugin contributions in
|
||||
[`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins)
|
||||
are also GPL-3.0-or-later unless individual plugins specify otherwise.
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the PR
|
||||
flow, and how to add a plugin. Bug reports and feature requests go in
|
||||
the [issue tracker](https://github.com/ChuckBuilds/LEDMatrix/issues).
|
||||
Security issues should be reported privately per
|
||||
[SECURITY.md](SECURITY.md).
|
||||
|
||||
86
SECURITY.md
86
SECURITY.md
@@ -1,86 +0,0 @@
|
||||
# Security Policy
|
||||
|
||||
## Reporting a vulnerability
|
||||
|
||||
If you've found a security issue in LEDMatrix, **please don't open a
|
||||
public GitHub issue**. Disclose it privately so we can fix it before it's
|
||||
exploited.
|
||||
|
||||
### How to report
|
||||
|
||||
Use one of these channels, in order of preference:
|
||||
|
||||
1. **GitHub Security Advisories** (preferred). On the LEDMatrix repo,
|
||||
go to **Security → Advisories → Report a vulnerability**. This
|
||||
creates a private discussion thread visible only to you and the
|
||||
maintainer.
|
||||
- Direct link: <https://github.com/ChuckBuilds/LEDMatrix/security/advisories/new>
|
||||
2. **Discord DM**. Send a direct message to a moderator on the
|
||||
[LEDMatrix Discord](https://discord.gg/uW36dVAtcT). Don't post in
|
||||
public channels.
|
||||
|
||||
Please include:
|
||||
|
||||
- A description of the issue
|
||||
- The version / commit hash you're testing against
|
||||
- Steps to reproduce, ideally a minimal proof of concept
|
||||
- The impact you can demonstrate
|
||||
- Any suggested mitigation
|
||||
|
||||
### What to expect
|
||||
|
||||
- An acknowledgement within a few days (this is a hobby project, not
|
||||
a 24/7 ops team).
|
||||
- A discussion of the issue's severity and a plan for the fix.
|
||||
- Credit in the release notes when the fix ships, unless you'd
|
||||
prefer to remain anonymous.
|
||||
- For high-severity issues affecting active deployments, we'll
|
||||
coordinate disclosure timing with you.
|
||||
|
||||
## Scope
|
||||
|
||||
In scope for this policy:
|
||||
|
||||
- The LEDMatrix display controller, web interface, and plugin loader
|
||||
in this repository
|
||||
- The official plugins in
|
||||
[`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins)
|
||||
- Installation scripts and systemd unit files
|
||||
|
||||
Out of scope (please report upstream):
|
||||
|
||||
- Vulnerabilities in `rpi-rgb-led-matrix` itself —
|
||||
report to <https://github.com/hzeller/rpi-rgb-led-matrix>
|
||||
- Vulnerabilities in Python packages we depend on — report to the
|
||||
upstream package maintainer
|
||||
- Issues in third-party plugins not in `ledmatrix-plugins` — report
|
||||
to that plugin's repository
|
||||
|
||||
## Known security model
|
||||
|
||||
LEDMatrix is designed for trusted local networks. Several limitations
|
||||
are intentional rather than vulnerabilities:
|
||||
|
||||
- **No web UI authentication.** The web interface assumes the network
|
||||
it's running on is trusted. Don't expose port 5000 to the internet.
|
||||
- **Plugins run unsandboxed.** Installed plugins execute in the same
|
||||
Python process as the display loop with full file-system and
|
||||
network access. Review plugin code (especially third-party plugins
|
||||
from arbitrary GitHub URLs) before installing. The Plugin Store
|
||||
marks community plugins as **Custom** to highlight this.
|
||||
- **The display service runs as root** for hardware GPIO access. This
|
||||
is required by `rpi-rgb-led-matrix`.
|
||||
- **`config_secrets.json` is plaintext.** API keys and tokens are
|
||||
stored unencrypted on the Pi. Lock down filesystem permissions on
|
||||
the config directory if this matters for your deployment.
|
||||
|
||||
These are documented as known limitations rather than bugs. If you
|
||||
have ideas for improving them while keeping the project usable on a
|
||||
Pi, open a discussion — we're interested.
|
||||
|
||||
## Supported versions
|
||||
|
||||
LEDMatrix is rolling-release on `main`. Security fixes land on `main`
|
||||
and become available the next time users run **Update Code** from the
|
||||
web UI's Overview tab (which does a `git pull`). There are no LTS
|
||||
branches.
|
||||
@@ -437,26 +437,26 @@ When on-demand expires or is cleared, the display returns to the next highest pr
|
||||
|
||||
### Web Interface Controls
|
||||
|
||||
Each installed plugin has its own tab in the second nav row of the web
|
||||
UI. Inside the plugin's tab, scroll to **On-Demand Controls**:
|
||||
**Access:** Navigate to Settings → Plugin Management
|
||||
|
||||
- **Run On-Demand** — triggers the plugin immediately, even if it's
|
||||
disabled in the rotation
|
||||
- **Stop On-Demand** — clears on-demand and returns to the normal
|
||||
rotation
|
||||
**Controls:**
|
||||
- **Show Now Button** - Triggers plugin immediately
|
||||
- **Duration Slider** - Set display time (0 = indefinite)
|
||||
- **Pin Checkbox** - Keep showing until manually cleared
|
||||
- **Stop Button** - Clear on-demand and return to rotation
|
||||
- **Shift+Click Stop** - Stop the entire display service
|
||||
|
||||
The display service must be running. The status banner at the top of
|
||||
the plugin tab shows the active on-demand plugin, mode, and remaining
|
||||
time when something is active.
|
||||
**Status Card:**
|
||||
- Real-time status updates
|
||||
- Shows active plugin and remaining time
|
||||
- Pin status indicator
|
||||
|
||||
### REST API Reference
|
||||
|
||||
The API is mounted at `/api/v3` (`web_interface/app.py:144`).
|
||||
|
||||
#### Start On-Demand Display
|
||||
|
||||
```bash
|
||||
POST /api/v3/display/on-demand/start
|
||||
POST /api/display/on-demand/start
|
||||
|
||||
# Body:
|
||||
{
|
||||
@@ -467,20 +467,20 @@ POST /api/v3/display/on-demand/start
|
||||
|
||||
# Examples:
|
||||
# 30-second preview
|
||||
curl -X POST http://localhost:5000/api/v3/display/on-demand/start \
|
||||
curl -X POST http://localhost:5050/api/display/on-demand/start \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "weather", "duration": 30}'
|
||||
|
||||
# Pin indefinitely
|
||||
curl -X POST http://localhost:5000/api/v3/display/on-demand/start \
|
||||
curl -X POST http://localhost:5050/api/display/on-demand/start \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "hockey-scoreboard", "pinned": true}'
|
||||
-d '{"plugin_id": "hockey-scores", "pinned": true}'
|
||||
```
|
||||
|
||||
#### Stop On-Demand Display
|
||||
|
||||
```bash
|
||||
POST /api/v3/display/on-demand/stop
|
||||
POST /api/display/on-demand/stop
|
||||
|
||||
# Body:
|
||||
{
|
||||
@@ -489,10 +489,10 @@ POST /api/v3/display/on-demand/stop
|
||||
|
||||
# Examples:
|
||||
# Clear on-demand
|
||||
curl -X POST http://localhost:5000/api/v3/display/on-demand/stop
|
||||
curl -X POST http://localhost:5050/api/display/on-demand/stop
|
||||
|
||||
# Stop service too
|
||||
curl -X POST http://localhost:5000/api/v3/display/on-demand/stop \
|
||||
curl -X POST http://localhost:5050/api/display/on-demand/stop \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"stop_service": true}'
|
||||
```
|
||||
@@ -500,10 +500,10 @@ curl -X POST http://localhost:5000/api/v3/display/on-demand/stop \
|
||||
#### Get On-Demand Status
|
||||
|
||||
```bash
|
||||
GET /api/v3/display/on-demand/status
|
||||
GET /api/display/on-demand/status
|
||||
|
||||
# Example:
|
||||
curl http://localhost:5000/api/v3/display/on-demand/status
|
||||
curl http://localhost:5050/api/display/on-demand/status
|
||||
|
||||
# Response:
|
||||
{
|
||||
@@ -516,15 +516,35 @@ curl http://localhost:5000/api/v3/display/on-demand/status
|
||||
}
|
||||
```
|
||||
|
||||
> There is no public Python on-demand API. The display controller's
|
||||
> on-demand machinery is internal — drive it through the REST endpoints
|
||||
> above (or the web UI buttons), which write a request into the cache
|
||||
> manager under the `display_on_demand_request` key
|
||||
> (`web_interface/blueprints/api_v3.py:1622,1687`) that the controller
|
||||
> polls at `src/display_controller.py:921`. A separate
|
||||
> `display_on_demand_config` key is used by the controller itself
|
||||
> during activation to track what's currently running (written at
|
||||
> `display_controller.py:1195`, cleared at `:1221`).
|
||||
### Python API Methods
|
||||
|
||||
```python
|
||||
from src.display_controller import DisplayController
|
||||
|
||||
controller = DisplayController()
|
||||
|
||||
# Show plugin for 30 seconds
|
||||
controller.show_on_demand('weather', duration=30)
|
||||
|
||||
# Pin plugin until manually cleared
|
||||
controller.show_on_demand('hockey-scores', pinned=True)
|
||||
|
||||
# Show indefinitely (not pinned, clears on expiry if duration set later)
|
||||
controller.show_on_demand('weather', duration=0)
|
||||
|
||||
# Use plugin's default duration
|
||||
controller.show_on_demand('weather')
|
||||
|
||||
# Clear on-demand
|
||||
controller.clear_on_demand()
|
||||
|
||||
# Check status
|
||||
is_active = controller.is_on_demand_active()
|
||||
|
||||
# Get detailed info
|
||||
info = controller.get_on_demand_info()
|
||||
# Returns: {'active': bool, 'mode': str, 'duration': float, 'remaining': float, 'pinned': bool}
|
||||
```
|
||||
|
||||
### Duration Modes
|
||||
|
||||
@@ -537,31 +557,27 @@ curl http://localhost:5000/api/v3/display/on-demand/status
|
||||
|
||||
### Use Case Examples
|
||||
|
||||
**Quick check (30-second preview):**
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/v3/display/on-demand/start \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "ledmatrix-weather", "duration": 30}'
|
||||
**Quick Check (30-second preview):**
|
||||
```python
|
||||
controller.show_on_demand('weather', duration=30)
|
||||
```
|
||||
|
||||
**Pin important information:**
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/v3/display/on-demand/start \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "hockey-scoreboard", "pinned": true}'
|
||||
**Pin Important Information:**
|
||||
```python
|
||||
controller.show_on_demand('game-score', pinned=True)
|
||||
# ... later ...
|
||||
curl -X POST http://localhost:5000/api/v3/display/on-demand/stop
|
||||
controller.clear_on_demand()
|
||||
```
|
||||
|
||||
**Indefinite display:**
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/v3/display/on-demand/start \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "text-display", "duration": 0}'
|
||||
**Indefinite Display:**
|
||||
```python
|
||||
controller.show_on_demand('welcome-message', duration=0)
|
||||
```
|
||||
|
||||
**Testing a plugin during development:** the same call works, or just
|
||||
click **Run On-Demand** in the plugin's tab.
|
||||
**Testing Plugin:**
|
||||
```python
|
||||
controller.show_on_demand('my-new-plugin', duration=60)
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
|
||||
@@ -597,10 +613,7 @@ click **Run On-Demand** in the plugin's tab.
|
||||
|
||||
### Overview
|
||||
|
||||
On-demand display uses cache keys (managed by `src/cache_manager.py` —
|
||||
file-based, not Redis) to coordinate state between the web interface
|
||||
and the display controller across service restarts. Understanding these
|
||||
keys helps troubleshoot stuck states.
|
||||
On-demand display uses Redis cache keys to manage state across service restarts and coordinate between web interface and display controller. Understanding these keys helps troubleshoot stuck states.
|
||||
|
||||
### Cache Keys
|
||||
|
||||
@@ -675,26 +688,19 @@ keys helps troubleshoot stuck states.
|
||||
### Manual Recovery Procedures
|
||||
|
||||
**Via Web Interface (Recommended):**
|
||||
1. Open the **Cache** tab in the web UI
|
||||
2. Find the `display_on_demand_*` entries
|
||||
3. Delete them
|
||||
4. Restart display: `sudo systemctl restart ledmatrix`
|
||||
1. Navigate to Settings → Cache Management
|
||||
2. Search for "on_demand" keys
|
||||
3. Select keys to delete
|
||||
4. Click "Delete Selected"
|
||||
5. Restart display: `sudo systemctl restart ledmatrix`
|
||||
|
||||
**Via Command Line:**
|
||||
|
||||
The cache is stored as JSON files under one of:
|
||||
|
||||
- `/var/cache/ledmatrix/` (preferred when the service has permission)
|
||||
- `~/.cache/ledmatrix/`
|
||||
- `/opt/ledmatrix/cache/`
|
||||
- `/tmp/ledmatrix-cache/` (fallback)
|
||||
|
||||
```bash
|
||||
# Find the cache dir actually in use
|
||||
journalctl -u ledmatrix | grep -i "cache directory" | tail -1
|
||||
# Clear specific key
|
||||
redis-cli DEL display_on_demand_config
|
||||
|
||||
# Clear all on-demand keys (replace path with the one above)
|
||||
rm /var/cache/ledmatrix/display_on_demand_*
|
||||
# Clear all on-demand keys
|
||||
redis-cli KEYS "display_on_demand_*" | xargs redis-cli DEL
|
||||
|
||||
# Restart service
|
||||
sudo systemctl restart ledmatrix
|
||||
@@ -705,22 +711,19 @@ sudo systemctl restart ledmatrix
|
||||
from src.cache_manager import CacheManager
|
||||
|
||||
cache = CacheManager()
|
||||
cache.clear_cache('display_on_demand_config')
|
||||
cache.clear_cache('display_on_demand_state')
|
||||
cache.clear_cache('display_on_demand_request')
|
||||
cache.clear_cache('display_on_demand_processed_id')
|
||||
cache.delete('display_on_demand_config')
|
||||
cache.delete('display_on_demand_state')
|
||||
cache.delete('display_on_demand_request')
|
||||
cache.delete('display_on_demand_processed_id')
|
||||
```
|
||||
|
||||
> The actual public method is `clear_cache(key=None)` — there is no
|
||||
> `delete()` method on `CacheManager`.
|
||||
|
||||
### Cache Impact on Running Service
|
||||
|
||||
**IMPORTANT:** Clearing cache keys does NOT immediately affect the running controller in memory.
|
||||
|
||||
**To fully reset:**
|
||||
1. Stop the service: `sudo systemctl stop ledmatrix`
|
||||
2. Clear cache keys (web UI Cache tab or `rm` from the cache directory)
|
||||
2. Clear cache keys (web UI or redis-cli)
|
||||
3. Clear systemd environment: `sudo systemctl daemon-reload`
|
||||
4. Start the service: `sudo systemctl start ledmatrix`
|
||||
|
||||
@@ -764,7 +767,7 @@ Enable background service per plugin in `config/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"football-scoreboard": {
|
||||
"nfl_scoreboard": {
|
||||
"enabled": true,
|
||||
"background_service": {
|
||||
"enabled": true,
|
||||
@@ -798,13 +801,19 @@ Enable background service per plugin in `config/config.json`:
|
||||
- Returns immediately: < 0.1 seconds
|
||||
- Background refresh (if stale): async, no blocking
|
||||
|
||||
### Plugins using the background service
|
||||
### Implementation Status
|
||||
|
||||
The background data service is used by all of the sports scoreboard
|
||||
plugins (football, hockey, baseball/MLB, basketball, soccer, lacrosse,
|
||||
F1, UFC), the odds ticker, and the leaderboard plugin. Each plugin's
|
||||
`background_service` block (under its own config namespace) follows the
|
||||
same shape as the example above.
|
||||
**Phase 1 (Complete):**
|
||||
- ✅ NFL scoreboard implemented
|
||||
- ✅ Background threading architecture
|
||||
- ✅ Cache integration
|
||||
- ✅ Error handling and retry logic
|
||||
|
||||
**Phase 2 (Planned):**
|
||||
- ⏳ NCAAFB (college football)
|
||||
- ⏳ NBA (basketball)
|
||||
- ⏳ NHL (hockey)
|
||||
- ⏳ MLB (baseball)
|
||||
|
||||
### Error Handling & Fallback
|
||||
|
||||
|
||||
@@ -250,29 +250,19 @@ WARNING - Plugin ID 'Football-Scoreboard' may conflict with 'football-scoreboard
|
||||
|
||||
## Checking Configuration via API
|
||||
|
||||
The API blueprint mounts at `/api/v3` (`web_interface/app.py:144`).
|
||||
|
||||
```bash
|
||||
# Get full main config (includes all plugin sections)
|
||||
curl http://localhost:5000/api/v3/config/main
|
||||
# Get current config
|
||||
curl http://localhost:5000/api/v3/config
|
||||
|
||||
# Save updated main config
|
||||
curl -X POST http://localhost:5000/api/v3/config/main \
|
||||
# Get specific plugin config
|
||||
curl http://localhost:5000/api/v3/config/plugin/football-scoreboard
|
||||
|
||||
# Validate config without saving
|
||||
curl -X POST http://localhost:5000/api/v3/config/validate \
|
||||
-H "Content-Type: application/json" \
|
||||
-d @new-config.json
|
||||
|
||||
# Get config schema for a specific plugin
|
||||
curl "http://localhost:5000/api/v3/plugins/schema?plugin_id=football-scoreboard"
|
||||
|
||||
# Get a single plugin's current config
|
||||
curl "http://localhost:5000/api/v3/plugins/config?plugin_id=football-scoreboard"
|
||||
-d '{"football-scoreboard": {"enabled": true}}'
|
||||
```
|
||||
|
||||
> There is no dedicated `/config/plugin/<id>` or `/config/validate`
|
||||
> endpoint — config validation runs server-side automatically when you
|
||||
> POST to `/config/main` or `/plugins/config`. See
|
||||
> [REST_API_REFERENCE.md](REST_API_REFERENCE.md) for the full list.
|
||||
|
||||
## Backup and Recovery
|
||||
|
||||
### Manual Backup
|
||||
|
||||
@@ -62,7 +62,7 @@ display_manager.defer_update(lambda: self.update_cache(), priority=0)
|
||||
# Basic caching
|
||||
cached = cache_manager.get("key", max_age=3600)
|
||||
cache_manager.set("key", data)
|
||||
cache_manager.clear_cache("key") # there is no delete() method
|
||||
cache_manager.delete("key")
|
||||
|
||||
# Advanced caching
|
||||
data = cache_manager.get_cached_data_with_strategy("key", data_type="weather")
|
||||
|
||||
@@ -141,27 +141,19 @@ stage('Checkout') {
|
||||
|
||||
---
|
||||
|
||||
## Plugins
|
||||
## Plugin Submodules
|
||||
|
||||
Plugins are **not** git submodules of this repository. The plugins
|
||||
directory (configured by `plugin_system.plugins_directory` in
|
||||
`config/config.json`, default `plugin-repos/`) is populated at install
|
||||
time by the plugin loader as users install plugins from the Plugin Store
|
||||
or from a GitHub URL via the web interface. Plugin source lives in a
|
||||
separate repository:
|
||||
[ChuckBuilds/ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins).
|
||||
Plugin submodules are located in the `plugins/` directory and are managed similarly:
|
||||
|
||||
To work on a plugin locally without going through the Plugin Store, clone
|
||||
that repo and symlink (or copy) the plugin directory into your configured
|
||||
plugins directory — by default `plugin-repos/<plugin-id>/`. The plugin
|
||||
loader will pick it up on the next display restart. The directory name
|
||||
must match the plugin's `id` in `manifest.json`.
|
||||
**Initialize all plugin submodules:**
|
||||
```bash
|
||||
git submodule update --init --recursive plugins/
|
||||
```
|
||||
|
||||
For more information, see:
|
||||
**Initialize a specific plugin:**
|
||||
```bash
|
||||
git submodule update --init --recursive plugins/hockey-scoreboard
|
||||
```
|
||||
|
||||
For more information about plugins, see the [Plugin Development Guide](.cursor/plugins_guide.md) and [Plugin Architecture Specification](docs/PLUGIN_ARCHITECTURE_SPEC.md).
|
||||
|
||||
- [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md) — end-to-end
|
||||
plugin development workflow
|
||||
- [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md) — plugin system
|
||||
specification
|
||||
- [DEV_PREVIEW.md](DEV_PREVIEW.md) — preview plugins on a desktop without a
|
||||
Pi
|
||||
|
||||
@@ -32,15 +32,10 @@ The LEDMatrix emulator allows you to run and test LEDMatrix displays on your com
|
||||
### 1. Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone --recurse-submodules https://github.com/ChuckBuilds/LEDMatrix.git
|
||||
git clone https://github.com/your-username/LEDMatrix.git
|
||||
cd LEDMatrix
|
||||
```
|
||||
|
||||
> The emulator does **not** require building the
|
||||
> `rpi-rgb-led-matrix-master` submodule (it uses `RGBMatrixEmulator`
|
||||
> instead), so `--recurse-submodules` is optional here. Run it anyway if
|
||||
> you also want to test the real-hardware code path.
|
||||
|
||||
### 2. Install Emulator Dependencies
|
||||
|
||||
Install the emulator-specific requirements:
|
||||
@@ -63,13 +58,12 @@ pip install -r requirements.txt
|
||||
|
||||
### 1. Emulator Configuration File
|
||||
|
||||
The emulator uses `emulator_config.json` for configuration. Here's the
|
||||
default configuration as it ships in the repo:
|
||||
The emulator uses `emulator_config.json` for configuration. Here's the default configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"pixel_outline": 0,
|
||||
"pixel_size": 5,
|
||||
"pixel_size": 16,
|
||||
"pixel_style": "square",
|
||||
"pixel_glow": 6,
|
||||
"display_adapter": "pygame",
|
||||
@@ -96,7 +90,7 @@ default configuration as it ships in the repo:
|
||||
| Option | Description | Default | Values |
|
||||
|--------|-------------|---------|--------|
|
||||
| `pixel_outline` | Pixel border thickness | 0 | 0-5 |
|
||||
| `pixel_size` | Size of each pixel | 5 | 1-64 (8–16 is typical for testing) |
|
||||
| `pixel_size` | Size of each pixel | 16 | 8-64 |
|
||||
| `pixel_style` | Pixel shape | "square" | "square", "circle" |
|
||||
| `pixel_glow` | Glow effect intensity | 6 | 0-20 |
|
||||
| `display_adapter` | Display backend | "pygame" | "pygame", "browser" |
|
||||
|
||||
@@ -138,29 +138,7 @@ font = self.font_manager.resolve_font(
|
||||
|
||||
## For Plugin Developers
|
||||
|
||||
> ⚠️ **Status**: the plugin-font registration described below is
|
||||
> implemented in `src/font_manager.py:150` (`register_plugin_fonts()`)
|
||||
> but is **not currently wired into the plugin loader**. Adding a
|
||||
> `"fonts"` block to your plugin's `manifest.json` will silently have
|
||||
> no effect — the FontManager method exists but nothing calls it.
|
||||
>
|
||||
> Until that's connected, plugin authors who need a custom font
|
||||
> should load it directly with PIL (or `freetype-py` for BDF) in
|
||||
> their plugin's `manager.py` — `FontManager.resolve_font(family=…,
|
||||
> size_px=…)` takes a **family name**, not a file path, so it can't
|
||||
> be used to pull a font from your plugin directory. The
|
||||
> `plugin://…` source URIs described below are only honored by
|
||||
> `register_plugin_fonts()` itself, which isn't wired up.
|
||||
>
|
||||
> The `/api/v3/fonts/overrides` endpoints and the **Fonts** tab in
|
||||
> the web UI are currently **placeholder implementations** — they
|
||||
> return empty arrays and contain "would integrate with the actual
|
||||
> font system" comments. Manually registered manager fonts do
|
||||
> **not** yet flow into that tab. If you need an override today,
|
||||
> load the font directly in your plugin and skip the
|
||||
> override system.
|
||||
|
||||
### Plugin Font Registration (planned)
|
||||
### Plugin Font Registration
|
||||
|
||||
In your plugin's `manifest.json`:
|
||||
|
||||
@@ -381,8 +359,5 @@ self.font = self.font_manager.resolve_font(
|
||||
|
||||
## Example: Complete Manager Implementation
|
||||
|
||||
For a working example of the font manager API in use, see
|
||||
`src/font_manager.py` itself and the bundled scoreboard base classes
|
||||
in `src/base_classes/` (e.g., `hockey.py`, `football.py`) which
|
||||
register and resolve fonts via the patterns documented above.
|
||||
See `test/font_manager_example.py` for a complete working example.
|
||||
|
||||
|
||||
@@ -39,7 +39,7 @@ This guide will help you set up your LEDMatrix display for the first time and ge
|
||||
|
||||
**If you see "LEDMatrix-Setup" WiFi network:**
|
||||
1. Connect your device to "LEDMatrix-Setup" (open network, no password)
|
||||
2. Open browser to: `http://192.168.4.1:5000`
|
||||
2. Open browser to: `http://192.168.4.1:5050`
|
||||
3. Navigate to the WiFi tab
|
||||
4. Click "Scan" to find your WiFi network
|
||||
5. Select your network, enter password
|
||||
@@ -48,14 +48,14 @@ This guide will help you set up your LEDMatrix display for the first time and ge
|
||||
|
||||
**If already connected to WiFi:**
|
||||
1. Find your Pi's IP address (check your router, or run `hostname -I` on the Pi)
|
||||
2. Open browser to: `http://your-pi-ip:5000`
|
||||
2. Open browser to: `http://your-pi-ip:5050`
|
||||
|
||||
### 3. Access the Web Interface
|
||||
|
||||
Once connected, access the web interface:
|
||||
|
||||
```
|
||||
http://your-pi-ip:5000
|
||||
http://your-pi-ip:5050
|
||||
```
|
||||
|
||||
You should see:
|
||||
@@ -69,84 +69,84 @@ You should see:
|
||||
|
||||
### Step 1: Configure Display Hardware
|
||||
|
||||
1. Open the **Display** tab
|
||||
1. Navigate to Settings → **Display Settings**
|
||||
2. Set your matrix configuration:
|
||||
- **Rows**: 32 or 64 (match your hardware)
|
||||
- **Columns**: commonly 64 or 96; the web UI accepts any integer
|
||||
in the 16–128 range, but 64 and 96 are the values the bundled
|
||||
panel hardware ships with
|
||||
- **Chain Length**: Number of panels chained horizontally
|
||||
- **Hardware Mapping**: usually `adafruit-hat-pwm` (with the PWM jumper
|
||||
mod) or `adafruit-hat` (without). See the root README for the full list.
|
||||
- **Brightness**: 70–90 is fine for indoor use
|
||||
3. Click **Save**
|
||||
4. From the **Overview** tab, click **Restart Display Service** to apply
|
||||
- **Columns**: 64, 128, or 256 (match your hardware)
|
||||
- **Chain Length**: Number of panels chained together
|
||||
- **Brightness**: 50-75% recommended for indoor use
|
||||
3. Click **Save Configuration**
|
||||
4. Click **Restart Display** to apply changes
|
||||
|
||||
**Tip:** if the display shows garbage or nothing, the most common culprits
|
||||
are an incorrect `hardware_mapping`, a `gpio_slowdown` value that doesn't
|
||||
match your Pi model, or panels needing the E-line mod. See
|
||||
[TROUBLESHOOTING.md](TROUBLESHOOTING.md).
|
||||
**Tip:** If the display doesn't look right, try different hardware mapping options.
|
||||
|
||||
### Step 2: Set Timezone and Location
|
||||
|
||||
1. Open the **General** tab
|
||||
2. Set your timezone (e.g., `America/New_York`) and location
|
||||
3. Click **Save**
|
||||
1. Navigate to Settings → **General Settings**
|
||||
2. Set your timezone (e.g., "America/New_York")
|
||||
3. Set your location (city, state, country)
|
||||
4. Click **Save Configuration**
|
||||
|
||||
Correct timezone ensures accurate time display, and location is used by
|
||||
weather and other location-aware plugins.
|
||||
**Why it matters:** Correct timezone ensures accurate time display. Location enables weather and location-based features.
|
||||
|
||||
### Step 3: Install Plugins
|
||||
|
||||
1. Open the **Plugin Manager** tab
|
||||
2. Scroll to the **Plugin Store** section to browse available plugins
|
||||
3. Click **Install** on the plugins you want
|
||||
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**
|
||||
1. Navigate to **Plugin Store** tab
|
||||
2. Browse available plugins:
|
||||
- **Time & Date**: Clock, calendar
|
||||
- **Weather**: Weather forecasts
|
||||
- **Sports**: NHL, NBA, NFL, MLB scores
|
||||
- **Finance**: Stocks, crypto
|
||||
- **Custom**: Community plugins
|
||||
3. Click **Install** on desired plugins
|
||||
4. Wait for installation to complete
|
||||
5. Navigate to **Plugin Management** tab
|
||||
6. Enable installed plugins (toggle switch)
|
||||
7. Click **Restart Display**
|
||||
|
||||
You can also install community plugins straight from a GitHub URL using the
|
||||
**Install from GitHub** section further down the same tab — see
|
||||
[PLUGIN_STORE_GUIDE.md](PLUGIN_STORE_GUIDE.md) for details.
|
||||
**Popular First Plugins:**
|
||||
- `clock-simple` - Simple digital clock
|
||||
- `weather` - Weather forecast
|
||||
- `nhl-scores` - NHL scores (if you're a hockey fan)
|
||||
|
||||
### Step 4: Configure Plugins
|
||||
|
||||
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, display duration, etc.)
|
||||
3. Click **Save**
|
||||
4. Restart the display service from **Overview** so the new settings take
|
||||
effect
|
||||
1. Navigate to **Plugin Management** tab
|
||||
2. Find a plugin you installed
|
||||
3. Click the ⚙️ **Configure** button
|
||||
4. Edit settings (e.g., favorite teams, update intervals)
|
||||
5. Click **Save**
|
||||
6. Click **Restart Display**
|
||||
|
||||
**Example: Weather Plugin**
|
||||
- Set your location (city, state, country)
|
||||
- Add an API key from OpenWeatherMap (free signup) to
|
||||
`config/config_secrets.json` or directly in the plugin's config screen
|
||||
- Set the update interval (300 seconds is reasonable)
|
||||
- Add API key from OpenWeatherMap (free signup)
|
||||
- Set update interval (300 seconds recommended)
|
||||
|
||||
---
|
||||
|
||||
## Testing Your Display
|
||||
|
||||
### Run a single plugin on demand
|
||||
### Quick Test
|
||||
|
||||
The fastest way to verify a plugin works without waiting for the rotation:
|
||||
1. Navigate to **Overview** tab
|
||||
2. Click **Test Display** button
|
||||
3. You should see a test pattern on your LED matrix
|
||||
|
||||
1. Open the plugin's tab (second nav row)
|
||||
2. Scroll to **On-Demand Controls**
|
||||
3. Click **Run On-Demand** — the plugin runs immediately even if disabled
|
||||
4. Click **Stop On-Demand** to return to the normal rotation
|
||||
### Manual Plugin Trigger
|
||||
|
||||
### Check the live preview and logs
|
||||
1. Navigate to **Plugin Management** tab
|
||||
2. Find a plugin
|
||||
3. Click **Show Now** button
|
||||
4. The plugin should display immediately
|
||||
5. Click **Stop** to return to rotation
|
||||
|
||||
- The **Overview** tab shows a **Live Display Preview** that mirrors what's
|
||||
on the matrix in real time — handy for debugging without looking at the
|
||||
panel.
|
||||
- The **Logs** tab streams the display and web service logs. Look for
|
||||
`ERROR` lines if something isn't working; normal operation just shows
|
||||
`INFO` messages about plugin rotation.
|
||||
### Check Logs
|
||||
|
||||
1. Navigate to **Logs** tab
|
||||
2. Watch real-time logs
|
||||
3. Look for any ERROR messages
|
||||
4. Normal operation shows INFO messages about plugin rotation
|
||||
|
||||
---
|
||||
|
||||
@@ -156,12 +156,12 @@ The fastest way to verify a plugin works without waiting for the rotation:
|
||||
|
||||
**Check:**
|
||||
1. Power supply connected and adequate (5V, 4A minimum)
|
||||
2. LED matrix connected to the bonnet/HAT correctly
|
||||
2. LED matrix connected to GPIO pins correctly
|
||||
3. Display service running: `sudo systemctl status ledmatrix`
|
||||
4. Hardware configuration matches your matrix (rows/cols/chain length)
|
||||
4. Hardware configuration matches your matrix (rows/columns)
|
||||
|
||||
**Fix:**
|
||||
1. Restart from the **Overview** tab → **Restart Display Service**
|
||||
1. Restart display: Settings → Overview → Restart Display
|
||||
2. Or via SSH: `sudo systemctl restart ledmatrix`
|
||||
|
||||
### Web Interface Won't Load
|
||||
@@ -169,8 +169,8 @@ The fastest way to verify a plugin works without waiting for the rotation:
|
||||
**Check:**
|
||||
1. Pi is connected to network: `ping your-pi-ip`
|
||||
2. Web service running: `sudo systemctl status ledmatrix-web`
|
||||
3. Correct port: the web UI listens on `:5000`
|
||||
4. Firewall not blocking port 5000
|
||||
3. Correct port: Use `:5050` not `:5000`
|
||||
4. Firewall not blocking port 5050
|
||||
|
||||
**Fix:**
|
||||
1. Restart web service: `sudo systemctl restart ledmatrix-web`
|
||||
@@ -179,15 +179,15 @@ The fastest way to verify a plugin works without waiting for the rotation:
|
||||
### Plugins Not Showing
|
||||
|
||||
**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
|
||||
1. Plugins are enabled (toggle switch in Plugin Management)
|
||||
2. Display has been restarted after enabling
|
||||
3. Plugin duration is reasonable (not too short)
|
||||
4. No errors in logs for the plugin
|
||||
|
||||
**Fix:**
|
||||
1. Enable the plugin from **Plugin Manager**
|
||||
2. Click **Restart Display Service** on **Overview**
|
||||
3. Check the **Logs** tab for plugin-specific errors
|
||||
1. Enable plugin in Plugin Management
|
||||
2. Restart display
|
||||
3. Check logs for plugin-specific errors
|
||||
|
||||
### Weather Plugin Shows "No Data"
|
||||
|
||||
@@ -207,18 +207,18 @@ The fastest way to verify a plugin works without waiting for the rotation:
|
||||
|
||||
### Customize Your Display
|
||||
|
||||
**Adjust display durations:**
|
||||
- Each plugin's tab has a **Display Duration (seconds)** field — set how
|
||||
long that plugin stays on screen each rotation.
|
||||
**Adjust Display Durations:**
|
||||
- Navigate to Settings → Durations
|
||||
- Set how long each plugin displays
|
||||
- Save and restart
|
||||
|
||||
**Organize plugin order:**
|
||||
- Use the **Plugin Manager** tab to enable/disable plugins. The display
|
||||
cycles through enabled plugins in the order they appear.
|
||||
**Organize Plugin Order:**
|
||||
- Use Plugin Management to enable/disable plugins
|
||||
- Display cycles through enabled plugins in order
|
||||
|
||||
**Add more plugins:**
|
||||
- Check the **Plugin Store** section of **Plugin Manager** for new plugins.
|
||||
- Install community plugins straight from a GitHub URL via
|
||||
**Install from GitHub** on the same tab.
|
||||
**Add More Plugins:**
|
||||
- Check Plugin Store regularly for new plugins
|
||||
- Install from GitHub URLs for custom/community plugins
|
||||
|
||||
### Enable Advanced Features
|
||||
|
||||
@@ -279,39 +279,26 @@ sudo journalctl -u ledmatrix-web -f
|
||||
│ ├── config.json # Main configuration
|
||||
│ ├── config_secrets.json # API keys and secrets
|
||||
│ └── wifi_config.json # WiFi settings
|
||||
├── plugin-repos/ # Installed plugins (default location)
|
||||
├── plugins/ # Installed plugins
|
||||
├── cache/ # Cached data
|
||||
└── web_interface/ # Web interface files
|
||||
```
|
||||
|
||||
> The plugin install location is configurable via
|
||||
> `plugin_system.plugins_directory` in `config.json`. The default is
|
||||
> `plugin-repos/`. Plugin discovery (`PluginManager.discover_plugins()`)
|
||||
> only scans the configured directory — it does not fall back to
|
||||
> `plugins/`. However, the Plugin Store install/update path and the
|
||||
> web UI's schema loader do also probe `plugins/` so the dev symlinks
|
||||
> created by `scripts/dev/dev_plugin_setup.sh` keep working.
|
||||
|
||||
### Web Interface
|
||||
|
||||
```
|
||||
Main Interface: http://your-pi-ip:5000
|
||||
Main Interface: http://your-pi-ip:5050
|
||||
|
||||
System tabs:
|
||||
- Overview System stats, live preview, quick actions
|
||||
- General Timezone, location, plugin-system settings
|
||||
- WiFi Network selection and AP-mode setup
|
||||
- Schedule Power and dim schedules
|
||||
- Display Matrix hardware configuration
|
||||
- Config Editor Raw config.json editor
|
||||
- Fonts Upload and manage fonts
|
||||
- Logs Real-time log viewing
|
||||
- Cache Cached data inspection and cleanup
|
||||
- Operation History Recent service operations
|
||||
|
||||
Plugin tabs (second row):
|
||||
- Plugin Manager Browse the Plugin Store, install/enable plugins
|
||||
- <plugin-id> One tab per installed plugin for its config
|
||||
Tabs:
|
||||
- Overview: System stats and quick actions
|
||||
- General Settings: Timezone, location, autostart
|
||||
- Display Settings: Hardware configuration
|
||||
- Durations: Plugin display times
|
||||
- Sports Configuration: Per-league settings
|
||||
- Plugin Management: Enable/disable, configure
|
||||
- Plugin Store: Install new plugins
|
||||
- Font Management: Upload and manage fonts
|
||||
- Logs: Real-time log viewing
|
||||
```
|
||||
|
||||
### WiFi Access Point
|
||||
@@ -319,7 +306,7 @@ Plugin tabs (second row):
|
||||
```
|
||||
Network Name: LEDMatrix-Setup
|
||||
Password: (none - open network)
|
||||
URL when connected: http://192.168.4.1:5000
|
||||
URL when connected: http://192.168.4.1:5050
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -13,7 +13,7 @@ Make sure you have the testing packages installed:
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Or install just the test dependencies
|
||||
pip install pytest pytest-cov pytest-mock
|
||||
pip install pytest pytest-cov pytest-mock pytest-timeout
|
||||
```
|
||||
|
||||
### 2. Set Environment Variables
|
||||
@@ -85,14 +85,8 @@ pytest -m slow
|
||||
# Run all tests in the test directory
|
||||
pytest test/
|
||||
|
||||
# Run plugin tests only
|
||||
pytest test/plugins/
|
||||
|
||||
# Run web interface tests only
|
||||
pytest test/web_interface/
|
||||
|
||||
# Run web interface integration tests
|
||||
pytest test/web_interface/integration/
|
||||
# Run all integration tests
|
||||
pytest test/integration/
|
||||
```
|
||||
|
||||
## Understanding Test Output
|
||||
@@ -237,41 +231,20 @@ pytest --maxfail=3
|
||||
|
||||
```
|
||||
test/
|
||||
├── conftest.py # Shared fixtures and configuration
|
||||
├── test_display_controller.py # Display controller tests
|
||||
├── test_display_manager.py # Display manager tests
|
||||
├── test_plugin_system.py # Plugin system tests
|
||||
├── test_plugin_loader.py # Plugin discovery/loading tests
|
||||
├── test_plugin_loading_failures.py # Plugin failure-mode tests
|
||||
├── test_cache_manager.py # Cache manager tests
|
||||
├── test_config_manager.py # Config manager tests
|
||||
├── test_config_service.py # Config service tests
|
||||
├── test_config_validation_edge_cases.py # Config edge cases
|
||||
├── test_font_manager.py # Font manager tests
|
||||
├── test_layout_manager.py # Layout manager tests
|
||||
├── test_text_helper.py # Text helper tests
|
||||
├── test_error_handling.py # Error handling tests
|
||||
├── test_error_aggregator.py # Error aggregation tests
|
||||
├── test_schema_manager.py # Schema manager tests
|
||||
├── test_web_api.py # Web API tests
|
||||
├── test_nba_*.py # NBA-specific test suites
|
||||
├── plugins/ # Per-plugin test suites
|
||||
│ ├── test_clock_simple.py
|
||||
│ ├── test_calendar.py
|
||||
│ ├── test_basketball_scoreboard.py
|
||||
│ ├── test_soccer_scoreboard.py
|
||||
│ ├── test_odds_ticker.py
|
||||
│ ├── test_text_display.py
|
||||
│ ├── test_visual_rendering.py
|
||||
│ └── test_plugin_base.py
|
||||
└── web_interface/
|
||||
├── test_config_manager_atomic.py
|
||||
├── test_state_reconciliation.py
|
||||
├── test_plugin_operation_queue.py
|
||||
├── test_dedup_unique_arrays.py
|
||||
└── integration/ # Web interface integration tests
|
||||
├── test_config_flows.py
|
||||
└── test_plugin_operations.py
|
||||
├── conftest.py # Shared fixtures and configuration
|
||||
├── test_display_controller.py # Display controller tests
|
||||
├── test_plugin_system.py # Plugin system tests
|
||||
├── test_display_manager.py # Display manager tests
|
||||
├── test_config_service.py # Config service tests
|
||||
├── test_cache_manager.py # Cache manager tests
|
||||
├── test_font_manager.py # Font manager tests
|
||||
├── test_error_handling.py # Error handling tests
|
||||
├── test_config_manager.py # Config manager tests
|
||||
├── integration/ # Integration tests
|
||||
│ ├── test_e2e.py # End-to-end tests
|
||||
│ └── test_plugin_integration.py # Plugin integration tests
|
||||
├── test_error_scenarios.py # Error scenario tests
|
||||
└── test_edge_cases.py # Edge case tests
|
||||
```
|
||||
|
||||
### Test Categories
|
||||
@@ -336,15 +309,11 @@ pytest --cov=src --cov-report=html
|
||||
|
||||
## Continuous Integration
|
||||
|
||||
There is currently no CI test workflow in this repo — `pytest` runs
|
||||
locally but is not gated on PRs. The only GitHub Actions workflow is
|
||||
[`.github/workflows/security-audit.yml`](../.github/workflows/security-audit.yml),
|
||||
which runs bandit and semgrep on every push.
|
||||
Tests are configured to run automatically in CI/CD. The GitHub Actions workflow (`.github/workflows/tests.yml`) runs:
|
||||
|
||||
If you'd like to add a test workflow, the recommended setup is a
|
||||
`.github/workflows/tests.yml` that runs `pytest` against the
|
||||
supported Python versions (3.10, 3.11, 3.12, 3.13 per
|
||||
`requirements.txt`). Open an issue or PR if you want to contribute it.
|
||||
- All tests on multiple Python versions (3.10, 3.11, 3.12)
|
||||
- Coverage reporting
|
||||
- Uploads coverage to Codecov (if configured)
|
||||
|
||||
## Best Practices
|
||||
|
||||
|
||||
@@ -88,8 +88,8 @@ If you encounter issues during migration:
|
||||
|
||||
1. Check the [README.md](README.md) for current installation and usage instructions
|
||||
2. Review script README files:
|
||||
- [`scripts/install/README.md`](../scripts/install/README.md) - Installation scripts documentation
|
||||
- [`scripts/fix_perms/README.md`](../scripts/fix_perms/README.md) - Permission scripts documentation
|
||||
- `scripts/install/README.md` - Installation scripts documentation
|
||||
- `scripts/fix_perms/README.md` (if exists) - Permission scripts documentation
|
||||
3. Check system logs: `journalctl -u ledmatrix -f` or `journalctl -u ledmatrix-web -f`
|
||||
4. Review the troubleshooting section in the main README
|
||||
|
||||
|
||||
@@ -114,95 +114,6 @@ Get display duration for this plugin. Can be overridden for dynamic durations.
|
||||
|
||||
Return plugin info for display in web UI. Override to provide additional state information.
|
||||
|
||||
### Dynamic-duration hooks
|
||||
|
||||
Plugins that render multi-step content (e.g. cycling through several games)
|
||||
can extend their display time until they've shown everything. To opt in,
|
||||
either set `dynamic_duration.enabled: true` in the plugin's config or
|
||||
override `supports_dynamic_duration()`.
|
||||
|
||||
#### `supports_dynamic_duration() -> bool`
|
||||
|
||||
Return `True` if this plugin should use dynamic durations. Default reads
|
||||
`config["dynamic_duration"]["enabled"]`.
|
||||
|
||||
#### `get_dynamic_duration_cap() -> Optional[float]`
|
||||
|
||||
Maximum number of seconds the controller will keep this plugin on screen
|
||||
in dynamic mode. Default reads
|
||||
`config["dynamic_duration"]["max_duration_seconds"]`.
|
||||
|
||||
#### `is_cycle_complete() -> bool`
|
||||
|
||||
Override this to return `True` only after the plugin has rendered all of
|
||||
its content for the current rotation. Default returns `True` immediately,
|
||||
which means a single `display()` call counts as a full cycle.
|
||||
|
||||
#### `reset_cycle_state() -> None`
|
||||
|
||||
Called by the controller before each new dynamic-duration session. Reset
|
||||
internal counters/iterators here.
|
||||
|
||||
### Live priority hooks
|
||||
|
||||
Live priority lets a plugin temporarily take over the rotation when it has
|
||||
urgent content (live games, breaking news). Enable by setting
|
||||
`live_priority: true` in the plugin's config and overriding
|
||||
`has_live_content()`.
|
||||
|
||||
#### `has_live_priority() -> bool`
|
||||
|
||||
Whether live priority is enabled in config (default reads
|
||||
`config["live_priority"]`).
|
||||
|
||||
#### `has_live_content() -> bool`
|
||||
|
||||
Override to return `True` when the plugin currently has urgent content.
|
||||
Default returns `False`.
|
||||
|
||||
#### `get_live_modes() -> List[str]`
|
||||
|
||||
List of display modes to show during a live takeover. Default returns the
|
||||
plugin's `display_modes` from its manifest.
|
||||
|
||||
### Vegas scroll hooks
|
||||
|
||||
Vegas mode shows multiple plugins as a single continuous scroll instead of
|
||||
rotating one at a time. Plugins control how their content appears via
|
||||
these hooks. See [ADVANCED_FEATURES.md](ADVANCED_FEATURES.md) for the user
|
||||
side of Vegas mode.
|
||||
|
||||
#### `get_vegas_content() -> Optional[PIL.Image | List[PIL.Image] | None]`
|
||||
|
||||
Return content to inject into the scroll. Multi-item plugins (sports,
|
||||
odds, news) should return a *list* of PIL Images so each item scrolls
|
||||
independently. Static plugins (clock, weather) can return a single image.
|
||||
Returning `None` falls back to capturing whatever `display()` produces.
|
||||
|
||||
#### `get_vegas_content_type() -> str`
|
||||
|
||||
`'multi'`, `'static'`, or `'none'`. Affects how Vegas mode treats the
|
||||
plugin. Default `'static'`.
|
||||
|
||||
#### `get_vegas_display_mode() -> VegasDisplayMode`
|
||||
|
||||
Returns one of `VegasDisplayMode.SCROLL`, `FIXED_SEGMENT`, or `STATIC`.
|
||||
Read from `config["vegas_mode"]` or override directly.
|
||||
|
||||
#### `get_supported_vegas_modes() -> List[VegasDisplayMode]`
|
||||
|
||||
The set of Vegas modes this plugin can render. Used by the UI to populate
|
||||
the mode selector for this plugin.
|
||||
|
||||
#### `get_vegas_segment_width() -> Optional[int]`
|
||||
|
||||
For `FIXED_SEGMENT` plugins, the width in pixels of the segment they
|
||||
occupy in the scroll. `None` lets the controller pick a default.
|
||||
|
||||
> The full source for `BasePlugin` lives in
|
||||
> `src/plugin_system/base_plugin.py`. If a method here disagrees with the
|
||||
> source, the source wins — please open an issue or PR to fix the doc.
|
||||
|
||||
---
|
||||
|
||||
## Display Manager
|
||||
@@ -317,31 +228,23 @@ date_str = self.display_manager.format_date_with_ordinal(datetime.now())
|
||||
|
||||
### Image Rendering
|
||||
|
||||
The display manager doesn't provide a dedicated `draw_image()` method.
|
||||
Instead, plugins paste directly onto the underlying PIL Image
|
||||
(`display_manager.image`), then call `update_display()` to push the buffer
|
||||
to the matrix.
|
||||
#### `draw_image(image: PIL.Image, x: int, y: int) -> None`
|
||||
|
||||
Draw a PIL Image object on the canvas.
|
||||
|
||||
**Parameters**:
|
||||
- `image`: PIL Image object
|
||||
- `x` (int): X position (left edge)
|
||||
- `y` (int): Y position (top edge)
|
||||
|
||||
**Example**:
|
||||
```python
|
||||
from PIL import Image
|
||||
|
||||
logo = Image.open("assets/logo.png").convert("RGB")
|
||||
self.display_manager.image.paste(logo, (10, 10))
|
||||
logo = Image.open("assets/logo.png")
|
||||
self.display_manager.draw_image(logo, x=10, y=10)
|
||||
self.display_manager.update_display()
|
||||
```
|
||||
|
||||
For transparency support, paste using a mask:
|
||||
|
||||
```python
|
||||
icon = Image.open("assets/icon.png").convert("RGBA")
|
||||
self.display_manager.image.paste(icon, (5, 5), icon)
|
||||
self.display_manager.update_display()
|
||||
```
|
||||
|
||||
This is the same pattern the bundled scoreboard base classes
|
||||
(`src/base_classes/baseball.py`, `basketball.py`, `football.py`,
|
||||
`hockey.py`) use, so it's the canonical way to render arbitrary images.
|
||||
|
||||
### Weather Icons
|
||||
|
||||
#### `draw_weather_icon(condition: str, x: int, y: int, size: int = 16) -> None`
|
||||
@@ -537,23 +440,12 @@ self.cache_manager.set("weather_data", {
|
||||
})
|
||||
```
|
||||
|
||||
#### `clear_cache(key: Optional[str] = None) -> None`
|
||||
#### `delete(key: str) -> None`
|
||||
|
||||
Remove a specific cache entry, or all cache entries when called without
|
||||
arguments.
|
||||
Remove a specific cache entry.
|
||||
|
||||
**Parameters**:
|
||||
- `key` (str, optional): Cache key to delete. If omitted, every cached
|
||||
entry (memory + disk) is cleared.
|
||||
|
||||
**Example**:
|
||||
```python
|
||||
# Drop one stale entry
|
||||
self.cache_manager.clear_cache("weather_data")
|
||||
|
||||
# Nuke everything (rare — typically only used by maintenance tooling)
|
||||
self.cache_manager.clear_cache()
|
||||
```
|
||||
- `key` (str): Cache key to delete
|
||||
|
||||
### Advanced Methods
|
||||
|
||||
|
||||
@@ -1,24 +1,5 @@
|
||||
# LEDMatrix Plugin Architecture Specification
|
||||
|
||||
> **Historical design document.** This spec was written *before* the
|
||||
> plugin system was built. Most of it is still architecturally
|
||||
> accurate, but specific details have drifted from the shipped
|
||||
> implementation:
|
||||
>
|
||||
> - Code paths reference `web_interface_v2.py`; the current web UI is
|
||||
> `web_interface/app.py` with v3 Blueprint-based templates.
|
||||
> - The example Flask routes use `/api/plugins/*`; the real API
|
||||
> blueprint is mounted at `/api/v3` (`web_interface/app.py:144`).
|
||||
> - The default plugin location is `plugin-repos/` (configurable via
|
||||
> `plugin_system.plugins_directory`), not `./plugins/`.
|
||||
> - The "Migration Strategy" and "Implementation Roadmap" sections
|
||||
> describe work that has now shipped.
|
||||
>
|
||||
> For the current system, see:
|
||||
> [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md),
|
||||
> [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md), and
|
||||
> [REST_API_REFERENCE.md](REST_API_REFERENCE.md).
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This document outlines the transformation of the LEDMatrix project into a modular, plugin-based architecture that enables user-created displays. The goal is to create a flexible, extensible system similar to Home Assistant Community Store (HACS) where users can discover, install, and manage custom display managers from GitHub repositories.
|
||||
@@ -28,7 +9,7 @@ This document outlines the transformation of the LEDMatrix project into a modula
|
||||
1. **Gradual Migration**: Existing managers remain in core while new plugin infrastructure is built
|
||||
2. **Migration Required**: Breaking changes with migration tools provided
|
||||
3. **GitHub-Based Store**: Simple discovery system, packages served from GitHub repos
|
||||
4. **Plugin Location**: `./plugins/` directory in project root *(actual default is now `plugin-repos/`)*
|
||||
4. **Plugin Location**: `./plugins/` directory in project root
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -184,45 +184,37 @@ plugin-repos/
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "my-plugin",
|
||||
"name": "My Plugin",
|
||||
"version": "1.0.0",
|
||||
"description": "Plugin description",
|
||||
"author": "Your Name",
|
||||
"entry_point": "manager.py",
|
||||
"class_name": "MyPlugin",
|
||||
"display_modes": ["my_plugin"],
|
||||
"config_schema": "config_schema.json"
|
||||
"config_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"enabled": {"type": "boolean", "default": false},
|
||||
"update_interval": {"type": "integer", "default": 3600}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The required fields the plugin loader will check for are `id`,
|
||||
`name`, `version`, `class_name`, and `display_modes`. `entry_point`
|
||||
defaults to `manager.py` if omitted. `config_schema` must be a
|
||||
**file path** (relative to the plugin directory) — the schema itself
|
||||
lives in a separate JSON file, not inline in the manifest. The
|
||||
`class_name` value must match the actual class defined in the entry
|
||||
point file **exactly** (case-sensitive, no spaces); otherwise the
|
||||
loader fails with `AttributeError` at load time.
|
||||
|
||||
### Plugin Manager Class
|
||||
|
||||
```python
|
||||
from src.plugin_system.base_plugin import BasePlugin
|
||||
|
||||
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.config, self.display_manager, self.cache_manager,
|
||||
# self.plugin_manager, self.logger, and self.enabled are
|
||||
# all set up by BasePlugin.__init__.
|
||||
|
||||
class MyPluginManager(BasePlugin):
|
||||
def __init__(self, config, display_manager, cache_manager, font_manager):
|
||||
super().__init__(config, display_manager, cache_manager, font_manager)
|
||||
self.enabled = config.get('enabled', False)
|
||||
|
||||
def update(self):
|
||||
"""Fetch/update data. Called based on update_interval."""
|
||||
"""Update plugin data"""
|
||||
pass
|
||||
|
||||
|
||||
def display(self, force_clear=False):
|
||||
"""Render plugin content to the LED matrix."""
|
||||
"""Display plugin content"""
|
||||
pass
|
||||
|
||||
def get_duration(self):
|
||||
|
||||
@@ -1,15 +1,5 @@
|
||||
# Plugin Configuration Tabs
|
||||
|
||||
> **Status note:** this doc was written during the rollout of the
|
||||
> per-plugin configuration tab feature. The feature itself is shipped
|
||||
> and working in the current v3 web interface, but a few file paths
|
||||
> in the "Implementation Details" section below still reference the
|
||||
> pre-v3 file layout (`web_interface_v2.py`, `templates/index_v2.html`).
|
||||
> The current implementation lives in `web_interface/app.py`,
|
||||
> `web_interface/blueprints/api_v3.py`, and `web_interface/templates/v3/`.
|
||||
> The user-facing description (Overview, Features, Form Generation
|
||||
> Process) is still accurate.
|
||||
|
||||
## Overview
|
||||
|
||||
Each installed plugin now gets its own dedicated configuration tab in the web interface. This provides a clean, organized way to configure plugins without cluttering the main Plugins management tab.
|
||||
@@ -39,14 +29,10 @@ Each installed plugin now gets its own dedicated configuration tab in the web in
|
||||
3. Click **Save Configuration**
|
||||
4. Restart the display service to apply changes
|
||||
|
||||
### Plugin Manager vs Per-Plugin Configuration
|
||||
### Plugin Management vs Configuration
|
||||
|
||||
- **Plugin Manager tab** (second nav row): used for browsing the
|
||||
Plugin Store, installing plugins, toggling installed plugins on/off,
|
||||
and updating/uninstalling them
|
||||
- **Per-plugin tabs** (one per installed plugin, also in the second
|
||||
nav row): used for configuring that specific plugin's behavior and
|
||||
settings via a form auto-generated from its `config_schema.json`
|
||||
- **Plugins Tab**: Used for plugin management (install, enable/disable, update, uninstall)
|
||||
- **Plugin-Specific Tabs**: Used for configuring plugin behavior and settings
|
||||
|
||||
## For Plugin Developers
|
||||
|
||||
@@ -208,12 +194,12 @@ Renders as: Dropdown select
|
||||
|
||||
### Form Generation Process
|
||||
|
||||
1. Web UI loads installed plugins via `/api/v3/plugins/installed`
|
||||
1. Web UI loads installed plugins via `/api/plugins/installed`
|
||||
2. For each plugin, the backend loads its `config_schema.json`
|
||||
3. Frontend generates a tab button with plugin name
|
||||
4. Frontend generates a form based on the JSON Schema
|
||||
5. Current config values from `config.json` are populated
|
||||
6. When saved, each field is sent to `/api/v3/plugins/config` endpoint
|
||||
6. When saved, each field is sent to `/api/plugins/config` endpoint
|
||||
|
||||
## Implementation Details
|
||||
|
||||
@@ -221,7 +207,7 @@ Renders as: Dropdown select
|
||||
|
||||
**File**: `web_interface_v2.py`
|
||||
|
||||
- Modified `/api/v3/plugins/installed` endpoint to include `config_schema_data`
|
||||
- Modified `/api/plugins/installed` endpoint to include `config_schema_data`
|
||||
- Loads each plugin's `config_schema.json` if it exists
|
||||
- Returns schema data along with plugin info
|
||||
|
||||
@@ -241,7 +227,7 @@ New Functions:
|
||||
```
|
||||
Page Load
|
||||
→ refreshPlugins()
|
||||
→ /api/v3/plugins/installed
|
||||
→ /api/plugins/installed
|
||||
→ Returns plugins with config_schema_data
|
||||
→ generatePluginTabs()
|
||||
→ Creates tab buttons
|
||||
@@ -255,7 +241,7 @@ User Saves
|
||||
→ savePluginConfiguration()
|
||||
→ Reads form data
|
||||
→ Converts types per schema
|
||||
→ Sends to /api/v3/plugins/config
|
||||
→ Sends to /api/plugins/config
|
||||
→ Updates config.json
|
||||
→ Shows success notification
|
||||
```
|
||||
|
||||
@@ -31,7 +31,7 @@
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Flask Backend │
|
||||
│ ┌───────────────────────────────────────────────────────┐ │
|
||||
│ │ /api/v3/plugins/installed │ │
|
||||
│ │ /api/plugins/installed │ │
|
||||
│ │ • Discover plugins in plugins/ directory │ │
|
||||
│ │ • Load manifest.json for each plugin │ │
|
||||
│ │ • Load config_schema.json if exists │ │
|
||||
@@ -40,7 +40,7 @@
|
||||
│ └───────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌───────────────────────────────────────────────────────┐ │
|
||||
│ │ /api/v3/plugins/config │ │
|
||||
│ │ /api/plugins/config │ │
|
||||
│ │ • Receive key-value pair │ │
|
||||
│ │ • Update config.json │ │
|
||||
│ │ • Return success/error │ │
|
||||
@@ -88,7 +88,7 @@ DOMContentLoaded Event
|
||||
refreshPlugins()
|
||||
│
|
||||
▼
|
||||
GET /api/v3/plugins/installed
|
||||
GET /api/plugins/installed
|
||||
│
|
||||
├─→ For each plugin directory:
|
||||
│ ├─→ Read manifest.json
|
||||
@@ -146,7 +146,7 @@ savePluginConfiguration(pluginId)
|
||||
│ │ • array: split(',')
|
||||
│ │ • string: as-is
|
||||
│ │
|
||||
│ └─→ POST /api/v3/plugins/config
|
||||
│ └─→ POST /api/plugins/config
|
||||
│ {
|
||||
│ plugin_id: "hello-world",
|
||||
│ key: "message",
|
||||
@@ -174,7 +174,7 @@ Refresh Plugins
|
||||
Window Load
|
||||
└── DOMContentLoaded
|
||||
└── refreshPlugins()
|
||||
├── fetch('/api/v3/plugins/installed')
|
||||
├── fetch('/api/plugins/installed')
|
||||
├── renderInstalledPlugins(plugins)
|
||||
└── generatePluginTabs(plugins)
|
||||
└── For each plugin:
|
||||
@@ -198,19 +198,19 @@ User Interactions
|
||||
│ ├── Process form data
|
||||
│ ├── Convert types per schema
|
||||
│ └── For each field:
|
||||
│ └── POST /api/v3/plugins/config
|
||||
│ └── POST /api/plugins/config
|
||||
│
|
||||
└── resetPluginConfig(pluginId)
|
||||
├── Get schema defaults
|
||||
└── For each field:
|
||||
└── POST /api/v3/plugins/config
|
||||
└── POST /api/plugins/config
|
||||
```
|
||||
|
||||
### Backend (Python)
|
||||
|
||||
```
|
||||
Flask Routes
|
||||
├── /api/v3/plugins/installed (GET)
|
||||
├── /api/plugins/installed (GET)
|
||||
│ └── api_plugins_installed()
|
||||
│ ├── PluginManager.discover_plugins()
|
||||
│ ├── For each plugin:
|
||||
@@ -219,7 +219,7 @@ Flask Routes
|
||||
│ │ └── Load config from config.json
|
||||
│ └── Return JSON response
|
||||
│
|
||||
└── /api/v3/plugins/config (POST)
|
||||
└── /api/plugins/config (POST)
|
||||
└── api_plugin_config()
|
||||
├── Parse request JSON
|
||||
├── Load current config
|
||||
@@ -279,7 +279,7 @@ LEDMatrix/
|
||||
### 3. Individual Config Updates
|
||||
|
||||
**Why**: Simplifies backend API
|
||||
**How**: Each field saved separately via `/api/v3/plugins/config`
|
||||
**How**: Each field saved separately via `/api/plugins/config`
|
||||
**Benefit**: Atomic updates, easier error handling
|
||||
|
||||
### 4. Type Conversion in Frontend
|
||||
|
||||
@@ -4,14 +4,13 @@
|
||||
|
||||
### For Users
|
||||
|
||||
1. Open the web interface: `http://your-pi-ip:5000`
|
||||
2. Open the **Plugin Manager** tab
|
||||
3. Find a plugin in the **Plugin Store** section (e.g., "Hello World")
|
||||
and click **Install**
|
||||
4. Notice a new tab appears in the second nav row with the plugin's name
|
||||
5. Click that tab to configure the plugin
|
||||
6. Modify settings and click **Save**
|
||||
7. From **Overview**, click **Restart Display Service** to see changes
|
||||
1. Open the web interface: `http://your-pi-ip:5001`
|
||||
2. Go to the **Plugin Store** tab
|
||||
3. Install a plugin (e.g., "Hello World")
|
||||
4. Notice a new tab appears with the plugin's name
|
||||
5. Click on the plugin's tab to configure it
|
||||
6. Modify settings and click **Save Configuration**
|
||||
7. Restart the display to see changes
|
||||
|
||||
That's it! Each installed plugin automatically gets its own configuration tab.
|
||||
|
||||
@@ -172,11 +171,9 @@ User enters: `255, 0, 0`
|
||||
### For Users
|
||||
|
||||
1. **Reset Anytime**: Use "Reset to Defaults" to restore original settings
|
||||
2. **Navigate Back**: Switch to the **Plugin Manager** tab to see the
|
||||
full list of installed plugins
|
||||
2. **Navigate Back**: Click "Back to Plugin Management" to return to Plugins tab
|
||||
3. **Check Help Text**: Each field has a description explaining what it does
|
||||
4. **Restart Required**: Remember to restart the display service from
|
||||
**Overview** after saving
|
||||
4. **Restart Required**: Remember to restart the display after saving
|
||||
|
||||
### For Developers
|
||||
|
||||
@@ -209,10 +206,8 @@ User enters: `255, 0, 0`
|
||||
## 📚 Next Steps
|
||||
|
||||
- Read the full documentation: [PLUGIN_CONFIGURATION_TABS.md](PLUGIN_CONFIGURATION_TABS.md)
|
||||
- Check the configuration architecture: [PLUGIN_CONFIG_ARCHITECTURE.md](PLUGIN_CONFIG_ARCHITECTURE.md)
|
||||
- Browse example plugins in the
|
||||
[ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins)
|
||||
repo, especially `plugins/hello-world/` and `plugins/clock-simple/`
|
||||
- Check implementation details: [PLUGIN_CONFIG_TABS_SUMMARY.md](PLUGIN_CONFIG_TABS_SUMMARY.md)
|
||||
- Browse example plugins: `plugins/hello-world/`, `plugins/clock-simple/`
|
||||
- Join the community for help and suggestions
|
||||
|
||||
## 🎉 That's It!
|
||||
|
||||
@@ -1,16 +1,5 @@
|
||||
# Plugin Custom Icons Guide
|
||||
|
||||
> ⚠️ **Status:** the `icon` field in `manifest.json` is currently
|
||||
> **not honored by the v3 web interface**. Plugin tab icons are
|
||||
> hardcoded to `fas fa-puzzle-piece` in
|
||||
> `web_interface/templates/v3/base.html:515` and `:774`. The icon
|
||||
> field was originally read by a `getPluginIcon()` helper in the v2
|
||||
> templates, but that helper wasn't ported to v3. Setting `icon` in a
|
||||
> manifest is harmless (it's just ignored) so plugin authors can leave
|
||||
> it in place for when this regression is fixed.
|
||||
>
|
||||
> Tracking issue: see the LEDMatrix repo for the open ticket.
|
||||
|
||||
## Overview
|
||||
|
||||
Plugins can specify custom icons that appear next to their name in the web interface tabs. This makes your plugin instantly recognizable and adds visual polish to the UI.
|
||||
|
||||
@@ -1,13 +1,4 @@
|
||||
# Plugin Custom Icons Feature
|
||||
|
||||
> ⚠️ **Status:** this doc describes the v2 web interface
|
||||
> implementation of plugin custom icons. The feature **regressed when
|
||||
> the v3 web interface was built** — the `getPluginIcon()` helper
|
||||
> referenced below lived in `templates/index_v2.html` (which is now
|
||||
> archived) and was not ported to the v3 templates. Plugin tab icons
|
||||
> in v3 are hardcoded to `fas fa-puzzle-piece`
|
||||
> (`web_interface/templates/v3/base.html:515` and `:774`). The
|
||||
> `icon` field in `manifest.json` is currently silently ignored.
|
||||
# ✅ Plugin Custom Icons Feature - Complete
|
||||
|
||||
## What Was Implemented
|
||||
|
||||
@@ -313,7 +304,7 @@ Result: `[logo] Company Metrics` tab
|
||||
|
||||
To test custom icons:
|
||||
|
||||
1. **Open web interface** at `http://your-pi-ip:5000`
|
||||
1. **Open web interface** at `http://your-pi:5001`
|
||||
2. **Check installed plugins**:
|
||||
- Hello World should show 👋
|
||||
- Clock Simple should show 🕐
|
||||
|
||||
@@ -37,7 +37,7 @@ sudo systemctl start ledmatrix-web
|
||||
|
||||
### ✅ Scenario 2: Web Interface Plugin Installation
|
||||
|
||||
**What:** Installing/enabling plugins via web interface at `http://pi-ip:5000`
|
||||
**What:** Installing/enabling plugins via web interface at `http://pi-ip:5001`
|
||||
|
||||
- **Web service runs as:** root (ledmatrix-web.service)
|
||||
- **Installs to:** System-wide
|
||||
|
||||
@@ -77,12 +77,10 @@ sudo chmod -R 755 /root/.cache
|
||||
|
||||
The web interface handles dependency installation correctly in the service context:
|
||||
|
||||
1. Access the web interface (`http://ledpi:5000` or `http://your-pi-ip:5000`)
|
||||
2. Open the **Plugin Manager** tab (use the **Plugin Store** section to
|
||||
find the plugin, or **Install from GitHub**)
|
||||
3. Install the plugin through the web UI
|
||||
4. The system automatically handles dependency installation in the
|
||||
service context (which has the right permissions)
|
||||
1. Access the web interface (usually http://ledpi:8080)
|
||||
2. Navigate to Plugin Store or Plugin Management
|
||||
3. Install plugins through the web UI
|
||||
4. The system will automatically handle dependencies
|
||||
|
||||
## Prevention
|
||||
|
||||
|
||||
@@ -12,21 +12,6 @@ When developing plugins in separate repositories, you need a way to:
|
||||
|
||||
The solution uses **symbolic links** to connect plugin repositories to the `plugins/` directory, combined with a helper script to manage the linking process.
|
||||
|
||||
> **Plugin directory note:** the dev workflow described here puts
|
||||
> symlinks in `plugins/`. The plugin loader's *production* default is
|
||||
> `plugin-repos/` (set by `plugin_system.plugins_directory` in
|
||||
> `config.json`). Importantly, the main discovery path
|
||||
> (`PluginManager.discover_plugins()`) only scans the configured
|
||||
> directory — it does **not** fall back to `plugins/`. Two narrower
|
||||
> paths do: the Plugin Store install/update logic in `store_manager.py`,
|
||||
> and `schema_manager.get_schema_path()` (which the web UI form
|
||||
> generator uses to find `config_schema.json`). That's why plugins
|
||||
> installed via the Plugin Store still work even with symlinks in
|
||||
> `plugins/`, but your own dev plugin won't appear in the rotation
|
||||
> until you either move it to `plugin-repos/` or change
|
||||
> `plugin_system.plugins_directory` to `plugins` in the General tab
|
||||
> of the web UI. The latter is the smoother dev setup.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Link a Plugin from GitHub
|
||||
@@ -481,9 +466,7 @@ When developing plugins, you'll need to use the APIs provided by the LEDMatrix s
|
||||
|
||||
**Display Manager** (`self.display_manager`):
|
||||
- `clear()`, `update_display()` - Core display operations
|
||||
- `draw_text()` - Text rendering. For images, paste directly onto
|
||||
`display_manager.image` (a PIL Image) and call `update_display()`;
|
||||
there is no `draw_image()` helper method.
|
||||
- `draw_text()`, `draw_image()` - Rendering methods
|
||||
- `draw_weather_icon()`, `draw_sun()`, `draw_cloud()` - Weather icons
|
||||
- `get_text_width()`, `get_font_height()` - Text utilities
|
||||
- `set_scrolling_state()`, `defer_update()` - Scrolling state management
|
||||
|
||||
@@ -1,11 +1,5 @@
|
||||
# LEDMatrix Plugin System - Implementation Summary
|
||||
|
||||
> **Status note:** this is a high-level summary written during the
|
||||
> initial plugin system rollout. Most of it is accurate, but a few
|
||||
> sections describe features that are aspirational or only partially
|
||||
> implemented (per-plugin virtual envs, resource limits, registry
|
||||
> manager). Drift from current reality is called out inline.
|
||||
|
||||
This document provides a comprehensive overview of the plugin architecture implementation, consolidating details from multiple plugin-related implementation summaries.
|
||||
|
||||
## Executive Summary
|
||||
@@ -20,25 +14,16 @@ The LEDMatrix plugin system transforms the project into a modular, extensible pl
|
||||
LEDMatrix/
|
||||
├── src/plugin_system/
|
||||
│ ├── base_plugin.py # Plugin interface contract
|
||||
│ ├── plugin_loader.py # Discovery + dynamic import
|
||||
│ ├── plugin_manager.py # Lifecycle management
|
||||
│ ├── store_manager.py # GitHub install / store integration
|
||||
│ ├── schema_manager.py # Config schema validation
|
||||
│ ├── health_monitor.py # Plugin health metrics
|
||||
│ ├── operation_queue.py # Async install/update operations
|
||||
│ └── state_manager.py # Persistent plugin state
|
||||
├── plugin-repos/ # Default plugin install location
|
||||
│ ├── store_manager.py # GitHub integration
|
||||
│ └── registry_manager.py # Plugin discovery
|
||||
├── plugins/ # User-installed plugins
|
||||
│ ├── football-scoreboard/
|
||||
│ ├── ledmatrix-music/
|
||||
│ └── ledmatrix-stocks/
|
||||
└── config/config.json # Plugin configurations
|
||||
```
|
||||
|
||||
> Earlier drafts of this doc referenced `registry_manager.py`. It was
|
||||
> never created — discovery happens in `plugin_loader.py`. The earlier
|
||||
> default plugin location of `plugins/` has been replaced with
|
||||
> `plugin-repos/` (see `config/config.template.json:130`).
|
||||
|
||||
### Key Design Decisions
|
||||
|
||||
✅ **Gradual Migration**: Plugin system added alongside existing managers
|
||||
@@ -92,26 +77,14 @@ LEDMatrix/
|
||||
- **Fallback System**: Default icons when custom ones unavailable
|
||||
|
||||
#### Dependency Management
|
||||
- **Requirements.txt**: Per-plugin dependencies, installed system-wide
|
||||
via pip on first plugin load
|
||||
- **Version Pinning**: Standard pip version constraints in
|
||||
`requirements.txt`
|
||||
- **Requirements.txt**: Per-plugin dependencies
|
||||
- **Virtual Environments**: Isolated dependency management
|
||||
- **Version Pinning**: Explicit version constraints
|
||||
|
||||
> Earlier plans called for per-plugin virtual environments. That isn't
|
||||
> implemented — plugin Python deps install into the system Python
|
||||
> environment (or whatever environment the LEDMatrix service is using).
|
||||
> Conflicting versions across plugins are not auto-resolved.
|
||||
|
||||
#### Health monitoring
|
||||
- **Resource Monitor** (`src/plugin_system/resource_monitor.py`): tracks
|
||||
CPU and memory metrics per plugin and warns about slow plugins
|
||||
- **Health Monitor** (`src/plugin_system/health_monitor.py`): tracks
|
||||
plugin failures and last-success timestamps
|
||||
|
||||
> Earlier plans called for hard CPU/memory limits and a sandboxed
|
||||
> permission system. Neither is implemented. Plugins run in the same
|
||||
> process as the display loop with full file-system and network access
|
||||
> — review third-party plugin code before installing.
|
||||
#### Permission System
|
||||
- **File Access Control**: Configurable file system permissions
|
||||
- **Network Access**: Controlled API access
|
||||
- **Resource Limits**: CPU and memory constraints
|
||||
|
||||
## Plugin Development
|
||||
|
||||
|
||||
@@ -2,20 +2,14 @@
|
||||
|
||||
## Overview
|
||||
|
||||
LEDMatrix is a modular, plugin-based system where users create, share,
|
||||
and install custom displays via a GitHub-based store (similar in spirit
|
||||
to HACS for Home Assistant). This page is a quick reference; for the
|
||||
full design see [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md)
|
||||
and [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md).
|
||||
Transform LEDMatrix into a modular, plugin-based system where users can create, share, and install custom displays via a GitHub-based store (similar to HACS for Home Assistant).
|
||||
|
||||
## Key Decisions
|
||||
|
||||
✅ **Plugin-First**: All display features (calendar excepted) are now plugins
|
||||
✅ **GitHub Store**: Discovery from `ledmatrix-plugins` registry plus
|
||||
any GitHub URL
|
||||
✅ **Plugin Location**: configured by `plugin_system.plugins_directory`
|
||||
in `config.json` (default `plugin-repos/`; the loader also searches
|
||||
`plugins/` as a fallback)
|
||||
✅ **Gradual Migration**: Existing managers stay, plugins added alongside
|
||||
✅ **Migration Required**: Breaking changes in v3.0, tools provided
|
||||
✅ **GitHub Store**: Simple discovery, packages from repos
|
||||
✅ **Plugin Location**: `./plugins/` directory
|
||||
|
||||
## File Structure
|
||||
|
||||
@@ -25,16 +19,15 @@ LEDMatrix/
|
||||
│ └── plugin_system/
|
||||
│ ├── base_plugin.py # Plugin interface
|
||||
│ ├── plugin_manager.py # Load/unload plugins
|
||||
│ ├── plugin_loader.py # Discovery + dynamic import
|
||||
│ └── store_manager.py # Install from GitHub
|
||||
├── plugin-repos/ # Default plugin install location
|
||||
├── plugins/
|
||||
│ ├── clock-simple/
|
||||
│ │ ├── manifest.json # Metadata
|
||||
│ │ ├── manager.py # Main plugin class
|
||||
│ │ ├── requirements.txt # Dependencies
|
||||
│ │ ├── config_schema.json # Validation
|
||||
│ │ └── README.md
|
||||
│ └── hockey-scoreboard/
|
||||
│ └── nhl-scores/
|
||||
│ └── ... (same structure)
|
||||
└── config/config.json # Plugin configs
|
||||
```
|
||||
@@ -116,45 +109,100 @@ git push origin v1.0.0
|
||||
|
||||
### Web UI
|
||||
|
||||
1. **Browse Store**: Plugin Manager tab → Plugin Store section → Search/filter
|
||||
2. **Install**: Click **Install** in the plugin's row
|
||||
3. **Configure**: open the plugin's tab in the second nav row
|
||||
4. **Enable/Disable**: toggle switch in the **Installed Plugins** list
|
||||
5. **Reorder**: order is set by the position in `display_modes` /
|
||||
plugin order; rearranging via drag-and-drop is not yet supported
|
||||
1. **Browse Store**: Plugin Store tab → Search/filter
|
||||
2. **Install**: Click "Install" button
|
||||
3. **Configure**: Plugin Manager → Click ⚙️ Configure
|
||||
4. **Enable/Disable**: Toggle switch
|
||||
5. **Reorder**: Drag and drop in rotation list
|
||||
|
||||
### REST API
|
||||
### API
|
||||
|
||||
The API is mounted at `/api/v3` (`web_interface/app.py:144`).
|
||||
|
||||
```bash
|
||||
# Install plugin from the registry
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "hockey-scoreboard"}'
|
||||
```python
|
||||
# Install plugin
|
||||
POST /api/plugins/install
|
||||
{"plugin_id": "my-plugin"}
|
||||
|
||||
# Install from custom URL
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/plugins/install-from-url \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"repo_url": "https://github.com/User/plugin"}'
|
||||
POST /api/plugins/install-from-url
|
||||
{"repo_url": "https://github.com/User/plugin"}
|
||||
|
||||
# List installed
|
||||
curl http://your-pi-ip:5000/api/v3/plugins/installed
|
||||
GET /api/plugins/installed
|
||||
|
||||
# Toggle
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/plugins/toggle \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "hockey-scoreboard", "enabled": true}'
|
||||
POST /api/plugins/toggle
|
||||
{"plugin_id": "my-plugin", "enabled": true}
|
||||
```
|
||||
|
||||
See [REST_API_REFERENCE.md](REST_API_REFERENCE.md) for the full list.
|
||||
### Command Line
|
||||
|
||||
```python
|
||||
from src.plugin_system.store_manager import PluginStoreManager
|
||||
|
||||
store = PluginStoreManager()
|
||||
|
||||
# Install
|
||||
store.install_plugin('nhl-scores')
|
||||
|
||||
# Install from URL
|
||||
store.install_from_url('https://github.com/User/plugin')
|
||||
|
||||
# Update
|
||||
store.update_plugin('nhl-scores')
|
||||
|
||||
# Uninstall
|
||||
store.uninstall_plugin('nhl-scores')
|
||||
```
|
||||
|
||||
## Migration Path
|
||||
|
||||
### Phase 1: v2.0.0 (Plugin Infrastructure)
|
||||
- Plugin system alongside existing managers
|
||||
- 100% backward compatible
|
||||
- Web UI shows plugin store
|
||||
|
||||
### Phase 2: v2.1.0 (Example Plugins)
|
||||
- Reference plugins created
|
||||
- Migration examples
|
||||
- Developer docs
|
||||
|
||||
### Phase 3: v2.2.0 (Migration Tools)
|
||||
- Auto-migration script
|
||||
- Config converter
|
||||
- Testing tools
|
||||
|
||||
### Phase 4: v2.5.0 (Deprecation)
|
||||
- Warnings on legacy managers
|
||||
- Migration guide
|
||||
- 95% backward compatible
|
||||
|
||||
### Phase 5: v3.0.0 (Plugin-Only)
|
||||
- Legacy managers removed from core
|
||||
- Packaged as official plugins
|
||||
- **Breaking change - migration required**
|
||||
|
||||
## Quick Migration
|
||||
|
||||
```bash
|
||||
# 1. Backup
|
||||
cp config/config.json config/config.json.backup
|
||||
|
||||
# 2. Run migration
|
||||
python3 scripts/migrate_to_plugins.py
|
||||
|
||||
# 3. Review
|
||||
cat config/config.json.migrated
|
||||
|
||||
# 4. Apply
|
||||
mv config/config.json.migrated config/config.json
|
||||
|
||||
# 5. Restart
|
||||
sudo systemctl restart ledmatrix
|
||||
```
|
||||
|
||||
## Plugin Registry Structure
|
||||
|
||||
The official registry lives at
|
||||
[`ChuckBuilds/ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins).
|
||||
The Plugin Store reads `plugins.json` at the root of that repo, which
|
||||
follows this shape:
|
||||
**ChuckBuilds/ledmatrix-plugin-registry/plugins.json**:
|
||||
```json
|
||||
{
|
||||
"plugins": [
|
||||
@@ -197,30 +245,42 @@ follows this shape:
|
||||
- ✅ Community handles custom displays
|
||||
- ✅ Easier to review changes
|
||||
|
||||
## Known Limitations
|
||||
## What's Missing?
|
||||
|
||||
The plugin system is shipped and stable, but some things are still
|
||||
intentionally simple:
|
||||
This specification covers the technical architecture. Additional considerations:
|
||||
|
||||
1. **Sandboxing**: plugins run in the same process as the display loop;
|
||||
there is no isolation. Review code before installing third-party
|
||||
plugins.
|
||||
2. **Resource limits**: there's a resource monitor that warns about
|
||||
slow plugins, but no hard CPU/memory caps.
|
||||
3. **Plugin ratings**: not yet — the Plugin Store shows version,
|
||||
author, and category but no community rating system.
|
||||
4. **Auto-updates**: manual via the Plugin Manager tab; no automatic
|
||||
background updates.
|
||||
5. **Dependency conflicts**: each plugin's `requirements.txt` is
|
||||
installed via pip; conflicting versions across plugins are not
|
||||
resolved automatically.
|
||||
6. **Plugin testing framework**: see
|
||||
[HOW_TO_RUN_TESTS.md](HOW_TO_RUN_TESTS.md) and
|
||||
[DEV_PREVIEW.md](DEV_PREVIEW.md) — there are tools, but no
|
||||
mandatory test gate.
|
||||
1. **Sandboxing**: Current design has no isolation (future enhancement)
|
||||
2. **Resource Limits**: No CPU/memory limits per plugin (future)
|
||||
3. **Plugin Ratings**: Registry needs rating/review system
|
||||
4. **Auto-Updates**: Manual update only (could add auto-update)
|
||||
5. **Dependency Conflicts**: No automatic resolution
|
||||
6. **Version Pinning**: Limited version constraint checking
|
||||
7. **Plugin Testing**: No automated testing framework
|
||||
8. **Marketplace**: No paid plugins (all free/open source)
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ Review this specification
|
||||
2. Start Phase 1 implementation
|
||||
3. Create first 3-4 example plugins
|
||||
4. Set up plugin registry repo
|
||||
5. Build web UI components
|
||||
6. Test on Pi hardware
|
||||
7. Release v2.0.0 alpha
|
||||
|
||||
## Questions to Resolve
|
||||
|
||||
Before implementing, consider:
|
||||
|
||||
1. Should we support plugin dependencies (plugin A requires plugin B)?
|
||||
2. How to handle breaking changes in core display_manager API?
|
||||
3. Should plugins be able to add new web UI pages?
|
||||
4. What about plugins that need hardware beyond LED matrix?
|
||||
5. How to prevent malicious plugins?
|
||||
6. Should there be plugin quotas (max API calls, etc.)?
|
||||
7. How to handle plugin conflicts (two clocks competing)?
|
||||
|
||||
---
|
||||
|
||||
**See [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md) for the
|
||||
full architectural specification.**
|
||||
**See PLUGIN_ARCHITECTURE_SPEC.md for full details**
|
||||
|
||||
|
||||
@@ -95,14 +95,14 @@ Official plugin registry for [LEDMatrix](https://github.com/ChuckBuilds/LEDMatri
|
||||
|
||||
All plugins can be installed through the LEDMatrix web interface:
|
||||
|
||||
1. Open web interface (http://your-pi-ip:5000)
|
||||
2. Open the **Plugin Manager** tab
|
||||
3. Browse or search the **Plugin Store** section
|
||||
4. Click **Install**
|
||||
1. Open web interface (http://your-pi-ip:5050)
|
||||
2. Go to Plugin Store tab
|
||||
3. Browse or search for plugins
|
||||
4. Click Install
|
||||
|
||||
Or via API:
|
||||
```bash
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \
|
||||
curl -X POST http://your-pi-ip:5050/api/plugins/install \
|
||||
-d '{"plugin_id": "clock-simple"}'
|
||||
```
|
||||
|
||||
@@ -152,7 +152,7 @@ Before submitting, ensure your plugin:
|
||||
1. **Test Your Plugin**
|
||||
```bash
|
||||
# Install via URL on your Pi
|
||||
curl -X POST http://your-pi:5000/api/v3/plugins/install-from-url \
|
||||
curl -X POST http://your-pi:5050/api/plugins/install-from-url \
|
||||
-d '{"repo_url": "https://github.com/you/ledmatrix-your-plugin"}'
|
||||
```
|
||||
|
||||
@@ -311,7 +311,7 @@ git push
|
||||
# 1. Receive PR on ledmatrix-plugins repo
|
||||
# 2. Review using VERIFICATION.md checklist
|
||||
# 3. Test installation:
|
||||
curl -X POST http://pi:5000/api/v3/plugins/install-from-url \
|
||||
curl -X POST http://pi:5050/api/plugins/install-from-url \
|
||||
-d '{"repo_url": "https://github.com/contributor/plugin"}'
|
||||
|
||||
# 4. If approved, merge PR
|
||||
|
||||
@@ -12,7 +12,7 @@ The LEDMatrix Plugin Store allows you to discover, install, and manage display p
|
||||
```bash
|
||||
# Web UI: Plugin Store → Search → Click Install
|
||||
# API:
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \
|
||||
curl -X POST http://your-pi-ip:5050/api/plugins/install \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "clock-simple"}'
|
||||
```
|
||||
@@ -21,7 +21,7 @@ curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \
|
||||
```bash
|
||||
# Web UI: Plugin Store → "Install from URL" → Paste URL
|
||||
# API:
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/plugins/install-from-url \
|
||||
curl -X POST http://your-pi-ip:5050/api/plugins/install-from-url \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"repo_url": "https://github.com/user/ledmatrix-plugin"}'
|
||||
```
|
||||
@@ -29,20 +29,20 @@ curl -X POST http://your-pi-ip:5000/api/v3/plugins/install-from-url \
|
||||
### Manage Plugins
|
||||
```bash
|
||||
# List installed
|
||||
curl "http://your-pi-ip:5000/api/v3/plugins/installed"
|
||||
curl "http://your-pi-ip:5050/api/plugins/installed"
|
||||
|
||||
# Enable/disable
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/plugins/toggle \
|
||||
curl -X POST http://your-pi-ip:5050/api/plugins/toggle \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "clock-simple", "enabled": true}'
|
||||
|
||||
# Update
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/plugins/update \
|
||||
curl -X POST http://your-pi-ip:5050/api/plugins/update \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "clock-simple"}'
|
||||
|
||||
# Uninstall
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/plugins/uninstall \
|
||||
curl -X POST http://your-pi-ip:5050/api/plugins/uninstall \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "clock-simple"}'
|
||||
```
|
||||
@@ -56,7 +56,7 @@ curl -X POST http://your-pi-ip:5000/api/v3/plugins/uninstall \
|
||||
The official plugin store contains curated, verified plugins that have been reviewed by maintainers.
|
||||
|
||||
**Via Web Interface:**
|
||||
1. Open the web interface at http://your-pi-ip:5000
|
||||
1. Open the web interface at http://your-pi-ip:5050
|
||||
2. Navigate to the "Plugin Store" tab
|
||||
3. Browse or search for plugins
|
||||
4. Click "Install" on the desired plugin
|
||||
@@ -65,7 +65,7 @@ The official plugin store contains curated, verified plugins that have been revi
|
||||
|
||||
**Via REST API:**
|
||||
```bash
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \
|
||||
curl -X POST http://your-pi-ip:5050/api/plugins/install \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "clock-simple"}'
|
||||
```
|
||||
@@ -101,7 +101,7 @@ Install any plugin directly from a GitHub repository, even if it's not in the of
|
||||
|
||||
**Via REST API:**
|
||||
```bash
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/plugins/install-from-url \
|
||||
curl -X POST http://your-pi-ip:5050/api/plugins/install-from-url \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"repo_url": "https://github.com/user/ledmatrix-my-plugin"}'
|
||||
```
|
||||
@@ -131,13 +131,13 @@ else:
|
||||
**Via REST API:**
|
||||
```bash
|
||||
# Search by query
|
||||
curl "http://your-pi-ip:5000/api/v3/plugins/store/search?q=hockey"
|
||||
curl "http://your-pi-ip:5050/api/plugins/store/search?q=hockey"
|
||||
|
||||
# Filter by category
|
||||
curl "http://your-pi-ip:5000/api/v3/plugins/store/search?category=sports"
|
||||
curl "http://your-pi-ip:5050/api/plugins/store/search?category=sports"
|
||||
|
||||
# Filter by tags
|
||||
curl "http://your-pi-ip:5000/api/v3/plugins/store/search?tags=nhl&tags=hockey"
|
||||
curl "http://your-pi-ip:5050/api/plugins/store/search?tags=nhl&tags=hockey"
|
||||
```
|
||||
|
||||
**Via Python:**
|
||||
@@ -168,7 +168,7 @@ results = store.search_plugins(tags=["nhl", "hockey"])
|
||||
|
||||
**Via REST API:**
|
||||
```bash
|
||||
curl "http://your-pi-ip:5000/api/v3/plugins/installed"
|
||||
curl "http://your-pi-ip:5050/api/plugins/installed"
|
||||
```
|
||||
|
||||
**Via Python:**
|
||||
@@ -192,7 +192,7 @@ for plugin_id in installed:
|
||||
|
||||
**Via REST API:**
|
||||
```bash
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/plugins/toggle \
|
||||
curl -X POST http://your-pi-ip:5050/api/plugins/toggle \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "clock-simple", "enabled": true}'
|
||||
```
|
||||
@@ -207,7 +207,7 @@ curl -X POST http://your-pi-ip:5000/api/v3/plugins/toggle \
|
||||
|
||||
**Via REST API:**
|
||||
```bash
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/plugins/update \
|
||||
curl -X POST http://your-pi-ip:5050/api/plugins/update \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "clock-simple"}'
|
||||
```
|
||||
@@ -230,7 +230,7 @@ success = store.update_plugin('clock-simple')
|
||||
|
||||
**Via REST API:**
|
||||
```bash
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/plugins/uninstall \
|
||||
curl -X POST http://your-pi-ip:5050/api/plugins/uninstall \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "clock-simple"}'
|
||||
```
|
||||
@@ -351,15 +351,15 @@ All API endpoints return JSON with this structure:
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/v3/plugins/store/list` | List all plugins in store |
|
||||
| GET | `/api/v3/plugins/store/search` | Search for plugins |
|
||||
| GET | `/api/v3/plugins/installed` | List installed plugins |
|
||||
| POST | `/api/v3/plugins/install` | Install from registry |
|
||||
| POST | `/api/v3/plugins/install-from-url` | Install from GitHub URL |
|
||||
| POST | `/api/v3/plugins/uninstall` | Uninstall plugin |
|
||||
| POST | `/api/v3/plugins/update` | Update plugin |
|
||||
| POST | `/api/v3/plugins/toggle` | Enable/disable plugin |
|
||||
| POST | `/api/v3/plugins/config` | Update plugin config |
|
||||
| GET | `/api/plugins/store/list` | List all plugins in store |
|
||||
| GET | `/api/plugins/store/search` | Search for plugins |
|
||||
| GET | `/api/plugins/installed` | List installed plugins |
|
||||
| POST | `/api/plugins/install` | Install from registry |
|
||||
| POST | `/api/plugins/install-from-url` | Install from GitHub URL |
|
||||
| POST | `/api/plugins/uninstall` | Uninstall plugin |
|
||||
| POST | `/api/plugins/update` | Update plugin |
|
||||
| POST | `/api/plugins/toggle` | Enable/disable plugin |
|
||||
| POST | `/api/plugins/config` | Update plugin config |
|
||||
|
||||
---
|
||||
|
||||
@@ -369,7 +369,7 @@ All API endpoints return JSON with this structure:
|
||||
|
||||
```bash
|
||||
# Install
|
||||
curl -X POST http://192.168.1.100:5000/api/v3/plugins/install \
|
||||
curl -X POST http://192.168.1.100:5050/api/plugins/install \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "clock-simple"}'
|
||||
|
||||
@@ -390,12 +390,12 @@ sudo systemctl restart ledmatrix
|
||||
|
||||
```bash
|
||||
# Install your own plugin during development
|
||||
curl -X POST http://192.168.1.100:5000/api/v3/plugins/install-from-url \
|
||||
curl -X POST http://192.168.1.100:5050/api/plugins/install-from-url \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"repo_url": "https://github.com/myusername/ledmatrix-my-custom-plugin"}'
|
||||
|
||||
# Enable it
|
||||
curl -X POST http://192.168.1.100:5000/api/v3/plugins/toggle \
|
||||
curl -X POST http://192.168.1.100:5050/api/plugins/toggle \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"plugin_id": "my-custom-plugin", "enabled": true}'
|
||||
|
||||
|
||||
241
docs/README.md
241
docs/README.md
@@ -1,84 +1,199 @@
|
||||
# LEDMatrix Documentation
|
||||
|
||||
This directory contains guides, references, and architectural notes for the
|
||||
LEDMatrix project. If you are setting up a Pi for the first time, start with
|
||||
the [project root README](../README.md) — it covers hardware, OS imaging, and
|
||||
the one-shot installer. The pages here go deeper.
|
||||
Welcome to the LEDMatrix documentation! This directory contains comprehensive guides, specifications, and reference materials for the LEDMatrix project.
|
||||
|
||||
## I'm a new user
|
||||
## 📚 Documentation Overview
|
||||
|
||||
1. [GETTING_STARTED.md](GETTING_STARTED.md) — first-time setup walkthrough
|
||||
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
|
||||
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
|
||||
This documentation has been recently consolidated (January 2026) to reduce redundancy while maintaining comprehensive coverage. We've reduced from 51 main documents to 16-17 well-organized files (~68% reduction) by merging duplicates, archiving ephemeral content, and unifying writing styles.
|
||||
|
||||
## I want to write a plugin
|
||||
## 📖 Quick Start
|
||||
|
||||
Start here:
|
||||
### For New Users
|
||||
1. **Installation**: Follow the main [README.md](../README.md) in the project root
|
||||
2. **First Setup**: See [GETTING_STARTED.md](GETTING_STARTED.md) for first-time setup guide
|
||||
3. **Web Interface**: Use [WEB_INTERFACE_GUIDE.md](WEB_INTERFACE_GUIDE.md) to learn the control panel
|
||||
4. **Troubleshooting**: Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues
|
||||
|
||||
1. [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md) — end-to-end workflow
|
||||
2. [PLUGIN_QUICK_REFERENCE.md](PLUGIN_QUICK_REFERENCE.md) — cheat sheet
|
||||
3. [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) — display, cache, and plugin-manager APIs
|
||||
4. [PLUGIN_ERROR_HANDLING.md](PLUGIN_ERROR_HANDLING.md) — error-handling patterns
|
||||
5. [DEV_PREVIEW.md](DEV_PREVIEW.md) — preview plugins on your dev machine without a Pi
|
||||
6. [EMULATOR_SETUP_GUIDE.md](EMULATOR_SETUP_GUIDE.md) — running the matrix emulator
|
||||
### For Developers
|
||||
1. **Plugin Development**: See [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md) for complete guide
|
||||
2. **Advanced Patterns**: Read [ADVANCED_PLUGIN_DEVELOPMENT.md](ADVANCED_PLUGIN_DEVELOPMENT.md) for advanced techniques
|
||||
3. **API Reference**: Check [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) for available methods
|
||||
4. **Configuration**: See [PLUGIN_CONFIGURATION_GUIDE.md](PLUGIN_CONFIGURATION_GUIDE.md) for config schemas
|
||||
|
||||
Going deeper:
|
||||
### For API Integration
|
||||
1. **REST API**: See [REST_API_REFERENCE.md](REST_API_REFERENCE.md) for all web interface endpoints
|
||||
2. **Plugin API**: See [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) for plugin developer APIs
|
||||
3. **Developer Reference**: See [DEVELOPER_QUICK_REFERENCE.md](DEVELOPER_QUICK_REFERENCE.md) for common tasks
|
||||
|
||||
- [ADVANCED_PLUGIN_DEVELOPMENT.md](ADVANCED_PLUGIN_DEVELOPMENT.md) — advanced patterns
|
||||
- [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md) — full plugin-system spec
|
||||
- [PLUGIN_DEPENDENCY_GUIDE.md](PLUGIN_DEPENDENCY_GUIDE.md) /
|
||||
[PLUGIN_DEPENDENCY_TROUBLESHOOTING.md](PLUGIN_DEPENDENCY_TROUBLESHOOTING.md)
|
||||
- [PLUGIN_WEB_UI_ACTIONS.md](PLUGIN_WEB_UI_ACTIONS.md) (+ [example JSON](PLUGIN_WEB_UI_ACTIONS_EXAMPLE.json))
|
||||
- [PLUGIN_CUSTOM_ICONS.md](PLUGIN_CUSTOM_ICONS.md) /
|
||||
[PLUGIN_CUSTOM_ICONS_FEATURE.md](PLUGIN_CUSTOM_ICONS_FEATURE.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
|
||||
## 📋 Documentation Categories
|
||||
|
||||
## Configuring plugins
|
||||
### 🚀 Getting Started & User Guides
|
||||
- [GETTING_STARTED.md](GETTING_STARTED.md) - First-time setup and quick start guide
|
||||
- [WEB_INTERFACE_GUIDE.md](WEB_INTERFACE_GUIDE.md) - Complete web interface user guide
|
||||
- [WIFI_NETWORK_SETUP.md](WIFI_NETWORK_SETUP.md) - WiFi configuration and AP mode setup
|
||||
- [PLUGIN_STORE_GUIDE.md](PLUGIN_STORE_GUIDE.md) - Installing and managing plugins
|
||||
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues and solutions
|
||||
|
||||
- [PLUGIN_CONFIG_QUICK_START.md](PLUGIN_CONFIG_QUICK_START.md) — minimal config you need
|
||||
- [PLUGIN_CONFIGURATION_GUIDE.md](PLUGIN_CONFIGURATION_GUIDE.md) — schema design
|
||||
- [PLUGIN_CONFIGURATION_TABS.md](PLUGIN_CONFIGURATION_TABS.md) — multi-tab UI configs
|
||||
- [PLUGIN_CONFIG_ARCHITECTURE.md](PLUGIN_CONFIG_ARCHITECTURE.md) — how the config system works
|
||||
- [PLUGIN_CONFIG_CORE_PROPERTIES.md](PLUGIN_CONFIG_CORE_PROPERTIES.md) — properties every plugin honors
|
||||
### ⚡ Advanced Features
|
||||
- [ADVANCED_FEATURES.md](ADVANCED_FEATURES.md) - Vegas scroll mode, on-demand display, cache management, background services, permissions
|
||||
|
||||
## Advanced features
|
||||
### 🔌 Plugin Development
|
||||
- [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md) - Complete plugin development workflow
|
||||
- [PLUGIN_QUICK_REFERENCE.md](PLUGIN_QUICK_REFERENCE.md) - Plugin development quick reference
|
||||
- [ADVANCED_PLUGIN_DEVELOPMENT.md](ADVANCED_PLUGIN_DEVELOPMENT.md) - Advanced patterns and examples
|
||||
- [PLUGIN_CONFIGURATION_GUIDE.md](PLUGIN_CONFIGURATION_GUIDE.md) - Configuration schema design
|
||||
- [PLUGIN_CONFIGURATION_TABS.md](PLUGIN_CONFIGURATION_TABS.md) - Configuration tabs feature
|
||||
- [PLUGIN_CONFIG_QUICK_START.md](PLUGIN_CONFIG_QUICK_START.md) - Quick configuration guide
|
||||
- [PLUGIN_DEPENDENCY_GUIDE.md](PLUGIN_DEPENDENCY_GUIDE.md) - Managing plugin dependencies
|
||||
- [PLUGIN_DEPENDENCY_TROUBLESHOOTING.md](PLUGIN_DEPENDENCY_TROUBLESHOOTING.md) - Dependency troubleshooting
|
||||
|
||||
- [ADVANCED_FEATURES.md](ADVANCED_FEATURES.md) — Vegas scroll, on-demand display,
|
||||
cache management, background services, permissions
|
||||
- [FONT_MANAGER.md](FONT_MANAGER.md) — font system
|
||||
### 🏗️ Plugin Features & Extensions
|
||||
- [PLUGIN_CUSTOM_ICONS.md](PLUGIN_CUSTOM_ICONS.md) - Custom plugin icons
|
||||
- [PLUGIN_CUSTOM_ICONS_FEATURE.md](PLUGIN_CUSTOM_ICONS_FEATURE.md) - Custom icons implementation
|
||||
- [PLUGIN_IMPLEMENTATION_SUMMARY.md](PLUGIN_IMPLEMENTATION_SUMMARY.md) - Plugin system implementation
|
||||
- [PLUGIN_REGISTRY_SETUP_GUIDE.md](PLUGIN_REGISTRY_SETUP_GUIDE.md) - Setting up plugin registry
|
||||
- [PLUGIN_WEB_UI_ACTIONS.md](PLUGIN_WEB_UI_ACTIONS.md) - Web UI actions for plugins
|
||||
|
||||
## Reference
|
||||
### 📡 API Reference
|
||||
- [REST_API_REFERENCE.md](REST_API_REFERENCE.md) - Complete REST API documentation (71+ endpoints)
|
||||
- [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) - Plugin developer API (Display Manager, Cache Manager, Plugin Manager)
|
||||
- [DEVELOPER_QUICK_REFERENCE.md](DEVELOPER_QUICK_REFERENCE.md) - Quick reference for common developer tasks
|
||||
|
||||
- [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
|
||||
- [DEVELOPER_QUICK_REFERENCE.md](DEVELOPER_QUICK_REFERENCE.md) — common dev tasks
|
||||
- [PLUGIN_IMPLEMENTATION_SUMMARY.md](PLUGIN_IMPLEMENTATION_SUMMARY.md) — what the plugin system actually does
|
||||
### 🏛️ Architecture & Design
|
||||
- [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md) - Complete plugin system specification
|
||||
- [PLUGIN_CONFIG_ARCHITECTURE.md](PLUGIN_CONFIG_ARCHITECTURE.md) - Configuration system architecture
|
||||
- [PLUGIN_CONFIG_CORE_PROPERTIES.md](PLUGIN_CONFIG_CORE_PROPERTIES.md) - Core configuration properties
|
||||
|
||||
## Contributing to LEDMatrix itself
|
||||
### 🛠️ Development & Tools
|
||||
- [DEVELOPMENT.md](DEVELOPMENT.md) - Development environment setup
|
||||
- [EMULATOR_SETUP_GUIDE.md](EMULATOR_SETUP_GUIDE.md) - Set up development environment with emulator
|
||||
- [HOW_TO_RUN_TESTS.md](HOW_TO_RUN_TESTS.md) - Testing documentation
|
||||
- [MULTI_ROOT_WORKSPACE_SETUP.md](MULTI_ROOT_WORKSPACE_SETUP.md) - Multi-workspace development
|
||||
- [FONT_MANAGER.md](FONT_MANAGER.md) - Font management system
|
||||
|
||||
- [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
|
||||
### 🔄 Migration & Updates
|
||||
- [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) - Breaking changes and migration instructions
|
||||
- [SSH_UNAVAILABLE_AFTER_INSTALL.md](SSH_UNAVAILABLE_AFTER_INSTALL.md) - SSH troubleshooting after install
|
||||
|
||||
## Archive
|
||||
### 📚 Miscellaneous
|
||||
- [widget-guide.md](widget-guide.md) - Widget development guide
|
||||
- Template files:
|
||||
- [plugin_registry_template.json](plugin_registry_template.json) - Plugin registry template
|
||||
- [PLUGIN_WEB_UI_ACTIONS_EXAMPLE.json](PLUGIN_WEB_UI_ACTIONS_EXAMPLE.json) - Web UI actions example
|
||||
|
||||
`docs/archive/` holds older guides that have been superseded or describe
|
||||
features that have been removed. They are kept for historical context and
|
||||
git history but should not be relied on.
|
||||
## 🎯 Key Resources by Use Case
|
||||
|
||||
## Contributing to the docs
|
||||
### I'm new to LEDMatrix
|
||||
1. [GETTING_STARTED.md](GETTING_STARTED.md) - Start here for first-time setup
|
||||
2. [WEB_INTERFACE_GUIDE.md](WEB_INTERFACE_GUIDE.md) - Learn the control panel
|
||||
3. [PLUGIN_STORE_GUIDE.md](PLUGIN_STORE_GUIDE.md) - Install plugins
|
||||
|
||||
- Markdown only, professional tone, minimal emoji.
|
||||
- Prefer adding to an existing page over creating a new one. If you add a
|
||||
new page, link it from this index in the section it belongs to.
|
||||
- If a page becomes obsolete, move it to `docs/archive/` rather than
|
||||
deleting it, so links don't rot.
|
||||
- Keep examples runnable — paths, commands, and config keys here should
|
||||
match what's actually in the repo.
|
||||
### I want to create a plugin
|
||||
1. [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md) - Complete development guide
|
||||
2. [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) - Available methods and APIs
|
||||
3. [ADVANCED_PLUGIN_DEVELOPMENT.md](ADVANCED_PLUGIN_DEVELOPMENT.md) - Advanced patterns
|
||||
4. [PLUGIN_CONFIGURATION_GUIDE.md](PLUGIN_CONFIGURATION_GUIDE.md) - Configuration setup
|
||||
5. [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md) - Complete specification
|
||||
|
||||
### I need to troubleshoot an issue
|
||||
1. [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Comprehensive troubleshooting guide
|
||||
2. [WIFI_NETWORK_SETUP.md](WIFI_NETWORK_SETUP.md) - WiFi/network issues
|
||||
3. [PLUGIN_DEPENDENCY_TROUBLESHOOTING.md](PLUGIN_DEPENDENCY_TROUBLESHOOTING.md) - Dependency issues
|
||||
|
||||
### I want to use advanced features
|
||||
1. [ADVANCED_FEATURES.md](ADVANCED_FEATURES.md) - Vegas scroll, on-demand display, background services
|
||||
2. [FONT_MANAGER.md](FONT_MANAGER.md) - Font management
|
||||
3. [REST_API_REFERENCE.md](REST_API_REFERENCE.md) - API integration
|
||||
|
||||
### I want to understand the architecture
|
||||
1. [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md) - System architecture
|
||||
2. [PLUGIN_CONFIG_ARCHITECTURE.md](PLUGIN_CONFIG_ARCHITECTURE.md) - Configuration architecture
|
||||
3. [PLUGIN_IMPLEMENTATION_SUMMARY.md](PLUGIN_IMPLEMENTATION_SUMMARY.md) - Implementation details
|
||||
|
||||
## 🔄 Recent Consolidations (January 2026)
|
||||
|
||||
### Major Consolidation Effort
|
||||
- **Before**: 51 main documentation files
|
||||
- **After**: 16-17 well-organized files
|
||||
- **Reduction**: ~68% fewer files
|
||||
- **Archived**: 33 files (consolidated sources + ephemeral docs)
|
||||
|
||||
### New Consolidated Guides
|
||||
- **GETTING_STARTED.md** - New first-time user guide
|
||||
- **WEB_INTERFACE_GUIDE.md** - Consolidated web interface documentation
|
||||
- **WIFI_NETWORK_SETUP.md** - Consolidated WiFi setup (5 files → 1)
|
||||
- **PLUGIN_STORE_GUIDE.md** - Consolidated plugin store guides (2 files → 1)
|
||||
- **TROUBLESHOOTING.md** - Consolidated troubleshooting (4 files → 1)
|
||||
- **ADVANCED_FEATURES.md** - Consolidated advanced features (6 files → 1)
|
||||
|
||||
### What Was Archived
|
||||
- Ephemeral debug documents (DEBUG_WEB_ISSUE.md, BROWSER_ERRORS_EXPLANATION.md, etc.)
|
||||
- Implementation summaries (PLUGIN_CONFIG_TABS_SUMMARY.md, STARTUP_OPTIMIZATION_SUMMARY.md, etc.)
|
||||
- Consolidated source files (WIFI_SETUP.md, V3_INTERFACE_README.md, etc.)
|
||||
- Testing documentation (CAPTIVE_PORTAL_TESTING.md, etc.)
|
||||
|
||||
All archived files are preserved in `docs/archive/` with full git history.
|
||||
|
||||
### Benefits
|
||||
- ✅ Easier to find information (fewer files to search)
|
||||
- ✅ No duplicate content
|
||||
- ✅ Consistent writing style (professional technical)
|
||||
- ✅ Updated outdated references
|
||||
- ✅ Fixed broken internal links
|
||||
- ✅ Better organization for users vs developers
|
||||
|
||||
## 📝 Contributing to Documentation
|
||||
|
||||
### Documentation Standards
|
||||
- Use Markdown format with consistent headers
|
||||
- Professional technical writing style
|
||||
- Minimal emojis (1-2 per major section for navigation)
|
||||
- Include code examples where helpful
|
||||
- Provide both quick start and detailed reference sections
|
||||
- Cross-reference related documentation
|
||||
|
||||
### Adding New Documentation
|
||||
1. Consider if content should be added to existing docs first
|
||||
2. Place in appropriate category (see sections above)
|
||||
3. Update this README.md with the new document
|
||||
4. Follow naming conventions (FEATURE_NAME.md)
|
||||
5. Use consistent formatting and voice
|
||||
|
||||
### Consolidation Guidelines
|
||||
- **User Guides**: Consolidate by topic (WiFi, troubleshooting, etc.)
|
||||
- **Developer Guides**: Keep development vs reference vs architecture separate
|
||||
- **Debug Documents**: Archive after issues are resolved
|
||||
- **Implementation Summaries**: Archive completed implementation details
|
||||
- **Ephemeral Content**: Archive, don't keep in main docs
|
||||
|
||||
## 🔗 Related Documentation
|
||||
|
||||
- [Main Project README](../README.md) - Installation and basic usage
|
||||
- [Web Interface README](../web_interface/README.md) - Web interface details
|
||||
- [GitHub Issues](https://github.com/ChuckBuilds/LEDMatrix/issues) - Bug reports and feature requests
|
||||
- [GitHub Discussions](https://github.com/ChuckBuilds/LEDMatrix/discussions) - Community support
|
||||
|
||||
## 📊 Documentation Statistics
|
||||
|
||||
- **Main Documents**: 16-17 files (after consolidation)
|
||||
- **Archived Documents**: 33 files (in docs/archive/)
|
||||
- **Categories**: 9 major sections
|
||||
- **Primary Language**: English
|
||||
- **Format**: Markdown (.md)
|
||||
- **Last Major Update**: January 2026
|
||||
- **Coverage**: Installation, user guides, development, troubleshooting, architecture, API references
|
||||
|
||||
### Documentation Highlights
|
||||
- ✅ Comprehensive user guides for first-time setup
|
||||
- ✅ Complete REST API documentation (71+ endpoints)
|
||||
- ✅ Complete Plugin API reference (Display Manager, Cache Manager, Plugin Manager)
|
||||
- ✅ Advanced plugin development guide with examples
|
||||
- ✅ Consolidated configuration documentation
|
||||
- ✅ Professional technical writing throughout
|
||||
- ✅ ~68% reduction in file count while maintaining coverage
|
||||
|
||||
---
|
||||
|
||||
*This documentation index was last updated: January 2026*
|
||||
|
||||
*For questions or suggestions about the documentation, please open an issue or start a discussion on GitHub.*
|
||||
|
||||
@@ -24,17 +24,6 @@ All endpoints return JSON responses with a standard format:
|
||||
- [Cache](#cache)
|
||||
- [WiFi](#wifi)
|
||||
- [Streams](#streams)
|
||||
- [Logs](#logs)
|
||||
- [Error tracking](#error-tracking)
|
||||
- [Health](#health)
|
||||
- [Schedule (dim/power)](#schedule-dimpower)
|
||||
- [Plugin-specific endpoints](#plugin-specific-endpoints)
|
||||
- [Starlark Apps](#starlark-apps)
|
||||
|
||||
> The API blueprint is mounted at `/api/v3` (`web_interface/app.py:144`).
|
||||
> SSE stream endpoints (`/api/v3/stream/*`) are defined directly on the
|
||||
> Flask app at `app.py:607-615`. There are about 92 routes total — see
|
||||
> `web_interface/blueprints/api_v3.py` for the canonical list.
|
||||
|
||||
---
|
||||
|
||||
@@ -1212,16 +1201,10 @@ Upload a custom font file.
|
||||
|
||||
### Delete Font
|
||||
|
||||
**DELETE** `/api/v3/fonts/<font_family>`
|
||||
**DELETE** `/api/v3/fonts/delete/<font_family>`
|
||||
|
||||
Delete an uploaded font.
|
||||
|
||||
### Font Preview
|
||||
|
||||
**GET** `/api/v3/fonts/preview?family=<font_family>&text=<sample>`
|
||||
|
||||
Render a small preview image of a font for use in the web UI font picker.
|
||||
|
||||
---
|
||||
|
||||
## Cache
|
||||
@@ -1456,130 +1439,6 @@ Get recent log entries.
|
||||
|
||||
---
|
||||
|
||||
## Error tracking
|
||||
|
||||
### Get Error Summary
|
||||
|
||||
**GET** `/api/v3/errors/summary`
|
||||
|
||||
Aggregated counts of recent errors across all plugins and core
|
||||
components, used by the web UI's error indicator.
|
||||
|
||||
### Get Plugin Errors
|
||||
|
||||
**GET** `/api/v3/errors/plugin/<plugin_id>`
|
||||
|
||||
Recent errors for a specific plugin.
|
||||
|
||||
### Clear Errors
|
||||
|
||||
**POST** `/api/v3/errors/clear`
|
||||
|
||||
Clear the in-memory error aggregator.
|
||||
|
||||
---
|
||||
|
||||
## Health
|
||||
|
||||
### Health Check
|
||||
|
||||
**GET** `/api/v3/health`
|
||||
|
||||
Lightweight liveness check used by the WiFi monitor and external
|
||||
monitoring tools.
|
||||
|
||||
---
|
||||
|
||||
## Schedule (dim/power)
|
||||
|
||||
### Get Dim Schedule
|
||||
|
||||
**GET** `/api/v3/config/dim-schedule`
|
||||
|
||||
Read the dim/power schedule that automatically reduces brightness or
|
||||
turns the display off at configured times.
|
||||
|
||||
### Update Dim Schedule
|
||||
|
||||
**POST** `/api/v3/config/dim-schedule`
|
||||
|
||||
Update the dim schedule. Body matches the structure returned by GET.
|
||||
|
||||
---
|
||||
|
||||
## Plugin-specific endpoints
|
||||
|
||||
A handful of endpoints belong to individual built-in or shipped plugins.
|
||||
|
||||
### Calendar
|
||||
|
||||
**GET** `/api/v3/plugins/calendar/list-calendars`
|
||||
|
||||
List the calendars available on the authenticated Google account.
|
||||
Used by the calendar plugin's config UI.
|
||||
|
||||
### Of The Day
|
||||
|
||||
**POST** `/api/v3/plugins/of-the-day/json/upload`
|
||||
|
||||
Upload a JSON data file for the Of-The-Day plugin's category data.
|
||||
|
||||
**POST** `/api/v3/plugins/of-the-day/json/delete`
|
||||
|
||||
Delete a previously uploaded Of-The-Day data file.
|
||||
|
||||
### Plugin Static Assets
|
||||
|
||||
**GET** `/api/v3/plugins/<plugin_id>/static/<path:file_path>`
|
||||
|
||||
Serve a static asset (image, font, etc.) from a plugin's directory.
|
||||
Used internally by the web UI to render plugin previews and icons.
|
||||
|
||||
---
|
||||
|
||||
## Starlark Apps
|
||||
|
||||
The Starlark plugin lets you run [Tronbyt](https://github.com/tronbyt/apps)
|
||||
Starlark apps on the matrix. These endpoints expose its UI.
|
||||
|
||||
### Status
|
||||
|
||||
**GET** `/api/v3/starlark/status`
|
||||
|
||||
Returns whether the Pixlet binary is installed and the Starlark plugin
|
||||
is operational.
|
||||
|
||||
### Install Pixlet
|
||||
|
||||
**POST** `/api/v3/starlark/install-pixlet`
|
||||
|
||||
Download and install the Pixlet binary on the Pi.
|
||||
|
||||
### Apps
|
||||
|
||||
**GET** `/api/v3/starlark/apps` — list installed Starlark apps
|
||||
**GET** `/api/v3/starlark/apps/<app_id>` — get app details
|
||||
**DELETE** `/api/v3/starlark/apps/<app_id>` — uninstall an app
|
||||
**GET** `/api/v3/starlark/apps/<app_id>/config` — get app config schema
|
||||
**PUT** `/api/v3/starlark/apps/<app_id>/config` — update app config
|
||||
**POST** `/api/v3/starlark/apps/<app_id>/render` — render app to a frame
|
||||
**POST** `/api/v3/starlark/apps/<app_id>/toggle` — enable/disable app
|
||||
|
||||
### Repository (Tronbyt community apps)
|
||||
|
||||
**GET** `/api/v3/starlark/repository/categories` — browse categories
|
||||
**GET** `/api/v3/starlark/repository/browse?category=<cat>` — browse apps
|
||||
**POST** `/api/v3/starlark/repository/install` — install an app from the
|
||||
community repository
|
||||
|
||||
### Upload custom app
|
||||
|
||||
**POST** `/api/v3/starlark/upload`
|
||||
|
||||
Upload a custom Starlark `.star` file as a new app.
|
||||
|
||||
---
|
||||
|
||||
## Error Responses
|
||||
|
||||
All endpoints may return error responses in the following format:
|
||||
|
||||
@@ -54,7 +54,7 @@ If the script reboots the Pi (which it recommends), network services may restart
|
||||
# Connect to your WiFi network (replace with your SSID and password)
|
||||
sudo nmcli device wifi connect "YourWiFiSSID" password "YourPassword"
|
||||
|
||||
# Or use the web interface at http://192.168.4.1:5000
|
||||
# Or use the web interface at http://192.168.4.1:5001
|
||||
# Navigate to WiFi tab and connect to your network
|
||||
```
|
||||
|
||||
@@ -177,9 +177,9 @@ sudo systemctl restart NetworkManager
|
||||
|
||||
Even if SSH is unavailable, you can access the web interface:
|
||||
|
||||
1. **Via AP Mode**: Connect to **LEDMatrix-Setup** network and visit `http://192.168.4.1:5000`
|
||||
2. **Via WiFi**: If WiFi is connected, visit `http://<pi-ip-address>:5000`
|
||||
3. **Via Ethernet**: Visit `http://<pi-ip-address>:5000`
|
||||
1. **Via AP Mode**: Connect to **LEDMatrix-Setup** network and visit `http://192.168.4.1:5001`
|
||||
2. **Via WiFi**: If WiFi is connected, visit `http://<pi-ip-address>:5001`
|
||||
3. **Via Ethernet**: Visit `http://<pi-ip-address>:5001`
|
||||
|
||||
The web interface allows you to:
|
||||
- Configure WiFi connections
|
||||
|
||||
@@ -91,7 +91,7 @@ Pixlet is the rendering engine that executes Starlark apps. The plugin will atte
|
||||
|
||||
#### Auto-Install via Web UI
|
||||
|
||||
Navigate to: **Plugin Manager → Starlark Apps tab (in the second nav row) → Status → Install Pixlet**
|
||||
Navigate to: **Plugins → Starlark Apps → Status → Install Pixlet**
|
||||
|
||||
This runs the bundled installation script which downloads the appropriate binary for your platform.
|
||||
|
||||
@@ -110,10 +110,10 @@ Verify installation:
|
||||
|
||||
### 2. Enable the Starlark Apps Plugin
|
||||
|
||||
1. Open the web UI (`http://your-pi-ip:5000`)
|
||||
2. Open the **Plugin Manager** tab
|
||||
3. Find **Starlark Apps** in the **Installed Plugins** list
|
||||
4. Enable the plugin (it then gets its own tab in the second nav row)
|
||||
1. Open the web UI
|
||||
2. Navigate to **Plugins**
|
||||
3. Find **Starlark Apps** in the installed plugins list
|
||||
4. Enable the plugin
|
||||
5. Configure settings:
|
||||
- **Magnify**: Auto-calculated based on your display size (or set manually)
|
||||
- **Render Interval**: How often apps re-render (default: 300s)
|
||||
@@ -122,7 +122,7 @@ Verify installation:
|
||||
|
||||
### 3. Browse and Install Apps
|
||||
|
||||
1. Navigate to **Plugin Manager → Starlark Apps tab (in the second nav row) → App Store**
|
||||
1. Navigate to **Plugins → Starlark Apps → App Store**
|
||||
2. Browse available apps (974+ options)
|
||||
3. Filter by category: Weather, Sports, Finance, Games, Clocks, etc.
|
||||
4. Click **Install** on desired apps
|
||||
@@ -307,7 +307,7 @@ Many apps require API keys for external services:
|
||||
**Symptom**: "Pixlet binary not found" error
|
||||
|
||||
**Solutions**:
|
||||
1. Run auto-installer: **Plugin Manager → Starlark Apps tab (in the second nav row) → Install Pixlet**
|
||||
1. Run auto-installer: **Plugins → Starlark Apps → Install Pixlet**
|
||||
2. Manual install: `bash scripts/download_pixlet.sh`
|
||||
3. Check permissions: `chmod +x bin/pixlet/pixlet-*`
|
||||
4. Verify architecture: `uname -m` matches binary name
|
||||
@@ -338,7 +338,7 @@ Many apps require API keys for external services:
|
||||
**Symptom**: Content appears stretched, squished, or cropped
|
||||
|
||||
**Solutions**:
|
||||
1. Check magnify setting: **Plugin Manager → Starlark Apps tab (in the second nav row) → Config**
|
||||
1. Check magnify setting: **Plugins → Starlark Apps → Config**
|
||||
2. Try `center_small_output=true` to preserve aspect ratio
|
||||
3. Adjust `magnify` manually (1-8) for your display size
|
||||
4. Some apps assume 64×32 - may not scale perfectly to all sizes
|
||||
@@ -349,7 +349,7 @@ Many apps require API keys for external services:
|
||||
|
||||
**Solutions**:
|
||||
1. Check render interval: **App Config → Render Interval** (300s default)
|
||||
2. Force re-render: **Plugin Manager → Starlark Apps tab (in the second nav row) → {App} → Render Now**
|
||||
2. Force re-render: **Plugins → Starlark Apps → {App} → Render Now**
|
||||
3. Clear cache: Restart LEDMatrix service
|
||||
4. API rate limits: Some services throttle requests
|
||||
5. Check app logs for API errors
|
||||
|
||||
@@ -47,15 +47,13 @@ bash scripts/diagnose_web_interface.sh
|
||||
# WiFi setup verification
|
||||
./scripts/verify_wifi_setup.sh
|
||||
|
||||
# Weather plugin troubleshooting
|
||||
./troubleshoot_weather.sh
|
||||
|
||||
# Captive portal troubleshooting
|
||||
./scripts/troubleshoot_captive_portal.sh
|
||||
```
|
||||
|
||||
> Weather is provided by the `ledmatrix-weather` plugin (installed via the
|
||||
> Plugin Store). To troubleshoot weather, check that plugin's tab in the
|
||||
> web UI for its API key and recent error messages, then watch the
|
||||
> **Logs** tab.
|
||||
|
||||
### 4. Check Configuration
|
||||
|
||||
```bash
|
||||
@@ -87,7 +85,7 @@ python3 web_interface/start.py
|
||||
#### Service Not Running/Starting
|
||||
|
||||
**Symptoms:**
|
||||
- Cannot access web interface at http://your-pi-ip:5000
|
||||
- Cannot access web interface at http://your-pi-ip:5050
|
||||
- `systemctl status ledmatrix-web` shows `inactive (dead)`
|
||||
|
||||
**Solutions:**
|
||||
@@ -159,13 +157,13 @@ sudo systemctl restart ledmatrix-web
|
||||
|
||||
**Symptoms:**
|
||||
- Error: `Address already in use`
|
||||
- Service fails to bind to port 5000
|
||||
- Service fails to bind to port 5050
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check what's using the port:**
|
||||
```bash
|
||||
sudo lsof -i :5000
|
||||
sudo lsof -i :5050
|
||||
```
|
||||
|
||||
2. **Kill the conflicting process:**
|
||||
@@ -267,7 +265,7 @@ sudo systemctl cat ledmatrix-web | grep User
|
||||
6. **Manually enable AP mode:**
|
||||
```bash
|
||||
# Via API
|
||||
curl -X POST http://localhost:5000/api/wifi/ap/enable
|
||||
curl -X POST http://localhost:5050/api/wifi/ap/enable
|
||||
|
||||
# Via Python
|
||||
python3 -c "
|
||||
@@ -293,8 +291,9 @@ sudo systemctl cat ledmatrix-web | grep User
|
||||
```
|
||||
|
||||
2. **Use correct IP address and port:**
|
||||
- Correct: `http://192.168.4.1:5000`
|
||||
- NOT: `http://192.168.4.1` (port 80 — nothing listens there)
|
||||
- Correct: `http://192.168.4.1:5050`
|
||||
- NOT: `http://192.168.4.1` (port 80)
|
||||
- NOT: `http://192.168.4.1:5000`
|
||||
|
||||
3. **Check wlan0 has correct IP:**
|
||||
```bash
|
||||
@@ -310,7 +309,7 @@ sudo systemctl cat ledmatrix-web | grep User
|
||||
|
||||
5. **Test from the Pi itself:**
|
||||
```bash
|
||||
curl http://192.168.4.1:5000
|
||||
curl http://192.168.4.1:5050
|
||||
# Should return HTML
|
||||
```
|
||||
|
||||
@@ -341,11 +340,11 @@ sudo systemctl cat ledmatrix-web | grep User
|
||||
|
||||
4. **Manual captive portal testing:**
|
||||
- Try these URLs manually:
|
||||
- `http://192.168.4.1:5000`
|
||||
- `http://192.168.4.1:5050`
|
||||
- `http://captive.apple.com`
|
||||
- `http://connectivitycheck.gstatic.com/generate_204`
|
||||
|
||||
#### Firewall Blocking Port 5000
|
||||
#### Firewall Blocking Port 5050
|
||||
|
||||
**Symptoms:**
|
||||
- Services running but cannot connect
|
||||
@@ -358,9 +357,9 @@ sudo systemctl cat ledmatrix-web | grep User
|
||||
sudo ufw status
|
||||
```
|
||||
|
||||
2. **Allow port 5000:**
|
||||
2. **Allow port 5050:**
|
||||
```bash
|
||||
sudo ufw allow 5000/tcp
|
||||
sudo ufw allow 5050/tcp
|
||||
```
|
||||
|
||||
3. **Check iptables:**
|
||||
@@ -373,7 +372,7 @@ sudo systemctl cat ledmatrix-web | grep User
|
||||
sudo ufw disable
|
||||
# Test if it works, then re-enable and add rule
|
||||
sudo ufw enable
|
||||
sudo ufw allow 5000/tcp
|
||||
sudo ufw allow 5050/tcp
|
||||
```
|
||||
|
||||
---
|
||||
@@ -404,9 +403,9 @@ sudo systemctl cat ledmatrix-web | grep User
|
||||
```
|
||||
|
||||
3. **Verify in web interface:**
|
||||
- Open the **Plugin Manager** tab
|
||||
- Toggle the plugin switch to enable
|
||||
- From **Overview**, click **Restart Display Service**
|
||||
- Navigate to Plugin Management tab
|
||||
- Toggle the switch to enable
|
||||
- Restart display
|
||||
|
||||
#### Plugin Not Loading
|
||||
|
||||
@@ -691,12 +690,12 @@ nslookup api.openweathermap.org
|
||||
dig api.openweathermap.org
|
||||
|
||||
# Test HTTP endpoint
|
||||
curl -I http://your-pi-ip:5000
|
||||
curl http://192.168.4.1:5000
|
||||
curl -I http://your-pi-ip:5050
|
||||
curl http://192.168.4.1:5050
|
||||
|
||||
# Check listening ports
|
||||
sudo lsof -i :5000
|
||||
sudo netstat -tuln | grep 5000
|
||||
sudo lsof -i :5050
|
||||
sudo netstat -tuln | grep 5050
|
||||
|
||||
# Check network interfaces
|
||||
ip addr show
|
||||
@@ -809,7 +808,7 @@ echo ""
|
||||
|
||||
echo "4. Network Status:"
|
||||
ip addr show | grep -E "(wlan|eth|inet )"
|
||||
curl -s http://localhost:5000 > /dev/null && echo "Web interface: OK" || echo "Web interface: FAILED"
|
||||
curl -s http://localhost:5050 > /dev/null && echo "Web interface: OK" || echo "Web interface: FAILED"
|
||||
echo ""
|
||||
|
||||
echo "5. File Structure:"
|
||||
@@ -838,22 +837,22 @@ A properly functioning system should show:
|
||||
```
|
||||
|
||||
2. **Web Interface Accessible:**
|
||||
- Navigate to http://your-pi-ip:5000
|
||||
- Navigate to http://your-pi-ip:5050
|
||||
- Page loads successfully
|
||||
- Display preview visible
|
||||
|
||||
3. **Logs Show Normal Operation:**
|
||||
```
|
||||
INFO: Web interface started on port 5000
|
||||
INFO: Web interface started on port 5050
|
||||
INFO: Loaded X plugins
|
||||
INFO: Display rotation active
|
||||
```
|
||||
|
||||
4. **Process Listening on Port:**
|
||||
```bash
|
||||
$ sudo lsof -i :5000
|
||||
$ sudo lsof -i :5050
|
||||
COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
|
||||
python3 1234 ledpi 3u IPv4 12345 0t0 TCP *:5000 (LISTEN)
|
||||
python3 1234 ledpi 3u IPv4 12345 0t0 TCP *:5050 (LISTEN)
|
||||
```
|
||||
|
||||
5. **Plugins Loading:**
|
||||
|
||||
@@ -17,7 +17,7 @@ The LEDMatrix web interface provides a complete control panel for managing your
|
||||
|
||||
2. Open a web browser and navigate to:
|
||||
```
|
||||
http://your-pi-ip:5000
|
||||
http://your-pi-ip:5050
|
||||
```
|
||||
|
||||
3. The interface will load with the Overview tab displaying system stats and a live display preview.
|
||||
@@ -31,28 +31,17 @@ sudo systemctl status ledmatrix-web
|
||||
|
||||
## Navigation
|
||||
|
||||
The interface uses a two-row tab layout. The system tabs are always
|
||||
present:
|
||||
The interface uses a tab-based layout for easy navigation between features:
|
||||
|
||||
- **Overview** — System stats, quick actions, live display preview
|
||||
- **General** — Timezone, location, plugin-system settings
|
||||
- **WiFi** — Network selection and AP-mode setup
|
||||
- **Schedule** — Power and dim schedules
|
||||
- **Display** — Matrix hardware configuration (rows, cols, hardware
|
||||
mapping, GPIO slowdown, brightness, PWM)
|
||||
- **Config Editor** — Raw `config.json` editor with validation
|
||||
- **Fonts** — Upload and manage fonts
|
||||
- **Logs** — Real-time log streaming
|
||||
- **Cache** — Cached data inspection and cleanup
|
||||
- **Operation History** — Recent service operations
|
||||
|
||||
A second nav row holds plugin tabs:
|
||||
|
||||
- **Plugin Manager** — browse the **Plugin Store** section, install
|
||||
plugins from GitHub, enable/disable installed plugins
|
||||
- **<plugin-id>** — one tab per installed plugin for its own
|
||||
configuration form (auto-generated from the plugin's
|
||||
`config_schema.json`)
|
||||
- **Overview** - System stats, quick actions, and display preview
|
||||
- **General Settings** - Timezone, location, and autostart configuration
|
||||
- **Display Settings** - Hardware configuration, brightness, and display options
|
||||
- **Durations** - Display rotation timing configuration
|
||||
- **Sports Configuration** - Per-league settings and on-demand modes
|
||||
- **Plugin Management** - Install, configure, enable/disable plugins
|
||||
- **Plugin Store** - Discover and install plugins
|
||||
- **Font Management** - Upload fonts, manage overrides, and preview
|
||||
- **Logs** - Real-time log streaming with filtering and search
|
||||
|
||||
---
|
||||
|
||||
@@ -68,84 +57,131 @@ The Overview tab provides at-a-glance information and quick actions:
|
||||
- Disk usage
|
||||
- Network status
|
||||
|
||||
**Quick Actions** (verified in `web_interface/templates/v3/partials/overview.html`):
|
||||
- **Start Display** / **Stop Display** — control the display service
|
||||
- **Restart Display Service** — apply configuration changes
|
||||
- **Restart Web Service** — restart the web UI itself
|
||||
- **Update Code** — `git pull` the latest version (stashes local changes)
|
||||
- **Reboot System** / **Shutdown System** — confirm-gated power controls
|
||||
**Quick Actions:**
|
||||
- **Start/Stop Display** - Control the display service
|
||||
- **Restart Display** - Restart to apply configuration changes
|
||||
- **Test Display** - Run a quick test pattern
|
||||
|
||||
**Display Preview:**
|
||||
- Live preview of what's currently shown on the LED matrix
|
||||
- Updates in real-time
|
||||
- Useful for remote monitoring
|
||||
|
||||
### General Tab
|
||||
### General Settings Tab
|
||||
|
||||
Configure basic system settings:
|
||||
|
||||
- **Timezone** — used by all time/date displays
|
||||
- **Location** — city/state/country for weather and other location-aware
|
||||
plugins
|
||||
- **Plugin System Settings** — including the `plugins_directory` (default
|
||||
`plugin-repos/`) used by the plugin loader
|
||||
- **Autostart** options for the display service
|
||||
**Timezone:**
|
||||
- Set your local timezone for accurate time display
|
||||
- Auto-detects common timezones
|
||||
|
||||
Click **Save** to write changes to `config/config.json`. Most changes
|
||||
require a display service restart from **Overview**.
|
||||
**Location:**
|
||||
- Set latitude/longitude for location-based features
|
||||
- Used by weather plugins and sunrise/sunset calculations
|
||||
|
||||
### Display Tab
|
||||
**Autostart:**
|
||||
- Enable/disable display autostart on boot
|
||||
- Configure systemd service settings
|
||||
|
||||
**Save Changes:**
|
||||
- Click "Save Configuration" to apply changes
|
||||
- Restart the display for changes to take effect
|
||||
|
||||
### Display Settings Tab
|
||||
|
||||
Configure your LED matrix hardware:
|
||||
|
||||
**Matrix configuration:**
|
||||
- `rows` — LED rows (typically 32 or 64)
|
||||
- `cols` — LED columns (typically 64 or 96)
|
||||
- `chain_length` — number of horizontally chained panels
|
||||
- `parallel` — number of parallel chains
|
||||
- `hardware_mapping` — `adafruit-hat-pwm` (with PWM jumper mod),
|
||||
`adafruit-hat` (without), `regular`, or `regular-pi1`
|
||||
- `gpio_slowdown` — must match your Pi model (3 for Pi 3, 4 for Pi 4, etc.)
|
||||
- `brightness` — 0–100%
|
||||
- `pwm_bits`, `pwm_lsb_nanoseconds`, `pwm_dither_bits` — PWM tuning
|
||||
- Dynamic Duration — global cap for plugins that extend their display
|
||||
time based on content
|
||||
**Matrix Configuration:**
|
||||
- Rows: Number of LED rows (typically 32 or 64)
|
||||
- Columns: Number of LED columns (typically 64, 128, or 256)
|
||||
- Chain Length: Number of chained panels
|
||||
- Parallel Chains: Number of parallel chains
|
||||
|
||||
Changes require **Restart Display Service** from the Overview tab.
|
||||
**Display Options:**
|
||||
- Brightness: Adjust LED brightness (0-100%)
|
||||
- Hardware Mapping: GPIO pin mapping
|
||||
- Slowdown GPIO: Timing adjustment for compatibility
|
||||
|
||||
### Plugin Manager Tab
|
||||
**Save and Apply:**
|
||||
- Changes require a display restart
|
||||
- Use "Test Display" to verify configuration
|
||||
|
||||
The Plugin Manager has three main sections:
|
||||
### Durations Tab
|
||||
|
||||
1. **Installed Plugins** — toggle installed plugins on/off, see version
|
||||
info. Each installed plugin also gets its own tab in the second nav
|
||||
row for its configuration form.
|
||||
2. **Plugin Store** — browse plugins from the official
|
||||
`ledmatrix-plugins` registry. Click **Install** to fetch and
|
||||
install. Filter by category and search.
|
||||
3. **Install from GitHub** — install third-party plugins by pasting a
|
||||
GitHub repository URL. **Install Single Plugin** for a single-plugin
|
||||
repo, **Load Registry** for a multi-plugin monorepo.
|
||||
Control how long each plugin displays:
|
||||
|
||||
When a plugin is installed and enabled:
|
||||
- A new tab for that plugin appears in the second nav row
|
||||
- Open the tab to edit its config (auto-generated form from
|
||||
`config_schema.json`)
|
||||
- The tab also exposes **Run On-Demand** / **Stop On-Demand** controls
|
||||
to render that plugin immediately, even if it's disabled in the
|
||||
rotation
|
||||
**Global Settings:**
|
||||
- Default Duration: Default time for plugins without specific durations
|
||||
- Transition Speed: Speed of transitions between plugins
|
||||
|
||||
### Per-plugin Configuration Tabs
|
||||
**Per-Plugin Durations:**
|
||||
- Set custom display duration for each plugin
|
||||
- Override global default for specific plugins
|
||||
- Measured in seconds
|
||||
|
||||
Each installed plugin has its own tab in the second nav row. The form
|
||||
fields are auto-generated from the plugin's `config_schema.json`, so
|
||||
options always match the plugin's current code.
|
||||
### Sports Configuration Tab
|
||||
|
||||
To temporarily run a plugin outside the normal rotation, use the
|
||||
**Run On-Demand** / **Stop On-Demand** buttons inside its tab. This
|
||||
works even when the plugin is disabled.
|
||||
Configure sports-specific settings:
|
||||
|
||||
### Fonts Tab
|
||||
**Per-League Settings:**
|
||||
- Favorite teams
|
||||
- Show favorite teams only
|
||||
- Include scores/standings
|
||||
- Refresh intervals
|
||||
|
||||
**On-Demand Modes:**
|
||||
- Live Priority: Show live games immediately
|
||||
- Game Day Mode: Enhanced display during game days
|
||||
- Score Alerts: Highlight score changes
|
||||
|
||||
### Plugin Management Tab
|
||||
|
||||
Manage installed plugins:
|
||||
|
||||
**Plugin List:**
|
||||
- View all installed plugins
|
||||
- See plugin status (enabled/disabled)
|
||||
- Check last update time
|
||||
|
||||
**Actions:**
|
||||
- **Enable/Disable**: Toggle plugin using the switch
|
||||
- **Configure**: Click ⚙️ to edit plugin settings
|
||||
- **Update**: Update plugin to latest version
|
||||
- **Uninstall**: Remove plugin completely
|
||||
|
||||
**Configuration:**
|
||||
- Edit plugin-specific settings
|
||||
- Changes are saved to `config/config.json`
|
||||
- Restart display to apply changes
|
||||
|
||||
**Note:** See [PLUGIN_STORE_GUIDE.md](PLUGIN_STORE_GUIDE.md) for information on installing plugins.
|
||||
|
||||
### Plugin Store Tab
|
||||
|
||||
Discover and install new plugins:
|
||||
|
||||
**Browse Plugins:**
|
||||
- View available plugins in the official store
|
||||
- Filter by category (sports, weather, time, finance, etc.)
|
||||
- Search by name, description, or author
|
||||
|
||||
**Install Plugins:**
|
||||
- Click "Install" next to any plugin
|
||||
- Wait for installation to complete
|
||||
- Restart the display to activate
|
||||
|
||||
**Install from URL:**
|
||||
- Install plugins from any GitHub repository
|
||||
- Paste the repository URL in the "Install from URL" section
|
||||
- Review the warning about unverified plugins
|
||||
- Click "Install from URL"
|
||||
|
||||
**Plugin Information:**
|
||||
- View plugin descriptions, ratings, and screenshots
|
||||
- Check compatibility and requirements
|
||||
- Read user reviews (when available)
|
||||
|
||||
### Font Management Tab
|
||||
|
||||
Manage fonts for your display:
|
||||
|
||||
@@ -193,37 +229,37 @@ View real-time system logs:
|
||||
|
||||
### Changing Display Brightness
|
||||
|
||||
1. Open the **Display** tab
|
||||
2. Adjust the **Brightness** slider (0–100)
|
||||
3. Click **Save**
|
||||
4. Click **Restart Display Service** on the **Overview** tab
|
||||
1. Navigate to the **Display Settings** tab
|
||||
2. Adjust the **Brightness** slider (0-100%)
|
||||
3. Click **Save Configuration**
|
||||
4. Restart the display for changes to take effect
|
||||
|
||||
### Installing a New Plugin
|
||||
|
||||
1. Open the **Plugin Manager** tab
|
||||
2. Scroll to the **Plugin Store** section and browse or search
|
||||
1. Navigate to the **Plugin Store** tab
|
||||
2. Browse or search for the desired plugin
|
||||
3. Click **Install** next to the plugin
|
||||
4. Toggle the plugin on in **Installed Plugins**
|
||||
5. Click **Restart Display Service** on **Overview**
|
||||
4. Wait for installation to complete
|
||||
5. Restart the display
|
||||
6. Enable the plugin in the **Plugin Management** tab
|
||||
|
||||
### Configuring a Plugin
|
||||
|
||||
1. Open the plugin's tab in the second nav row (each installed plugin
|
||||
has its own tab)
|
||||
2. Edit the auto-generated form
|
||||
3. Click **Save**
|
||||
4. Restart the display service from **Overview**
|
||||
1. Navigate to the **Plugin Management** tab
|
||||
2. Find the plugin you want to configure
|
||||
3. Click the ⚙️ **Configure** button
|
||||
4. Edit the settings in the form
|
||||
5. Click **Save**
|
||||
6. Restart the display to apply changes
|
||||
|
||||
### Setting Favorite Sports Teams
|
||||
|
||||
Sports favorites live in the relevant plugin's tab — there is no
|
||||
separate "Sports Configuration" tab. For example:
|
||||
|
||||
1. Install **Hockey Scoreboard** from **Plugin Manager → Plugin Store**
|
||||
2. Open the **Hockey Scoreboard** tab in the second nav row
|
||||
3. Add your favorites under `favorite_teams.<league>` (e.g.
|
||||
`favorite_teams.nhl`)
|
||||
4. Click **Save** and restart the display service
|
||||
1. Navigate to the **Sports Configuration** tab
|
||||
2. Select the league (NHL, NBA, MLB, NFL)
|
||||
3. Choose your favorite teams from the dropdown
|
||||
4. Enable "Show favorite teams only" if desired
|
||||
5. Click **Save Configuration**
|
||||
6. Restart the display
|
||||
|
||||
### Troubleshooting Display Issues
|
||||
|
||||
@@ -260,10 +296,12 @@ The interface is fully responsive and works on mobile devices:
|
||||
- Touch-friendly interface
|
||||
- Responsive layout adapts to screen size
|
||||
- All features available on mobile
|
||||
- Swipe navigation between tabs
|
||||
|
||||
**Tips for Mobile:**
|
||||
- Use landscape mode for better visibility
|
||||
- Pinch to zoom on display preview
|
||||
- Long-press for context menus
|
||||
|
||||
---
|
||||
|
||||
@@ -284,21 +322,15 @@ The web interface is built on a REST API that you can access programmatically:
|
||||
|
||||
**API Base URL:**
|
||||
```
|
||||
http://your-pi-ip:5000/api/v3
|
||||
http://your-pi-ip:5050/api
|
||||
```
|
||||
|
||||
The API blueprint mounts at `/api/v3` (see
|
||||
`web_interface/app.py:144`). All endpoints below are relative to that
|
||||
base.
|
||||
|
||||
**Common Endpoints:**
|
||||
- `GET /api/v3/config/main` — Get main configuration
|
||||
- `POST /api/v3/config/main` — Update main configuration
|
||||
- `GET /api/v3/system/status` — Get system status
|
||||
- `POST /api/v3/system/action` — Control display (start/stop/restart, reboot, etc.)
|
||||
- `GET /api/v3/plugins/installed` — List installed plugins
|
||||
- `POST /api/v3/plugins/install` — Install a plugin from the store
|
||||
- `POST /api/v3/plugins/install-from-url` — Install a plugin from a GitHub URL
|
||||
- `GET /api/config/main` - Get configuration
|
||||
- `POST /api/config/main` - Update configuration
|
||||
- `GET /api/system/status` - Get system status
|
||||
- `POST /api/system/action` - Control display (start/stop/restart)
|
||||
- `GET /api/plugins/installed` - List installed plugins
|
||||
|
||||
**Note:** See [REST_API_REFERENCE.md](REST_API_REFERENCE.md) for complete API documentation.
|
||||
|
||||
@@ -321,7 +353,7 @@ base.
|
||||
sudo systemctl start ledmatrix-web
|
||||
```
|
||||
|
||||
3. Check that port 5000 is not blocked by firewall
|
||||
3. Check that port 5050 is not blocked by firewall
|
||||
4. Verify the Pi's IP address is correct
|
||||
|
||||
### Changes Not Applying
|
||||
@@ -397,12 +429,7 @@ The web interface uses modern web technologies:
|
||||
- Web service: `sudo journalctl -u ledmatrix-web -f`
|
||||
|
||||
**Plugins:**
|
||||
- Plugin directory: configurable via
|
||||
`plugin_system.plugins_directory` in `config.json` (default
|
||||
`plugin-repos/`). Main plugin discovery only scans this directory;
|
||||
the Plugin Store install flow and the schema loader additionally
|
||||
probe `plugins/` so dev symlinks created by
|
||||
`scripts/dev/dev_plugin_setup.sh` keep working.
|
||||
- Plugin directory: `/plugins/`
|
||||
- Plugin config: `/config/config.json` (per-plugin sections)
|
||||
|
||||
---
|
||||
|
||||
@@ -21,15 +21,13 @@ The LEDMatrix WiFi system provides automatic network configuration with intellig
|
||||
|
||||
**If not connected to WiFi:**
|
||||
1. Wait 90 seconds after boot (AP mode activation grace period)
|
||||
2. Connect to WiFi network **LEDMatrix-Setup** (default password
|
||||
`ledmatrix123` — change it in `config/wifi_config.json` if you want
|
||||
an open network or a different password)
|
||||
3. Open browser to: `http://192.168.4.1:5000`
|
||||
4. Open the **WiFi** tab
|
||||
2. Connect to WiFi network: **LEDMatrix-Setup** (open network)
|
||||
3. Open browser to: `http://192.168.4.1:5050`
|
||||
4. Navigate to the WiFi tab
|
||||
5. Scan, select your network, and connect
|
||||
|
||||
**If already connected:**
|
||||
1. Open browser to: `http://your-pi-ip:5000`
|
||||
1. Open browser to: `http://your-pi-ip:5050`
|
||||
2. Navigate to the WiFi tab
|
||||
3. Configure as needed
|
||||
|
||||
@@ -78,7 +76,7 @@ WiFi settings are stored in `config/wifi_config.json`:
|
||||
```json
|
||||
{
|
||||
"ap_ssid": "LEDMatrix-Setup",
|
||||
"ap_password": "ledmatrix123",
|
||||
"ap_password": "",
|
||||
"ap_channel": 7,
|
||||
"auto_enable_ap_mode": true,
|
||||
"saved_networks": [
|
||||
@@ -95,10 +93,10 @@ WiFi settings are stored in `config/wifi_config.json`:
|
||||
|
||||
| Setting | Default | Description |
|
||||
|---------|---------|-------------|
|
||||
| `ap_ssid` | `LEDMatrix-Setup` | Network name broadcast in AP mode |
|
||||
| `ap_password` | `ledmatrix123` | AP password. Set to `""` to make the network open (no password). |
|
||||
| `ap_channel` | `7` | WiFi channel (1, 6, or 11 are non-overlapping) |
|
||||
| `auto_enable_ap_mode` | `true` | Automatically enable AP mode when both WiFi and Ethernet are disconnected |
|
||||
| `ap_ssid` | `LEDMatrix-Setup` | Network name for AP mode |
|
||||
| `ap_password` | `` (empty) | AP password (empty = open network) |
|
||||
| `ap_channel` | `7` | WiFi channel (use 1, 6, or 11 for non-overlapping) |
|
||||
| `auto_enable_ap_mode` | `true` | Automatically enable AP mode when disconnected |
|
||||
| `saved_networks` | `[]` | Array of saved WiFi credentials |
|
||||
|
||||
### Auto-Enable AP Mode Behavior
|
||||
@@ -132,10 +130,10 @@ WiFi settings are stored in `config/wifi_config.json`:
|
||||
**Via API:**
|
||||
```bash
|
||||
# Scan for networks
|
||||
curl "http://your-pi-ip:5000/api/v3/wifi/scan"
|
||||
curl "http://your-pi-ip:5050/api/wifi/scan"
|
||||
|
||||
# Connect to network
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/wifi/connect \
|
||||
curl -X POST http://your-pi-ip:5050/api/wifi/connect \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"ssid": "YourNetwork", "password": "your-password"}'
|
||||
```
|
||||
@@ -149,10 +147,10 @@ curl -X POST http://your-pi-ip:5000/api/v3/wifi/connect \
|
||||
**Via API:**
|
||||
```bash
|
||||
# Enable AP mode
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/wifi/ap/enable
|
||||
curl -X POST http://your-pi-ip:5050/api/wifi/ap/enable
|
||||
|
||||
# Disable AP mode
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/wifi/ap/disable
|
||||
curl -X POST http://your-pi-ip:5050/api/wifi/ap/disable
|
||||
```
|
||||
|
||||
**Note:** Manual enable still requires both WiFi and Ethernet to be disconnected.
|
||||
@@ -213,17 +211,16 @@ The system checks connections in this order:
|
||||
|
||||
### AP Mode Settings
|
||||
|
||||
- **SSID**: `LEDMatrix-Setup` (configurable via `ap_ssid`)
|
||||
- **Network**: WPA2, default password `ledmatrix123` (configurable via
|
||||
`ap_password` — set to `""` for an open network)
|
||||
- **SSID**: LEDMatrix-Setup (configurable)
|
||||
- **Network**: Open (no password by default)
|
||||
- **IP Address**: 192.168.4.1
|
||||
- **DHCP Range**: 192.168.4.2 – 192.168.4.20
|
||||
- **Channel**: 7 (configurable via `ap_channel`)
|
||||
- **DHCP Range**: 192.168.4.2 - 192.168.4.20
|
||||
- **Channel**: 7 (configurable)
|
||||
|
||||
### Accessing Services in AP Mode
|
||||
|
||||
When AP mode is active:
|
||||
- Web Interface: `http://192.168.4.1:5000`
|
||||
- Web Interface: `http://192.168.4.1:5050`
|
||||
- SSH: `ssh ledpi@192.168.4.1`
|
||||
- Captive portal may automatically redirect browsers
|
||||
|
||||
@@ -240,9 +237,7 @@ When AP mode is active:
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** The default password is `ledmatrix123` for easy initial
|
||||
setup. Change it for any deployment in a public area, or set
|
||||
`ap_password` to `""` if you specifically want an open network.
|
||||
**Note:** The default is an open network for easy initial setup. For deployments in public areas, consider adding a password.
|
||||
|
||||
**2. Use Non-Overlapping WiFi Channels:**
|
||||
- Channels 1, 6, 11 are non-overlapping (2.4GHz)
|
||||
@@ -403,7 +398,7 @@ Interface should exist
|
||||
|
||||
**Check 4: Try Manual Enable**
|
||||
- Use web interface: WiFi tab → Enable AP Mode
|
||||
- Or via API: `curl -X POST http://localhost:5000/api/v3/wifi/ap/enable`
|
||||
- Or via API: `curl -X POST http://localhost:5050/api/wifi/ap/enable`
|
||||
|
||||
### Cannot Connect to WiFi Network
|
||||
|
||||
@@ -556,36 +551,36 @@ The WiFi setup feature exposes the following API endpoints:
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/v3/wifi/status` | Get current WiFi connection status |
|
||||
| GET | `/api/v3/wifi/scan` | Scan for available WiFi networks |
|
||||
| POST | `/api/v3/wifi/connect` | Connect to a WiFi network |
|
||||
| POST | `/api/v3/wifi/ap/enable` | Enable access point mode |
|
||||
| POST | `/api/v3/wifi/ap/disable` | Disable access point mode |
|
||||
| GET | `/api/v3/wifi/ap/auto-enable` | Get auto-enable setting |
|
||||
| POST | `/api/v3/wifi/ap/auto-enable` | Set auto-enable setting |
|
||||
| GET | `/api/wifi/status` | Get current WiFi connection status |
|
||||
| GET | `/api/wifi/scan` | Scan for available WiFi networks |
|
||||
| POST | `/api/wifi/connect` | Connect to a WiFi network |
|
||||
| POST | `/api/wifi/ap/enable` | Enable access point mode |
|
||||
| POST | `/api/wifi/ap/disable` | Disable access point mode |
|
||||
| GET | `/api/wifi/ap/auto-enable` | Get auto-enable setting |
|
||||
| POST | `/api/wifi/ap/auto-enable` | Set auto-enable setting |
|
||||
|
||||
### Example Usage
|
||||
|
||||
```bash
|
||||
# Get WiFi status
|
||||
curl "http://your-pi-ip:5000/api/v3/wifi/status"
|
||||
curl "http://your-pi-ip:5050/api/wifi/status"
|
||||
|
||||
# Scan for networks
|
||||
curl "http://your-pi-ip:5000/api/v3/wifi/scan"
|
||||
curl "http://your-pi-ip:5050/api/wifi/scan"
|
||||
|
||||
# Connect to network
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/wifi/connect \
|
||||
curl -X POST http://your-pi-ip:5050/api/wifi/connect \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"ssid": "MyNetwork", "password": "mypassword"}'
|
||||
|
||||
# Enable AP mode
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/wifi/ap/enable
|
||||
curl -X POST http://your-pi-ip:5050/api/wifi/ap/enable
|
||||
|
||||
# Check auto-enable setting
|
||||
curl "http://your-pi-ip:5000/api/v3/wifi/ap/auto-enable"
|
||||
curl "http://your-pi-ip:5050/api/wifi/ap/auto-enable"
|
||||
|
||||
# Set auto-enable
|
||||
curl -X POST http://your-pi-ip:5000/api/v3/wifi/ap/auto-enable \
|
||||
curl -X POST http://your-pi-ip:5050/api/wifi/ap/auto-enable \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"auto_enable_ap_mode": true}'
|
||||
```
|
||||
|
||||
@@ -47,55 +47,26 @@ class WebUIInfoPlugin(BasePlugin):
|
||||
|
||||
# IP refresh tracking
|
||||
self.last_ip_refresh = time.time()
|
||||
self.ip_refresh_interval = 300.0 # Refresh IP every 5 minutes
|
||||
|
||||
# AP mode cache
|
||||
self._ap_mode_cached = False
|
||||
self._ap_mode_cache_time = 0.0
|
||||
self._ap_mode_cache_ttl = 60.0 # Cache AP mode check for 60 seconds
|
||||
|
||||
self.ip_refresh_interval = 30.0 # Refresh IP every 30 seconds
|
||||
|
||||
# Rotation state
|
||||
self.current_display_mode = "hostname" # "hostname" or "ip"
|
||||
self.last_rotation_time = time.time()
|
||||
self.rotation_interval = 10.0 # Rotate every 10 seconds
|
||||
|
||||
|
||||
self.web_ui_url = f"http://{self.device_id}:5000"
|
||||
|
||||
# Display cache - avoid re-rendering when nothing changed
|
||||
self._cached_display_image = None
|
||||
self._display_dirty = True
|
||||
self._font_small = self._load_font()
|
||||
|
||||
|
||||
self.logger.info(f"Web UI Info plugin initialized - Hostname: {self.device_id}, IP: {self.device_ip}")
|
||||
|
||||
def _load_font(self):
|
||||
"""Load and cache the display font."""
|
||||
try:
|
||||
current_dir = Path(__file__).resolve().parent
|
||||
project_root = current_dir.parent.parent
|
||||
font_path = project_root / "assets" / "fonts" / "4x6-font.ttf"
|
||||
if font_path.exists():
|
||||
return ImageFont.truetype(str(font_path), 6)
|
||||
font_path = "assets/fonts/4x6-font.ttf"
|
||||
if os.path.exists(font_path):
|
||||
return ImageFont.truetype(font_path, 6)
|
||||
return ImageFont.load_default()
|
||||
except (FileNotFoundError, OSError) as e:
|
||||
self.logger.debug(f"Could not load custom font: {e}, using default")
|
||||
return ImageFont.load_default()
|
||||
|
||||
def _is_ap_mode_active(self) -> bool:
|
||||
"""
|
||||
Check if AP mode is currently active (cached with TTL).
|
||||
|
||||
Check if AP mode is currently active.
|
||||
|
||||
Returns:
|
||||
bool: True if AP mode is active, False otherwise
|
||||
"""
|
||||
current_time = time.time()
|
||||
if current_time - self._ap_mode_cache_time < self._ap_mode_cache_ttl:
|
||||
return self._ap_mode_cached
|
||||
|
||||
try:
|
||||
# Check if hostapd service is running
|
||||
result = subprocess.run(
|
||||
["systemctl", "is-active", "hostapd"],
|
||||
capture_output=True,
|
||||
@@ -103,10 +74,9 @@ class WebUIInfoPlugin(BasePlugin):
|
||||
timeout=2
|
||||
)
|
||||
if result.returncode == 0 and result.stdout.strip() == "active":
|
||||
self._ap_mode_cached = True
|
||||
self._ap_mode_cache_time = current_time
|
||||
return True
|
||||
|
||||
|
||||
# Check if wlan0 has AP mode IP (192.168.4.1)
|
||||
result = subprocess.run(
|
||||
["ip", "addr", "show", "wlan0"],
|
||||
capture_output=True,
|
||||
@@ -114,24 +84,18 @@ class WebUIInfoPlugin(BasePlugin):
|
||||
timeout=2
|
||||
)
|
||||
if result.returncode == 0 and "192.168.4.1" in result.stdout:
|
||||
self._ap_mode_cached = True
|
||||
self._ap_mode_cache_time = current_time
|
||||
return True
|
||||
|
||||
self._ap_mode_cached = False
|
||||
self._ap_mode_cache_time = current_time
|
||||
|
||||
return False
|
||||
except Exception as e:
|
||||
self.logger.debug(f"Error checking AP mode status: {e}")
|
||||
self._ap_mode_cached = False
|
||||
self._ap_mode_cache_time = current_time
|
||||
return False
|
||||
|
||||
def _get_local_ip(self) -> str:
|
||||
"""
|
||||
Get the local IP address of the device using network interfaces.
|
||||
Handles AP mode, no internet connectivity, and network state changes.
|
||||
|
||||
|
||||
Returns:
|
||||
str: Local IP address, or "localhost" if unable to determine
|
||||
"""
|
||||
@@ -139,23 +103,9 @@ class WebUIInfoPlugin(BasePlugin):
|
||||
if self._is_ap_mode_active():
|
||||
self.logger.debug("AP mode detected, returning AP IP: 192.168.4.1")
|
||||
return "192.168.4.1"
|
||||
|
||||
|
||||
try:
|
||||
# Try socket method first (zero subprocess overhead, fastest)
|
||||
try:
|
||||
s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
|
||||
try:
|
||||
s.connect(('8.8.8.8', 80))
|
||||
ip = s.getsockname()[0]
|
||||
if ip and not ip.startswith("127.") and ip != "192.168.4.1":
|
||||
self.logger.debug(f"Found IP via socket method: {ip}")
|
||||
return ip
|
||||
finally:
|
||||
s.close()
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
# Fallback: Try using 'hostname -I'
|
||||
# Try using 'hostname -I' first (fastest, gets all IPs)
|
||||
result = subprocess.run(
|
||||
["hostname", "-I"],
|
||||
capture_output=True,
|
||||
@@ -164,12 +114,13 @@ class WebUIInfoPlugin(BasePlugin):
|
||||
)
|
||||
if result.returncode == 0:
|
||||
ips = result.stdout.strip().split()
|
||||
# Filter out loopback and AP mode IPs
|
||||
for ip in ips:
|
||||
ip = ip.strip()
|
||||
if ip and not ip.startswith("127.") and ip != "192.168.4.1":
|
||||
self.logger.debug(f"Found IP via hostname -I: {ip}")
|
||||
return ip
|
||||
|
||||
|
||||
# Fallback: Use 'ip addr show' to get interface IPs
|
||||
result = subprocess.run(
|
||||
["ip", "-4", "addr", "show"],
|
||||
@@ -181,18 +132,22 @@ class WebUIInfoPlugin(BasePlugin):
|
||||
current_interface = None
|
||||
for line in result.stdout.split('\n'):
|
||||
line = line.strip()
|
||||
# Check for interface name
|
||||
if ':' in line and not line.startswith('inet'):
|
||||
parts = line.split(':')
|
||||
if len(parts) >= 2:
|
||||
current_interface = parts[1].strip().split('@')[0]
|
||||
# Check for inet address
|
||||
elif line.startswith('inet '):
|
||||
parts = line.split()
|
||||
if len(parts) >= 2:
|
||||
ip_with_cidr = parts[1]
|
||||
ip = ip_with_cidr.split('/')[0]
|
||||
# Skip loopback and AP mode IPs
|
||||
if not ip.startswith("127.") and ip != "192.168.4.1":
|
||||
# Prefer eth0/ethernet interfaces, then wlan0, then others
|
||||
if current_interface and (
|
||||
current_interface.startswith("eth") or
|
||||
current_interface.startswith("eth") or
|
||||
current_interface.startswith("enp")
|
||||
):
|
||||
self.logger.debug(f"Found Ethernet IP: {ip} on {current_interface}")
|
||||
@@ -200,6 +155,19 @@ class WebUIInfoPlugin(BasePlugin):
|
||||
elif current_interface == "wlan0":
|
||||
self.logger.debug(f"Found WiFi IP: {ip} on {current_interface}")
|
||||
return ip
|
||||
|
||||
# Fallback: Try socket method (requires internet connectivity)
|
||||
try:
|
||||
s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
|
||||
try:
|
||||
# Connect to a public DNS server (doesn't actually connect)
|
||||
s.connect(('8.8.8.8', 80))
|
||||
ip = s.getsockname()[0]
|
||||
if ip and not ip.startswith("127.") and ip != "192.168.4.1":
|
||||
self.logger.debug(f"Found IP via socket method: {ip}")
|
||||
return ip
|
||||
finally:
|
||||
s.close()
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
@@ -222,24 +190,24 @@ class WebUIInfoPlugin(BasePlugin):
|
||||
def update(self) -> None:
|
||||
"""
|
||||
Update method - refreshes IP address periodically to handle network state changes.
|
||||
|
||||
|
||||
The hostname is determined at initialization and doesn't change,
|
||||
but IP address can change when network state changes (WiFi connect/disconnect, AP mode, etc.)
|
||||
"""
|
||||
current_time = time.time()
|
||||
if current_time - self.last_ip_refresh >= self.ip_refresh_interval:
|
||||
# Refresh IP address to handle network state changes
|
||||
new_ip = self._get_local_ip()
|
||||
if new_ip != self.device_ip:
|
||||
self.logger.info(f"IP address changed from {self.device_ip} to {new_ip}")
|
||||
self.device_ip = new_ip
|
||||
self._display_dirty = True
|
||||
self.last_ip_refresh = current_time
|
||||
|
||||
def display(self, force_clear: bool = False) -> None:
|
||||
"""
|
||||
Display the web UI URL message.
|
||||
Rotates between hostname and IP address every 10 seconds.
|
||||
|
||||
|
||||
Args:
|
||||
force_clear: If True, clear display before rendering
|
||||
"""
|
||||
@@ -247,66 +215,93 @@ class WebUIInfoPlugin(BasePlugin):
|
||||
# Check if we need to rotate between hostname and IP
|
||||
current_time = time.time()
|
||||
if current_time - self.last_rotation_time >= self.rotation_interval:
|
||||
# Switch display mode
|
||||
if self.current_display_mode == "hostname":
|
||||
self.current_display_mode = "ip"
|
||||
else:
|
||||
self.current_display_mode = "hostname"
|
||||
self.last_rotation_time = current_time
|
||||
self._display_dirty = True
|
||||
self.logger.debug(f"Rotated to display mode: {self.current_display_mode}")
|
||||
|
||||
|
||||
if force_clear:
|
||||
self.display_manager.clear()
|
||||
self._display_dirty = True
|
||||
|
||||
# Use cached image if nothing changed
|
||||
if not self._display_dirty and self._cached_display_image is not None:
|
||||
self.display_manager.image = self._cached_display_image
|
||||
self.display_manager.update_display()
|
||||
return
|
||||
|
||||
|
||||
# Get display dimensions
|
||||
width = self.display_manager.matrix.width
|
||||
height = self.display_manager.matrix.height
|
||||
|
||||
|
||||
# Create a new image for the display
|
||||
img = Image.new('RGB', (width, height), (0, 0, 0))
|
||||
draw = ImageDraw.Draw(img)
|
||||
|
||||
|
||||
# Try to load a small font
|
||||
# Try to find project root and use assets/fonts
|
||||
font_small = None
|
||||
try:
|
||||
# Try to find project root (parent of plugins directory)
|
||||
current_dir = Path(__file__).resolve().parent
|
||||
project_root = current_dir.parent.parent
|
||||
font_path = project_root / "assets" / "fonts" / "4x6-font.ttf"
|
||||
|
||||
if font_path.exists():
|
||||
font_small = ImageFont.truetype(str(font_path), 6)
|
||||
else:
|
||||
# Try relative path from current working directory
|
||||
font_path = "assets/fonts/4x6-font.ttf"
|
||||
if os.path.exists(font_path):
|
||||
font_small = ImageFont.truetype(font_path, 6)
|
||||
else:
|
||||
font_small = ImageFont.load_default()
|
||||
except Exception as e:
|
||||
self.logger.debug(f"Could not load custom font: {e}, using default")
|
||||
font_small = ImageFont.load_default()
|
||||
|
||||
# Determine which address to display
|
||||
if self.current_display_mode == "ip":
|
||||
address = self.device_ip
|
||||
else:
|
||||
address = self.device_id
|
||||
|
||||
|
||||
# Prepare text to display
|
||||
lines = [
|
||||
"visit web ui",
|
||||
f"at {address}:5000"
|
||||
]
|
||||
|
||||
|
||||
# Calculate text positions (centered)
|
||||
y_start = 5
|
||||
line_height = 8
|
||||
|
||||
total_height = len(lines) * line_height
|
||||
|
||||
# Draw each line
|
||||
for i, line in enumerate(lines):
|
||||
bbox = draw.textbbox((0, 0), line, font=self._font_small)
|
||||
# Get text size for centering
|
||||
bbox = draw.textbbox((0, 0), line, font=font_small)
|
||||
text_width = bbox[2] - bbox[0]
|
||||
text_height = bbox[3] - bbox[1]
|
||||
|
||||
# Center horizontally
|
||||
x = (width - text_width) // 2
|
||||
y = y_start + (i * line_height)
|
||||
draw.text((x, y), line, font=self._font_small, fill=(255, 255, 255))
|
||||
|
||||
self._cached_display_image = img
|
||||
self._display_dirty = False
|
||||
|
||||
# Draw text in white
|
||||
draw.text((x, y), line, font=font_small, fill=(255, 255, 255))
|
||||
|
||||
# Set the image on the display manager
|
||||
self.display_manager.image = img
|
||||
|
||||
# Update the display
|
||||
self.display_manager.update_display()
|
||||
|
||||
|
||||
self.logger.debug(f"Displayed web UI info: {address}:5000 (mode: {self.current_display_mode})")
|
||||
|
||||
|
||||
except Exception as e:
|
||||
self.logger.error(f"Error displaying web UI info: {e}")
|
||||
# Fallback: just clear the display
|
||||
try:
|
||||
self.display_manager.clear()
|
||||
self.display_manager.update_display()
|
||||
except Exception:
|
||||
except:
|
||||
pass
|
||||
|
||||
def get_display_duration(self) -> float:
|
||||
|
||||
@@ -48,25 +48,3 @@ pytest>=7.4.0,<8.0.0
|
||||
pytest-cov>=4.1.0,<5.0.0
|
||||
pytest-mock>=3.11.0,<4.0.0
|
||||
mypy>=1.5.0,<2.0.0
|
||||
|
||||
# ───────────────────────────────────────────────────────────────────────
|
||||
# Optional dependencies — the code imports these inside try/except
|
||||
# blocks and gracefully degrades when missing. Install them for the
|
||||
# full feature set, or skip them for a minimal install.
|
||||
# ───────────────────────────────────────────────────────────────────────
|
||||
#
|
||||
# scipy — sub-pixel interpolation in
|
||||
# src/common/scroll_helper.py for smoother
|
||||
# scrolling. Falls back to a simpler shift algorithm.
|
||||
# pip install 'scipy>=1.10.0,<2.0.0'
|
||||
#
|
||||
# psutil — per-plugin resource monitoring in
|
||||
# src/plugin_system/resource_monitor.py. The monitor
|
||||
# silently no-ops when missing (PSUTIL_AVAILABLE = False).
|
||||
# pip install 'psutil>=5.9.0,<6.0.0'
|
||||
#
|
||||
# Flask-Limiter — request rate limiting in web_interface/app.py
|
||||
# (accidental-abuse protection, not security). The
|
||||
# web interface starts without rate limiting when
|
||||
# this is missing.
|
||||
# pip install 'Flask-Limiter>=3.5.0,<4.0.0'
|
||||
|
||||
@@ -1,40 +1,29 @@
|
||||
# NBA Logo Downloader
|
||||
|
||||
This script downloads all NBA team logos from the ESPN API and saves
|
||||
them in the `assets/sports/nba_logos/` directory.
|
||||
|
||||
> **Heads up:** the NBA leaderboard and basketball scoreboards now
|
||||
> live as plugins in the
|
||||
> [`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins)
|
||||
> repo (`basketball-scoreboard`, `ledmatrix-leaderboard`). Those
|
||||
> plugins download the logos they need automatically on first display.
|
||||
> This standalone script is mainly useful when you want to pre-populate
|
||||
> the assets directory ahead of time, or for development/debugging.
|
||||
|
||||
All commands below should be run from the LEDMatrix project root.
|
||||
This script downloads all NBA team logos from the ESPN API and saves them in the `assets/sports/nba_logos/` directory for use with the NBA leaderboard.
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Usage
|
||||
```bash
|
||||
python3 scripts/download_nba_logos.py
|
||||
python download_nba_logos.py
|
||||
```
|
||||
|
||||
### Force Re-download
|
||||
If you want to re-download all logos (even if they already exist):
|
||||
```bash
|
||||
python3 scripts/download_nba_logos.py --force
|
||||
python download_nba_logos.py --force
|
||||
```
|
||||
|
||||
### Quiet Mode
|
||||
Reduce logging output:
|
||||
```bash
|
||||
python3 scripts/download_nba_logos.py --quiet
|
||||
python download_nba_logos.py --quiet
|
||||
```
|
||||
|
||||
### Combined Options
|
||||
```bash
|
||||
python3 scripts/download_nba_logos.py --force --quiet
|
||||
python download_nba_logos.py --force --quiet
|
||||
```
|
||||
|
||||
## What It Does
|
||||
@@ -93,14 +82,12 @@ assets/sports/nba_logos/
|
||||
└── WAS.png # Washington Wizards
|
||||
```
|
||||
|
||||
## Integration with NBA plugins
|
||||
## Integration with NBA Leaderboard
|
||||
|
||||
Once the logos are in `assets/sports/nba_logos/`, both the
|
||||
`basketball-scoreboard` and `ledmatrix-leaderboard` plugins will pick
|
||||
them up automatically and skip their own first-run download. This is
|
||||
useful if you want to deploy a Pi without internet access to ESPN, or
|
||||
if you want to preview the display on your dev machine without
|
||||
waiting for downloads.
|
||||
Once the logos are downloaded, the NBA leaderboard will:
|
||||
- ✅ Use local logos instantly (no download delays)
|
||||
- ✅ Display team logos in the scrolling leaderboard
|
||||
- ✅ Show proper team branding for all 30 NBA teams
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
@@ -115,6 +102,6 @@ This is normal - some teams might have temporary API issues or the ESPN API migh
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.9+ (matches the project's overall minimum)
|
||||
- `requests` library (already in `requirements.txt`)
|
||||
- Python 3.7+
|
||||
- `requests` library (should be installed with the project)
|
||||
- Write access to `assets/sports/nba_logos/` directory
|
||||
|
||||
@@ -1,70 +0,0 @@
|
||||
# Permission Fix Scripts
|
||||
|
||||
This directory contains shell scripts for repairing file/directory
|
||||
permissions on a LEDMatrix installation. They're typically only needed
|
||||
when something has gone wrong — for example, after running parts of the
|
||||
install as the wrong user, after a manual file copy that didn't preserve
|
||||
ownership, or after a permissions-related error from the display or
|
||||
web service.
|
||||
|
||||
Most of these scripts require `sudo` since they touch directories
|
||||
owned by the `ledmatrix` service user or by `root`.
|
||||
|
||||
## Scripts
|
||||
|
||||
- **`fix_assets_permissions.sh`** — Fixes ownership and write
|
||||
permissions on the `assets/` tree so plugins can download and cache
|
||||
team logos, fonts, and other static content.
|
||||
|
||||
- **`fix_cache_permissions.sh`** — Fixes permissions on every cache
|
||||
directory the project may use (`/var/cache/ledmatrix/`,
|
||||
`~/.cache/ledmatrix/`, `/opt/ledmatrix/cache/`, project-local
|
||||
`cache/`). Also creates placeholder logo subdirectories used by the
|
||||
sports plugins.
|
||||
|
||||
- **`fix_plugin_permissions.sh`** — Fixes ownership on the plugins
|
||||
directory so both the root display service and the web service user
|
||||
can read and write plugin files (manifests, configs, requirements
|
||||
installs).
|
||||
|
||||
- **`fix_web_permissions.sh`** — Fixes permissions on log files,
|
||||
systemd journal access, and the sudoers entries the web interface
|
||||
needs to control the display service.
|
||||
|
||||
- **`fix_nhl_cache.sh`** — Targeted fix for NHL plugin cache issues
|
||||
(clears the NHL cache and restarts the display service).
|
||||
|
||||
- **`safe_plugin_rm.sh`** — Validates that a plugin removal path is
|
||||
inside an allowed base directory before deleting it. Used by the web
|
||||
interface (via sudo) when a user clicks **Uninstall** on a plugin —
|
||||
prevents path-traversal abuse from the web UI.
|
||||
|
||||
## When to use these
|
||||
|
||||
Most users never need to run these directly. The first-time installer
|
||||
(`first_time_install.sh`) sets up permissions correctly, and the web
|
||||
interface manages plugin install/uninstall through the sudoers entries
|
||||
the installer creates.
|
||||
|
||||
Run these scripts only when:
|
||||
|
||||
- You see "Permission denied" errors in `journalctl -u ledmatrix` or
|
||||
the web UI Logs tab.
|
||||
- You manually copied files into the project directory as the wrong
|
||||
user.
|
||||
- You restored from a backup that didn't preserve ownership.
|
||||
- You moved the LEDMatrix directory and need to re-anchor permissions.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Run from the project root
|
||||
sudo ./scripts/fix_perms/fix_cache_permissions.sh
|
||||
sudo ./scripts/fix_perms/fix_assets_permissions.sh
|
||||
sudo ./scripts/fix_perms/fix_plugin_permissions.sh
|
||||
sudo ./scripts/fix_perms/fix_web_permissions.sh
|
||||
```
|
||||
|
||||
If you're not sure which one you need, run `fix_cache_permissions.sh`
|
||||
first — it's the most commonly needed and creates several directories
|
||||
the other scripts assume exist.
|
||||
@@ -4,26 +4,16 @@ This directory contains scripts for installing and configuring the LEDMatrix sys
|
||||
|
||||
## Scripts
|
||||
|
||||
- **`one-shot-install.sh`** - Single-command installer; clones the
|
||||
repo, checks prerequisites, then runs `first_time_install.sh`.
|
||||
Invoked via `curl ... | bash` from the project root README.
|
||||
- **`install_service.sh`** - Installs the main LED Matrix display service (systemd)
|
||||
- **`install_web_service.sh`** - Installs the web interface service (systemd)
|
||||
- **`install_wifi_monitor.sh`** - Installs the WiFi monitor daemon service
|
||||
- **`setup_cache.sh`** - Sets up persistent cache directory with proper permissions
|
||||
- **`configure_web_sudo.sh`** - Configures passwordless sudo access for web interface actions
|
||||
- **`configure_wifi_permissions.sh`** - Grants the `ledmatrix` user
|
||||
the WiFi management permissions needed by the web interface and
|
||||
the WiFi monitor service
|
||||
- **`migrate_config.sh`** - Migrates configuration files to new formats (if needed)
|
||||
- **`debug_install.sh`** - Diagnostic helper used when an install
|
||||
fails; collects environment info and recent logs
|
||||
|
||||
## Usage
|
||||
|
||||
These scripts are typically called by `first_time_install.sh` in the
|
||||
project root (which itself is invoked by `one-shot-install.sh`), but
|
||||
can also be run individually if needed.
|
||||
These scripts are typically called by `first_time_install.sh` in the project root, but can also be run individually if needed.
|
||||
|
||||
**Note:** Most installation scripts require `sudo` privileges to install systemd services and configure system settings.
|
||||
|
||||
|
||||
@@ -62,11 +62,6 @@ $WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH start dnsmasq
|
||||
$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH stop dnsmasq
|
||||
$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH restart dnsmasq
|
||||
$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH restart NetworkManager
|
||||
|
||||
# Allow copying hostapd and dnsmasq config files into place
|
||||
$WEB_USER ALL=(ALL) NOPASSWD: /usr/bin/cp /tmp/hostapd.conf /etc/hostapd/hostapd.conf
|
||||
$WEB_USER ALL=(ALL) NOPASSWD: /usr/bin/cp /tmp/dnsmasq.conf /etc/dnsmasq.d/ledmatrix-captive.conf
|
||||
$WEB_USER ALL=(ALL) NOPASSWD: /usr/bin/rm -f /etc/dnsmasq.d/ledmatrix-captive.conf
|
||||
EOF
|
||||
|
||||
echo "Generated sudoers configuration:"
|
||||
|
||||
@@ -71,17 +71,6 @@ General-purpose utility functions:
|
||||
- Boolean parsing
|
||||
- Logger creation (deprecated - use `src.logging_config.get_logger()`)
|
||||
|
||||
## Permission Utilities (`permission_utils.py`)
|
||||
|
||||
Helpers for ensuring directory permissions and ownership are correct
|
||||
when running as a service (used by `CacheManager` to set up its
|
||||
persistent cache directory).
|
||||
|
||||
## CLI Helpers (`cli.py`)
|
||||
|
||||
Shared CLI argument parsing helpers used by `scripts/dev/*` and other
|
||||
command-line entry points.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use centralized logging**: Import from `src.logging_config` instead of creating loggers directly
|
||||
|
||||
@@ -32,10 +32,7 @@ class DisplayController:
|
||||
def __init__(self):
|
||||
start_time = time.time()
|
||||
logger.info("Starting DisplayController initialization")
|
||||
|
||||
# Throttle tracking for _tick_plugin_updates in high-FPS loops
|
||||
self._last_plugin_tick_time = 0.0
|
||||
|
||||
|
||||
# Initialize ConfigManager and wrap with ConfigService for hot-reload
|
||||
config_manager = ConfigManager()
|
||||
enable_hot_reload = os.environ.get('LEDMATRIX_HOT_RELOAD', 'true').lower() == 'true'
|
||||
@@ -82,8 +79,7 @@ class DisplayController:
|
||||
logger.info("Display modes initialized in %.3f seconds", time.time() - init_time)
|
||||
|
||||
self.force_change = False
|
||||
self._next_live_priority_check = 0.0 # monotonic timestamp for throttled live priority checks
|
||||
|
||||
|
||||
# All sports and content managers now handled via plugins
|
||||
logger.info("All sports and content managers now handled via plugin system")
|
||||
|
||||
@@ -722,22 +718,6 @@ class DisplayController:
|
||||
except Exception: # pylint: disable=broad-except
|
||||
logger.exception("Error running scheduled plugin updates")
|
||||
|
||||
def _tick_plugin_updates_throttled(self, min_interval: float = 0.0):
|
||||
"""Throttled version of _tick_plugin_updates for high-FPS loops.
|
||||
|
||||
Args:
|
||||
min_interval: Minimum seconds between calls. When <= 0 the
|
||||
call passes straight through to _tick_plugin_updates so
|
||||
plugin-configured update_interval values are never capped.
|
||||
"""
|
||||
if min_interval <= 0:
|
||||
self._tick_plugin_updates()
|
||||
return
|
||||
now = time.time()
|
||||
if now - self._last_plugin_tick_time >= min_interval:
|
||||
self._last_plugin_tick_time = now
|
||||
self._tick_plugin_updates()
|
||||
|
||||
def _sleep_with_plugin_updates(self, duration: float, tick_interval: float = 1.0):
|
||||
"""Sleep while continuing to service plugin update schedules."""
|
||||
if duration <= 0:
|
||||
@@ -1746,7 +1726,7 @@ class DisplayController:
|
||||
)
|
||||
|
||||
target_duration = max_duration
|
||||
start_time = time.monotonic()
|
||||
start_time = time.time()
|
||||
|
||||
def _should_exit_dynamic(elapsed_time: float) -> bool:
|
||||
if not dynamic_enabled:
|
||||
@@ -1806,33 +1786,15 @@ class DisplayController:
|
||||
logger.exception("Error during display update")
|
||||
|
||||
time.sleep(display_interval)
|
||||
self._tick_plugin_updates_throttled(min_interval=1.0)
|
||||
self._tick_plugin_updates()
|
||||
self._poll_on_demand_requests()
|
||||
self._check_on_demand_expiration()
|
||||
|
||||
# Check for live priority every ~30s so live
|
||||
# games can interrupt long display durations
|
||||
elapsed = time.monotonic() - start_time
|
||||
now = time.monotonic()
|
||||
if not self.on_demand_active and now >= self._next_live_priority_check:
|
||||
self._next_live_priority_check = now + 30.0
|
||||
live_mode = self._check_live_priority()
|
||||
if live_mode and live_mode != active_mode:
|
||||
logger.info("Live priority detected during high-FPS loop: %s", live_mode)
|
||||
self.current_display_mode = live_mode
|
||||
self.force_change = True
|
||||
try:
|
||||
self.current_mode_index = self.available_modes.index(live_mode)
|
||||
except ValueError:
|
||||
pass
|
||||
# continue the main while loop to skip
|
||||
# post-loop rotation/sleep logic
|
||||
break
|
||||
|
||||
if self.current_display_mode != active_mode:
|
||||
logger.debug("Mode changed during high-FPS loop, breaking early")
|
||||
break
|
||||
|
||||
elapsed = time.time() - start_time
|
||||
if elapsed >= target_duration:
|
||||
logger.debug(
|
||||
"Reached high-FPS target duration %.2fs for mode %s",
|
||||
@@ -1862,7 +1824,7 @@ class DisplayController:
|
||||
time.sleep(display_interval)
|
||||
self._tick_plugin_updates()
|
||||
|
||||
elapsed = time.monotonic() - start_time
|
||||
elapsed = time.time() - start_time
|
||||
if elapsed >= target_duration:
|
||||
logger.debug(
|
||||
"Reached standard target duration %.2fs for mode %s",
|
||||
@@ -1891,23 +1853,6 @@ class DisplayController:
|
||||
|
||||
self._poll_on_demand_requests()
|
||||
self._check_on_demand_expiration()
|
||||
|
||||
# Check for live priority every ~30s so live
|
||||
# games can interrupt long display durations
|
||||
now = time.monotonic()
|
||||
if not self.on_demand_active and now >= self._next_live_priority_check:
|
||||
self._next_live_priority_check = now + 30.0
|
||||
live_mode = self._check_live_priority()
|
||||
if live_mode and live_mode != active_mode:
|
||||
logger.info("Live priority detected during display loop: %s", live_mode)
|
||||
self.current_display_mode = live_mode
|
||||
self.force_change = True
|
||||
try:
|
||||
self.current_mode_index = self.available_modes.index(live_mode)
|
||||
except ValueError:
|
||||
pass
|
||||
break
|
||||
|
||||
if self.current_display_mode != active_mode:
|
||||
logger.info("Mode changed during display loop from %s to %s, breaking early", active_mode, self.current_display_mode)
|
||||
break
|
||||
@@ -1921,26 +1866,19 @@ class DisplayController:
|
||||
loop_completed = True
|
||||
break
|
||||
|
||||
# If live priority preempted the display loop, skip
|
||||
# all post-loop logic (remaining sleep, rotation) and
|
||||
# restart the main loop so the live mode displays
|
||||
# immediately.
|
||||
if self.current_display_mode != active_mode:
|
||||
continue
|
||||
|
||||
# Ensure we honour minimum duration when not dynamic and loop ended early
|
||||
if (
|
||||
not dynamic_enabled
|
||||
and not loop_completed
|
||||
and not needs_high_fps
|
||||
):
|
||||
elapsed = time.monotonic() - start_time
|
||||
elapsed = time.time() - start_time
|
||||
remaining_sleep = max(0.0, max_duration - elapsed)
|
||||
if remaining_sleep > 0:
|
||||
self._sleep_with_plugin_updates(remaining_sleep)
|
||||
|
||||
if dynamic_enabled:
|
||||
elapsed_total = time.monotonic() - start_time
|
||||
elapsed_total = time.time() - start_time
|
||||
cycle_done = self._plugin_cycle_complete(manager_to_display)
|
||||
|
||||
# Log cycle completion status and metrics
|
||||
|
||||
@@ -43,9 +43,6 @@ class LogoDownloader:
|
||||
'ncaaw': 'https://site.api.espn.com/apis/site/v2/sports/basketball/womens-college-basketball/teams', # Alias for basketball plugin
|
||||
'ncaa_baseball': 'https://site.api.espn.com/apis/site/v2/sports/baseball/college-baseball/teams',
|
||||
'ncaam_hockey': 'https://site.api.espn.com/apis/site/v2/sports/hockey/mens-college-hockey/teams',
|
||||
'ncaaw_hockey': 'https://site.api.espn.com/apis/site/v2/sports/hockey/womens-college-hockey/teams',
|
||||
'ncaam_lacrosse': 'https://site.api.espn.com/apis/site/v2/sports/lacrosse/mens-college-lacrosse/teams',
|
||||
'ncaaw_lacrosse': 'https://site.api.espn.com/apis/site/v2/sports/lacrosse/womens-college-lacrosse/teams',
|
||||
# Soccer leagues
|
||||
'soccer_eng.1': 'https://site.api.espn.com/apis/site/v2/sports/soccer/eng.1/teams',
|
||||
'soccer_esp.1': 'https://site.api.espn.com/apis/site/v2/sports/soccer/esp.1/teams',
|
||||
@@ -76,8 +73,6 @@ class LogoDownloader:
|
||||
'ncaa_baseball': 'assets/sports/ncaa_logos',
|
||||
'ncaam_hockey': 'assets/sports/ncaa_logos',
|
||||
'ncaaw_hockey': 'assets/sports/ncaa_logos',
|
||||
'ncaam_lacrosse': 'assets/sports/ncaa_logos',
|
||||
'ncaaw_lacrosse': 'assets/sports/ncaa_logos',
|
||||
# Soccer leagues - all use the same soccer_logos directory
|
||||
'soccer_eng.1': 'assets/sports/soccer_logos',
|
||||
'soccer_esp.1': 'assets/sports/soccer_logos',
|
||||
|
||||
@@ -265,29 +265,19 @@ class RenderPipeline:
|
||||
if buffer_status['staging_count'] > 0:
|
||||
return True
|
||||
|
||||
# Trigger recompose when pending updates affect visible segments
|
||||
if self.stream_manager.has_pending_updates_for_visible_segments():
|
||||
return True
|
||||
|
||||
return False
|
||||
|
||||
def hot_swap_content(self) -> bool:
|
||||
"""
|
||||
Hot-swap to new composed content.
|
||||
|
||||
Called when staging buffer has updated content or pending updates exist.
|
||||
Preserves scroll position for mid-cycle updates to prevent visual jumps.
|
||||
Called when staging buffer has updated content.
|
||||
Swaps atomically to prevent visual glitches.
|
||||
|
||||
Returns:
|
||||
True if swap occurred
|
||||
"""
|
||||
try:
|
||||
# Save scroll position for mid-cycle updates
|
||||
saved_position = self.scroll_helper.scroll_position
|
||||
saved_total_distance = self.scroll_helper.total_distance_scrolled
|
||||
saved_total_width = max(1, self.scroll_helper.total_scroll_width)
|
||||
was_mid_cycle = not self._cycle_complete
|
||||
|
||||
# Process any pending updates
|
||||
self.stream_manager.process_updates()
|
||||
self.stream_manager.swap_buffers()
|
||||
@@ -295,19 +285,7 @@ class RenderPipeline:
|
||||
# Recompose with updated content
|
||||
if self.compose_scroll_content():
|
||||
self.stats['hot_swaps'] += 1
|
||||
# Restore scroll position for mid-cycle updates so the
|
||||
# scroll continues from where it was instead of jumping to 0
|
||||
if was_mid_cycle:
|
||||
new_total_width = max(1, self.scroll_helper.total_scroll_width)
|
||||
progress_ratio = min(saved_total_distance / saved_total_width, 0.999)
|
||||
self.scroll_helper.total_distance_scrolled = progress_ratio * new_total_width
|
||||
self.scroll_helper.scroll_position = min(
|
||||
saved_position,
|
||||
float(new_total_width - 1)
|
||||
)
|
||||
self.scroll_helper.scroll_complete = False
|
||||
self._cycle_complete = False
|
||||
logger.debug("Hot-swap completed (mid_cycle_restore=%s)", was_mid_cycle)
|
||||
logger.debug("Hot-swap completed")
|
||||
return True
|
||||
|
||||
return False
|
||||
|
||||
@@ -199,21 +199,6 @@ class StreamManager:
|
||||
|
||||
logger.debug("Plugin %s marked for update", plugin_id)
|
||||
|
||||
def has_pending_updates(self) -> bool:
|
||||
"""Check if any plugins have pending updates awaiting processing."""
|
||||
with self._buffer_lock:
|
||||
return len(self._pending_updates) > 0
|
||||
|
||||
def has_pending_updates_for_visible_segments(self) -> bool:
|
||||
"""Check if pending updates affect plugins currently in the active buffer."""
|
||||
with self._buffer_lock:
|
||||
if not self._pending_updates:
|
||||
return False
|
||||
active_ids = {
|
||||
seg.plugin_id for seg in self._active_buffer if seg.images
|
||||
}
|
||||
return bool(active_ids & self._pending_updates.keys())
|
||||
|
||||
def process_updates(self) -> None:
|
||||
"""
|
||||
Process pending plugin updates.
|
||||
|
||||
@@ -25,8 +25,7 @@ Sudoers Requirements:
|
||||
ledpi ALL=(ALL) NOPASSWD: /usr/sbin/iptables
|
||||
ledpi ALL=(ALL) NOPASSWD: /usr/sbin/sysctl
|
||||
ledpi ALL=(ALL) NOPASSWD: /usr/bin/cp /tmp/hostapd.conf /etc/hostapd/hostapd.conf
|
||||
ledpi ALL=(ALL) NOPASSWD: /usr/bin/cp /tmp/dnsmasq.conf /etc/dnsmasq.d/ledmatrix-captive.conf
|
||||
ledpi ALL=(ALL) NOPASSWD: /usr/bin/rm -f /etc/dnsmasq.d/ledmatrix-captive.conf
|
||||
ledpi ALL=(ALL) NOPASSWD: /usr/bin/cp /tmp/dnsmasq.conf /etc/dnsmasq.conf
|
||||
"""
|
||||
|
||||
import subprocess
|
||||
@@ -59,7 +58,7 @@ def get_wifi_config_path():
|
||||
return Path(project_root) / "config" / "wifi_config.json"
|
||||
|
||||
HOSTAPD_CONFIG_PATH = Path("/etc/hostapd/hostapd.conf")
|
||||
DNSMASQ_CONFIG_PATH = Path("/etc/dnsmasq.d/ledmatrix-captive.conf")
|
||||
DNSMASQ_CONFIG_PATH = Path("/etc/dnsmasq.conf")
|
||||
HOSTAPD_SERVICE = "hostapd"
|
||||
DNSMASQ_SERVICE = "dnsmasq"
|
||||
|
||||
@@ -659,31 +658,33 @@ class WiFiManager:
|
||||
except (subprocess.TimeoutExpired, subprocess.SubprocessError, OSError):
|
||||
return False
|
||||
|
||||
def scan_networks(self, allow_cached: bool = True) -> Tuple[List[WiFiNetwork], bool]:
|
||||
def scan_networks(self) -> List[WiFiNetwork]:
|
||||
"""
|
||||
Scan for available WiFi networks.
|
||||
|
||||
When AP mode is active, returns cached scan results instead of
|
||||
disabling AP (which would disconnect the user). Cached results
|
||||
come from either nmcli's internal cache or a pre-scan file saved
|
||||
before AP mode was enabled.
|
||||
|
||||
Scan for available WiFi networks
|
||||
|
||||
If AP mode is active, it will be temporarily disabled during scanning
|
||||
and re-enabled afterward. This is necessary because WiFi interfaces
|
||||
in AP mode cannot scan for other networks.
|
||||
|
||||
Returns:
|
||||
Tuple of (list of WiFiNetwork objects, was_cached bool)
|
||||
List of WiFiNetwork objects
|
||||
"""
|
||||
ap_was_active = False
|
||||
try:
|
||||
ap_active = self._is_ap_mode_active()
|
||||
|
||||
if ap_active:
|
||||
# Don't disable AP — user would lose their connection.
|
||||
# Try nmcli cached results first (no rescan trigger).
|
||||
logger.info("AP mode active — returning cached scan results")
|
||||
networks = self._scan_nmcli_cached()
|
||||
if not networks and allow_cached:
|
||||
networks = self._load_cached_scan()
|
||||
return networks, True
|
||||
|
||||
# Normal scan (not in AP mode)
|
||||
# Check if AP mode is active - if so, we need to disable it temporarily
|
||||
ap_was_active = self._is_ap_mode_active()
|
||||
|
||||
if ap_was_active:
|
||||
logger.info("AP mode is active, temporarily disabling for WiFi scan...")
|
||||
success, message = self.disable_ap_mode()
|
||||
if not success:
|
||||
logger.warning(f"Failed to disable AP mode for scanning: {message}")
|
||||
# Continue anyway - scan might still work
|
||||
else:
|
||||
# Wait for interface to switch modes
|
||||
time.sleep(3)
|
||||
|
||||
# Perform the scan
|
||||
if self.has_nmcli:
|
||||
networks = self._scan_nmcli()
|
||||
elif self.has_iwlist:
|
||||
@@ -691,87 +692,24 @@ class WiFiManager:
|
||||
else:
|
||||
logger.error("No WiFi scanning tools available")
|
||||
networks = []
|
||||
|
||||
# Save results for later use in AP mode
|
||||
if networks:
|
||||
self._save_cached_scan(networks)
|
||||
|
||||
return networks, False
|
||||
|
||||
|
||||
return networks
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Error scanning networks: {e}")
|
||||
return [], False
|
||||
|
||||
def _scan_nmcli_cached(self) -> List[WiFiNetwork]:
|
||||
"""Return nmcli's cached WiFi list without triggering a rescan."""
|
||||
networks = []
|
||||
try:
|
||||
result = subprocess.run(
|
||||
["nmcli", "-t", "-f", "SSID,SIGNAL,SECURITY,FREQ", "device", "wifi", "list"],
|
||||
capture_output=True, text=True, timeout=5
|
||||
)
|
||||
if result.returncode != 0:
|
||||
return []
|
||||
|
||||
seen_ssids = set()
|
||||
for line in result.stdout.strip().split('\n'):
|
||||
if not line or ':' not in line:
|
||||
continue
|
||||
parts = line.split(':')
|
||||
if len(parts) >= 3:
|
||||
ssid = parts[0].strip()
|
||||
if not ssid or ssid in seen_ssids:
|
||||
continue
|
||||
seen_ssids.add(ssid)
|
||||
try:
|
||||
signal = int(parts[1].strip())
|
||||
security = parts[2].strip() if len(parts) > 2 else "open"
|
||||
frequency_str = parts[3].strip() if len(parts) > 3 else "0"
|
||||
frequency_str = frequency_str.replace(" MHz", "").replace("MHz", "").strip()
|
||||
frequency = float(frequency_str) if frequency_str else 0.0
|
||||
if "WPA3" in security:
|
||||
sec_type = "wpa3"
|
||||
elif "WPA2" in security:
|
||||
sec_type = "wpa2"
|
||||
elif "WPA" in security:
|
||||
sec_type = "wpa"
|
||||
else:
|
||||
sec_type = "open"
|
||||
networks.append(WiFiNetwork(ssid=ssid, signal=signal, security=sec_type, frequency=frequency))
|
||||
except (ValueError, IndexError):
|
||||
continue
|
||||
networks.sort(key=lambda x: x.signal, reverse=True)
|
||||
except Exception as e:
|
||||
logger.debug(f"nmcli cached list failed: {e}")
|
||||
return networks
|
||||
|
||||
def _save_cached_scan(self, networks: List[WiFiNetwork]) -> None:
|
||||
"""Save scan results to a cache file for use during AP mode."""
|
||||
try:
|
||||
cache_path = get_wifi_config_path().parent / "cached_networks.json"
|
||||
data = [{"ssid": n.ssid, "signal": n.signal, "security": n.security, "frequency": n.frequency} for n in networks]
|
||||
with open(cache_path, 'w') as f:
|
||||
json.dump({"timestamp": time.time(), "networks": data}, f)
|
||||
except Exception as e:
|
||||
logger.debug(f"Failed to save cached scan: {e}")
|
||||
|
||||
def _load_cached_scan(self) -> List[WiFiNetwork]:
|
||||
"""Load pre-cached scan results (saved before AP mode was enabled)."""
|
||||
try:
|
||||
cache_path = get_wifi_config_path().parent / "cached_networks.json"
|
||||
if not cache_path.exists():
|
||||
return []
|
||||
with open(cache_path) as f:
|
||||
data = json.load(f)
|
||||
# Accept cache up to 10 minutes old
|
||||
if time.time() - data.get("timestamp", 0) > 600:
|
||||
return []
|
||||
return [WiFiNetwork(ssid=n["ssid"], signal=n["signal"], security=n["security"], frequency=n.get("frequency", 0.0))
|
||||
for n in data.get("networks", [])]
|
||||
except Exception as e:
|
||||
logger.debug(f"Failed to load cached scan: {e}")
|
||||
return []
|
||||
|
||||
finally:
|
||||
# Always try to restore AP mode if it was active before
|
||||
if ap_was_active:
|
||||
logger.info("Re-enabling AP mode after WiFi scan...")
|
||||
time.sleep(1) # Brief delay before re-enabling
|
||||
success, message = self.enable_ap_mode()
|
||||
if success:
|
||||
logger.info("AP mode re-enabled successfully after scan")
|
||||
else:
|
||||
logger.warning(f"Failed to re-enable AP mode after scan: {message}")
|
||||
# Log but don't fail - user can manually re-enable if needed
|
||||
|
||||
def _scan_nmcli(self) -> List[WiFiNetwork]:
|
||||
"""Scan networks using nmcli"""
|
||||
networks = []
|
||||
@@ -2061,16 +1999,26 @@ class WiFiManager:
|
||||
timeout=10
|
||||
)
|
||||
|
||||
# Remove the drop-in captive portal config (only for hostapd mode)
|
||||
if hostapd_active and DNSMASQ_CONFIG_PATH.exists():
|
||||
try:
|
||||
# Restore original dnsmasq config if backup exists (only for hostapd mode)
|
||||
if hostapd_active:
|
||||
backup_path = f"{DNSMASQ_CONFIG_PATH}.backup"
|
||||
if os.path.exists(backup_path):
|
||||
subprocess.run(
|
||||
["sudo", "rm", "-f", str(DNSMASQ_CONFIG_PATH)],
|
||||
capture_output=True, timeout=5
|
||||
["sudo", "cp", backup_path, str(DNSMASQ_CONFIG_PATH)],
|
||||
timeout=10
|
||||
)
|
||||
logger.info(f"Removed captive portal dnsmasq config: {DNSMASQ_CONFIG_PATH}")
|
||||
except Exception as e:
|
||||
logger.warning(f"Could not remove dnsmasq drop-in config: {e}")
|
||||
logger.info("Restored original dnsmasq config from backup")
|
||||
else:
|
||||
# No backup - clear the captive portal config
|
||||
# Create a minimal config that won't interfere
|
||||
minimal_config = "# dnsmasq config - restored to minimal\n"
|
||||
with open("/tmp/dnsmasq.conf", 'w') as f:
|
||||
f.write(minimal_config)
|
||||
subprocess.run(
|
||||
["sudo", "cp", "/tmp/dnsmasq.conf", str(DNSMASQ_CONFIG_PATH)],
|
||||
timeout=10
|
||||
)
|
||||
logger.info("Cleared dnsmasq captive portal config")
|
||||
|
||||
# Remove iptables port forwarding rules and disable IP forwarding (only for hostapd mode)
|
||||
if hostapd_active:
|
||||
@@ -2241,14 +2189,26 @@ ignore_broadcast_ssid=0
|
||||
|
||||
def _create_dnsmasq_config(self):
|
||||
"""
|
||||
Create dnsmasq drop-in configuration for captive portal DNS redirection.
|
||||
Create dnsmasq configuration file with captive portal DNS redirection.
|
||||
|
||||
Writes to /etc/dnsmasq.d/ledmatrix-captive.conf so we don't overwrite
|
||||
the main /etc/dnsmasq.conf (preserves Pi-hole, etc.).
|
||||
Note: This will overwrite /etc/dnsmasq.conf. If dnsmasq is already in use
|
||||
(e.g., for Pi-hole), this may break that service. A backup is created.
|
||||
"""
|
||||
try:
|
||||
# Using a drop-in file in /etc/dnsmasq.d/ to avoid overwriting the
|
||||
# main /etc/dnsmasq.conf (which may belong to Pi-hole or other services).
|
||||
# Check for conflicts
|
||||
conflict, conflict_msg = self._check_dnsmasq_conflict()
|
||||
if conflict:
|
||||
logger.warning(f"dnsmasq conflict detected: {conflict_msg}")
|
||||
logger.warning("Proceeding anyway - backup will be created")
|
||||
|
||||
# Backup existing config
|
||||
if DNSMASQ_CONFIG_PATH.exists():
|
||||
subprocess.run(
|
||||
["sudo", "cp", str(DNSMASQ_CONFIG_PATH), f"{DNSMASQ_CONFIG_PATH}.backup"],
|
||||
timeout=10
|
||||
)
|
||||
logger.info(f"Backed up existing dnsmasq config to {DNSMASQ_CONFIG_PATH}.backup")
|
||||
|
||||
config_content = f"""interface={self._wifi_interface}
|
||||
dhcp-range=192.168.4.2,192.168.4.20,255.255.255.0,24h
|
||||
|
||||
@@ -2329,16 +2289,7 @@ address=/detectportal.firefox.com/192.168.4.1
|
||||
self._disconnected_checks >= self._disconnected_checks_required)
|
||||
|
||||
if should_have_ap and not ap_active:
|
||||
# Pre-cache a WiFi scan so the captive portal can show networks
|
||||
try:
|
||||
logger.info("Running pre-AP WiFi scan for captive portal cache...")
|
||||
networks, _cached = self.scan_networks(allow_cached=False)
|
||||
if networks:
|
||||
self._save_cached_scan(networks)
|
||||
logger.info(f"Cached {len(networks)} networks for captive portal")
|
||||
except Exception as scan_err:
|
||||
logger.debug(f"Pre-AP scan failed (non-critical): {scan_err}")
|
||||
|
||||
# Should have AP but don't - enable AP mode (only if auto-enable is on and grace period passed)
|
||||
logger.info(f"Enabling AP mode after {self._disconnected_checks} consecutive disconnected checks")
|
||||
success, message = self.enable_ap_mode()
|
||||
if success:
|
||||
|
||||
@@ -28,29 +28,14 @@ These service files are installed by the installation scripts in `scripts/instal
|
||||
|
||||
## Manual Installation
|
||||
|
||||
> **Important:** the unit files in this directory contain
|
||||
> `__PROJECT_ROOT_DIR__` placeholders that the install scripts replace
|
||||
> with the actual project directory at install time. Do **not** copy
|
||||
> them directly to `/etc/systemd/system/` — the service will fail to
|
||||
> start with `WorkingDirectory=__PROJECT_ROOT_DIR__` errors.
|
||||
>
|
||||
> Always install via the helper script:
|
||||
>
|
||||
> ```bash
|
||||
> sudo ./scripts/install/install_service.sh
|
||||
> ```
|
||||
>
|
||||
> If you really need to do it by hand, substitute the placeholder
|
||||
> first:
|
||||
>
|
||||
> ```bash
|
||||
> PROJECT_ROOT="$(pwd)"
|
||||
> sed "s|__PROJECT_ROOT_DIR__|$PROJECT_ROOT|g" systemd/ledmatrix.service \
|
||||
> | sudo tee /etc/systemd/system/ledmatrix.service > /dev/null
|
||||
> sudo systemctl daemon-reload
|
||||
> sudo systemctl enable ledmatrix.service
|
||||
> sudo systemctl start ledmatrix.service
|
||||
> ```
|
||||
If you need to install a service manually:
|
||||
|
||||
```bash
|
||||
sudo cp systemd/ledmatrix.service /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable ledmatrix.service
|
||||
sudo systemctl start ledmatrix.service
|
||||
```
|
||||
|
||||
## Service Management
|
||||
|
||||
|
||||
@@ -583,130 +583,3 @@ class TestAPIErrorHandling:
|
||||
response = client.get('/api/v3/display/on-demand/start')
|
||||
|
||||
assert response.status_code in [200, 405] # Depends on implementation
|
||||
|
||||
|
||||
class TestDottedKeyNormalization:
|
||||
"""Regression tests for fix_array_structures / ensure_array_defaults with dotted schema keys."""
|
||||
|
||||
def test_save_plugin_config_dotted_key_arrays(self, client, mock_config_manager):
|
||||
"""Nested dotted-key objects with numeric-keyed dicts are converted to arrays."""
|
||||
from web_interface.blueprints.api_v3 import api_v3
|
||||
|
||||
api_v3.config_manager = mock_config_manager
|
||||
mock_config_manager.load_config.return_value = {}
|
||||
|
||||
schema_mgr = MagicMock()
|
||||
schema = {
|
||||
'type': 'object',
|
||||
'properties': {
|
||||
'leagues': {
|
||||
'type': 'object',
|
||||
'properties': {
|
||||
'eng.1': {
|
||||
'type': 'object',
|
||||
'properties': {
|
||||
'enabled': {'type': 'boolean', 'default': True},
|
||||
'favorite_teams': {
|
||||
'type': 'array',
|
||||
'items': {'type': 'string'},
|
||||
'default': [],
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
schema_mgr.load_schema.return_value = schema
|
||||
schema_mgr.generate_default_config.return_value = {
|
||||
'leagues': {'eng.1': {'enabled': True, 'favorite_teams': []}},
|
||||
}
|
||||
schema_mgr.merge_with_defaults.side_effect = lambda config, defaults: {**defaults, **config}
|
||||
schema_mgr.validate_config_against_schema.return_value = []
|
||||
api_v3.schema_manager = schema_mgr
|
||||
|
||||
request_data = {
|
||||
'plugin_id': 'soccer-scoreboard',
|
||||
'config': {
|
||||
'leagues': {
|
||||
'eng.1': {
|
||||
'enabled': True,
|
||||
'favorite_teams': ['Arsenal', 'Chelsea'],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
response = client.post(
|
||||
'/api/v3/plugins/config',
|
||||
data=json.dumps(request_data),
|
||||
content_type='application/json',
|
||||
)
|
||||
|
||||
assert response.status_code == 200, f"Expected 200, got {response.status_code}: {response.data}"
|
||||
saved = mock_config_manager.save_config_atomic.call_args[0][0]
|
||||
soccer_cfg = saved.get('soccer-scoreboard', {})
|
||||
leagues = soccer_cfg.get('leagues', {})
|
||||
assert 'eng.1' in leagues, f"Expected 'eng.1' key, got: {list(leagues.keys())}"
|
||||
assert isinstance(leagues['eng.1'].get('favorite_teams'), list)
|
||||
assert leagues['eng.1']['favorite_teams'] == ['Arsenal', 'Chelsea']
|
||||
|
||||
def test_save_plugin_config_none_array_gets_default(self, client, mock_config_manager):
|
||||
"""None array fields under dotted-key parents are replaced with defaults."""
|
||||
from web_interface.blueprints.api_v3 import api_v3
|
||||
|
||||
api_v3.config_manager = mock_config_manager
|
||||
mock_config_manager.load_config.return_value = {}
|
||||
|
||||
schema_mgr = MagicMock()
|
||||
schema = {
|
||||
'type': 'object',
|
||||
'properties': {
|
||||
'leagues': {
|
||||
'type': 'object',
|
||||
'properties': {
|
||||
'eng.1': {
|
||||
'type': 'object',
|
||||
'properties': {
|
||||
'favorite_teams': {
|
||||
'type': 'array',
|
||||
'items': {'type': 'string'},
|
||||
'default': [],
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
schema_mgr.load_schema.return_value = schema
|
||||
schema_mgr.generate_default_config.return_value = {
|
||||
'leagues': {'eng.1': {'favorite_teams': []}},
|
||||
}
|
||||
schema_mgr.merge_with_defaults.side_effect = lambda config, defaults: {**defaults, **config}
|
||||
schema_mgr.validate_config_against_schema.return_value = []
|
||||
api_v3.schema_manager = schema_mgr
|
||||
|
||||
request_data = {
|
||||
'plugin_id': 'soccer-scoreboard',
|
||||
'config': {
|
||||
'leagues': {
|
||||
'eng.1': {
|
||||
'favorite_teams': None,
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
response = client.post(
|
||||
'/api/v3/plugins/config',
|
||||
data=json.dumps(request_data),
|
||||
content_type='application/json',
|
||||
)
|
||||
|
||||
assert response.status_code == 200, f"Expected 200, got {response.status_code}: {response.data}"
|
||||
saved = mock_config_manager.save_config_atomic.call_args[0][0]
|
||||
soccer_cfg = saved.get('soccer-scoreboard', {})
|
||||
teams = soccer_cfg.get('leagues', {}).get('eng.1', {}).get('favorite_teams')
|
||||
assert isinstance(teams, list), f"Expected list, got: {type(teams)}"
|
||||
assert teams == [], f"Expected empty default list, got: {teams}"
|
||||
|
||||
@@ -66,53 +66,38 @@ Once running, access the web interface at:
|
||||
|
||||
The web interface reads configuration from:
|
||||
- `config/config.json` - Main configuration
|
||||
- `config/config_secrets.json` - API keys and secrets
|
||||
- `config/secrets.json` - API keys and secrets
|
||||
|
||||
## API Documentation
|
||||
|
||||
The V3 API is mounted at `/api/v3/` (`app.py:144`). For the complete
|
||||
list and request/response formats, see
|
||||
[`docs/REST_API_REFERENCE.md`](../docs/REST_API_REFERENCE.md). Quick
|
||||
reference for the most common endpoints:
|
||||
The V3 API is available at `/api/v3/` with the following endpoints:
|
||||
|
||||
### Configuration
|
||||
- `GET /api/v3/config/main` - Get main configuration
|
||||
- `POST /api/v3/config/main` - Save main configuration
|
||||
- `GET /api/v3/config/secrets` - Get secrets configuration
|
||||
- `POST /api/v3/config/raw/main` - Save raw main config (Config Editor)
|
||||
- `POST /api/v3/config/raw/secrets` - Save raw secrets
|
||||
- `POST /api/v3/config/secrets` - Save secrets configuration
|
||||
|
||||
### Display & System Control
|
||||
- `GET /api/v3/system/status` - System status
|
||||
- `POST /api/v3/system/action` - Control display (action body:
|
||||
`start_display`, `stop_display`, `restart_display_service`,
|
||||
`restart_web_service`, `git_pull`, `reboot_system`, `shutdown_system`,
|
||||
`enable_autostart`, `disable_autostart`)
|
||||
- `GET /api/v3/display/current` - Current display frame
|
||||
- `GET /api/v3/display/on-demand/status` - On-demand status
|
||||
- `POST /api/v3/display/on-demand/start` - Trigger on-demand display
|
||||
- `POST /api/v3/display/on-demand/stop` - Clear on-demand
|
||||
### Display Control
|
||||
- `POST /api/v3/display/start` - Start display service
|
||||
- `POST /api/v3/display/stop` - Stop display service
|
||||
- `POST /api/v3/display/restart` - Restart display service
|
||||
- `GET /api/v3/display/status` - Get display service status
|
||||
|
||||
### Plugins
|
||||
- `GET /api/v3/plugins/installed` - List installed plugins
|
||||
- `GET /api/v3/plugins/config?plugin_id=<id>` - Get plugin config
|
||||
- `POST /api/v3/plugins/config` - Update plugin configuration
|
||||
- `GET /api/v3/plugins/schema?plugin_id=<id>` - Get plugin schema
|
||||
- `POST /api/v3/plugins/toggle` - Enable/disable plugin
|
||||
- `POST /api/v3/plugins/install` - Install from registry
|
||||
- `POST /api/v3/plugins/install-from-url` - Install from GitHub URL
|
||||
- `POST /api/v3/plugins/uninstall` - Uninstall plugin
|
||||
- `POST /api/v3/plugins/update` - Update plugin
|
||||
- `GET /api/v3/plugins` - List installed plugins
|
||||
- `GET /api/v3/plugins/<id>` - Get plugin details
|
||||
- `POST /api/v3/plugins/<id>/config` - Update plugin configuration
|
||||
- `GET /api/v3/plugins/<id>/enable` - Enable plugin
|
||||
- `GET /api/v3/plugins/<id>/disable` - Disable plugin
|
||||
|
||||
### Plugin Store
|
||||
- `GET /api/v3/plugins/store/list` - List available registry plugins
|
||||
- `GET /api/v3/plugins/store/github-status` - GitHub authentication status
|
||||
- `POST /api/v3/plugins/store/refresh` - Refresh registry from GitHub
|
||||
- `GET /api/v3/store/plugins` - List available plugins
|
||||
- `POST /api/v3/store/install/<id>` - Install plugin
|
||||
- `POST /api/v3/store/uninstall/<id>` - Uninstall plugin
|
||||
- `POST /api/v3/store/update/<id>` - Update plugin
|
||||
|
||||
### Real-time Streams (SSE)
|
||||
SSE stream endpoints are defined directly on the Flask app
|
||||
(`app.py:607-619` — includes the CSRF exemption and rate-limit hookup
|
||||
alongside the three route definitions), not on the api_v3 blueprint:
|
||||
- `GET /api/v3/stream/stats` - System statistics stream
|
||||
- `GET /api/v3/stream/display` - Display preview stream
|
||||
- `GET /api/v3/stream/logs` - Service logs stream
|
||||
|
||||
@@ -1,6 +1,5 @@
|
||||
from flask import Flask, Blueprint, render_template, request, redirect, url_for, flash, jsonify, Response, send_from_directory
|
||||
import json
|
||||
import logging
|
||||
import os
|
||||
import sys
|
||||
import subprocess
|
||||
@@ -226,62 +225,48 @@ def serve_plugin_asset(plugin_id, filename):
|
||||
'message': 'Internal server error'
|
||||
}), 500
|
||||
|
||||
# Cached AP mode check — avoids creating a WiFiManager per request
|
||||
_ap_mode_cache = {'value': False, 'timestamp': 0}
|
||||
_AP_MODE_CACHE_TTL = 5 # seconds
|
||||
|
||||
# Helper function to check if AP mode is active
|
||||
def is_ap_mode_active():
|
||||
"""
|
||||
Check if access point mode is currently active (cached, 5s TTL).
|
||||
Uses a direct systemctl check instead of instantiating WiFiManager.
|
||||
Check if access point mode is currently active.
|
||||
|
||||
Returns:
|
||||
bool: True if AP mode is active, False otherwise.
|
||||
Returns False on error to avoid breaking normal operation.
|
||||
"""
|
||||
now = time.time()
|
||||
if (now - _ap_mode_cache['timestamp']) < _AP_MODE_CACHE_TTL:
|
||||
return _ap_mode_cache['value']
|
||||
try:
|
||||
result = subprocess.run(
|
||||
['systemctl', 'is-active', 'hostapd'],
|
||||
capture_output=True, text=True, timeout=2
|
||||
)
|
||||
active = result.stdout.strip() == 'active'
|
||||
_ap_mode_cache['value'] = active
|
||||
_ap_mode_cache['timestamp'] = now
|
||||
return active
|
||||
except (subprocess.SubprocessError, OSError) as e:
|
||||
logging.getLogger('web_interface').error(f"AP mode check failed: {e}")
|
||||
return _ap_mode_cache['value']
|
||||
wifi_manager = WiFiManager()
|
||||
return wifi_manager._is_ap_mode_active()
|
||||
except Exception as e:
|
||||
# Log error but don't break normal operation
|
||||
# Default to False so normal web interface works even if check fails
|
||||
print(f"Warning: Could not check AP mode status: {e}")
|
||||
return False
|
||||
|
||||
# Captive portal detection endpoints
|
||||
# When AP mode is active, return responses that TRIGGER the captive portal popup.
|
||||
# When not in AP mode, return normal "success" responses so connectivity checks pass.
|
||||
# These help devices detect that a captive portal is active
|
||||
@app.route('/hotspot-detect.html')
|
||||
def hotspot_detect():
|
||||
"""iOS/macOS captive portal detection endpoint"""
|
||||
if is_ap_mode_active():
|
||||
# Non-"Success" title triggers iOS captive portal popup
|
||||
return redirect(url_for('pages_v3.captive_setup'), code=302)
|
||||
# Return simple HTML that redirects to setup page
|
||||
return '<HTML><HEAD><TITLE>Success</TITLE></HEAD><BODY>Success</BODY></HTML>', 200
|
||||
|
||||
@app.route('/generate_204')
|
||||
def generate_204():
|
||||
"""Android captive portal detection endpoint"""
|
||||
if is_ap_mode_active():
|
||||
# Android expects 204 = "internet works". Non-204 triggers portal popup.
|
||||
return redirect(url_for('pages_v3.captive_setup'), code=302)
|
||||
# Return 204 No Content - Android checks for this
|
||||
return '', 204
|
||||
|
||||
@app.route('/connecttest.txt')
|
||||
def connecttest_txt():
|
||||
"""Windows captive portal detection endpoint"""
|
||||
if is_ap_mode_active():
|
||||
return redirect(url_for('pages_v3.captive_setup'), code=302)
|
||||
# Return simple text response
|
||||
return 'Microsoft Connect Test', 200
|
||||
|
||||
@app.route('/success.txt')
|
||||
def success_txt():
|
||||
"""Firefox captive portal detection endpoint"""
|
||||
if is_ap_mode_active():
|
||||
return redirect(url_for('pages_v3.captive_setup'), code=302)
|
||||
# Return simple text response
|
||||
return 'success', 200
|
||||
|
||||
# Initialize logging
|
||||
@@ -382,9 +367,10 @@ def captive_portal_redirect():
|
||||
path = request.path
|
||||
|
||||
# List of paths that should NOT be redirected (allow normal operation)
|
||||
# This ensures the full web interface works normally when in AP mode
|
||||
allowed_paths = [
|
||||
'/v3', # Main interface and all sub-paths (includes /v3/setup)
|
||||
'/api/v3/', # All API endpoints
|
||||
'/v3', # Main interface and all sub-paths
|
||||
'/api/v3/', # All API endpoints (plugins, config, wifi, stream, etc.)
|
||||
'/static/', # Static files (CSS, JS, images)
|
||||
'/hotspot-detect.html', # iOS/macOS detection
|
||||
'/generate_204', # Android detection
|
||||
@@ -392,13 +378,17 @@ def captive_portal_redirect():
|
||||
'/success.txt', # Firefox detection
|
||||
'/favicon.ico', # Favicon
|
||||
]
|
||||
|
||||
|
||||
# Check if this path should be allowed
|
||||
for allowed_path in allowed_paths:
|
||||
if path.startswith(allowed_path):
|
||||
return None
|
||||
|
||||
# Redirect to lightweight captive portal setup page (not the full UI)
|
||||
return redirect(url_for('pages_v3.captive_setup'), code=302)
|
||||
return None # Allow this request to proceed normally
|
||||
|
||||
# For all other paths, redirect to main interface
|
||||
# This ensures users see the WiFi setup page when they try to access any website
|
||||
# The main interface (/v3) is already in allowed_paths, so it won't redirect
|
||||
# Static files (/static/) and API calls (/api/v3/) are also allowed
|
||||
return redirect(url_for('pages_v3.index'), code=302)
|
||||
|
||||
# Add security headers and caching to all responses
|
||||
@app.after_request
|
||||
|
||||
@@ -740,39 +740,6 @@ def save_main_config():
|
||||
except (ValueError, TypeError):
|
||||
return jsonify({'status': 'error', 'message': f"Invalid multiplexing value '{data['multiplexing']}'. Must be an integer from 0 to 22."}), 400
|
||||
|
||||
# Validate integer display hardware fields (bounds check)
|
||||
_int_field_limits = {
|
||||
'rows': (8, 128),
|
||||
'cols': (16, 128),
|
||||
'chain_length': (1, 32),
|
||||
'parallel': (1, 4),
|
||||
'brightness': (1, 100),
|
||||
'scan_mode': (0, 1),
|
||||
'pwm_bits': (1, 11),
|
||||
'pwm_dither_bits': (0, 2),
|
||||
'pwm_lsb_nanoseconds': (50, 500),
|
||||
'limit_refresh_rate_hz': (0, 1000),
|
||||
'gpio_slowdown': (0, 5),
|
||||
'max_dynamic_duration_seconds': (1, 3600),
|
||||
}
|
||||
for field, (lo, hi) in _int_field_limits.items():
|
||||
if field in data:
|
||||
raw = data[field]
|
||||
if isinstance(raw, bool):
|
||||
return jsonify({'status': 'error', 'message': f"Invalid {field} value '{raw}'. Must be an integer."}), 400
|
||||
if isinstance(raw, float):
|
||||
return jsonify({'status': 'error', 'message': f"Invalid {field} value '{raw}'. Must be an integer, not a float."}), 400
|
||||
if isinstance(raw, int):
|
||||
val = raw
|
||||
elif isinstance(raw, str):
|
||||
if not re.fullmatch(r'-?\d+', raw):
|
||||
return jsonify({'status': 'error', 'message': f"Invalid {field} value '{raw}'. Must be an integer."}), 400
|
||||
val = int(raw)
|
||||
else:
|
||||
return jsonify({'status': 'error', 'message': f"Invalid {field} value '{raw}'. Must be an integer."}), 400
|
||||
if val < lo or val > hi:
|
||||
return jsonify({'status': 'error', 'message': f"Invalid {field} value {val}. Must be between {lo} and {hi}."}), 400
|
||||
|
||||
# Handle hardware settings
|
||||
for field in ['rows', 'cols', 'chain_length', 'parallel', 'brightness', 'hardware_mapping', 'scan_mode',
|
||||
'pwm_bits', 'pwm_dither_bits', 'pwm_lsb_nanoseconds', 'limit_refresh_rate_hz',
|
||||
@@ -800,7 +767,7 @@ def save_main_config():
|
||||
if 'max_dynamic_duration_seconds' in data:
|
||||
if 'dynamic_duration' not in current_config['display']:
|
||||
current_config['display']['dynamic_duration'] = {}
|
||||
current_config['display']['dynamic_duration']['max_duration_seconds'] = int(data['max_dynamic_duration_seconds']) # Already validated by _int_field_limits
|
||||
current_config['display']['dynamic_duration']['max_duration_seconds'] = int(data['max_dynamic_duration_seconds'])
|
||||
|
||||
# Handle Vegas scroll mode settings
|
||||
vegas_fields = ['vegas_scroll_enabled', 'vegas_scroll_speed', 'vegas_separator_width',
|
||||
@@ -4146,7 +4113,8 @@ def save_plugin_config():
|
||||
nested_dict = config_dict.get(prop_key)
|
||||
|
||||
if nested_dict is None:
|
||||
config_dict[prop_key] = {}
|
||||
if prop_key not in config_dict:
|
||||
config_dict[prop_key] = {}
|
||||
nested_dict = config_dict[prop_key]
|
||||
|
||||
if isinstance(nested_dict, dict):
|
||||
@@ -6396,17 +6364,24 @@ def get_wifi_status():
|
||||
|
||||
@api_v3.route('/wifi/scan', methods=['GET'])
|
||||
def scan_wifi_networks():
|
||||
"""Scan for available WiFi networks.
|
||||
"""Scan for available WiFi networks
|
||||
|
||||
When AP mode is active, returns cached scan results to avoid
|
||||
disconnecting the user from the setup network.
|
||||
If AP mode is active, it will be temporarily disabled during scanning
|
||||
and automatically re-enabled afterward. Users connected to the AP will
|
||||
be briefly disconnected during this process.
|
||||
"""
|
||||
try:
|
||||
from src.wifi_manager import WiFiManager
|
||||
|
||||
wifi_manager = WiFiManager()
|
||||
networks, was_cached = wifi_manager.scan_networks()
|
||||
|
||||
# Check if AP mode is active before scanning (for user notification)
|
||||
ap_was_active = wifi_manager._is_ap_mode_active()
|
||||
|
||||
# Perform the scan (this will handle AP mode disabling/enabling internally)
|
||||
networks = wifi_manager.scan_networks()
|
||||
|
||||
# Convert to dict format
|
||||
networks_data = [
|
||||
{
|
||||
'ssid': net.ssid,
|
||||
@@ -6419,14 +6394,16 @@ def scan_wifi_networks():
|
||||
|
||||
response_data = {
|
||||
'status': 'success',
|
||||
'data': networks_data,
|
||||
'cached': was_cached,
|
||||
'data': networks_data
|
||||
}
|
||||
|
||||
if was_cached and networks_data:
|
||||
response_data['message'] = f'Found {len(networks_data)} cached networks.'
|
||||
elif was_cached and not networks_data:
|
||||
response_data['message'] = 'No cached networks available. Enter your network name manually.'
|
||||
# Inform user if AP mode was temporarily disabled
|
||||
if ap_was_active:
|
||||
response_data['message'] = (
|
||||
f'Found {len(networks_data)} networks. '
|
||||
'Note: AP mode was temporarily disabled during scanning and has been re-enabled. '
|
||||
'If you were connected to the setup network, you may need to reconnect.'
|
||||
)
|
||||
|
||||
return jsonify(response_data)
|
||||
except Exception as e:
|
||||
|
||||
@@ -296,11 +296,6 @@ def _load_raw_json_partial():
|
||||
except Exception as e:
|
||||
return f"Error: {str(e)}", 500
|
||||
|
||||
@pages_v3.route('/setup')
|
||||
def captive_setup():
|
||||
"""Lightweight captive portal setup page — self-contained, no frameworks."""
|
||||
return render_template('v3/captive_setup.html')
|
||||
|
||||
def _load_wifi_partial():
|
||||
"""Load WiFi setup partial"""
|
||||
try:
|
||||
|
||||
@@ -90,48 +90,6 @@ Table-based RSS feed editor with logo uploads.
|
||||
- Enable/disable individual feeds
|
||||
- Automatic row re-indexing
|
||||
|
||||
### Other Built-in Widgets
|
||||
|
||||
In addition to the three documented above, these widgets are
|
||||
registered and ready to use via `x-widget`:
|
||||
|
||||
**Inputs:**
|
||||
- `text-input` — Plain text field with optional length constraints
|
||||
- `textarea` — Multi-line text input
|
||||
- `number-input` — Numeric input with min/max validation
|
||||
- `email-input` — Email field with format validation
|
||||
- `url-input` — URL field with format validation
|
||||
- `password-input` — Password field with show/hide toggle
|
||||
|
||||
**Selectors:**
|
||||
- `select-dropdown` — Single-select dropdown for `enum` fields
|
||||
- `radio-group` — Radio buttons for `enum` fields (alternative to dropdown)
|
||||
- `toggle-switch` — Boolean toggle (alternative to a checkbox)
|
||||
- `slider` — Numeric range slider for `integer`/`number` with `min`/`max`
|
||||
- `color-picker` — RGB color picker; outputs `[r, g, b]` arrays
|
||||
- `font-selector` — Picks from fonts in `assets/fonts/` (TTF + BDF)
|
||||
- `timezone-selector` — IANA timezone picker
|
||||
|
||||
**Date / time / scheduling:**
|
||||
- `date-picker` — Single date input
|
||||
- `day-selector` — Days-of-week multi-select (Mon–Sun checkboxes)
|
||||
- `time-range` — Start/end time pair (e.g. for dim schedules)
|
||||
- `schedule-picker` — Full cron-style or weekday/time schedule editor
|
||||
|
||||
**Composite / data-source:**
|
||||
- `array-table` — Generic table editor for arrays of objects
|
||||
- `google-calendar-picker` — Picks from the user's authenticated Google
|
||||
Calendars (used by the calendar plugin)
|
||||
|
||||
**Internal (typically not used directly by plugins):**
|
||||
- `notification` — Toast notification helper
|
||||
- `base-widget` — Base class other widgets extend
|
||||
|
||||
The canonical source for each widget's exact schema and options is the
|
||||
file in this directory (e.g., `slider.js`, `color-picker.js`). If you
|
||||
need a feature one of these doesn't support, see "Creating Custom
|
||||
Widgets" below.
|
||||
|
||||
## Using Existing Widgets
|
||||
|
||||
To use an existing widget in your plugin's `config_schema.json`, simply add the `x-widget` property to your field definition:
|
||||
|
||||
@@ -2334,15 +2334,6 @@ function dotToNested(obj, schema) {
|
||||
while (i < parts.length - 1) {
|
||||
let matched = false;
|
||||
if (currentSchema) {
|
||||
// First, check if the full remaining tail is a leaf property
|
||||
// (e.g., "eng.1" as a complete dotted key with no sub-properties)
|
||||
const tailCandidate = parts.slice(i).join('.');
|
||||
if (tailCandidate in currentSchema) {
|
||||
current[tailCandidate] = obj[key];
|
||||
matched = true;
|
||||
i = parts.length; // consumed all parts
|
||||
break;
|
||||
}
|
||||
// Try progressively longer candidates (longest first) to greedily
|
||||
// match dotted property names like "eng.1"
|
||||
for (let j = parts.length - 1; j > i; j--) {
|
||||
@@ -2378,11 +2369,8 @@ function dotToNested(obj, schema) {
|
||||
}
|
||||
|
||||
// Set the final key (remaining parts joined — may itself be dotted)
|
||||
// Skip if tail-matching already consumed all parts and wrote the value
|
||||
if (i < parts.length) {
|
||||
const finalKey = parts.slice(i).join('.');
|
||||
current[finalKey] = obj[key];
|
||||
}
|
||||
const finalKey = parts.slice(i).join('.');
|
||||
current[finalKey] = obj[key];
|
||||
}
|
||||
|
||||
return result;
|
||||
@@ -2407,20 +2395,42 @@ function collectBooleanFields(schema, prefix = '') {
|
||||
return boolFields;
|
||||
}
|
||||
|
||||
/**
|
||||
* Normalize FormData from a plugin config form into a nested config object.
|
||||
* Handles _data JSON inputs, bracket-notation checkboxes, array-of-objects,
|
||||
* file-upload widgets, proper checkbox DOM detection, unchecked boolean
|
||||
* handling, and schema-aware dotted-key nesting.
|
||||
*
|
||||
* @param {HTMLFormElement} form - The form element (needed for checkbox DOM detection)
|
||||
* @param {Object|null} schema - The plugin's JSON Schema
|
||||
* @returns {Object} Nested config object ready for saving
|
||||
*/
|
||||
function normalizeFormDataForConfig(form, schema) {
|
||||
function handlePluginConfigSubmit(e) {
|
||||
e.preventDefault();
|
||||
console.log('Form submitted');
|
||||
|
||||
if (!currentPluginConfig) {
|
||||
showNotification('Plugin configuration not loaded', 'error');
|
||||
return;
|
||||
}
|
||||
|
||||
const pluginId = currentPluginConfig.pluginId;
|
||||
const schema = currentPluginConfig.schema;
|
||||
const form = e.target;
|
||||
|
||||
// Fix invalid hidden fields before submission
|
||||
// This prevents "invalid form control is not focusable" errors
|
||||
const allInputs = form.querySelectorAll('input[type="number"]');
|
||||
allInputs.forEach(input => {
|
||||
const min = parseFloat(input.getAttribute('min'));
|
||||
const max = parseFloat(input.getAttribute('max'));
|
||||
const value = parseFloat(input.value);
|
||||
|
||||
if (!isNaN(value)) {
|
||||
if (!isNaN(min) && value < min) {
|
||||
input.value = min;
|
||||
} else if (!isNaN(max) && value > max) {
|
||||
input.value = max;
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
const formData = new FormData(form);
|
||||
const flatConfig = {};
|
||||
|
||||
|
||||
console.log('Schema loaded:', schema ? 'Yes' : 'No');
|
||||
|
||||
// Process form data with type conversion (using dot notation for nested fields)
|
||||
for (const [key, value] of formData.entries()) {
|
||||
// Check if this is a patternProperties or array-of-objects hidden input (contains JSON data)
|
||||
// Only match keys ending with '_data' to avoid false positives like 'meta_data_field'
|
||||
@@ -2432,35 +2442,36 @@ function normalizeFormDataForConfig(form, schema) {
|
||||
// Only treat as JSON-backed when it's a non-null object (null is typeof 'object' in JavaScript)
|
||||
if (jsonValue !== null && typeof jsonValue === 'object') {
|
||||
flatConfig[baseKey] = jsonValue;
|
||||
console.log(`JSON data field ${baseKey}: parsed ${Array.isArray(jsonValue) ? 'array' : 'object'}`, jsonValue);
|
||||
continue; // Skip normal processing for JSON data fields
|
||||
}
|
||||
} catch (e) {
|
||||
// Not valid JSON, continue with normal processing
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
// Skip checkbox-group inputs with bracket notation (they're handled by the hidden _data input)
|
||||
// Pattern: fieldName[] - these are individual checkboxes, actual data is in fieldName_data
|
||||
if (key.endsWith('[]')) {
|
||||
continue;
|
||||
}
|
||||
|
||||
|
||||
// Skip key_value pair inputs (they're handled by the hidden _data input)
|
||||
if (key.includes('[key_') || key.includes('[value_')) {
|
||||
continue;
|
||||
}
|
||||
|
||||
|
||||
// Skip array-of-objects per-item inputs (they're handled by the hidden _data input)
|
||||
// Pattern: feeds_item_0_name, feeds_item_1_url, etc.
|
||||
if (key.includes('_item_') && /_item_\d+_/.test(key)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
|
||||
// Try to get schema property - handle both dot notation and underscore notation
|
||||
let propSchema = getSchemaPropertyType(schema, key);
|
||||
let actualKey = key;
|
||||
let actualValue = value;
|
||||
|
||||
|
||||
// If not found with dots, try converting underscores to dots (for nested fields)
|
||||
if (!propSchema && key.includes('_')) {
|
||||
const dotKey = key.replace(/_/g, '.');
|
||||
@@ -2471,10 +2482,10 @@ function normalizeFormDataForConfig(form, schema) {
|
||||
actualValue = value;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
if (propSchema) {
|
||||
const propType = propSchema.type;
|
||||
|
||||
|
||||
if (propType === 'array') {
|
||||
// Check if this is a file upload widget (JSON array)
|
||||
if (propSchema['x-widget'] === 'file-upload') {
|
||||
@@ -2488,10 +2499,11 @@ function normalizeFormDataForConfig(form, schema) {
|
||||
tempDiv.innerHTML = actualValue;
|
||||
decodedValue = tempDiv.textContent || tempDiv.innerText || actualValue;
|
||||
}
|
||||
|
||||
|
||||
const jsonValue = JSON.parse(decodedValue);
|
||||
if (Array.isArray(jsonValue)) {
|
||||
flatConfig[actualKey] = jsonValue;
|
||||
console.log(`File upload array field ${actualKey}: parsed JSON array with ${jsonValue.length} items`);
|
||||
} else {
|
||||
// Fallback to comma-separated
|
||||
const arrayValue = decodedValue ? decodedValue.split(',').map(v => v.trim()).filter(v => v) : [];
|
||||
@@ -2501,11 +2513,13 @@ function normalizeFormDataForConfig(form, schema) {
|
||||
// Not JSON, use comma-separated
|
||||
const arrayValue = actualValue ? actualValue.split(',').map(v => v.trim()).filter(v => v) : [];
|
||||
flatConfig[actualKey] = arrayValue;
|
||||
console.log(`Array field ${actualKey}: "${actualValue}" -> `, arrayValue);
|
||||
}
|
||||
} else {
|
||||
// Regular array: convert comma-separated string to array
|
||||
const arrayValue = actualValue ? actualValue.split(',').map(v => v.trim()).filter(v => v) : [];
|
||||
flatConfig[actualKey] = arrayValue;
|
||||
console.log(`Array field ${actualKey}: "${actualValue}" -> `, arrayValue);
|
||||
}
|
||||
} else if (propType === 'integer') {
|
||||
flatConfig[actualKey] = parseInt(actualValue, 10);
|
||||
@@ -2516,13 +2530,14 @@ function normalizeFormDataForConfig(form, schema) {
|
||||
// Escape special CSS selector characters in the name
|
||||
const escapedKey = escapeCssSelector(key);
|
||||
const formElement = form.querySelector(`input[type="checkbox"][name="${escapedKey}"]`);
|
||||
|
||||
|
||||
if (formElement) {
|
||||
// Element found - use its checked state
|
||||
flatConfig[actualKey] = formElement.checked;
|
||||
} else {
|
||||
// Element not found - normalize string booleans and check FormData value
|
||||
// Checkboxes send "on" when checked, nothing when unchecked
|
||||
// Normalize string representations of booleans
|
||||
if (typeof actualValue === 'string') {
|
||||
const lowerValue = actualValue.toLowerCase().trim();
|
||||
if (lowerValue === 'true' || lowerValue === '1' || lowerValue === 'on') {
|
||||
@@ -2530,11 +2545,13 @@ function normalizeFormDataForConfig(form, schema) {
|
||||
} else if (lowerValue === 'false' || lowerValue === '0' || lowerValue === 'off' || lowerValue === '') {
|
||||
flatConfig[actualKey] = false;
|
||||
} else {
|
||||
// Non-empty string that's not a boolean representation - treat as truthy
|
||||
flatConfig[actualKey] = true;
|
||||
}
|
||||
} else if (actualValue === undefined || actualValue === null) {
|
||||
flatConfig[actualKey] = false;
|
||||
} else {
|
||||
// Non-string value - coerce to boolean
|
||||
flatConfig[actualKey] = Boolean(actualValue);
|
||||
}
|
||||
}
|
||||
@@ -2551,9 +2568,10 @@ function normalizeFormDataForConfig(form, schema) {
|
||||
const tempDiv = document.createElement('div');
|
||||
tempDiv.innerHTML = actualValue;
|
||||
decodedValue = tempDiv.textContent || tempDiv.innerText || actualValue;
|
||||
|
||||
|
||||
const parsed = JSON.parse(decodedValue);
|
||||
flatConfig[actualKey] = parsed;
|
||||
console.log(`No schema for ${actualKey}, but parsed as JSON:`, parsed);
|
||||
} catch (e) {
|
||||
// Not valid JSON, save as string
|
||||
flatConfig[actualKey] = actualValue;
|
||||
@@ -2562,10 +2580,12 @@ function normalizeFormDataForConfig(form, schema) {
|
||||
// No schema - try to detect checkbox by finding the element
|
||||
const escapedKey = escapeCssSelector(key);
|
||||
const formElement = form.querySelector(`input[type="checkbox"][name="${escapedKey}"]`);
|
||||
|
||||
|
||||
if (formElement && formElement.type === 'checkbox') {
|
||||
// Found checkbox element - use its checked state
|
||||
flatConfig[actualKey] = formElement.checked;
|
||||
} else {
|
||||
// Not a checkbox or element not found - normalize string booleans
|
||||
if (typeof actualValue === 'string') {
|
||||
const lowerValue = actualValue.toLowerCase().trim();
|
||||
if (lowerValue === 'true' || lowerValue === '1' || lowerValue === 'on') {
|
||||
@@ -2573,16 +2593,18 @@ function normalizeFormDataForConfig(form, schema) {
|
||||
} else if (lowerValue === 'false' || lowerValue === '0' || lowerValue === 'off' || lowerValue === '') {
|
||||
flatConfig[actualKey] = false;
|
||||
} else {
|
||||
// Non-empty string that's not a boolean representation - keep as string
|
||||
flatConfig[actualKey] = actualValue;
|
||||
}
|
||||
} else {
|
||||
// Non-string value - use as-is
|
||||
flatConfig[actualKey] = actualValue;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
// Handle unchecked checkboxes (not in FormData) - including nested ones
|
||||
if (schema && schema.properties) {
|
||||
const allBoolFields = collectBooleanFields(schema);
|
||||
@@ -2592,43 +2614,11 @@ function normalizeFormDataForConfig(form, schema) {
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
// Convert dot notation to nested object
|
||||
return dotToNested(flatConfig, schema);
|
||||
}
|
||||
|
||||
function handlePluginConfigSubmit(e) {
|
||||
e.preventDefault();
|
||||
console.log('Form submitted');
|
||||
|
||||
if (!currentPluginConfig) {
|
||||
showNotification('Plugin configuration not loaded', 'error');
|
||||
return;
|
||||
}
|
||||
|
||||
const pluginId = currentPluginConfig.pluginId;
|
||||
const schema = currentPluginConfig.schema;
|
||||
const form = e.target;
|
||||
|
||||
// Fix invalid hidden fields before submission
|
||||
// This prevents "invalid form control is not focusable" errors
|
||||
const allInputs = form.querySelectorAll('input[type="number"]');
|
||||
allInputs.forEach(input => {
|
||||
const min = parseFloat(input.getAttribute('min'));
|
||||
const max = parseFloat(input.getAttribute('max'));
|
||||
const value = parseFloat(input.value);
|
||||
|
||||
if (!isNaN(value)) {
|
||||
if (!isNaN(min) && value < min) {
|
||||
input.value = min;
|
||||
} else if (!isNaN(max) && value > max) {
|
||||
input.value = max;
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
const config = normalizeFormDataForConfig(form, schema);
|
||||
|
||||
const config = dotToNested(flatConfig, schema);
|
||||
|
||||
console.log('Flat config:', flatConfig);
|
||||
console.log('Nested config to save:', config);
|
||||
|
||||
// Save the configuration
|
||||
@@ -4473,9 +4463,42 @@ function switchPluginConfigView(view) {
|
||||
function syncFormToJson() {
|
||||
const form = document.getElementById('plugin-config-form');
|
||||
if (!form) return;
|
||||
|
||||
|
||||
const formData = new FormData(form);
|
||||
const config = {};
|
||||
|
||||
// Get schema for type conversion
|
||||
const schema = currentPluginConfigState.schema;
|
||||
const config = normalizeFormDataForConfig(form, schema);
|
||||
|
||||
for (let [key, value] of formData.entries()) {
|
||||
if (key === 'enabled') continue; // Skip enabled, managed separately
|
||||
|
||||
// Handle nested keys (dot notation)
|
||||
const keys = key.split('.');
|
||||
let current = config;
|
||||
for (let i = 0; i < keys.length - 1; i++) {
|
||||
if (!current[keys[i]]) {
|
||||
current[keys[i]] = {};
|
||||
}
|
||||
current = current[keys[i]];
|
||||
}
|
||||
|
||||
const finalKey = keys[keys.length - 1];
|
||||
const prop = schema?.properties?.[finalKey] || (keys.length > 1 ? null : schema?.properties?.[key]);
|
||||
|
||||
// Type conversion based on schema
|
||||
if (prop?.type === 'array') {
|
||||
current[finalKey] = value.split(',').map(item => item.trim()).filter(item => item.length > 0);
|
||||
} else if (prop?.type === 'integer' || key === 'display_duration') {
|
||||
current[finalKey] = parseInt(value) || 0;
|
||||
} else if (prop?.type === 'number') {
|
||||
current[finalKey] = parseFloat(value) || 0;
|
||||
} else if (prop?.type === 'boolean') {
|
||||
current[finalKey] = value === 'true' || value === true;
|
||||
} else {
|
||||
current[finalKey] = value;
|
||||
}
|
||||
}
|
||||
|
||||
// Deep merge with existing config to preserve nested structures
|
||||
function deepMerge(target, source) {
|
||||
|
||||
@@ -519,9 +519,6 @@
|
||||
}
|
||||
});
|
||||
|
||||
// Guard flag to prevent duplicate stub-to-full enhancement
|
||||
window._appEnhanced = false;
|
||||
|
||||
// Define app() function early so Alpine can find it when it initializes
|
||||
// This is a complete implementation that will work immediately
|
||||
(function() {
|
||||
@@ -537,25 +534,15 @@
|
||||
init() {
|
||||
// Try to enhance immediately with full implementation
|
||||
const tryEnhance = () => {
|
||||
if (window._appEnhanced) return true;
|
||||
if (typeof window.app === 'function') {
|
||||
const fullApp = window.app();
|
||||
// Check if this is the full implementation (has updatePluginTabs with proper implementation)
|
||||
if (fullApp && typeof fullApp.updatePluginTabs === 'function' && fullApp.updatePluginTabs.toString().includes('_doUpdatePluginTabs')) {
|
||||
window._appEnhanced = true;
|
||||
// Preserve runtime state that should not be reset
|
||||
const preservedPlugins = this.installedPlugins;
|
||||
const preservedTab = this.activeTab;
|
||||
const defaultTab = isAPMode ? 'wifi' : 'overview';
|
||||
// Full implementation is available, copy all methods
|
||||
// But preserve _initialized flag to prevent double init
|
||||
const wasInitialized = this._initialized;
|
||||
Object.assign(this, fullApp);
|
||||
// Restore runtime state if non-default
|
||||
if (preservedPlugins && preservedPlugins.length > 0) {
|
||||
this.installedPlugins = preservedPlugins;
|
||||
}
|
||||
if (preservedTab && preservedTab !== defaultTab) {
|
||||
this.activeTab = preservedTab;
|
||||
}
|
||||
// Restore _initialized flag if it was set
|
||||
if (wasInitialized) {
|
||||
this._initialized = wasInitialized;
|
||||
}
|
||||
@@ -1265,27 +1252,11 @@
|
||||
<template x-if="activeTab === plugin.id">
|
||||
<div class="bg-white rounded-lg shadow p-6 plugin-config-tab"
|
||||
:id="'plugin-config-' + plugin.id"
|
||||
x-init="$nextTick(() => {
|
||||
const el = $el;
|
||||
const pid = plugin.id;
|
||||
const loadContent = (retries) => {
|
||||
if (window.htmx && !el.dataset.htmxLoaded) {
|
||||
el.dataset.htmxLoaded = 'true';
|
||||
htmx.ajax('GET', '/v3/partials/plugin-config/' + pid, {target: el, swap: 'innerHTML'});
|
||||
} else if (!window.htmx && retries < 15) {
|
||||
setTimeout(() => loadContent(retries + 1), 200);
|
||||
} else if (!window.htmx) {
|
||||
fetch('/v3/partials/plugin-config/' + pid)
|
||||
.then(r => r.text())
|
||||
.then(html => {
|
||||
el.innerHTML = html;
|
||||
if (window.Alpine) {
|
||||
window.Alpine.initTree(el);
|
||||
}
|
||||
});
|
||||
}
|
||||
};
|
||||
loadContent(0);
|
||||
x-init="$nextTick(() => {
|
||||
if (window.htmx && !$el.dataset.htmxLoaded) {
|
||||
$el.dataset.htmxLoaded = 'true';
|
||||
htmx.ajax('GET', '/v3/partials/plugin-config/' + plugin.id, {target: $el, swap: 'innerHTML'});
|
||||
}
|
||||
})">
|
||||
<!-- Loading skeleton shown until HTMX loads server-rendered content -->
|
||||
<div class="animate-pulse space-y-6">
|
||||
@@ -3095,28 +3066,13 @@
|
||||
if (window.Alpine) {
|
||||
// Use requestAnimationFrame for immediate execution without blocking
|
||||
requestAnimationFrame(() => {
|
||||
if (window._appEnhanced) return;
|
||||
window._appEnhanced = true;
|
||||
const isAPMode = window.location.hostname === '192.168.4.1' ||
|
||||
window.location.hostname.startsWith('192.168.4.');
|
||||
const defaultTab = isAPMode ? 'wifi' : 'overview';
|
||||
const appElement = document.querySelector('[x-data]');
|
||||
if (appElement && appElement._x_dataStack && appElement._x_dataStack[0]) {
|
||||
const existingComponent = appElement._x_dataStack[0];
|
||||
// Preserve runtime state that should not be reset
|
||||
const preservedPlugins = existingComponent.installedPlugins;
|
||||
const preservedTab = existingComponent.activeTab;
|
||||
// Replace all properties and methods from full implementation
|
||||
Object.keys(fullImplementation).forEach(key => {
|
||||
existingComponent[key] = fullImplementation[key];
|
||||
});
|
||||
// Restore runtime state if non-default
|
||||
if (preservedPlugins && preservedPlugins.length > 0) {
|
||||
existingComponent.installedPlugins = preservedPlugins;
|
||||
}
|
||||
if (preservedTab && preservedTab !== defaultTab) {
|
||||
existingComponent.activeTab = preservedTab;
|
||||
}
|
||||
// Call init to load plugins and set up watchers (only if not already initialized)
|
||||
if (typeof existingComponent.init === 'function' && !existingComponent._initialized) {
|
||||
existingComponent.init();
|
||||
|
||||
@@ -1,249 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>LEDMatrix WiFi Setup</title>
|
||||
<style>
|
||||
*{box-sizing:border-box;margin:0;padding:0}
|
||||
body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;background:#f3f4f6;color:#1f2937;padding:16px;max-width:480px;margin:0 auto}
|
||||
h1{font-size:20px;margin-bottom:4px}
|
||||
.subtitle{color:#6b7280;font-size:13px;margin-bottom:20px}
|
||||
.card{background:#fff;border-radius:12px;padding:20px;box-shadow:0 1px 3px rgba(0,0,0,.1);margin-bottom:16px}
|
||||
label{display:block;font-size:13px;font-weight:600;color:#374151;margin-bottom:6px}
|
||||
select,input[type=text],input[type=password]{width:100%;padding:10px 12px;border:1px solid #d1d5db;border-radius:8px;font-size:15px;background:#fff;-webkit-appearance:none;appearance:none}
|
||||
select{background-image:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8'%3E%3Cpath d='M1 1l5 5 5-5' stroke='%236b7280' stroke-width='1.5' fill='none'/%3E%3C/svg%3E");background-repeat:no-repeat;background-position:right 12px center}
|
||||
select:focus,input:focus{outline:none;border-color:#3b82f6;box-shadow:0 0 0 3px rgba(59,130,246,.15)}
|
||||
.btn{display:block;width:100%;padding:12px;border:none;border-radius:8px;font-size:15px;font-weight:600;cursor:pointer;text-align:center;transition:background .15s}
|
||||
.btn-primary{background:#2563eb;color:#fff}.btn-primary:hover{background:#1d4ed8}
|
||||
.btn-scan{background:#e5e7eb;color:#374151}.btn-scan:hover{background:#d1d5db}
|
||||
.btn:disabled{background:#d1d5db;color:#9ca3af;cursor:not-allowed}
|
||||
.row{display:flex;gap:8px;margin-bottom:16px}
|
||||
.row>*:first-child{flex:1}
|
||||
.msg{padding:12px;border-radius:8px;font-size:13px;margin-bottom:12px;display:none}
|
||||
.msg-ok{background:#d1fae5;color:#065f46;display:block}
|
||||
.msg-err{background:#fee2e2;color:#991b1b;display:block}
|
||||
.msg-info{background:#dbeafe;color:#1e40af;display:block}
|
||||
.step{font-size:12px;color:#6b7280;text-transform:uppercase;letter-spacing:.5px;margin-bottom:4px}
|
||||
.sep{margin:16px 0;border:none;border-top:1px solid #e5e7eb}
|
||||
.spinner{display:inline-block;width:14px;height:14px;border:2px solid rgba(255,255,255,.3);border-top-color:#fff;border-radius:50%;animation:spin .6s linear infinite;vertical-align:middle;margin-right:6px}
|
||||
@keyframes spin{to{transform:rotate(360deg)}}
|
||||
.footer{text-align:center;margin-top:20px;font-size:12px;color:#9ca3af}
|
||||
.footer a{color:#3b82f6;text-decoration:none}
|
||||
.success-box{text-align:center;padding:24px}
|
||||
.success-box .icon{font-size:48px;margin-bottom:12px}
|
||||
.success-box .ip{font-size:18px;font-weight:700;color:#2563eb;word-break:break-all}
|
||||
.hidden{display:none}
|
||||
.or-divider{text-align:center;color:#9ca3af;font-size:12px;margin:12px 0;position:relative}
|
||||
.or-divider::before,.or-divider::after{content:'';position:absolute;top:50%;width:40%;height:1px;background:#e5e7eb}
|
||||
.or-divider::before{left:0}
|
||||
.or-divider::after{right:0}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<h1>LEDMatrix WiFi Setup</h1>
|
||||
<p class="subtitle">Connect your device to a WiFi network</p>
|
||||
|
||||
<div id="msg" class="msg"></div>
|
||||
|
||||
<div id="setup-form">
|
||||
<div class="card">
|
||||
<div class="step">Step 1 — Choose Network</div>
|
||||
<label for="net-select">Available Networks</label>
|
||||
<div class="row">
|
||||
<select id="net-select" onchange="onSelectNetwork()">
|
||||
<option value="">-- Scan to find networks --</option>
|
||||
</select>
|
||||
<button class="btn btn-scan" id="btn-scan" onclick="doScan()" style="width:auto;padding:10px 16px">
|
||||
Scan
|
||||
</button>
|
||||
</div>
|
||||
<div class="or-divider">or enter manually</div>
|
||||
<input type="text" id="manual-ssid" placeholder="Network name (SSID)" oninput="onManualInput()">
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<div class="step">Step 2 — Password</div>
|
||||
<label for="password">WiFi Password</label>
|
||||
<input type="password" id="password" placeholder="Leave empty for open networks">
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<button class="btn btn-primary" id="btn-connect" onclick="doConnect()" disabled>
|
||||
Connect
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div id="success-view" class="card hidden">
|
||||
<div class="success-box">
|
||||
<div class="icon">✓</div>
|
||||
<p style="font-size:16px;font-weight:600;margin-bottom:8px">Connected!</p>
|
||||
<p style="font-size:13px;color:#6b7280;margin-bottom:12px">Your device is now on the network. Access the full interface at:</p>
|
||||
<p class="ip" id="new-ip"></p>
|
||||
<p style="font-size:12px;color:#9ca3af;margin-top:12px">You may need to reconnect your phone to the same WiFi network.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="footer">
|
||||
<a href="/v3">Open Full Interface</a>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
var selectedSSID = '';
|
||||
var scanning = false;
|
||||
var connecting = false;
|
||||
|
||||
function $(id) { return document.getElementById(id); }
|
||||
|
||||
function showMsg(text, type) {
|
||||
var el = $('msg');
|
||||
el.textContent = text;
|
||||
el.className = 'msg msg-' + (type || 'info');
|
||||
if (type === 'ok') setTimeout(function() { el.style.display = 'none'; }, 8000);
|
||||
}
|
||||
|
||||
function clearMsg() { $('msg').className = 'msg'; }
|
||||
|
||||
function updateConnectBtn() {
|
||||
var ssid = $('net-select').value || $('manual-ssid').value.trim();
|
||||
$('btn-connect').disabled = !ssid || connecting;
|
||||
}
|
||||
|
||||
function onSelectNetwork() {
|
||||
$('manual-ssid').value = '';
|
||||
selectedSSID = $('net-select').value;
|
||||
updateConnectBtn();
|
||||
}
|
||||
|
||||
function onManualInput() {
|
||||
$('net-select').value = '';
|
||||
selectedSSID = '';
|
||||
updateConnectBtn();
|
||||
}
|
||||
|
||||
function doScan() {
|
||||
if (scanning) return;
|
||||
scanning = true;
|
||||
var btn = $('btn-scan');
|
||||
btn.disabled = true;
|
||||
btn.innerHTML = '<span class="spinner"></span>Scanning';
|
||||
clearMsg();
|
||||
|
||||
fetch('/api/v3/wifi/scan')
|
||||
.then(function(r) { return r.json(); })
|
||||
.then(function(data) {
|
||||
var sel = $('net-select');
|
||||
sel.innerHTML = '<option value="">-- Select a network --</option>';
|
||||
if (data.status === 'success' && Array.isArray(data.data)) {
|
||||
var nets = data.data;
|
||||
for (var i = 0; i < nets.length; i++) {
|
||||
var n = nets[i];
|
||||
var opt = document.createElement('option');
|
||||
opt.value = n.ssid;
|
||||
opt.textContent = n.ssid + ' (' + n.signal + '% - ' + n.security + ')';
|
||||
sel.appendChild(opt);
|
||||
}
|
||||
if (nets.length > 0) {
|
||||
var msg = 'Found ' + nets.length + ' network' + (nets.length > 1 ? 's' : '');
|
||||
if (data.cached) {
|
||||
msg += ' \u2014 Showing cached networks. Connect to see the latest.';
|
||||
}
|
||||
showMsg(msg, data.cached ? 'info' : 'ok');
|
||||
} else {
|
||||
showMsg('No networks found. ' + (data.cached ? 'Enter your network name manually.' : 'Try scanning again.'), 'info');
|
||||
}
|
||||
} else {
|
||||
showMsg(data.message || 'Scan failed', 'err');
|
||||
}
|
||||
})
|
||||
.catch(function(e) {
|
||||
showMsg('Scan failed: ' + e.message, 'err');
|
||||
})
|
||||
.finally(function() {
|
||||
scanning = false;
|
||||
btn.disabled = false;
|
||||
btn.innerHTML = 'Scan';
|
||||
updateConnectBtn();
|
||||
});
|
||||
}
|
||||
|
||||
function doConnect() {
|
||||
var ssid = $('net-select').value || $('manual-ssid').value.trim();
|
||||
if (!ssid || connecting) return;
|
||||
connecting = true;
|
||||
var btn = $('btn-connect');
|
||||
btn.disabled = true;
|
||||
btn.innerHTML = '<span class="spinner"></span>Connecting...';
|
||||
clearMsg();
|
||||
showMsg('Connecting to ' + ssid + '... This may take 15-30 seconds.', 'info');
|
||||
|
||||
fetch('/api/v3/wifi/connect', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ ssid: ssid, password: $('password').value || '' })
|
||||
})
|
||||
.then(function(r) { return r.json(); })
|
||||
.then(function(data) {
|
||||
if (data.status === 'success') {
|
||||
clearMsg();
|
||||
// Poll for the new IP
|
||||
setTimeout(function() { checkNewIP(ssid); }, 3000);
|
||||
} else {
|
||||
showMsg(data.message || 'Connection failed', 'err');
|
||||
connecting = false;
|
||||
btn.disabled = false;
|
||||
btn.innerHTML = 'Connect';
|
||||
}
|
||||
})
|
||||
.catch(function(e) {
|
||||
// Connection may drop if AP mode was disabled — that's expected
|
||||
clearMsg();
|
||||
showMsg('Connection attempt sent. If the page stops responding, the device is connecting to ' + ssid + '.', 'info');
|
||||
setTimeout(function() { showSuccessFallback(ssid); }, 5000);
|
||||
});
|
||||
}
|
||||
|
||||
var MAX_IP_RETRIES = 20;
|
||||
|
||||
function checkNewIP(ssid, retriesLeft) {
|
||||
if (retriesLeft === undefined) retriesLeft = MAX_IP_RETRIES;
|
||||
if (retriesLeft <= 0) {
|
||||
showSuccessFallback(ssid);
|
||||
return;
|
||||
}
|
||||
fetch('/api/v3/wifi/status')
|
||||
.then(function(r) { return r.json(); })
|
||||
.then(function(data) {
|
||||
if (data.status === 'success' && data.data && data.data.connected && data.data.ip_address) {
|
||||
showSuccess(data.data.ip_address);
|
||||
} else {
|
||||
setTimeout(function() { checkNewIP(ssid, retriesLeft - 1); }, 3000);
|
||||
}
|
||||
})
|
||||
.catch(function() {
|
||||
// AP likely down — show fallback
|
||||
showSuccessFallback(ssid);
|
||||
});
|
||||
}
|
||||
|
||||
function showSuccess(ip) {
|
||||
$('setup-form').classList.add('hidden');
|
||||
$('success-view').classList.remove('hidden');
|
||||
$('new-ip').textContent = 'http://' + ip + ':5000';
|
||||
$('msg').className = 'msg';
|
||||
}
|
||||
|
||||
function showSuccessFallback(ssid) {
|
||||
$('setup-form').classList.add('hidden');
|
||||
$('success-view').classList.remove('hidden');
|
||||
$('new-ip').textContent = 'Check your router for the device IP';
|
||||
$('msg').className = 'msg';
|
||||
}
|
||||
|
||||
// Auto-scan on load
|
||||
doScan();
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -49,9 +49,9 @@
|
||||
name="chain_length"
|
||||
value="{{ main_config.display.hardware.chain_length or 2 }}"
|
||||
min="1"
|
||||
max="32"
|
||||
max="8"
|
||||
class="form-control">
|
||||
<p class="mt-1 text-sm text-gray-600">Number of LED panels chained together (e.g. 2 for 128×32, 5 for 320×32)</p>
|
||||
<p class="mt-1 text-sm text-gray-600">Number of LED panels chained together</p>
|
||||
</div>
|
||||
|
||||
<div class="form-group">
|
||||
|
||||
@@ -215,6 +215,9 @@
|
||||
var fontOverrides = window.fontOverrides;
|
||||
var selectedFontFiles = window.selectedFontFiles;
|
||||
|
||||
// Base URL for API calls (shared scope)
|
||||
var baseUrl = window.location.origin;
|
||||
|
||||
// Retry counter for initialization
|
||||
var initRetryCount = 0;
|
||||
var MAX_INIT_RETRIES = 50; // 5 seconds max (50 * 100ms)
|
||||
@@ -381,9 +384,9 @@ async function loadFontData() {
|
||||
try {
|
||||
// Use absolute URLs to ensure they work when loaded via HTMX
|
||||
const [catalogRes, tokensRes, overridesRes] = await Promise.all([
|
||||
fetch(`/api/v3/fonts/catalog`),
|
||||
fetch(`/api/v3/fonts/tokens`),
|
||||
fetch(`/api/v3/fonts/overrides`)
|
||||
fetch(`${baseUrl}/api/v3/fonts/catalog`),
|
||||
fetch(`${baseUrl}/api/v3/fonts/tokens`),
|
||||
fetch(`${baseUrl}/api/v3/fonts/overrides`)
|
||||
]);
|
||||
|
||||
// Check if all responses are successful
|
||||
@@ -555,7 +558,7 @@ async function deleteFont(fontFamily) {
|
||||
}
|
||||
|
||||
try {
|
||||
const response = await fetch(`/api/v3/fonts/${encodeURIComponent(fontFamily)}`, {
|
||||
const response = await fetch(`${baseUrl}/api/v3/fonts/${encodeURIComponent(fontFamily)}`, {
|
||||
method: 'DELETE'
|
||||
});
|
||||
|
||||
@@ -664,7 +667,7 @@ async function addFontOverride() {
|
||||
if (sizePx) overrideData.size_px = sizePx;
|
||||
}
|
||||
|
||||
const response = await fetch(`/api/v3/fonts/overrides`, {
|
||||
const response = await fetch(`${baseUrl}/api/v3/fonts/overrides`, {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
@@ -709,7 +712,7 @@ async function deleteFontOverride(elementKey) {
|
||||
}
|
||||
|
||||
try {
|
||||
const response = await fetch(`/api/v3/fonts/overrides/${elementKey}`, {
|
||||
const response = await fetch(`${baseUrl}/api/v3/fonts/overrides/${elementKey}`, {
|
||||
method: 'DELETE'
|
||||
});
|
||||
|
||||
@@ -857,7 +860,7 @@ async function updateFontPreview() {
|
||||
fg: 'ffffff'
|
||||
});
|
||||
|
||||
const response = await fetch(`/api/v3/fonts/preview?${params}`);
|
||||
const response = await fetch(`${baseUrl}/api/v3/fonts/preview?${params}`);
|
||||
|
||||
if (!response.ok) {
|
||||
const text = await response.text();
|
||||
@@ -987,7 +990,7 @@ async function uploadSelectedFonts() {
|
||||
formData.append('font_file', file);
|
||||
formData.append('font_family', i === 0 ? fontFamily : `${fontFamily}_${i + 1}`);
|
||||
|
||||
const response = await fetch(`/api/v3/fonts/upload`, {
|
||||
const response = await fetch(`${baseUrl}/api/v3/fonts/upload`, {
|
||||
method: 'POST',
|
||||
body: formData
|
||||
});
|
||||
|
||||
@@ -561,8 +561,8 @@
|
||||
data-full-key="{{ full_key }}"
|
||||
data-max-items="{{ max_items }}"
|
||||
data-plugin-id="{{ plugin_id }}"
|
||||
data-item-properties='{% set ns = namespace(d={}) %}{% for k in display_columns %}{% if k in item_properties %}{% set _ = ns.d.update({k: item_properties[k]}) %}{% endif %}{% endfor %}{{ ns.d|tojson }}'
|
||||
data-display-columns='{{ display_columns|tojson }}'
|
||||
data-item-properties="{{ item_properties|tojson|e }}"
|
||||
data-display-columns="{{ display_columns|tojson|e }}"
|
||||
class="mt-3 px-4 py-2 text-sm bg-blue-600 hover:bg-blue-700 text-white rounded-md"
|
||||
{% if array_value|length >= max_items %}disabled style="opacity: 0.5;"{% endif %}>
|
||||
<i class="fas fa-plus mr-1"></i> Add Item
|
||||
|
||||
@@ -114,7 +114,7 @@
|
||||
<input type="text"
|
||||
id="manual-ssid"
|
||||
x-model="manualSSID"
|
||||
@input="selectedSSID = ''"
|
||||
@input="selectedSSID = ''; selectedSSID = $event.target.value"
|
||||
placeholder="Enter network name"
|
||||
class="form-control">
|
||||
</div>
|
||||
|
||||
Reference in New Issue
Block a user