rick/LEDMatrix
1
0
Fork 0
mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-04-12 13:42: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

445
docs/archive/CAPTIVE_PORTAL_TESTING.md Normal file
View File

@@ -0,0 +1,445 @@
# Captive Portal Testing Guide
This guide explains how to test the captive portal WiFi setup functionality.
## Prerequisites
1. **Raspberry Pi with LEDMatrix installed**
2. **WiFi adapter** (built-in or USB)
3. **Test devices** (smartphone, tablet, or laptop)
4. **Access to Pi** (SSH or direct access)
## Important: Before Testing
**⚠️ Make sure you have a way to reconnect!**
Before starting testing, ensure you have:
- **Ethernet cable** (if available) as backup connection
- **SSH access** via another method (Ethernet, direct connection)
- **Physical access** to Pi (keyboard/monitor) as last resort
- **Your WiFi credentials** saved/noted down
**If testing fails, see:** [Reconnecting After Testing](RECONNECT_AFTER_CAPTIVE_PORTAL_TESTING.md)
**Quick recovery script:** `sudo ./scripts/emergency_reconnect.sh`
## Pre-Testing Setup
### 0. Verify WiFi is Ready (IMPORTANT!)
**⚠️ CRITICAL: Run this BEFORE disconnecting Ethernet!**
```bash
sudo ./scripts/verify_wifi_before_testing.sh
```
This script will verify:
- WiFi interface exists and is enabled
- WiFi can scan for networks
- You have saved WiFi connections (for reconnecting)
- Required services are ready
- Current network status
**Do NOT disconnect Ethernet until this script passes all checks!**
### 1. Ensure WiFi Monitor Service is Running
```bash
sudo systemctl status ledmatrix-wifi-monitor
```
If not running:
```bash
sudo systemctl start ledmatrix-wifi-monitor
sudo systemctl enable ledmatrix-wifi-monitor
```
### 2. Disconnect Pi from WiFi/Ethernet
**⚠️ Only do this AFTER running the verification script!**
To test captive portal, the Pi should NOT be connected to any network:
```bash
# First, verify WiFi is ready (see step 0 above)
sudo ./scripts/verify_wifi_before_testing.sh
# Check current network status
nmcli device status
# Disconnect WiFi (if connected)
sudo nmcli device disconnect wlan0
# Disconnect Ethernet (if connected)
# Option 1: Unplug Ethernet cable (safest)
# Option 2: Via command (if you're sure WiFi works):
sudo nmcli device disconnect eth0
# Verify disconnection
nmcli device status
# Both should show "disconnected" or "unavailable"
```
### 3. Enable AP Mode
You can enable AP mode manually or wait for it to auto-enable (if `auto_enable_ap_mode` is true):
**Manual enable via web interface:**
- Access web interface at `http://<pi-ip>:5000` (if still accessible)
- Go to WiFi tab
- Click "Enable AP Mode"
**Manual enable via command line:**
```bash
python3 -c "from src.wifi_manager import WiFiManager; wm = WiFiManager(); print(wm.enable_ap_mode())"
```
**Or via API:**
```bash
curl -X POST http://localhost:5000/api/v3/wifi/ap/enable
```
### 4. Verify AP Mode is Active
```bash
# Check hostapd service
sudo systemctl status hostapd
# Check dnsmasq service
sudo systemctl status dnsmasq
# Check if wlan0 is in AP mode
iwconfig wlan0
# Should show "Mode:Master"
# Check IP address
ip addr show wlan0
# Should show 192.168.4.1
```
### 5. Verify DNSMASQ Configuration
```bash
# Check dnsmasq config
sudo cat /etc/dnsmasq.conf
# Should contain:
# - address=/#/192.168.4.1
# - address=/captive.apple.com/192.168.4.1
# - address=/connectivitycheck.gstatic.com/192.168.4.1
# - address=/www.msftconnecttest.com/192.168.4.1
# - address=/detectportal.firefox.com/192.168.4.1
```
### 6. Verify Web Interface is Running
```bash
# Check if web service is running
sudo systemctl status ledmatrix-web
# Or check if Flask app is running
ps aux | grep "web_interface"
```
## Testing Procedures
### Test 1: DNS Redirection
**Purpose:** Verify that DNS queries are redirected to the Pi.
**Steps:**
1. Connect a device to "LEDMatrix-Setup" network (password: `ledmatrix123`)
2. Try to resolve any domain name:
```bash
# On Linux/Mac
nslookup google.com
# Should return 192.168.4.1
# On Windows
nslookup google.com
# Should return 192.168.4.1
```
**Expected Result:** All DNS queries should resolve to 192.168.4.1
### Test 2: HTTP Redirect (Manual Browser Test)
**Purpose:** Verify that HTTP requests redirect to WiFi setup page.
**Steps:**
1. Connect device to "LEDMatrix-Setup" network
2. Open a web browser
3. Try to access any website:
- `http://google.com`
- `http://example.com`
- `http://192.168.4.1` (direct IP)
**Expected Result:** All requests should redirect to `http://192.168.4.1:5000/v3` (WiFi setup interface)
### Test 3: Captive Portal Detection Endpoints
**Purpose:** Verify that device detection endpoints respond correctly.
**Test each endpoint:**
```bash
# iOS/macOS detection
curl http://192.168.4.1:5000/hotspot-detect.html
# Expected: HTML response with "Success"
# Android detection
curl -I http://192.168.4.1:5000/generate_204
# Expected: HTTP 204 No Content
# Windows detection
curl http://192.168.4.1:5000/connecttest.txt
# Expected: "Microsoft Connect Test"
# Firefox detection
curl http://192.168.4.1:5000/success.txt
# Expected: "success"
```
**Expected Result:** Each endpoint should return the appropriate response
### Test 4: iOS Device (iPhone/iPad)
**Purpose:** Test automatic captive portal detection on iOS.
**Steps:**
1. On iPhone/iPad, go to Settings > Wi-Fi
2. Connect to "LEDMatrix-Setup" network
3. Enter password: `ledmatrix123`
4. Wait a few seconds
**Expected Result:**
- iOS should automatically detect the captive portal
- A popup should appear saying "Sign in to Network" or similar
- Tapping it should open Safari with the WiFi setup page
- The setup page should show the captive portal banner
**If it doesn't auto-open:**
- Open Safari manually
- Try to visit any website (e.g., apple.com)
- Should redirect to WiFi setup page
### Test 5: Android Device
**Purpose:** Test automatic captive portal detection on Android.
**Steps:**
1. On Android device, go to Settings > Wi-Fi
2. Connect to "LEDMatrix-Setup" network
3. Enter password: `ledmatrix123`
4. Wait a few seconds
**Expected Result:**
- Android should show a notification: "Sign in to network" or "Network sign-in required"
- Tapping the notification should open a browser with the WiFi setup page
- The setup page should show the captive portal banner
**If notification doesn't appear:**
- Open Chrome browser
- Try to visit any website
- Should redirect to WiFi setup page
### Test 6: Windows Laptop
**Purpose:** Test captive portal on Windows.
**Steps:**
1. Connect Windows laptop to "LEDMatrix-Setup" network
2. Enter password: `ledmatrix123`
3. Wait a few seconds
**Expected Result:**
- Windows may show a notification about network sign-in
- Opening any browser and visiting any website should redirect to WiFi setup page
- Edge/Chrome may automatically open a sign-in window
**Manual test:**
- Open any browser
- Visit `http://www.msftconnecttest.com` or any website
- Should redirect to WiFi setup page
### Test 7: API Endpoints Still Work
**Purpose:** Verify that WiFi API endpoints function normally during AP mode.
**Steps:**
1. While connected to "LEDMatrix-Setup" network
2. Test API endpoints:
```bash
# Status endpoint
curl http://192.168.4.1:5000/api/v3/wifi/status
# Scan networks
curl http://192.168.4.1:5000/api/v3/wifi/scan
```
**Expected Result:** API endpoints should return JSON responses normally (not redirect)
### Test 8: WiFi Connection Flow
**Purpose:** Test the complete flow of connecting to WiFi via captive portal.
**Steps:**
1. Connect device to "LEDMatrix-Setup" network
2. Wait for captive portal to redirect to setup page
3. Click "Scan" to find available networks
4. Select a network from the list
5. Enter WiFi password
6. Click "Connect"
7. Wait for connection to establish
**Expected Result:**
- Device should connect to selected WiFi network
- AP mode should automatically disable
- Device should now be on the new network
- Can access Pi via new network IP address
## Troubleshooting
### Issue: DNS Not Redirecting
**Symptoms:** DNS queries resolve to actual IPs, not 192.168.4.1
**Solutions:**
1. Check dnsmasq config:
```bash
sudo cat /etc/dnsmasq.conf | grep address
```
2. Restart dnsmasq:
```bash
sudo systemctl restart dnsmasq
```
3. Check dnsmasq logs:
```bash
sudo journalctl -u dnsmasq -n 50
```
### Issue: HTTP Not Redirecting
**Symptoms:** Browser shows actual websites instead of redirecting
**Solutions:**
1. Check if AP mode is active:
```bash
python3 -c "from src.wifi_manager import WiFiManager; wm = WiFiManager(); print(wm._is_ap_mode_active())"
```
2. Check Flask app logs for errors
3. Verify web interface is running on port 5000
4. Test redirect middleware manually:
```bash
curl -I http://192.168.4.1:5000/google.com
# Should return 302 redirect
```
### Issue: Captive Portal Not Detected by Device
**Symptoms:** Device doesn't show sign-in notification/popup
**Solutions:**
1. Verify detection endpoints are accessible:
```bash
curl http://192.168.4.1:5000/hotspot-detect.html
curl http://192.168.4.1:5000/generate_204
```
2. Try manually opening browser and visiting any website
3. Some devices require specific responses - check endpoint implementations
4. Clear device's network settings and reconnect
### Issue: Infinite Redirect Loop
**Symptoms:** Browser keeps redirecting in a loop
**Solutions:**
1. Check that `/v3` path is in allowed_paths list
2. Verify redirect middleware logic in `app.py`
3. Check Flask logs for errors
4. Ensure WiFi API endpoints are not being redirected
### Issue: AP Mode Not Enabling
**Symptoms:** Can't connect to "LEDMatrix-Setup" network
**Solutions:**
1. Check WiFi monitor service:
```bash
sudo systemctl status ledmatrix-wifi-monitor
```
2. Check WiFi config:
```bash
cat config/wifi_config.json
```
3. Manually enable AP mode:
```bash
python3 -c "from src.wifi_manager import WiFiManager; wm = WiFiManager(); print(wm.enable_ap_mode())"
```
4. Check hostapd logs:
```bash
sudo journalctl -u hostapd -n 50
```
## Verification Checklist
- [ ] DNS redirection works (all domains resolve to 192.168.4.1)
- [ ] HTTP redirect works (all websites redirect to setup page)
- [ ] Captive portal detection endpoints respond correctly
- [ ] iOS device auto-opens setup page
- [ ] Android device shows sign-in notification
- [ ] Windows device redirects to setup page
- [ ] WiFi API endpoints still work during AP mode
- [ ] Can successfully connect to WiFi via setup page
- [ ] AP mode disables after WiFi connection
- [ ] No infinite redirect loops
- [ ] Captive portal banner appears on setup page when AP mode is active
## Quick Test Script
Save this as `test_captive_portal.sh`:
```bash
#!/bin/bash
echo "Testing Captive Portal Functionality"
echo "===================================="
# Test DNS redirection
echo -e "\n1. Testing DNS redirection..."
nslookup google.com | grep -q "192.168.4.1" && echo "✓ DNS redirection works" || echo "✗ DNS redirection failed"
# Test HTTP redirect
echo -e "\n2. Testing HTTP redirect..."
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -L http://192.168.4.1:5000/google.com)
[ "$HTTP_CODE" = "200" ] && echo "✓ HTTP redirect works" || echo "✗ HTTP redirect failed (got $HTTP_CODE)"
# Test detection endpoints
echo -e "\n3. Testing captive portal detection endpoints..."
curl -s http://192.168.4.1:5000/hotspot-detect.html | grep -q "Success" && echo "✓ iOS endpoint works" || echo "✗ iOS endpoint failed"
curl -s -o /dev/null -w "%{http_code}" http://192.168.4.1:5000/generate_204 | grep -q "204" && echo "✓ Android endpoint works" || echo "✗ Android endpoint failed"
curl -s http://192.168.4.1:5000/connecttest.txt | grep -q "Microsoft" && echo "✓ Windows endpoint works" || echo "✗ Windows endpoint failed"
curl -s http://192.168.4.1:5000/success.txt | grep -q "success" && echo "✓ Firefox endpoint works" || echo "✗ Firefox endpoint failed"
# Test API endpoints
echo -e "\n4. Testing API endpoints..."
API_RESPONSE=$(curl -s http://192.168.4.1:5000/api/v3/wifi/status)
echo "$API_RESPONSE" | grep -q "status" && echo "✓ API endpoints work" || echo "✗ API endpoints failed"
echo -e "\nTesting complete!"
```
Make it executable and run:
```bash
chmod +x test_captive_portal.sh
./test_captive_portal.sh
```
## Notes
- **Port Number:** The web interface runs on port 5000 by default. If you've changed this, update all URLs accordingly.
- **Network Range:** The AP uses 192.168.4.0/24 network. If you need a different range, update both hostapd and dnsmasq configs.
- **Password:** Default AP password is `ledmatrix123`. Change it in `config/wifi_config.json` if needed.
- **Testing on Same Device:** If testing from the Pi itself, you'll need a second device to connect to the AP network.