LEDMatrix/docs/WIFI_SETUP.md

WiFi Setup Feature

The LED Matrix project includes a WiFi setup feature that allows you to configure WiFi connections through a web interface. When the Raspberry Pi is not connected to WiFi, it automatically broadcasts an access point (AP) that you can connect to for initial setup.

Features

• Automatic AP Mode: When no WiFi connection is detected, the Raspberry Pi automatically creates a WiFi access point named "LEDMatrix-Setup"
• Web Interface: Access the WiFi setup interface through your web browser
• Network Scanning: Scan for available WiFi networks from the web interface
• Secure Connection: Save WiFi credentials securely
• Automatic Management: The WiFi monitor daemon automatically enables/disables AP mode based on connection status

Requirements

The following packages are required for WiFi setup functionality:

• hostapd: Access point software
• dnsmasq: DHCP server for AP mode
• NetworkManager (or iwlist): WiFi management tools

These packages are automatically checked and can be installed during the WiFi monitor service installation.

Installation

1. Install WiFi Monitor Service

Run the installation script to set up the WiFi monitor daemon:

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

2. Verify Service Status

Check that the WiFi monitor service is running:

sudo systemctl status ledmatrix-wifi-monitor

You should see output indicating the service is active and running.

Usage

Accessing the WiFi Setup Interface

1. If WiFi is NOT connected: The Raspberry Pi will automatically create an access point (after a 90-second grace period)

   • Connect to the WiFi network: LEDMatrix-Setup (open network, no password required)
   • Open a web browser and navigate to: http://192.168.4.1:5000 or http://192.168.4.1 (captive portal may redirect)
   • Or use the IP address shown in the web interface

2. If WiFi IS connected: Access the web interface normally

   • Navigate to: http://<raspberry-pi-ip>:5000
   • Click on the WiFi tab in the navigation

Connecting to a WiFi Network

1. Navigate to the WiFi tab in the web interface
2. Click Scan to search for available networks
3. Select a network from the dropdown menu, or enter the SSID manually
4. Enter the WiFi password (leave empty for open networks)
5. Click Connect
6. The system will attempt to connect to the selected network
7. Once connected, AP mode will automatically disable

Manual AP Mode Control

You can manually enable or disable AP mode from the web interface:

• Enable AP Mode: Click "Enable AP Mode" button (only available when WiFi is not connected)
• Disable AP Mode: Click "Disable AP Mode" button (only available when AP mode is active)

How It Works

WiFi Monitor Daemon

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

1. Checks WiFi connection status every 30 seconds (configurable)
2. Automatically enables AP mode only if:
   • auto_enable_ap_mode is enabled in config AND
   • No WiFi connection is detected AND
   • No Ethernet connection is detected
3. Automatically disables AP mode when WiFi or Ethernet connection is established
4. Logs all state changes for troubleshooting

Note: By default, auto_enable_ap_mode is true, meaning AP mode will automatically activate when both WiFi and Ethernet are disconnected. However, there's a 90-second grace period (3 consecutive checks at 30-second intervals) to prevent AP mode from enabling on transient network hiccups. This ensures you can always configure the device even when it has no network connection.

WiFi Manager Module

The WiFi manager (src/wifi_manager.py) provides:

• Connection Status: Checks current WiFi connection state
• Network Scanning: Scans for available WiFi networks
• Connection Management: Connects to WiFi networks and saves credentials
• AP Mode Control: Manages access point mode (hostapd/dnsmasq)

Configuration

WiFi settings are stored in config/wifi_config.json:

{
  "ap_ssid": "LEDMatrix-Setup",
  "ap_password": "ledmatrix123",
  "ap_channel": 7,
  "auto_enable_ap_mode": true,
  "saved_networks": [
    {
      "ssid": "MyNetwork",
      "password": "mypassword",
      "saved_at": 1234567890.0
    }
  ]
}

Configuration Options:

• ap_ssid: SSID for the access point (default: "LEDMatrix-Setup")
• ap_channel: WiFi channel for AP mode (default: 7)
• auto_enable_ap_mode: Automatically enable AP mode when WiFi/Ethernet disconnect (default: true)
  • When true: AP mode automatically enables after a 90-second grace period when both WiFi and Ethernet are disconnected
  • When false: AP mode must be manually enabled through the web interface
• saved_networks: List of saved WiFi network credentials

Note: The access point is configured as an open network (no password required) for ease of initial setup. This allows any device to connect without credentials.

