LEDMatrix/docs/WEB_INTERFACE_GUIDE.md

Web Interface Guide

Overview

The LEDMatrix web interface provides a complete control panel for managing your LED matrix display. Access all features through a modern, responsive web interface that works on desktop, tablet, and mobile devices.

---

Quick Start

Accessing the Interface

1. Find your Raspberry Pi's IP address:

   hostname -I
   

2. Open a web browser and navigate to:

   http://your-pi-ip:5000
   

3. The interface will load with the Overview tab displaying system stats and a live display preview.

Note: If the interface doesn't load, verify the web service is running:

sudo systemctl status ledmatrix-web

---

Navigation

The interface uses a two-row tab layout. The system tabs are always present:

• 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) and Vegas Scroll Mode settings
• Rotation — drag-and-drop Rotation Order list and per-plugin Screen Durations
• Config Editor — Raw config.json editor with validation
• Backup & Restore — back up and restore your configuration
• Fonts — Upload and manage fonts
• Logs — Real-time log streaming
• Cache — Cached data inspection and cleanup
• Operation History — Recent service operations
• Tools — system diagnostics, git & updates, Python dependencies, maintenance, power supply, network radio, services, and plugin health

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)

---

Features and Usage

Overview Tab

The Overview tab provides at-a-glance information and quick actions:

System Stats:

• CPU usage and temperature
• Memory usage
• 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

Display Preview:

• Live preview of what's currently shown on the LED matrix
• Updates in real-time
• Useful for remote monitoring

