LEDMatrix/docs/OPTIMAL_WIFI_AP_FAILOVER_SETUP.md

Optimal WiFi Configuration with Failover AP Mode

Overview

This guide explains the optimal way to configure WiFi with automatic failover to Access Point (AP) mode, ensuring you can always connect to your Raspberry Pi even when the primary WiFi network is unavailable.

System Architecture

How It Works

The LEDMatrix WiFi system uses a grace period mechanism to prevent false positives from transient network hiccups:

1. WiFi Monitor Daemon runs as a background service (every 30 seconds by default)
2. Grace Period: Requires 3 consecutive disconnected checks before enabling AP mode
   • At 30-second intervals, this means 90 seconds of confirmed disconnection
   • This prevents AP mode from activating during brief network interruptions
3. Automatic Failover: When both WiFi and Ethernet are disconnected for the grace period, AP mode activates
4. Automatic Recovery: When WiFi or Ethernet reconnects, AP mode automatically disables

Connection Priority

The system checks connections in this order:

1. WiFi Connection (highest priority)
2. Ethernet Connection (fallback)
3. AP Mode (last resort - only when both WiFi and Ethernet are disconnected)

Optimal Configuration

Recommended Settings

For a reliable failover system, use these settings:

{
  "ap_ssid": "LEDMatrix-Setup",
  "ap_password": "ledmatrix123",
  "ap_channel": 7,
  "auto_enable_ap_mode": true,
  "saved_networks": [
    {
      "ssid": "YourPrimaryNetwork",
      "password": "your-password"
    }
  ]
}

Key Configuration Options

Setting	Recommended Value	Purpose
auto_enable_ap_mode	true	Enables automatic failover to AP mode
ap_ssid	LEDMatrix-Setup	Network name for AP mode (customizable)
ap_password	ledmatrix123	Password for AP mode (change for security)
ap_channel	7 (or 1, 6, 11)	WiFi channel (use non-overlapping channels)
saved_networks	Array of networks	Pre-configured networks for quick connection

Step-by-Step Setup

1. Initial Configuration

Via Web Interface (Recommended):

1. Connect to your Raspberry Pi (via Ethernet or existing WiFi)
2. Navigate to the WiFi tab in the web interface
3. Configure your primary WiFi network:
   • Click Scan to find networks
   • Select your network from the dropdown
   • Enter your WiFi password
   • Click Connect
4. Enable auto-failover:
   • Toggle "Auto-Enable AP Mode" to ON
   • This enables automatic failover when WiFi disconnects

Via Configuration File:

# Edit the WiFi configuration
nano config/wifi_config.json

Set auto_enable_ap_mode to true:

{
  "auto_enable_ap_mode": true,
  ...
}

2. Verify WiFi Monitor Service

The WiFi monitor daemon must be running for automatic failover:

# Check service status
sudo systemctl status ledmatrix-wifi-monitor

# If not running, start it
sudo systemctl start ledmatrix-wifi-monitor

# Enable on boot
sudo systemctl enable ledmatrix-wifi-monitor

3. Test Failover Behavior

Test Scenario 1: WiFi Disconnection

1. Disconnect your WiFi router or move the Pi out of range
2. Wait 90 seconds (3 check intervals × 30 seconds)
3. AP mode should automatically activate
4. Connect to LEDMatrix-Setup network from your device
5. Access web interface at http://192.168.4.1:5000

Test Scenario 2: WiFi Reconnection

1. Reconnect WiFi router or move Pi back in range
2. Within 30 seconds, AP mode should automatically disable
3. Pi should reconnect to your primary WiFi network

How the Grace Period Works

Disconnected Check Counter

The system uses a disconnected check counter to prevent false positives:

Check Interval: 30 seconds (configurable)
Required Checks: 3 consecutive
Grace Period: 90 seconds total

Example Timeline:

Time 0s:   WiFi disconnects
Time 30s:  Check 1 - Disconnected (counter = 1)
Time 60s:  Check 2 - Disconnected (counter = 2)
Time 90s:  Check 3 - Disconnected (counter = 3) → AP MODE ENABLED

If WiFi reconnects at any point, the counter resets to 0.

Why Grace Period is Important

Without a grace period, AP mode would activate during:

• Brief network hiccups
• Router reboots
• Temporary signal interference
• NetworkManager reconnection attempts

The 90-second grace period ensures AP mode only activates when there's a sustained disconnection.

Best Practices

1. Security Considerations

Change Default AP Password:

{
  "ap_password": "your-strong-password-here"
}

Use Non-Overlapping WiFi Channels:

• Channels 1, 6, 11 are non-overlapping (2.4GHz)
• Choose a channel that doesn't conflict with your primary network
• Example: If primary network uses channel 1, use channel 11 for AP mode

2. Network Configuration

Save Multiple Networks:

You can save multiple WiFi networks for automatic connection:

{
  "saved_networks": [
    {
      "ssid": "Home-Network",
      "password": "home-password"
    },
    {
      "ssid": "Office-Network",
      "password": "office-password"
    }
  ]
}

