LEDMatrix/docs/WIFI_NETWORK_SETUP.md

WiFi Network Setup Guide

Overview

The LEDMatrix WiFi system provides automatic network configuration with intelligent failover to Access Point (AP) mode. When your Raspberry Pi loses network connectivity, it automatically creates a WiFi access point for easy configuration—ensuring you can always connect to your device.

Key Features

• Automatic AP Mode: Creates a WiFi access point when network connection is lost
• Intelligent Failover: Only activates after a grace period to prevent false positives
• Dual Connectivity: Supports both WiFi and Ethernet with automatic priority management
• Web Interface: Configure WiFi through an easy-to-use web interface
• Network Scanning: Scan and connect to available WiFi networks
• Secure Storage: WiFi credentials stored securely

---

Quick Start

Accessing WiFi Setup

If not connected to WiFi:

1. Wait 90 seconds after boot (AP mode activation grace period)
2. Connect to WiFi network LEDMatrix-Setup (an open network: no password)
3. Open browser to: http://192.168.4.1:5000
4. Open the WiFi tab
5. Scan, select your network, and connect

If already connected:

1. Open browser to: http://your-pi-ip:5000
2. Navigate to the WiFi tab
3. Configure as needed

---

Installation

Prerequisites

The following packages are required:

• hostapd - Access point software
• dnsmasq - DHCP server for AP mode
• NetworkManager - WiFi management

Install WiFi Monitor Service

cd /home/ledpi/LEDMatrix
sudo ./scripts/install/install_wifi_monitor.sh

This script will:

• Check for required packages and offer to install them
• Create the systemd service file
• Enable and start the WiFi monitor service
• Configure the service to start on boot

Verify Installation

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

# Run verification script
./scripts/verify_wifi_setup.sh

---

Configuration

Configuration File

WiFi settings are stored in config/wifi_config.json:

{
  "ap_ssid": "LEDMatrix-Setup",
  "ap_channel": 7,
  "auto_enable_ap_mode": true
}

Configuration Options

Setting	Default	Description
ap_ssid	LEDMatrix-Setup	Network name broadcast in AP mode
ap_channel	7	WiFi channel (1, 6, or 11 are non-overlapping)
auto_enable_ap_mode	true	Automatically enable AP mode when both WiFi and Ethernet are disconnected

Auto-Enable AP Mode Behavior

When enabled (true - recommended):

• AP mode activates automatically after 90-second grace period
• Only when both WiFi AND Ethernet are disconnected
• Automatically disables when either WiFi or Ethernet connects
• Best for portable devices or unreliable network environments

When disabled (false):

• AP mode must be manually enabled through web interface
• Prevents unnecessary AP activation
• Best for devices with stable network connections

---

Using WiFi Setup

Connecting to a WiFi Network

Via Web Interface:

1. Navigate to the WiFi tab
2. Click Scan to search for networks
3. Select a network from the dropdown (or enter SSID manually)
4. Enter the WiFi password (leave empty for open networks)
5. Click Connect
6. System will attempt connection
7. AP mode automatically disables once connected

Via API:

# Scan for networks
curl "http://your-pi-ip:5000/api/v3/wifi/scan"

# Connect to network
curl -X POST http://your-pi-ip:5000/api/v3/wifi/connect \
  -H "Content-Type: application/json" \
  -d '{"ssid": "YourNetwork", "password": "your-password"}'

Manual AP Mode Control

Via Web Interface:

• Enable AP Mode: Click "Enable AP Mode" button (only when WiFi/Ethernet disconnected)
• Disable AP Mode: Click "Disable AP Mode" button (when AP is active)

Via API:

# Enable AP mode
curl -X POST http://your-pi-ip:5000/api/v3/wifi/ap/enable

# Disable AP mode
curl -X POST http://your-pi-ip:5000/api/v3/wifi/ap/disable

Note: Manual enable still requires both WiFi and Ethernet to be disconnected.

---

Understanding AP Mode Failover

How the Grace Period Works

The system uses a grace period mechanism to prevent false positives from temporary network hiccups:

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

Timeline Example:

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 or Ethernet 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 during sustained disconnection.

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 disconnected)

Behavior Summary