General 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
• Web Display Autostart — whether the web interface service starts with the system (web_display_autostart)
• Automatic updates — once a week, update LEDMatrix and every installed plugin with a newer version. Off by default. Runs 2–5 AM local time when possible, otherwise within a day of being due. The last result and next check are shown under the toggle, and anything other than success raises a banner on Overview.
  • Checks first: the code update is skipped, with the reason shown, if tracked files were edited locally (permission-only changes and edits under plugins/ or plugin-repos/ don't count; the pull carries those across and puts them back), the checkout has local commits, a rebase/merge is in progress, the branch has no upstream, less than 300 MB is free, or the newest version already failed once. A failed fetch is retried the next day.
  • Health check and rollback: after pulling, ledmatrix-update-verify.service restarts the services and checks that the web interface responds and the display (if it was running) stays up. If not — or if the new dependencies failed to install — it resets to the previous commit, reinstalls the previous dependencies and restarts again. A running display is restarted; a stopped one stays stopped.
  • Plugins update through the Plugin Store, which refuses versions that need a newer LEDMatrix and restores the old copy when an install fails. When the code changed, plugins wait until it passes its health check. Plugins are not health-checked after updating.
  • Setup needs no SSH. Turning the toggle on restarts the display service, which installs the health check (ledmatrix-update-verify.path and .service); the General tab shows when it is ready, or why setup failed. Until then only plugins update. New installs set it up during installation and can switch updates on with first_time_install.sh --enable-auto-update (or LEDMATRIX_AUTO_UPDATE=1, which one-shot-install.sh passes through), or at the installer's prompt.

Click Save to write changes to config/config.json. Most changes require a display service restart from Overview.

Below the settings, the Security section (its own buttons, not the Save button) controls the optional login:

• Web interface password — off by default. Setting one turns login on: browsers on your network then see a login page, and stay logged in for 30 days (across restarts). The browser you set it from stays logged in. Changing the password logs every other browser out. Turn login off needs the current password. A Log out button appears in the header while you are logged in. Five wrong passwords in a minute (or 30 in an hour) from one address make it wait.
• API tokens — for Home Assistant, scripts, or the MQTT bridge on another machine. Give it a name, click Create token, and copy the token right away: it is shown once. Revoke it here when it is no longer needed.
• Never asked for a password: a browser on the Pi itself, and the Wi-Fi setup page while the Pi is in access-point mode (so you can always get it back on a network).

Forgot the password? SSH into the Pi and run:

sudo python3 ~/LEDMatrix/scripts/reset_web_password.py

(use the folder LEDMatrix is installed in). Login is off again right away, no restart needed, and you can set a new password. API tokens are kept; add --revoke-tokens to delete them too. Alternatively, open http://localhost:5000 in a browser on the Pi itself.

Display Tab

Configure your LED matrix hardware:

Matrix configuration:

• rows — LED rows per panel (typically 32 or 64; even, at least 8 — the current rgbmatrix library rejects more than 64)
• cols — LED columns per panel (typically 64 or 96; at least 16)
• chain_length — number of horizontally chained panels
• parallel — number of parallel chains (1–3)
• hardware_mapping — adafruit-hat-pwm (with PWM jumper mod), adafruit-hat (without), regular (direct wiring, and the Adafruit Triple LED Matrix Bonnet), or regular-pi1
• gpio_slowdown — depends on your Pi and panel (roughly 1–3 on a Pi 3, 2–4 on a Pi 4); raise it if rows jump or the image is garbage
• brightness — 1–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

The collapsed Advanced Hardware & Display Options section holds multiplexing, panel type, row address type, scan mode, PWM tuning, the refresh-rate cap and hardware pulsing. Every field has a help tip, and the README's Display Settings section describes each one with its allowed range.

Vegas Scroll Mode: the Display tab also has a full Vegas Scroll Mode section — enable toggle, scroll speed, separator width, dynamic duration, and related settings — so you can configure Vegas mode entirely from the web UI without hand-editing JSON. See ADVANCED_FEATURES.md for what the options do.

Brightness and the Vegas Scroll settings apply to the running display within a few seconds. Matrix hardware settings (rows, columns, chain length, mapping, GPIO slowdown, PWM and refresh settings) are only read when the display starts, so those need Restart Display Service from the Overview tab.

Plugin Manager Tab

The Plugin Manager has three main sections:

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.

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

Per-plugin Configuration Tabs

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.

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.

Fonts Tab

Manage fonts for your display:

Upload Fonts:

• Drag and drop font files (.ttf, .otf, .bdf)
• Upload multiple files at once
• Progress indicator shows upload status

Font Catalog:

• View all available fonts
• See font previews
• Check font sizes and styles

Font Preview:

• Render sample text in any TTF/OTF font at a chosen size

Fonts used by a plugin are chosen in that plugin's own settings tab; the Fonts tab has no per-element override editor.

Delete Fonts:

• Remove unused fonts
• Free up disk space

Logs Tab

View real-time system logs:

Log Viewer:

• Streaming logs from the display service
• Auto-scroll to latest entries
• Timestamps for each log entry

Filtering:

• Filter by log level (INFO, WARNING, ERROR)
• Search for specific text
• Filter by plugin or component

Actions:

• Refresh: Reload the log view
• Clear: Clear the current view
• Download: Download logs for offline analysis
• Auto-scroll checkbox: toggle automatic scrolling to the latest entries

---

Common Tasks

Changing Display Brightness

1. Open the Display tab
2. Adjust the Brightness slider (1–100)
3. Click Save. The panel picks up the new brightness within a few seconds; no restart is needed

Installing a New Plugin

1. Open the Plugin Manager tab
2. Scroll to the Plugin Store section and browse or search
3. Click Install next to the plugin
4. Toggle the plugin on in Installed Plugins. The running display loads it within a few seconds; no restart is needed

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

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

Troubleshooting Display Issues

1. Navigate to the Logs tab
2. Look for ERROR or WARNING messages
3. Filter by the problematic plugin or component
4. Check the error message for clues
5. See TROUBLESHOOTING.md for common solutions

---

Real-Time Features

The web interface uses Server-Sent Events (SSE) for real-time updates:

Live Updates:

• System stats refresh automatically every few seconds
• Display preview updates in real-time
• Logs stream continuously
• No page refresh required

Performance:

• Minimal bandwidth usage
• Server-side rendering for fast load times
• The UI is built on Alpine.js and HTMX, so JavaScript must be enabled in the browser

---

Mobile Access

The interface is fully responsive and works on mobile devices:

Mobile Features:

• Touch-friendly interface
• Responsive layout adapts to screen size
• All features available on mobile

Tips for Mobile:

• Use landscape mode for better visibility
• Pinch to zoom on display preview

---

API Access

The web interface is built on a REST API that you can access programmatically:

API Base URL:

http://your-pi-ip:5000/api/v3

The API blueprint (web_interface/blueprints/api_v3/) is registered at /api/v3 in web_interface/app.py.

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

If the optional login is on, send an API token (General > Security):

curl -H "Authorization: Bearer lmx_..." http://your-pi-ip:5000/api/v3/display/current

Scripts running on the Pi itself need no token.

Note: See REST_API_REFERENCE.md for complete API documentation.

---

Troubleshooting

Interface Won't Load

Problem: Browser shows "Unable to connect" or "Connection refused"

Solutions:

1. Verify the web service is running:

   sudo systemctl status ledmatrix-web
   

2. Start the service if stopped:

   sudo systemctl start ledmatrix-web
   

3. Check that port 5000 is not blocked by firewall

4. Verify the Pi's IP address is correct

Changes Not Applying

Problem: Configuration changes don't take effect

Solutions:

1. Ensure you clicked "Save Configuration"
2. Restart the display service for changes to apply:

   sudo systemctl restart ledmatrix
   

3. Check logs for error messages

Display Preview Not Updating

Problem: Display preview shows old content or doesn't update

Solutions:

1. Refresh the browser page (F5)
2. Check that the display service is running
3. Verify SSE streams are working (check browser console)

Plugin Configuration Not Saving

Problem: Plugin settings revert after restart

Solutions:

1. Check file permissions on config/config.json:

   ls -l config/config.json
   

2. Ensure the web service has write permissions
3. Check logs for permission errors

---

Security Considerations

Network Access:

• By default the interface is accessible to anyone on your local network
• An optional password (General > Security) makes every page and API call need a login or an API token; see General Tab. Requests from the Pi itself and the Wi-Fi setup flow in access-point mode stay open, and /api/v3/health answers only its overall status without a login
• The interface speaks plain HTTP, so the password and tokens cross your network unencrypted: still recommended for trusted networks only
• Behind a reverse proxy on the Pi, make it send X-Forwarded-For (nginx: proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;). Without it every proxied request looks like it comes from the Pi itself, which is never asked to log in

Other websites:

• A web page you open elsewhere could otherwise make your browser send commands to the Pi (reboot, update, config changes). The interface refuses any change request whose Origin/Referer header names a different site (403 CROSS_SITE_REQUEST), so use the interface from its own address.
• Scripts, curl, Home Assistant and the MQTT bridge send no such header and keep working. Behind a reverse proxy, forward the original Host header with its port (nginx: proxy_set_header Host $http_host; -- $host drops the port).

Best Practices:

1. Run on a private network (not exposed to internet)
2. Use a firewall to restrict access if needed
3. Consider VPN access for remote control
4. Keep the system updated

---

Technical Details

Architecture

The web interface uses modern web technologies:

• Backend: Flask with Blueprint-based modular design
• Frontend: HTMX for dynamic content, Alpine.js for reactive components
• Styling: Tailwind CSS for responsive design
• Real-Time: Server-Sent Events (SSE) for live updates

File Locations

Configuration (relative to the LEDMatrix folder, e.g. ~/LEDMatrix):

• Main config: config/config.json
• Secrets: config/config_secrets.json
• WiFi config: config/wifi_config.json

Logs:

• Display service: sudo journalctl -u ledmatrix -f
• 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 config: config/config.json (per-plugin sections)

---

Related Documentation

• PLUGIN_STORE_GUIDE.md - Installing and managing plugins
• REST_API_REFERENCE.md - Complete REST API documentation
• TROUBLESHOOTING.md - Troubleshooting common issues
• FONT_MANAGER.md - Font management details