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

Docs/consolidate documentation (#217)

Browse Source 
* docs: rename FONT_MANAGER_USAGE.md to FONT_MANAGER.md

Renamed for clearer naming convention.
Part of documentation consolidation effort.

* docs: consolidate Plugin Store guides (2→1)

Merged:
- PLUGIN_STORE_USER_GUIDE.md
- PLUGIN_STORE_QUICK_REFERENCE.md

Into: PLUGIN_STORE_GUIDE.md

- Unified writing style to professional technical
- Added Quick Reference section at top for easy access
- Removed duplicate content
- Added cross-references to related documentation
- Updated formatting to match style guidelines

* docs: create user-focused Web Interface Guide

Created WEB_INTERFACE_GUIDE.md consolidating:
- V3_INTERFACE_README.md (technical details)
- User-facing interface documentation

- Focused on end-user tasks and navigation
- Removed technical implementation details
- Added common tasks section
- Included troubleshooting
- Professional technical writing style

* docs: consolidate WiFi setup guides (4→1)

Merged:
- WIFI_SETUP.md
- OPTIMAL_WIFI_AP_FAILOVER_SETUP.md
- AP_MODE_MANUAL_ENABLE.md
- WIFI_ETHERNET_AP_MODE_FIX.md (behavior documentation)

Into: WIFI_NETWORK_SETUP.md

- Comprehensive coverage of WiFi setup and configuration
- Clear explanation of AP mode failover and grace period
- Configuration scenarios and best practices
- Troubleshooting section combining all sources
- Professional technical writing style
- Added quick reference table for behavior

* docs: consolidate troubleshooting guides (4→1)

Merged:
- TROUBLESHOOTING_QUICK_START.md
- WEB_INTERFACE_TROUBLESHOOTING.md
- CAPTIVE_PORTAL_TROUBLESHOOTING.md
- WEATHER_TROUBLESHOOTING.md

Into: TROUBLESHOOTING.md

- Organized by issue category (web, WiFi, plugins)
- Comprehensive diagnostic commands reference
- Quick diagnosis steps at the top
- Service file template preserved
- Complete diagnostic script included
- Professional technical writing style

* docs: create consolidated Advanced Features guide

Merged:
- VEGAS_SCROLL_MODE.md
- ON_DEMAND_DISPLAY_QUICK_START.md
- ON_DEMAND_DISPLAY_API.md
- ON_DEMAND_CACHE_MANAGEMENT.md
- BACKGROUND_SERVICE_README.md
- PERMISSION_MANAGEMENT_GUIDE.md

Into: ADVANCED_FEATURES.md

- Comprehensive guide covering all advanced features
- Vegas scroll mode with integration examples
- On-demand display with API reference
- Cache management troubleshooting
- Background service documentation
- Permission management patterns
- Professional technical writing style

* docs: create Getting Started guide for first-time users

Created GETTING_STARTED.md:
- Quick start guide (5 minutes)
- Initial configuration walkthrough
- Common first-time issues and solutions
- Next steps and quick reference
- User-friendly tone for beginners
- Links to detailed documentation

* docs: archive consolidated source files and ephemeral docs

Archived files that have been consolidated:
- Plugin Store guides (2 files → PLUGIN_STORE_GUIDE.md)
- Web Interface guide (V3_INTERFACE_README.md → WEB_INTERFACE_GUIDE.md)
- WiFi Setup guides (4 files → WIFI_NETWORK_SETUP.md)
- Troubleshooting guides (4 files → TROUBLESHOOTING.md)
- Advanced Features (6 files → ADVANCED_FEATURES.md)

Archived ephemeral/debug documentation:
- DEBUG_WEB_ISSUE.md
- BROWSER_ERRORS_EXPLANATION.md
- FORM_VALIDATION_FIXES.md
- WEB_UI_RELIABILITY_IMPROVEMENTS.md
- CAPTIVE_PORTAL_TESTING.md
- NEXT_STEPS_COMMANDS.md
- STATIC_IMAGE_MULTI_UPLOAD_PLAN.md
- RECONNECT_AFTER_CAPTIVE_PORTAL_TESTING.md

Archived implementation summaries:
- PLUGIN_CONFIG_TABS_SUMMARY.md
- PLUGIN_CONFIG_SYSTEM_VERIFICATION.md
- PLUGIN_SCHEMA_AUDIT_SUMMARY.md
- STARTUP_OPTIMIZATION_SUMMARY.md
- PLUGIN_DISPATCH_IMPLEMENTATION.md
- NESTED_SCHEMA_IMPLEMENTATION.md
- AP_MODE_MANUAL_ENABLE_CHANGES.md
- PLUGIN_CONFIG_SYSTEM_EXPLANATION.md

Total archived: 27 files
Preserves git history while cleaning up main docs directory

* docs: rename API_REFERENCE.md to REST_API_REFERENCE.md

Renamed for clarity - this is specifically the REST API reference
for the web interface, not a general API reference.

* docs: update README.md to reflect consolidated documentation structure

Updated documentation index:
- Reflects new consolidated guides (51 → 16-17 files)
- Updated Quick Start sections with new file names
- Added consolidation history (January 2026)
- Updated file references (API_REFERENCE → REST_API_REFERENCE)
- Documented archival of 33 files
- Added benefits of consolidation
- Updated statistics and highlights
- Removed outdated references
- Professional writing style maintained throughout

* docs: add Vegas scroll mode system architecture documentation

Added comprehensive internal architecture section for Vegas mode:
- Component overview with diagram
- VegasModeCoordinator responsibilities and main loop
- StreamManager buffering strategy and content flow
- PluginAdapter integration and fallback behavior
- RenderPipeline 125 FPS rendering process
- Component interaction flows
- Thread safety patterns
- Performance characteristics

Covers:
- How the four components work together
- Initialization and render loop flows
- Config update handling
- Frame rate management and optimization
- Memory usage and CPU characteristics

---------

Co-authored-by: Chuck <chuck@example.com>
This commit is contained in:
Chuck
2026-01-29 10:32:00 -05:00
committed by GitHub
parent 7524747e44
commit ddd300a117
42 changed files with 3954 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

442
docs/WEB_INTERFACE_GUIDE.md Normal file
View File

@@ -0,0 +1,442 @@
# 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:5050
```
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 tab-based layout for easy navigation between features:
- **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
---
## 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:**
- **Start/Stop Display** - Control the display service
- **Restart Display** - Restart to apply configuration changes
- **Test Display** - Run a quick test pattern
**Display Preview:**
- Live preview of what's currently shown on the LED matrix
- Updates in real-time
- Useful for remote monitoring
### General Settings Tab
Configure basic system settings:
**Timezone:**
- Set your local timezone for accurate time display
- Auto-detects common timezones
**Location:**
- Set latitude/longitude for location-based features
- Used by weather plugins and sunrise/sunset calculations
**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
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
**Display Options:**
- Brightness: Adjust LED brightness (0-100%)
- Hardware Mapping: GPIO pin mapping
- Slowdown GPIO: Timing adjustment for compatibility
**Save and Apply:**
- Changes require a display restart
- Use "Test Display" to verify configuration
### Durations Tab
Control how long each plugin displays:
**Global Settings:**
- Default Duration: Default time for plugins without specific durations
- Transition Speed: Speed of transitions between plugins
**Per-Plugin Durations:**
- Set custom display duration for each plugin
- Override global default for specific plugins
- Measured in seconds
### Sports Configuration Tab
Configure sports-specific settings:
**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
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
**Plugin Font Overrides:**
- Set custom fonts for specific plugins
- Override default font choices
- Preview font changes
**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:**
- **Clear**: Clear the current view
- **Download**: Download logs for offline analysis
- **Pause**: Pause auto-scrolling
---
## Common Tasks
### 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
### Installing a New Plugin
1. Navigate to the **Plugin Store** tab
2. Browse or search for the desired plugin
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
### 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
### 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
### 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
- Progressive enhancement - works without JavaScript
---
## 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
- Swipe navigation between tabs
**Tips for Mobile:**
- Use landscape mode for better visibility
- Pinch to zoom on display preview
- Long-press for context menus
---
## Keyboard Shortcuts
Use keyboard shortcuts for faster navigation:
- **Tab**: Navigate between form fields
- **Enter**: Submit forms
- **Esc**: Close modals
- **Ctrl+F**: Search in logs
---
## API Access
The web interface is built on a REST API that you can access programmatically:
**API Base URL:**
```
http://your-pi-ip:5050/api
```
**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
**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 5050 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:**
- The interface is accessible to anyone on your local network
- No authentication is currently implemented
- Recommended for trusted networks only
**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:**
- 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: `/plugins/`
- 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