WiFi Status	Ethernet Status	Auto-Enable	AP Mode Behavior
Any	Any	false	Manual enable only
Connected	Any	true	Disabled
Disconnected	Connected	true	Disabled (Ethernet available)
Disconnected	Disconnected	true	Auto-enabled after 90s

---

Access Point Configuration

AP Mode Settings

• SSID: LEDMatrix-Setup (configurable via ap_ssid)
• Network: open (no password). Both AP paths create an open network (_create_hostapd_config() and _enable_ap_mode_nmcli_hotspot() in src/wifi_manager.py); an ap_password key in wifi_config.json is not read
• IP Address: 192.168.4.1
• DHCP Range: 192.168.4.2 – 192.168.4.20
• Channel: 7 (configurable via ap_channel)

Accessing Services in AP Mode

When AP mode is active:

• Web Interface: http://192.168.4.1:5000
• SSH: ssh ledpi@192.168.4.1
• Captive portal may automatically redirect browsers

---

Best Practices

Security Recommendations

1. Keep AP mode short-lived: The setup network is open, so anyone nearby can join it and reach the web interface while it is up. AP mode only comes up when WiFi and Ethernet are both disconnected (after the 90 second grace period) and goes down again once the Pi is connected; in a public area, consider setting auto_enable_ap_mode to false and enabling AP mode by hand when needed.

2. 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 uses channel 1, use channel 11 for AP mode

3. Secure WiFi Credentials:

sudo chmod 600 config/wifi_config.json

Network Configuration Tips

Multiple Networks:

NetworkManager remembers every network you connect to and rejoins whichever is in range; list them with nmcli connection show. LEDMatrix itself does not store WiFi passwords.

Adjust Check Interval:

Edit the systemd service file to change grace period:

sudo systemctl edit ledmatrix-wifi-monitor

Add:

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

Note: Interval affects 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: Portable Device with Auto-Failover (Recommended)

Use Case: Device 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
• Best for devices that move or have unreliable WiFi

Scenario 2: Stable Network Connection

Use Case: Ethernet or reliable WiFi connection

Configuration:

{
  "auto_enable_ap_mode": false
}

Behavior:

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

Scenario 3: Ethernet Primary with WiFi Backup

Use Case: Primary 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
• Verify: nmcli device status
• Disconnect Ethernet to test AP mode

Check 5: Required Packages

# Verify hostapd is installed
which hostapd

# Verify dnsmasq is installed
which dnsmasq

Cannot Access AP Mode

Check 1: AP Mode Active

sudo systemctl status hostapd
sudo systemctl status dnsmasq

Both should be running

Check 2: Network Interface

ip addr show wlan0

Should show IP 192.168.4.1

Check 3: WiFi Interface Available

ip link show wlan0

Interface should exist

Check 4: Try Manual Enable

• Use web interface: WiFi tab → Enable AP Mode
• Or via API: curl -X POST http://localhost:5000/api/v3/wifi/ap/enable

Cannot Connect to WiFi Network

Check 1: Verify Credentials

• Ensure SSID and password are correct
• Check for hidden networks (manual SSID entry required)

Check 2: Check Logs

# WiFi monitor logs
sudo journalctl -u ledmatrix-wifi-monitor -f

# NetworkManager logs
sudo journalctl -u NetworkManager -n 50

Check 3: Network Compatibility

• Verify network is 2.4GHz (5GHz may not be supported on all Pi models)
• Check if network requires special authentication

AP Mode Not Disabling After WiFi Connect

Check 1: WiFi Connection Status

nmcli device status

Check 2: Manually Disable

• Use web interface: WiFi tab → Disable AP Mode
• Or restart service: sudo systemctl restart ledmatrix-wifi-monitor

Check 3: Check Logs

sudo journalctl -u ledmatrix-wifi-monitor -n 50

AP Mode Activating Unexpectedly

Check 1: Network Stability

• Verify WiFi connection is stable
• Check router status
• Check signal strength

Check 2: Disable Auto-Enable

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

Check 3: Increase Grace Period

• Edit service file to increase check interval
• Longer interval = longer grace period
• See "Best Practices" section above

---

Monitoring and Diagnostics

