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:
   ```bash
   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:
```bash
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:

```bash
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](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](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):

```bash
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](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:
   ```bash
   sudo systemctl status ledmatrix-web
   ```

2. Start the service if stopped:
   ```bash
   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:
   ```bash
   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`:
   ```bash
   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](#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](PLUGIN_STORE_GUIDE.md) - Installing and managing plugins
- [REST_API_REFERENCE.md](REST_API_REFERENCE.md) - Complete REST API documentation
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Troubleshooting common issues
- [FONT_MANAGER.md](FONT_MANAGER.md) - Font management details