rick/LEDMatrix
1
0
Fork 0
mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-04-29 12:03:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: fix WEB_INTERFACE_GUIDE and WIFI_NETWORK_SETUP

Browse Source 
WEB_INTERFACE_GUIDE.md
- Web UI port: 5050 -> 5000 (4 occurrences)
- Tab list was almost entirely fictional. Documented tabs:
  General Settings, Display Settings, Durations, Sports Configuration,
  Plugin Management, Plugin Store, Font Management. None of these
  exist. Real tabs (verified in web_interface/templates/v3/base.html:
  935-1000): Overview, General, WiFi, Schedule, Display, Config Editor,
  Fonts, Logs, Cache, Operation History, plus Plugin Manager and
  per-plugin tabs in the second nav row. Rewrote the navigation
  section, the General/Display/Plugin sections, and the Common Tasks
  walkthroughs to match.
- Quick Actions list referenced "Test Display" button (doesn't exist).
  Replaced with the real button list verified in
  partials/overview.html:88-152: Start/Stop Display, Restart Display
  Service, Restart Web Service, Update Code, Reboot, Shutdown.
- API endpoints used /api/* paths. The api_v3 blueprint mounts at
  /api/v3 (web_interface/app.py:144), so the real paths are
  /api/v3/config/main, /api/v3/system/status, etc. Fixed.
- Removed bogus "Sports Configuration tab" walkthrough; sports
  favorites live inside each scoreboard plugin's own tab now.
- Plugin directory listed as /plugins/. Real default is plugin-repos/
  (verified in config/config.template.json:130 and
  display_controller.py:132); plugins/ is a fallback.
- Removed "Swipe navigation between tabs" mobile claim (not implemented).

WIFI_NETWORK_SETUP.md
- 21 occurrences of port 5050 -> 5000.
- All /api/wifi/* curl examples used the wrong path. The real wifi
  API routes are at /api/v3/wifi/* (api_v3.py:6367-6609). Fixed.
- ap_password default was documented as "" (empty/open network) but
  config/wifi_config.json ships with "ledmatrix123". Updated the
  Quick Start, Configuration table, AP Mode Settings section, and
  Security Recommendations to match. Also clarified that setting
  ap_password to "" is the way to make it an open network.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Chuck
2026-04-06 21:39:11 -04:00
parent 2a7a318cf7
commit 1d31465df0
2 changed files with 152 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files

258
docs/WEB_INTERFACE_GUIDE.md
View File

@@ -17,7 +17,7 @@ The LEDMatrix web interface provides a complete control panel for managing your
2. Open a web browser and navigate to: 2. Open a web browser and navigate to:
``` ```
http://your-pi-ip:5050 http://your-pi-ip:5000
``` ```
3. The interface will load with the Overview tab displaying system stats and a live display preview. 3. The interface will load with the Overview tab displaying system stats and a live display preview.
@@ -31,17 +31,28 @@ sudo systemctl status ledmatrix-web
## Navigation ## Navigation
The interface uses a tab-based layout for easy navigation between features: The interface uses a two-row tab layout. The system tabs are always
present:
- **Overview** - System stats, quick actions, and display preview - **Overview** — System stats, quick actions, live display preview
- **General Settings** - Timezone, location, and autostart configuration - **General** — Timezone, location, plugin-system settings
- **Display Settings** - Hardware configuration, brightness, and display options - **WiFi** — Network selection and AP-mode setup
- **Durations** - Display rotation timing configuration - **Schedule** — Power and dim schedules
- **Sports Configuration** - Per-league settings and on-demand modes - **Display** — Matrix hardware configuration (rows, cols, hardware
- **Plugin Management** - Install, configure, enable/disable plugins mapping, GPIO slowdown, brightness, PWM)
- **Plugin Store** - Discover and install plugins - **Config Editor** — Raw `config.json` editor with validation
- **Font Management** - Upload fonts, manage overrides, and preview - **Fonts** — Upload and manage fonts
- **Logs** - Real-time log streaming with filtering and search - **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
- **&lt;plugin-id&gt;** — one tab per installed plugin for its own
configuration form (auto-generated from the plugin's
`config_schema.json`)
--- ---
@@ -57,131 +68,84 @@ The Overview tab provides at-a-glance information and quick actions:
- Disk usage - Disk usage
- Network status - Network status
**Quick Actions:** **Quick Actions** (verified in `web_interface/templates/v3/partials/overview.html`):
- **Start/Stop Display** - Control the display service - **Start Display** / **Stop Display** — control the display service
- **Restart Display** - Restart to apply configuration changes - **Restart Display Service** — apply configuration changes
- **Test Display** - Run a quick test pattern - **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:** **Display Preview:**
- Live preview of what's currently shown on the LED matrix - Live preview of what's currently shown on the LED matrix
- Updates in real-time - Updates in real-time
- Useful for remote monitoring - Useful for remote monitoring
### General Settings Tab ### General Tab
Configure basic system settings: Configure basic system settings:
**Timezone:** - **Timezone** — used by all time/date displays
- Set your local timezone for accurate time display - **Location** — city/state/country for weather and other location-aware
- Auto-detects common timezones plugins
- **Plugin System Settings** — including the `plugins_directory` (default
`plugin-repos/`) used by the plugin loader
- **Autostart** options for the display service
**Location:** Click **Save** to write changes to `config/config.json`. Most changes
- Set latitude/longitude for location-based features require a display service restart from **Overview**.
- Used by weather plugins and sunrise/sunset calculations
**Autostart:** ### Display Tab
- 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: Configure your LED matrix hardware:
**Matrix Configuration:** **Matrix configuration:**
- Rows: Number of LED rows (typically 32 or 64) - `rows` — LED rows (typically 32 or 64)
- Columns: Number of LED columns (typically 64, 128, or 256) - `cols` — LED columns (typically 64 or 96)
- Chain Length: Number of chained panels - `chain_length` — number of horizontally chained panels
- Parallel Chains: Number of parallel chains - `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
**Display Options:** Changes require **Restart Display Service** from the Overview tab.
- Brightness: Adjust LED brightness (0-100%)
- Hardware Mapping: GPIO pin mapping
- Slowdown GPIO: Timing adjustment for compatibility
**Save and Apply:** ### Plugin Manager Tab
- Changes require a display restart
- Use "Test Display" to verify configuration
### Durations Tab The Plugin Manager has three main sections:
Control how long each plugin displays: 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.
**Global Settings:** When a plugin is installed and enabled:
- Default Duration: Default time for plugins without specific durations - A new tab for that plugin appears in the second nav row
- Transition Speed: Speed of transitions between plugins - 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 Durations:** ### Per-plugin Configuration Tabs
- Set custom display duration for each plugin
- Override global default for specific plugins
- Measured in seconds
### Sports Configuration Tab 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.
Configure sports-specific settings: 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.
**Per-League Settings:** ### Fonts Tab
- 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: Manage fonts for your display:
@@ -229,37 +193,37 @@ View real-time system logs:
### Changing Display Brightness ### Changing Display Brightness
1. Navigate to the **Display Settings** tab 1. Open the **Display** tab
2. Adjust the **Brightness** slider (0-100%) 2. Adjust the **Brightness** slider (0–100)
3. Click **Save Configuration** 3. Click **Save**
4. Restart the display for changes to take effect 4. Click **Restart Display Service** on the **Overview** tab
### Installing a New Plugin ### Installing a New Plugin
1. Navigate to the **Plugin Store** tab 1. Open the **Plugin Manager** tab
2. Browse or search for the desired plugin 2. Scroll to the **Plugin Store** section and browse or search
3. Click **Install** next to the plugin 3. Click **Install** next to the plugin
4. Wait for installation to complete 4. Toggle the plugin on in **Installed Plugins**
5. Restart the display 5. Click **Restart Display Service** on **Overview**
6. Enable the plugin in the **Plugin Management** tab
### Configuring a Plugin ### Configuring a Plugin
1. Navigate to the **Plugin Management** tab 1. Open the plugin's tab in the second nav row (each installed plugin
2. Find the plugin you want to configure has its own tab)
3. Click the ⚙️ **Configure** button 2. Edit the auto-generated form
4. Edit the settings in the form 3. Click **Save**
5. Click **Save** 4. Restart the display service from **Overview**
6. Restart the display to apply changes
### Setting Favorite Sports Teams ### Setting Favorite Sports Teams
1. Navigate to the **Sports Configuration** tab Sports favorites live in the relevant plugin's tab — there is no
2. Select the league (NHL, NBA, MLB, NFL) separate "Sports Configuration" tab. For example:
3. Choose your favorite teams from the dropdown
4. Enable "Show favorite teams only" if desired 1. Install **Hockey Scoreboard** from **Plugin Manager → Plugin Store**
5. Click **Save Configuration** 2. Open the **Hockey Scoreboard** tab in the second nav row
6. Restart the display 3. Add your favorites under `favorite_teams.<league>` (e.g.
`favorite_teams.nhl`)
4. Click **Save** and restart the display service
### Troubleshooting Display Issues ### Troubleshooting Display Issues
@@ -296,12 +260,10 @@ The interface is fully responsive and works on mobile devices:
- Touch-friendly interface - Touch-friendly interface
- Responsive layout adapts to screen size - Responsive layout adapts to screen size
- All features available on mobile - All features available on mobile
- Swipe navigation between tabs
**Tips for Mobile:** **Tips for Mobile:**
- Use landscape mode for better visibility - Use landscape mode for better visibility
- Pinch to zoom on display preview - Pinch to zoom on display preview
- Long-press for context menus
--- ---
@@ -322,15 +284,21 @@ The web interface is built on a REST API that you can access programmatically:
**API Base URL:** **API Base URL:**
``` ```
http://your-pi-ip:5050/api http://your-pi-ip:5000/api/v3
``` ```
The API blueprint mounts at `/api/v3` (see
`web_interface/app.py:144`). All endpoints below are relative to that
base.
**Common Endpoints:** **Common Endpoints:**
- `GET /api/config/main` - Get configuration - `GET /api/v3/config/main` — Get main configuration
- `POST /api/config/main` - Update configuration - `POST /api/v3/config/main` — Update main configuration
- `GET /api/system/status` - Get system status - `GET /api/v3/system/status` — Get system status
- `POST /api/system/action` - Control display (start/stop/restart) - `POST /api/v3/system/action` — Control display (start/stop/restart, reboot, etc.)
- `GET /api/plugins/installed` - List installed plugins - `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
**Note:** See [REST_API_REFERENCE.md](REST_API_REFERENCE.md) for complete API documentation. **Note:** See [REST_API_REFERENCE.md](REST_API_REFERENCE.md) for complete API documentation.
@@ -353,7 +321,7 @@ http://your-pi-ip:5050/api
sudo systemctl start ledmatrix-web sudo systemctl start ledmatrix-web
``` ```
3. Check that port 5050 is not blocked by firewall 3. Check that port 5000 is not blocked by firewall
4. Verify the Pi's IP address is correct 4. Verify the Pi's IP address is correct
### Changes Not Applying ### Changes Not Applying
@@ -429,7 +397,9 @@ The web interface uses modern web technologies:
- Web service: `sudo journalctl -u ledmatrix-web -f` - Web service: `sudo journalctl -u ledmatrix-web -f`
**Plugins:** **Plugins:**
- Plugin directory: `/plugins/` - Plugin directory: configurable via
`plugin_system.plugins_directory` in `config.json` (default
`plugin-repos/`); the loader also searches `plugins/` as a fallback
- Plugin config: `/config/config.json` (per-plugin sections) - Plugin config: `/config/config.json` (per-plugin sections)
--- ---

71
docs/WIFI_NETWORK_SETUP.md
View File

@@ -21,13 +21,15 @@ The LEDMatrix WiFi system provides automatic network configuration with intellig
**If not connected to WiFi:** **If not connected to WiFi:**
1. Wait 90 seconds after boot (AP mode activation grace period) 1. Wait 90 seconds after boot (AP mode activation grace period)
2. Connect to WiFi network: **LEDMatrix-Setup** (open network) 2. Connect to WiFi network **LEDMatrix-Setup** (default password
3. Open browser to: `http://192.168.4.1:5050` `ledmatrix123` — change it in `config/wifi_config.json` if you want
4. Navigate to the WiFi tab an open network or a different password)
3. Open browser to: `http://192.168.4.1:5000`
4. Open the **WiFi** tab
5. Scan, select your network, and connect 5. Scan, select your network, and connect
**If already connected:** **If already connected:**
1. Open browser to: `http://your-pi-ip:5050` 1. Open browser to: `http://your-pi-ip:5000`
2. Navigate to the WiFi tab 2. Navigate to the WiFi tab
3. Configure as needed 3. Configure as needed
@@ -76,7 +78,7 @@ WiFi settings are stored in `config/wifi_config.json`:
```json ```json
{ {
"ap_ssid": "LEDMatrix-Setup", "ap_ssid": "LEDMatrix-Setup",
"ap_password": "", "ap_password": "ledmatrix123",
"ap_channel": 7, "ap_channel": 7,
"auto_enable_ap_mode": true, "auto_enable_ap_mode": true,
"saved_networks": [ "saved_networks": [
@@ -93,10 +95,10 @@ WiFi settings are stored in `config/wifi_config.json`:
| Setting | Default | Description | | Setting | Default | Description |
|---------|---------|-------------| |---------|---------|-------------|
| `ap_ssid` | `LEDMatrix-Setup` | Network name for AP mode | | `ap_ssid` | `LEDMatrix-Setup` | Network name broadcast in AP mode |
| `ap_password` | `` (empty) | AP password (empty = open network) | | `ap_password` | `ledmatrix123` | AP password. Set to `""` to make the network open (no password). |
| `ap_channel` | `7` | WiFi channel (use 1, 6, or 11 for non-overlapping) | | `ap_channel` | `7` | WiFi channel (1, 6, or 11 are non-overlapping) |
| `auto_enable_ap_mode` | `true` | Automatically enable AP mode when disconnected | | `auto_enable_ap_mode` | `true` | Automatically enable AP mode when both WiFi and Ethernet are disconnected |
| `saved_networks` | `[]` | Array of saved WiFi credentials | | `saved_networks` | `[]` | Array of saved WiFi credentials |
### Auto-Enable AP Mode Behavior ### Auto-Enable AP Mode Behavior
@@ -130,10 +132,10 @@ WiFi settings are stored in `config/wifi_config.json`:
**Via API:** **Via API:**
```bash ```bash
# Scan for networks # Scan for networks
curl "http://your-pi-ip:5050/api/wifi/scan" curl "http://your-pi-ip:5000/api/v3/wifi/scan"
# Connect to network # Connect to network
curl -X POST http://your-pi-ip:5050/api/wifi/connect \ curl -X POST http://your-pi-ip:5000/api/v3/wifi/connect \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"ssid": "YourNetwork", "password": "your-password"}' -d '{"ssid": "YourNetwork", "password": "your-password"}'
``` ```
@@ -147,10 +149,10 @@ curl -X POST http://your-pi-ip:5050/api/wifi/connect \
**Via API:** **Via API:**
```bash ```bash
# Enable AP mode # Enable AP mode
curl -X POST http://your-pi-ip:5050/api/wifi/ap/enable curl -X POST http://your-pi-ip:5000/api/v3/wifi/ap/enable
# Disable AP mode # Disable AP mode
curl -X POST http://your-pi-ip:5050/api/wifi/ap/disable curl -X POST http://your-pi-ip:5000/api/v3/wifi/ap/disable
``` ```
**Note:** Manual enable still requires both WiFi and Ethernet to be disconnected. **Note:** Manual enable still requires both WiFi and Ethernet to be disconnected.
@@ -211,16 +213,17 @@ The system checks connections in this order:
### AP Mode Settings ### AP Mode Settings
- **SSID**: LEDMatrix-Setup (configurable) - **SSID**: `LEDMatrix-Setup` (configurable via `ap_ssid`)
- **Network**: Open (no password by default) - **Network**: WPA2, default password `ledmatrix123` (configurable via
`ap_password` — set to `""` for an open network)
- **IP Address**: 192.168.4.1 - **IP Address**: 192.168.4.1
- **DHCP Range**: 192.168.4.2 - 192.168.4.20 - **DHCP Range**: 192.168.4.2 – 192.168.4.20
- **Channel**: 7 (configurable) - **Channel**: 7 (configurable via `ap_channel`)
### Accessing Services in AP Mode ### Accessing Services in AP Mode
When AP mode is active: When AP mode is active:
- Web Interface: `http://192.168.4.1:5050` - Web Interface: `http://192.168.4.1:5000`
- SSH: `ssh ledpi@192.168.4.1` - SSH: `ssh ledpi@192.168.4.1`
- Captive portal may automatically redirect browsers - Captive portal may automatically redirect browsers
@@ -237,7 +240,9 @@ When AP mode is active:
} }
``` ```
**Note:** The default is an open network for easy initial setup. For deployments in public areas, consider adding a password. **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.
**2. Use Non-Overlapping WiFi Channels:** **2. Use Non-Overlapping WiFi Channels:**
- Channels 1, 6, 11 are non-overlapping (2.4GHz) - Channels 1, 6, 11 are non-overlapping (2.4GHz)
@@ -398,7 +403,7 @@ Interface should exist
**Check 4: Try Manual Enable** **Check 4: Try Manual Enable**
- Use web interface: WiFi tab → Enable AP Mode - Use web interface: WiFi tab → Enable AP Mode
- Or via API: `curl -X POST http://localhost:5050/api/wifi/ap/enable` - Or via API: `curl -X POST http://localhost:5000/api/v3/wifi/ap/enable`
### Cannot Connect to WiFi Network ### Cannot Connect to WiFi Network
@@ -551,36 +556,36 @@ The WiFi setup feature exposes the following API endpoints:
| Method | Endpoint | Description | | Method | Endpoint | Description |
|--------|----------|-------------| |--------|----------|-------------|
| GET | `/api/wifi/status` | Get current WiFi connection status | | GET | `/api/v3/wifi/status` | Get current WiFi connection status |
| GET | `/api/wifi/scan` | Scan for available WiFi networks | | GET | `/api/v3/wifi/scan` | Scan for available WiFi networks |
| POST | `/api/wifi/connect` | Connect to a WiFi network | | POST | `/api/v3/wifi/connect` | Connect to a WiFi network |
| POST | `/api/wifi/ap/enable` | Enable access point mode | | POST | `/api/v3/wifi/ap/enable` | Enable access point mode |
| POST | `/api/wifi/ap/disable` | Disable access point mode | | POST | `/api/v3/wifi/ap/disable` | Disable access point mode |
| GET | `/api/wifi/ap/auto-enable` | Get auto-enable setting | | GET | `/api/v3/wifi/ap/auto-enable` | Get auto-enable setting |
| POST | `/api/wifi/ap/auto-enable` | Set auto-enable setting | | POST | `/api/v3/wifi/ap/auto-enable` | Set auto-enable setting |
### Example Usage ### Example Usage
```bash ```bash
# Get WiFi status # Get WiFi status
curl "http://your-pi-ip:5050/api/wifi/status" curl "http://your-pi-ip:5000/api/v3/wifi/status"
# Scan for networks # Scan for networks
curl "http://your-pi-ip:5050/api/wifi/scan" curl "http://your-pi-ip:5000/api/v3/wifi/scan"
# Connect to network # Connect to network
curl -X POST http://your-pi-ip:5050/api/wifi/connect \ curl -X POST http://your-pi-ip:5000/api/v3/wifi/connect \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"ssid": "MyNetwork", "password": "mypassword"}' -d '{"ssid": "MyNetwork", "password": "mypassword"}'
# Enable AP mode # Enable AP mode
curl -X POST http://your-pi-ip:5050/api/wifi/ap/enable curl -X POST http://your-pi-ip:5000/api/v3/wifi/ap/enable
# Check auto-enable setting # Check auto-enable setting
curl "http://your-pi-ip:5050/api/wifi/ap/auto-enable" curl "http://your-pi-ip:5000/api/v3/wifi/ap/auto-enable"
# Set auto-enable # Set auto-enable
curl -X POST http://your-pi-ip:5050/api/wifi/ap/auto-enable \ curl -X POST http://your-pi-ip:5000/api/v3/wifi/ap/auto-enable \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"auto_enable_ap_mode": true}' -d '{"auto_enable_ap_mode": true}'
``` ```