Note: Saved networks are stored for reference but connection still requires manual selection or NetworkManager auto-connect.

3. Monitoring and Troubleshooting

Check Service Logs:

# View real-time logs
sudo journalctl -u ledmatrix-wifi-monitor -f

# View recent logs
sudo journalctl -u ledmatrix-wifi-monitor -n 50

Check WiFi Status:

# Via Python
python3 -c "
from src.wifi_manager import WiFiManager
wm = WiFiManager()
status = wm.get_wifi_status()
print(f'Connected: {status.connected}')
print(f'SSID: {status.ssid}')
print(f'IP: {status.ip_address}')
print(f'AP Mode: {status.ap_mode_active}')
print(f'Auto-Enable: {wm.config.get(\"auto_enable_ap_mode\", False)}')
"

Check NetworkManager Status:

# View device status
nmcli device status

# View connections
nmcli connection show

# View WiFi networks
nmcli device wifi list

4. Customization Options

Adjust Check Interval:

Edit the systemd service file:

sudo systemctl edit ledmatrix-wifi-monitor

Add:

[Service]
ExecStart=
ExecStart=/usr/bin/python3 /path/to/LEDMatrix/scripts/utils/wifi_monitor_daemon.py --interval 20

Then restart:

sudo systemctl daemon-reload
sudo systemctl restart ledmatrix-wifi-monitor

Note: Changing the interval affects the grace period:

• 20-second interval = 60-second grace period (3 × 20)
• 30-second interval = 90-second grace period (3 × 30) ← Default
• 60-second interval = 180-second grace period (3 × 60)

Configuration Scenarios

Scenario 1: Always-On Failover (Recommended)

Use Case: Portable device that may lose WiFi connection

Configuration:

{
  "auto_enable_ap_mode": true
}

Behavior:

• AP mode activates automatically after 90 seconds of disconnection
• Always provides a way to connect to the device
• Best for devices that move or have unreliable WiFi

Scenario 2: Manual AP Mode Only

Use Case: Stable network connection (e.g., Ethernet or reliable WiFi)

Configuration:

{
  "auto_enable_ap_mode": false
}

Behavior:

• AP mode must be manually enabled via web UI
• Prevents unnecessary AP mode activation
• Best for stationary devices with stable connections

Scenario 3: Ethernet Primary with WiFi Failover

Use Case: Device primarily uses Ethernet, WiFi as backup

Configuration:

{
  "auto_enable_ap_mode": true
}

Behavior:

• Ethernet connection prevents AP mode activation
• If Ethernet disconnects, WiFi is attempted
• If both disconnect, AP mode activates after grace period
• Best for devices with both Ethernet and WiFi

Troubleshooting

AP Mode Not Activating

Check 1: Auto-Enable Setting

cat config/wifi_config.json | grep auto_enable_ap_mode

Should show "auto_enable_ap_mode": true

Check 2: Service Status

sudo systemctl status ledmatrix-wifi-monitor

Service should be active (running)

Check 3: Grace Period

• Wait at least 90 seconds after disconnection
• Check logs: sudo journalctl -u ledmatrix-wifi-monitor -f

Check 4: Ethernet Connection

• If Ethernet is connected, AP mode won't activate
• Disconnect Ethernet to test AP mode

AP Mode Activating Unexpectedly

Check 1: Network Stability

• Verify WiFi connection is stable
• Check for router issues or signal problems

Check 2: Grace Period Too Short

• Current grace period is 90 seconds
• Brief disconnections shouldn't trigger AP mode
• Check logs for disconnection patterns

Check 3: Disable Auto-Enable

# Set to false
nano config/wifi_config.json
# Change: "auto_enable_ap_mode": false
sudo systemctl restart ledmatrix-wifi-monitor

Cannot Connect to AP Mode

Check 1: AP Mode Active

sudo systemctl status hostapd
sudo systemctl status dnsmasq

Check 2: Network Interface

ip addr show wlan0

Should show IP 192.168.4.1

Check 3: Firewall

sudo iptables -L -n

Check if port 5000 is accessible

Check 4: Manual Enable

• Try manually enabling AP mode via web UI
• Or via API: curl -X POST http://localhost:5001/api/v3/wifi/ap/enable

Summary

Optimal Configuration Checklist

• auto_enable_ap_mode set to true
• WiFi monitor service running and enabled
• Primary WiFi network configured and tested
• AP password changed from default
• AP channel configured (non-overlapping)
• Grace period understood (90 seconds)
• Failover behavior tested

Key Takeaways

1. Grace Period: 90 seconds prevents false positives
2. Auto-Enable: Set to true for reliable failover
3. Service: WiFi monitor daemon must be running
4. Priority: WiFi → Ethernet → AP Mode
5. Automatic: AP mode disables when WiFi/Ethernet connects

This configuration provides a robust failover system that ensures you can always access your Raspberry Pi, even when the primary network connection fails.