diff --git a/docs/ADVANCED_FEATURES.md b/docs/ADVANCED_FEATURES.md index d620fef7..a942b152 100644 --- a/docs/ADVANCED_FEATURES.md +++ b/docs/ADVANCED_FEATURES.md @@ -377,9 +377,16 @@ Vegas mode consists of four core components working together to provide smooth 1 5. Compose into continuous stream with separators **Key Methods:** -- `get_stream_content()` - Returns current stream content as PIL Image -- `advance_stream(pixels)` - Advances stream by N pixels -- `refresh_stream()` - Regenerates stream from current plugins +- `get_next_segment()` - Returns the next buffered `ContentSegment` (or `None`) +- `take_next_group(count=None, offscreen_only=False)` - Hands over the next + slice of the rotation as `(plugin_id, images)` groups +- `get_grouped_content_for_composition()` - Buffered images grouped by plugin +- `mark_plugin_updated(plugin_id)` / `process_updates()` - Refresh one + plugin's segment in place when its data changes +- `refresh()` - Re-read the plugin list and config +- `advance_cycle()` - Clear the active buffer when a scroll cycle completes + +(`src/vegas_mode/stream_manager.py`) #### 3. PluginAdapter @@ -552,7 +559,8 @@ time when something is active. ### REST API Reference -The API is mounted at `/api/v3` (`web_interface/app.py:199`). +The API is mounted at `/api/v3` (the `api_v3` blueprint, registered in +`web_interface/app.py`). Full details: [REST_API_REFERENCE.md](REST_API_REFERENCE.md#display-control). #### Start On-Demand Display @@ -608,20 +616,30 @@ curl http://localhost:5000/api/v3/display/on-demand/status # Response: { - "active": true, - "plugin_id": "weather", - "mode": "weather", - "remaining": 25.5, - "pinned": false, - "status": "active" + "status": "success", + "data": { + "state": { + "active": true, + "plugin_id": "weather", + "mode": "weather", + "duration": 30, + "pinned": false, + "status": "running", + "last_updated": 1234567890.1 + }, + "service": {"active": true, "returncode": 0, "stdout": "active", "stderr": ""} + } } ``` +When nothing is running on demand, `data.state` is +`{"active": false, "status": "idle", "last_updated": null}`. + > 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). The API handlers > (`start_on_demand_display()` / `stop_on_demand_display()` in -> `web_interface/blueprints/api_v3.py`) write a request into the cache +> `web_interface/blueprints/api_v3/display.py`) write a request into the cache > manager under the `display_on_demand_request` key, which > `DisplayController._poll_on_demand_requests()` > (`src/display_controller.py`) picks up. A separate diff --git a/docs/CONFIG_DEBUGGING.md b/docs/CONFIG_DEBUGGING.md index 2454f755..4adae1fb 100644 --- a/docs/CONFIG_DEBUGGING.md +++ b/docs/CONFIG_DEBUGGING.md @@ -250,14 +250,21 @@ 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`). +The API blueprint (`web_interface/blueprints/api_v3/`) is registered at +`/api/v3` in `web_interface/app.py`. ```bash -# Get full main config (includes all plugin sections) +# Get full main config (includes all plugin sections; credential-named +# fields are blanked in the response) curl http://localhost:5000/api/v3/config/main -# Save updated main config +# Change some settings: only the keys you send are changed curl -X POST http://localhost:5000/api/v3/config/main \ + -H "Content-Type: application/json" \ + -d '{"timezone": "America/Chicago", "brightness": 80}' + +# Replace config.json wholesale (advanced) +curl -X POST http://localhost:5000/api/v3/config/raw/main \ -H "Content-Type: application/json" \ -d @new-config.json @@ -269,8 +276,10 @@ curl "http://localhost:5000/api/v3/plugins/config?plugin_id=football-scoreboard" ``` > There is no dedicated `/config/plugin/` or `/config/validate` -> endpoint — config validation runs server-side automatically when you -> POST to `/config/main` or `/plugins/config`. See +> endpoint. `POST /plugins/config` validates against the plugin's schema +> and rejects an invalid config with `400`; `POST /config/main` checks the +> individual fields it knows (display hardware values, durations, Vegas +> and sync settings). See > [REST_API_REFERENCE.md](REST_API_REFERENCE.md) for the full list. ## Backup and Recovery diff --git a/docs/PLUGIN_ARCHITECTURE_SPEC.md b/docs/PLUGIN_ARCHITECTURE_SPEC.md index 3c8ddb6f..8df78fd9 100644 --- a/docs/PLUGIN_ARCHITECTURE_SPEC.md +++ b/docs/PLUGIN_ARCHITECTURE_SPEC.md @@ -8,7 +8,8 @@ > - 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:199`). +> blueprint (`web_interface/blueprints/api_v3/`) is mounted at `/api/v3` +> in `web_interface/app.py`. > - The default plugin location is `plugin-repos/` (configurable via > `plugin_system.plugins_directory`), not `./plugins/`. > - Example imports use `src/plugin_system/base_classes/*_plugin.py`; diff --git a/docs/PLUGIN_CONFIGURATION_TABS.md b/docs/PLUGIN_CONFIGURATION_TABS.md index ed5de33d..9fcecef4 100644 --- a/docs/PLUGIN_CONFIGURATION_TABS.md +++ b/docs/PLUGIN_CONFIGURATION_TABS.md @@ -6,7 +6,8 @@ > 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/`. +> `web_interface/blueprints/api_v3/` (plugin config handlers in +> `plugins.py`), and `web_interface/templates/v3/`. > The user-facing description (Overview, Features, Form Generation > Process) is still accurate. diff --git a/docs/PLUGIN_QUICK_REFERENCE.md b/docs/PLUGIN_QUICK_REFERENCE.md index 850fbb22..09c54b76 100644 --- a/docs/PLUGIN_QUICK_REFERENCE.md +++ b/docs/PLUGIN_QUICK_REFERENCE.md @@ -127,7 +127,8 @@ git push origin v1.0.0 ### REST API -The API is mounted at `/api/v3` (`web_interface/app.py:199`). +The API is mounted at `/api/v3` (the `api_v3` blueprint in +`web_interface/blueprints/api_v3/`, registered in `web_interface/app.py`). ```bash # Install plugin from the registry diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index fe3a1a74..db5b3cac 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -273,7 +273,7 @@ sudo systemctl cat ledmatrix-web | grep User 1. **Verify file structure:** ```bash ls -l web_interface/app.py - ls -l web_interface/blueprints/api_v3.py + ls -ld web_interface/blueprints/api_v3/ ls -l web_interface/blueprints/pages_v3.py ``` @@ -531,7 +531,7 @@ sudo systemctl cat ledmatrix-web | grep User ```bash # Clear the cache with the helper script - sudo python3 scripts/utils/clear_cache.py + sudo python3 scripts/utils/clear_cache.py --clear-all # Or remove files manually from the cache dir in use, e.g.: sudo rm -rf /var/cache/ledmatrix/* diff --git a/web_interface/README.md b/web_interface/README.md index b6235ded..9dd13376 100644 --- a/web_interface/README.md +++ b/web_interface/README.md @@ -20,7 +20,9 @@ web_interface/ ├── run.sh # Shell runner script ├── requirements.txt # Python dependencies ├── blueprints/ # Flask blueprints -│ ├── api_v3.py # API endpoints +│ ├── api_v3/ # API endpoints (package: config, display, +│ │ # plugins, system, backup, fonts, misc, +│ │ # wifi, starlark) │ └── pages_v3.py # Page routes ├── templates/ # HTML templates │ └── v3/ @@ -75,7 +77,8 @@ The web interface reads configuration from: ## API Documentation -The V3 API is mounted at `/api/v3/` (`app.py:144`). For the complete +The V3 API is the `api_v3` blueprint, registered at `/api/v3/` in +`app.py`. 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: @@ -115,9 +118,9 @@ reference for the most common endpoints: - `POST /api/v3/plugins/store/refresh` - Refresh registry from GitHub ### 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: +SSE stream endpoints are defined directly on the Flask app in `app.py` +(`stream_stats`, `stream_display`, `stream_logs`, followed by their CSRF +exemption and rate-limit hookup), 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