rick/LEDMatrix
1
0
Fork 0
mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-04-10 21:03:01 +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:
```
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.
@@ -31,17 +31,28 @@ sudo systemctl status ledmatrix-web
## 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
- **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
- **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
- **&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
- Network status
**Quick Actions:**
- **Start/Stop Display** - Control the display service
- **Restart Display** - Restart to apply configuration changes
- **Test Display** - Run a quick test pattern
**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 Settings Tab
### General Tab
Configure basic system settings:
**Timezone:**
- Set your local timezone for accurate time display
- Auto-detects common timezones
- **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
**Location:**
- Set latitude/longitude for location-based features
- Used by weather plugins and sunrise/sunset calculations
Click **Save** to write changes to `config/config.json`. Most changes
require a display service restart from **Overview**.
**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
### Display Tab
Configure your LED matrix hardware:
**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
**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
**Display Options:**
- Brightness: Adjust LED brightness (0-100%)
- Hardware Mapping: GPIO pin mapping
- Slowdown GPIO: Timing adjustment for compatibility
Changes require **Restart Display Service** from the Overview tab.
**Save and Apply:**
- Changes require a display restart
- Use "Test Display" to verify configuration
### Plugin Manager Tab
### 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:**
- Default Duration: Default time for plugins without specific durations
- Transition Speed: Speed of transitions between plugins
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 Durations:**
- Set custom display duration for each plugin
- Override global default for specific plugins
- Measured in seconds
### Per-plugin Configuration Tabs
### 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:**
- 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
### Fonts Tab
Manage fonts for your display:
@@ -229,37 +193,37 @@ View real-time system logs:
### Changing Display Brightness
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
1. Open the **Display** tab
2. Adjust the **Brightness** slider (0–100)
3. Click **Save**
4. Click **Restart Display Service** on the **Overview** tab
### Installing a New Plugin
1. Navigate to the **Plugin Store** tab
2. Browse or search for the desired 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. Wait for installation to complete
5. Restart the display
6. Enable the plugin in the **Plugin Management** tab
4. Toggle the plugin on in **Installed Plugins**
5. Click **Restart Display Service** on **Overview**
### Configuring a Plugin
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
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
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
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
@@ -296,12 +260,10 @@ 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
---
@@ -322,15 +284,21 @@ The web interface is built on a REST API that you can access programmatically:
**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:**
- `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
- `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
**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
```
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
### Changes Not Applying
@@ -429,7 +397,9 @@ The web interface uses modern web technologies:
- Web service: `sudo journalctl -u ledmatrix-web -f`
**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)
---

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:**
1. Wait 90 seconds after boot (AP mode activation grace period)
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
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
5. Scan, select your network, and connect
**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
3. Configure as needed
@@ -76,7 +78,7 @@ WiFi settings are stored in `config/wifi_config.json`:
```json
{
"ap_ssid": "LEDMatrix-Setup",
"ap_password": "",
"ap_password": "ledmatrix123",
"ap_channel": 7,
"auto_enable_ap_mode": true,
"saved_networks": [
@@ -93,10 +95,10 @@ WiFi settings are stored in `config/wifi_config.json`:
| Setting | Default | Description |
|---------|---------|-------------|
| `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 |
| `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 |
| `saved_networks` | `[]` | Array of saved WiFi credentials |
### Auto-Enable AP Mode Behavior
@@ -130,10 +132,10 @@ WiFi settings are stored in `config/wifi_config.json`:
**Via API:**
```bash
# 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
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" \
-d '{"ssid": "YourNetwork", "password": "your-password"}'
```
@@ -147,10 +149,10 @@ curl -X POST http://your-pi-ip:5050/api/wifi/connect \
**Via API:**
```bash
# 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
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.
@@ -211,16 +213,17 @@ The system checks connections in this order:
### AP Mode Settings
- **SSID**: LEDMatrix-Setup (configurable)
- **Network**: Open (no password by default)
- **SSID**: `LEDMatrix-Setup` (configurable via `ap_ssid`)
- **Network**: WPA2, default password `ledmatrix123` (configurable via
`ap_password` — set to `""` for an open network)
- **IP Address**: 192.168.4.1
- **DHCP Range**: 192.168.4.2 - 192.168.4.20
- **Channel**: 7 (configurable)
- **DHCP Range**: 192.168.4.2 – 192.168.4.20
- **Channel**: 7 (configurable via `ap_channel`)
### Accessing Services in AP Mode
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`
- 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:**
- Channels 1, 6, 11 are non-overlapping (2.4GHz)
@@ -398,7 +403,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:5050/api/wifi/ap/enable`
- Or via API: `curl -X POST http://localhost:5000/api/v3/wifi/ap/enable`
### Cannot Connect to WiFi Network
@@ -551,36 +556,36 @@ The WiFi setup feature exposes the following API endpoints:
| Method | Endpoint | Description |
|--------|----------|-------------|
| 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 |
| 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 |
### Example Usage
```bash
# 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
curl "http://your-pi-ip:5050/api/wifi/scan"
curl "http://your-pi-ip:5000/api/v3/wifi/scan"
# 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" \
-d '{"ssid": "MyNetwork", "password": "mypassword"}'
# 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
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
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" \
-d '{"auto_enable_ap_mode": true}'
```