Check WiFi Status

Via Python:

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 Address: {status.ip_address}')
print(f'AP Mode Active: {status.ap_mode_active}')
print(f'Auto-Enable: {wm.config.get("auto_enable_ap_mode", False)}')

Via NetworkManager:

# View device status
nmcli device status

# View connections
nmcli connection show

# View available WiFi networks
nmcli device wifi list

View Service Logs

# Real-time logs
sudo journalctl -u ledmatrix-wifi-monitor -f

# Recent logs (last 50 lines)
sudo journalctl -u ledmatrix-wifi-monitor -n 50

# Logs from specific time
sudo journalctl -u ledmatrix-wifi-monitor --since "1 hour ago"

Run Verification Script

cd /home/ledpi/LEDMatrix
./scripts/verify_wifi_setup.sh

Checks:

• Required packages installed
• WiFi monitor service running
• Configuration files valid
• WiFi interface available
• Current connection status
• AP mode status

---

Service Management

Useful Commands

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

# Start the service
sudo systemctl start ledmatrix-wifi-monitor

# Stop the service
sudo systemctl stop ledmatrix-wifi-monitor

# Restart the service
sudo systemctl restart ledmatrix-wifi-monitor

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

# Disable service from starting on boot
sudo systemctl disable ledmatrix-wifi-monitor

# Enable service to start on boot
sudo systemctl enable ledmatrix-wifi-monitor

---

API Reference

The WiFi setup feature exposes the following API endpoints:

Method	Endpoint	Description
GET	/api/v3/wifi/status	Get current WiFi connection status
GET	/api/v3/wifi/scan	Scan for available WiFi networks
POST	/api/v3/wifi/connect	Connect to a WiFi network
POST	/api/v3/wifi/ap/enable	Enable access point mode
POST	/api/v3/wifi/ap/disable	Disable access point mode
GET	/api/v3/wifi/ap/auto-enable	Get auto-enable setting
POST	/api/v3/wifi/ap/auto-enable	Set auto-enable setting

Example Usage

# Get WiFi status
curl "http://your-pi-ip:5000/api/v3/wifi/status"

# Scan for networks
curl "http://your-pi-ip:5000/api/v3/wifi/scan"

# Connect to network
curl -X POST http://your-pi-ip:5000/api/v3/wifi/connect \
  -H "Content-Type: application/json" \
  -d '{"ssid": "MyNetwork", "password": "mypassword"}'

# Enable AP mode
curl -X POST http://your-pi-ip:5000/api/v3/wifi/ap/enable

# Check auto-enable setting
curl "http://your-pi-ip:5000/api/v3/wifi/ap/auto-enable"

# Set auto-enable
curl -X POST http://your-pi-ip:5000/api/v3/wifi/ap/auto-enable \
  -H "Content-Type: application/json" \
  -d '{"auto_enable_ap_mode": true}'

---

Technical Details

WiFi Monitor Daemon

The WiFi monitor daemon (wifi_monitor_daemon.py) runs as a background service that:

1. Checks WiFi and Ethernet connection status every 30 seconds (configurable)
2. Maintains disconnected check counter for grace period
3. Automatically enables AP mode when:
   • auto_enable_ap_mode is enabled AND
   • Both WiFi and Ethernet disconnected AND
   • Grace period elapsed (3 consecutive checks)
4. Automatically disables AP mode when WiFi or Ethernet connects
5. Logs all state changes

WiFi Detection Methods

The WiFi manager tries multiple methods:

1. NetworkManager (nmcli) - Preferred method
2. iwconfig - Fallback for systems without NetworkManager

Network Scanning Methods

1. nmcli - Fast, preferred method
2. iwlist - Fallback for older systems

Access Point Implementation

• Uses hostapd for WiFi access point functionality
• Uses dnsmasq for DHCP and DNS services
• Configures wlan0 interface with IP 192.168.4.1
• Provides DHCP range: 192.168.4.2-20
• Captive portal with DNS redirection

---

Related Documentation

• WEB_INTERFACE_GUIDE.md - Using the web interface
• TROUBLESHOOTING.md - General troubleshooting
• GETTING_STARTED.md - Initial setup guide