Access Point Configuration

The AP mode uses hostapd and dnsmasq for access point functionality:

• SSID: LEDMatrix-Setup (configurable)
• IP Range: 192.168.4.2 - 192.168.4.20
• Gateway: 192.168.4.1
• Channel: 7 (configurable)

Verification

Running the WiFi Verification Script

Use the comprehensive verification script to check your WiFi setup:

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

This script checks:

• Required packages are installed
• WiFi monitor service is running
• Configuration files are valid
• WiFi permissions are configured
• WiFi interface is available
• WiFi radio status
• Current connection status
• AP mode status
• WiFi Manager module availability
• Web interface API accessibility

The script provides a summary with passed/warning/failed checks to help diagnose issues.

Troubleshooting

WiFi Monitor Service Not Starting

Check the service logs:

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

Common issues:

• Missing packages (hostapd, dnsmasq)
• Permission issues
• Network interface not available

Cannot Access AP Mode

1. Check if AP mode is active:

   sudo systemctl status hostapd
   

2. Check if dnsmasq is running:

   sudo systemctl status dnsmasq
   

3. Verify WiFi interface exists:

   ip link show wlan0
   

Cannot Connect to WiFi Network

1. Verify the SSID and password are correct

2. Check if the network requires a password (some networks may appear open but require a password)

3. Check WiFi monitor logs for connection errors:

   sudo journalctl -u ledmatrix-wifi-monitor -f
   

4. Check NetworkManager logs:

   sudo journalctl -u NetworkManager -n 50
   

AP Mode Not Disabling

If AP mode doesn't disable after connecting to WiFi:

1. Check WiFi connection status:

   nmcli device status
   

2. Manually disable AP mode from the web interface

3. Restart the WiFi monitor service:

   sudo systemctl restart ledmatrix-wifi-monitor
   

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

Configuration Options

You can modify the check interval by editing the service file:

sudo systemctl edit ledmatrix-wifi-monitor

Or modify the service file directly:

sudo nano /etc/systemd/system/ledmatrix-wifi-monitor.service

Change the --interval parameter in the ExecStart line (default is 30 seconds).

After modifying, reload and restart:

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

Security Considerations

• Open AP Network: The access point is configured as an open network (no password) for ease of initial setup. This allows any device within range to connect to the setup network. Consider your deployment environment when using this feature.
• WiFi Credentials: Saved WiFi credentials are stored in config/wifi_config.json. Ensure proper file permissions:

  sudo chmod 600 config/wifi_config.json
  

• Network Access: When in AP mode, anyone within range can connect to the setup network. This is by design to allow easy initial configuration. For production deployments in secure environments, consider using the web interface when connected to WiFi instead.

API Endpoints

The WiFi setup feature exposes the following API endpoints:

• 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

Technical Details

WiFi Detection Methods

The WiFi manager tries multiple methods to detect WiFi status:

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

Network Scanning

The system supports multiple scanning methods:

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

Access Point Setup

AP mode configuration:

• Uses hostapd (preferred) or nmcli hotspot (fallback) for WiFi access point functionality
• Uses dnsmasq for DHCP and DNS services (hostapd mode only)
• Configures wlan0 interface in AP mode
• Provides DHCP range: 192.168.4.2-20
• Gateway IP: 192.168.4.1
• Open network: No password required (configures as open network for easy setup)
• Captive portal: DNS redirection for automatic browser redirects (hostapd mode only)

Development

Testing WiFi Manager

You can test the WiFi manager directly:

from src.wifi_manager import WiFiManager

# Create WiFi manager instance
wifi_manager = WiFiManager()

# Get status
status = wifi_manager.get_wifi_status()
print(f"Connected: {status.connected}, SSID: {status.ssid}")

# Scan networks
networks = wifi_manager.scan_networks()
for net in networks:
    print(f"{net.ssid}: {net.signal}% ({net.security})")

# Connect to network
success, message = wifi_manager.connect_to_network("MyNetwork", "password")
print(f"Connection: {success}, Message: {message}")

Running Monitor Daemon Manually

For testing, you can run the daemon in foreground mode:

sudo python3 wifi_monitor_daemon.py --interval 10 --foreground

Support

For issues or questions:

1. Check the logs: sudo journalctl -u ledmatrix-wifi-monitor -f
2. Review this documentation
3. Check the main project README for general troubleshooting
4. Open an issue on GitHub if needed