rick/LEDMatrix
1
0
Fork 0
mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-04-11 21:33:00 +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

361
docs/archive/RECONNECT_AFTER_CAPTIVE_PORTAL_TESTING.md Normal file
View File

@@ -0,0 +1,361 @@
# Reconnecting to Internet After Captive Portal Testing
If captive portal testing fails or you need to reconnect to your normal network, here are several methods to get back online.
## Quick Reference
**Before testing:** Always run `sudo ./scripts/verify_wifi_before_testing.sh` first!
**If stuck:** Run `sudo ./scripts/emergency_reconnect.sh` for automated recovery.
## Quick Recovery Methods
### Method 1: Via Web Interface (If Accessible)
If you can still access the web interface at `http://192.168.4.1:5000`:
1. **Navigate to WiFi tab**
2. **Click "Scan"** to find available networks
3. **Select your network** from the dropdown
4. **Enter your WiFi password**
5. **Click "Connect"**
6. **Wait for connection** - AP mode should automatically disable
### Method 2: Via SSH (If You Have Direct Access)
If you have SSH access to the Pi (via Ethernet, direct connection, or still connected to AP):
```bash
# Connect via SSH
ssh user@192.168.4.1 # If connected to AP
# OR
ssh user@<pi-ip> # If on same network
# Disable AP mode first
sudo systemctl stop hostapd
sudo systemctl stop dnsmasq
# Connect to WiFi using nmcli
sudo nmcli device wifi connect "YourNetworkName" password "YourPassword"
# Or if you have a saved connection
sudo nmcli connection up "YourNetworkName"
```
### Method 3: Via API Endpoints (If Web Interface Works)
If the web interface is accessible but you can't use the UI:
```bash
# Connect to WiFi via API
curl -X POST http://192.168.4.1:5000/api/v3/wifi/connect \
-H "Content-Type: application/json" \
-d '{"ssid": "YourNetworkName", "password": "YourPassword"}'
# Disable AP mode
curl -X POST http://192.168.4.1:5000/api/v3/wifi/ap/disable
```
### Method 4: Direct Command Line (Physical Access)
If you have physical access to the Pi or a keyboard/monitor:
```bash
# Disable AP mode services
sudo systemctl stop hostapd
sudo systemctl stop dnsmasq
# Check available networks
nmcli device wifi list
# Connect to your network
sudo nmcli device wifi connect "YourNetworkName" password "YourPassword"
# Verify connection
nmcli device status
ip addr show wlan0
```
### Method 5: Using Saved Network Configuration
If you've previously connected to a network, it may be saved:
```bash
# List saved connections
nmcli connection show
# Activate a saved connection
sudo nmcli connection up "YourSavedConnectionName"
# Or by UUID
sudo nmcli connection up <uuid>
```
## Step-by-Step Recovery Procedure
### Scenario 1: Still Connected to AP Network
If you're still connected to "LEDMatrix-Setup":
1. **Access web interface:**
```
http://192.168.4.1:5000
```
2. **Go to WiFi tab**
3. **Connect to your network** using the interface
4. **Wait for connection** - you'll be disconnected from AP
5. **Reconnect to your new network** and access Pi at its new IP
### Scenario 2: Can't Access Web Interface
If web interface is not accessible:
1. **SSH into Pi** (if possible):
```bash
ssh user@192.168.4.1 # Via AP
# OR via Ethernet if connected
```
2. **Disable AP mode:**
```bash
sudo systemctl stop hostapd dnsmasq
```
3. **Connect to WiFi:**
```bash
sudo nmcli device wifi connect "YourNetwork" password "YourPassword"
```
4. **Verify connection:**
```bash
nmcli device status
ping -c 3 8.8.8.8 # Test internet connectivity
```
### Scenario 3: No Network Access at All
If you have no network access (AP not working, no Ethernet):
1. **Physical access required:**
- Connect keyboard and monitor to Pi
- Or use serial console if available
2. **Disable AP services:**
```bash
sudo systemctl stop hostapd
sudo systemctl stop dnsmasq
sudo systemctl disable hostapd # Prevent auto-start
sudo systemctl disable dnsmasq
```
3. **Connect to WiFi manually:**
```bash
sudo nmcli device wifi list
sudo nmcli device wifi connect "YourNetwork" password "YourPassword"
```
4. **Restart network services if needed:**
```bash
sudo systemctl restart NetworkManager
```
## Emergency Recovery Script
Create this script for quick recovery:
```bash
#!/bin/bash
# emergency_reconnect.sh - Emergency WiFi reconnection script
echo "Emergency WiFi Reconnection"
echo "=========================="
# Stop AP mode
echo "Stopping AP mode..."
sudo systemctl stop hostapd 2>/dev/null
sudo systemctl stop dnsmasq 2>/dev/null
# List available networks
echo ""
echo "Available networks:"
nmcli device wifi list
# Prompt for network
echo ""
read -p "Enter network SSID: " SSID
read -sp "Enter password: " PASSWORD
echo ""
# Connect
echo "Connecting to $SSID..."
sudo nmcli device wifi connect "$SSID" password "$PASSWORD"
# Wait a moment
sleep 3
# Check status
if nmcli device status | grep -q "connected"; then
echo "✓ Connected successfully!"
IP=$(ip addr show wlan0 | grep "inet " | awk '{print $2}' | cut -d/ -f1)
echo "IP Address: $IP"
else
echo "✗ Connection failed. Check credentials and try again."
fi
```
Save as `scripts/emergency_reconnect.sh` and make executable:
```bash
chmod +x scripts/emergency_reconnect.sh
sudo ./scripts/emergency_reconnect.sh
```
## Preventing Issues
### Before Testing
1. **Save your current network connection:**
```bash
# Your network should already be saved if you've connected before
nmcli connection show
```
2. **Note your Pi's IP address** on your normal network:
```bash
hostname -I
```
3. **Ensure you have alternative access:**
- Ethernet cable (if available)
- SSH access via another method
- Physical access to Pi
### During Testing
1. **Keep a terminal/SSH session open** to the Pi
2. **Test from a secondary device** (not your main computer)
3. **Have the recovery commands ready**
### After Testing
1. **Verify internet connectivity:**
```bash
ping -c 3 8.8.8.8
curl -I https://www.google.com
```
2. **Check Pi's new IP address:**
```bash
hostname -I
ip addr show wlan0
```
3. **Update your SSH/config** if IP changed
## Troubleshooting Reconnection
### Issue: Can't Connect to Saved Network
**Solution:**
```bash
# Remove old connection and reconnect
nmcli connection delete "NetworkName"
sudo nmcli device wifi connect "NetworkName" password "Password"
```
### Issue: AP Mode Won't Disable
**Solution:**
```bash
# Force stop services
sudo systemctl stop hostapd dnsmasq
sudo systemctl disable hostapd dnsmasq
# Kill processes if needed
sudo pkill hostapd
sudo pkill dnsmasq
# Restart NetworkManager
sudo systemctl restart NetworkManager
```
### Issue: WiFi Interface Stuck
**Solution:**
```bash
# Reset WiFi interface
sudo nmcli radio wifi off
sleep 2
sudo nmcli radio wifi on
sleep 3
# Try connecting again
sudo nmcli device wifi connect "NetworkName" password "Password"
```
### Issue: No Networks Found
**Solution:**
```bash
# Check WiFi is enabled
nmcli radio wifi
# Enable if off
sudo nmcli radio wifi on
# Check interface status
ip link show wlan0
# Restart NetworkManager
sudo systemctl restart NetworkManager
```
## Quick Reference Commands
```bash
# Disable AP mode
sudo systemctl stop hostapd dnsmasq
# List WiFi networks
nmcli device wifi list
# Connect to network
sudo nmcli device wifi connect "SSID" password "Password"
# Check connection status
nmcli device status
# Get IP address
hostname -I
ip addr show wlan0
# Test internet
ping -c 3 8.8.8.8
# Restart network services
sudo systemctl restart NetworkManager
```
## Best Practices
1. **Always test from a secondary device** - Keep your main computer on your normal network
2. **Have Ethernet backup** - If available, keep Ethernet connected as fallback
3. **Save network credentials** - Ensure your network is saved before testing
4. **Document your Pi's IP** - Note the IP on your normal network before testing
5. **Keep SSH session open** - Maintain an active SSH connection during testing
6. **Test during safe times** - Don't test when you need immediate internet access
## Recovery Checklist
- [ ] Stop AP mode services (hostapd, dnsmasq)
- [ ] Verify WiFi interface is available
- [ ] Scan for available networks
- [ ] Connect to your network
- [ ] Verify connection status
- [ ] Test internet connectivity
- [ ] Note new IP address
- [ ] Update any configurations that reference old IP