LEDMatrix/docs/archive/CAPTIVE_PORTAL_TESTING.md

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

Quick recovery script: sudo ./scripts/emergency_reconnect.sh

Pre-Testing Setup

0. Verify WiFi is Ready (IMPORTANT!)

⚠️ CRITICAL: Run this BEFORE disconnecting Ethernet!

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

sudo systemctl status ledmatrix-wifi-monitor

If not running:

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:

# 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:

python3 -c "from src.wifi_manager import WiFiManager; wm = WiFiManager(); print(wm.enable_ap_mode())"

Or via API:

curl -X POST http://localhost:5000/api/v3/wifi/ap/enable

4. Verify AP Mode is Active

# 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

# 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

# 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:

   # 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:

# 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:

# 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:

   sudo cat /etc/dnsmasq.conf | grep address
   

2. Restart dnsmasq:

   sudo systemctl restart dnsmasq
   

3. Check dnsmasq logs:

   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:

   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:

   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:

   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:

   sudo systemctl status ledmatrix-wifi-monitor
   

2. Check WiFi config:

   cat config/wifi_config.json
   

3. Manually enable AP mode:

   python3 -c "from src.wifi_manager import WiFiManager; wm = WiFiManager(); print(wm.enable_ap_mode())"
   

4. Check hostapd logs:

   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:

#!/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:

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.