mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-04-13 14:03:00 +00:00
Docs/consolidate documentation (#217)
* 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
314
docs/archive/WEB_INTERFACE_TROUBLESHOOTING.md
Normal file
314
docs/archive/WEB_INTERFACE_TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,314 @@
|
||||
# Web Interface Troubleshooting Guide
|
||||
|
||||
## Quick Diagnosis Steps
|
||||
|
||||
Since the web interface doesn't seem to run and shows no logging after reorganization, follow these steps **on your Raspberry Pi** to diagnose the issue:
|
||||
|
||||
### 1. Check Service Status
|
||||
|
||||
```bash
|
||||
# Check if the web service is running
|
||||
sudo systemctl status ledmatrix-web
|
||||
|
||||
# Check if it's enabled to start on boot
|
||||
sudo systemctl is-enabled ledmatrix-web
|
||||
```
|
||||
|
||||
### 2. View Service Logs
|
||||
|
||||
The service logs to **syslog**, not stdout. Use these commands to view logs:
|
||||
|
||||
```bash
|
||||
# View recent web interface logs
|
||||
sudo journalctl -u ledmatrix-web -n 50 --no-pager
|
||||
|
||||
# Follow logs in real-time
|
||||
sudo journalctl -u ledmatrix-web -f
|
||||
|
||||
# View logs since last boot
|
||||
sudo journalctl -u ledmatrix-web -b
|
||||
```
|
||||
|
||||
### 3. Check Configuration
|
||||
|
||||
```bash
|
||||
# Check if web_display_autostart is enabled in config
|
||||
cat ~/LEDMatrix/config/config.json | grep web_display_autostart
|
||||
|
||||
# Should show: "web_display_autostart": true
|
||||
```
|
||||
|
||||
If it shows `false` or is missing, the web interface won't start (by design).
|
||||
|
||||
### 4. Test Manual Startup
|
||||
|
||||
Try starting the web interface manually to see error messages:
|
||||
|
||||
```bash
|
||||
cd ~/LEDMatrix
|
||||
python3 web_interface/start.py
|
||||
```
|
||||
|
||||
This will show any import errors or startup issues directly in the terminal.
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Issue 1: Service Not Running
|
||||
|
||||
**Symptom:** `systemctl status ledmatrix-web` shows "inactive (dead)"
|
||||
|
||||
**Solutions:**
|
||||
```bash
|
||||
# Start the service
|
||||
sudo systemctl start ledmatrix-web
|
||||
|
||||
# Enable it to start on boot
|
||||
sudo systemctl enable ledmatrix-web
|
||||
|
||||
# Check status again
|
||||
sudo systemctl status ledmatrix-web
|
||||
```
|
||||
|
||||
### Issue 2: web_display_autostart is False
|
||||
|
||||
**Symptom:** Service starts but immediately exits gracefully
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Edit config.json
|
||||
nano ~/LEDMatrix/config/config.json
|
||||
|
||||
# Set web_display_autostart to true:
|
||||
"web_display_autostart": true
|
||||
|
||||
# Restart the service
|
||||
sudo systemctl restart ledmatrix-web
|
||||
```
|
||||
|
||||
### Issue 3: Import Errors
|
||||
|
||||
**Symptom:** Service fails immediately with import errors in logs
|
||||
|
||||
**Possible causes:**
|
||||
- Missing dependencies
|
||||
- Python path issues
|
||||
- Circular import problems
|
||||
|
||||
**Solutions:**
|
||||
|
||||
```bash
|
||||
# Install/reinstall web dependencies
|
||||
cd ~/LEDMatrix
|
||||
pip3 install --break-system-packages -r web_interface/requirements.txt
|
||||
|
||||
# Check for Python errors
|
||||
python3 -c "from web_interface.app import app; print('OK')"
|
||||
```
|
||||
|
||||
### Issue 4: Port Already in Use
|
||||
|
||||
**Symptom:** Error message about port 5000 being in use
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check what's using port 5000
|
||||
sudo lsof -i :5000
|
||||
|
||||
# Kill the process if needed
|
||||
sudo kill -9 <PID>
|
||||
|
||||
# Or change the port in web_interface/start.py
|
||||
```
|
||||
|
||||
### Issue 5: Permission Issues
|
||||
|
||||
**Symptom:** Permission denied errors in logs
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Ensure proper ownership
|
||||
cd ~/LEDMatrix
|
||||
sudo chown -R ledpi:ledpi .
|
||||
|
||||
# Restart service
|
||||
sudo systemctl restart ledmatrix-web
|
||||
```
|
||||
|
||||
### Issue 6: Flask/Blueprint Import Errors
|
||||
|
||||
**Symptom:** ImportError or ModuleNotFoundError in logs
|
||||
|
||||
**Check these files exist:**
|
||||
```bash
|
||||
ls -la ~/LEDMatrix/web_interface/app.py
|
||||
ls -la ~/LEDMatrix/web_interface/start.py
|
||||
ls -la ~/LEDMatrix/web_interface/blueprints/api_v3.py
|
||||
ls -la ~/LEDMatrix/web_interface/blueprints/pages_v3.py
|
||||
```
|
||||
|
||||
If any are missing, you may need to restore from git or the reorganization.
|
||||
|
||||
## Detailed Logging Commands
|
||||
|
||||
### View All Web Service Logs
|
||||
```bash
|
||||
# Show all logs with timestamps
|
||||
sudo journalctl -u ledmatrix-web --no-pager
|
||||
|
||||
# Show logs from the last hour
|
||||
sudo journalctl -u ledmatrix-web --since "1 hour ago"
|
||||
|
||||
# Show logs between specific times
|
||||
sudo journalctl -u ledmatrix-web --since "2024-10-14 10:00:00" --until "2024-10-14 11:00:00"
|
||||
|
||||
# Show only errors
|
||||
sudo journalctl -u ledmatrix-web -p err
|
||||
```
|
||||
|
||||
### Check Python Import Issues
|
||||
```bash
|
||||
cd ~/LEDMatrix
|
||||
|
||||
# Test imports step by step
|
||||
python3 -c "import sys; sys.path.insert(0, '.'); from src.config_manager import ConfigManager; print('ConfigManager OK')"
|
||||
|
||||
python3 -c "import sys; sys.path.insert(0, '.'); from src.plugin_system.plugin_manager import PluginManager; print('PluginManager OK')"
|
||||
|
||||
python3 -c "import sys; sys.path.insert(0, '.'); from web_interface.app import app; print('Flask App OK')"
|
||||
```
|
||||
|
||||
## Service File Check
|
||||
|
||||
Verify the service file is correct:
|
||||
|
||||
```bash
|
||||
cat /etc/systemd/system/ledmatrix-web.service
|
||||
```
|
||||
|
||||
Should contain:
|
||||
```
|
||||
[Unit]
|
||||
Description=LED Matrix Web Interface Service
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=root
|
||||
WorkingDirectory=/home/ledpi/LEDMatrix
|
||||
Environment=USE_THREADING=1
|
||||
ExecStart=/usr/bin/python3 /home/ledpi/LEDMatrix/start_web_conditionally.py
|
||||
Restart=on-failure
|
||||
RestartSec=10
|
||||
StandardOutput=syslog
|
||||
StandardError=syslog
|
||||
SyslogIdentifier=ledmatrix-web
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
If it's different or points to old paths, reinstall it:
|
||||
|
||||
```bash
|
||||
cd ~/LEDMatrix
|
||||
sudo bash install_web_service.sh
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart ledmatrix-web
|
||||
```
|
||||
|
||||
## Post-Reorganization Checklist
|
||||
|
||||
Verify the reorganization completed correctly:
|
||||
|
||||
```bash
|
||||
cd ~/LEDMatrix
|
||||
|
||||
# These files should exist in new locations:
|
||||
ls web_interface/app.py
|
||||
ls web_interface/start.py
|
||||
ls web_interface/requirements.txt
|
||||
ls web_interface/blueprints/api_v3.py
|
||||
ls web_interface/blueprints/pages_v3.py
|
||||
|
||||
# start_web_conditionally.py should point to new location
|
||||
grep "web_interface/start.py" start_web_conditionally.py
|
||||
```
|
||||
|
||||
## Emergency Recovery
|
||||
|
||||
If nothing works, you can rollback to the old structure:
|
||||
|
||||
```bash
|
||||
cd ~/LEDMatrix
|
||||
|
||||
# Check git status
|
||||
git status
|
||||
|
||||
# If changes aren't committed, revert
|
||||
git checkout .
|
||||
|
||||
# Or restore specific files from old_web_interface
|
||||
# (if that directory exists)
|
||||
```
|
||||
|
||||
## Recommended Diagnostic Sequence
|
||||
|
||||
Run these commands in order to get a complete picture:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
echo "=== Web Interface Diagnostic Report ==="
|
||||
echo ""
|
||||
echo "1. Service Status:"
|
||||
sudo systemctl status ledmatrix-web
|
||||
echo ""
|
||||
echo "2. Config Autostart Setting:"
|
||||
cat ~/LEDMatrix/config/config.json | grep web_display_autostart
|
||||
echo ""
|
||||
echo "3. Recent Logs (last 20 lines):"
|
||||
sudo journalctl -u ledmatrix-web -n 20 --no-pager
|
||||
echo ""
|
||||
echo "4. File Structure Check:"
|
||||
ls -la ~/LEDMatrix/web_interface/
|
||||
echo ""
|
||||
echo "5. Python Import Test:"
|
||||
cd ~/LEDMatrix
|
||||
python3 -c "from web_interface.app import app; print('✓ Flask app imports successfully')" 2>&1
|
||||
echo ""
|
||||
echo "=== End of Diagnostic Report ==="
|
||||
```
|
||||
|
||||
Save this as `diagnose_web.sh`, make it executable, and run it:
|
||||
|
||||
```bash
|
||||
chmod +x diagnose_web.sh
|
||||
./diagnose_web.sh
|
||||
```
|
||||
|
||||
## Success Indicators
|
||||
|
||||
When the web interface is running correctly, you should see:
|
||||
|
||||
1. **Service Status:** "active (running)" in green
|
||||
2. **Logs:** "Starting LED Matrix Web Interface V3..."
|
||||
3. **Network:** Accessible at `http://<pi-ip>:5000`
|
||||
4. **Process:** Python process listening on port 5000
|
||||
|
||||
```bash
|
||||
# Check if it's listening
|
||||
sudo netstat -tlnp | grep :5000
|
||||
# or
|
||||
sudo ss -tlnp | grep :5000
|
||||
```
|
||||
|
||||
## Contact/Help
|
||||
|
||||
If you've tried all these steps and it still doesn't work, collect the following information:
|
||||
|
||||
1. Output from the diagnostic script above
|
||||
2. Full service logs: `sudo journalctl -u ledmatrix-web -n 100 --no-pager`
|
||||
3. Output from manual startup attempt
|
||||
4. Git status and recent commits
|
||||
|
||||
This will help identify the exact issue.
|
||||
|
||||
Reference in New Issue
Block a user