LEDMatrix/docs/archive/CAPTIVE_PORTAL_TROUBLESHOOTING.md

Captive Portal Troubleshooting Guide

Problem: Can't Access Web Interface When Connected to AP

If you've connected to the "LEDMatrix-Setup" WiFi network but can't access the web interface, follow these steps:

Quick Checks

1. Verify Web Server is Running

sudo systemctl status ledmatrix-web

If not running:

sudo systemctl start ledmatrix-web
sudo systemctl enable ledmatrix-web

2. Try Direct IP Access

On your phone/device, try accessing the web interface directly:

• http://192.168.4.1:5000/v3
• http://192.168.4.1:5000

The port :5000 is required - the web server runs on port 5000, not the standard port 80.

3. Check DNS Resolution

The captive portal uses DNS redirection. Try accessing:

• http://captive.apple.com (should redirect to setup page)
• http://www.google.com (should redirect to setup page)
• http://192.168.4.1:5000 (direct access - should always work)

4. Verify AP Mode is Active

sudo systemctl status hostapd
sudo systemctl status dnsmasq
ip addr show wlan0 | grep 192.168.4.1

All should be active/running.

5. Check Firewall

If you have a firewall enabled, ensure port 5000 is open:

# For UFW
sudo ufw allow 5000/tcp

# For iptables
sudo iptables -A INPUT -p tcp --dport 5000 -j ACCEPT

Common Issues

Issue: "Can't connect to server" or "Connection refused"

Cause: Web server not running or not listening on the correct interface.

Solution:

sudo systemctl start ledmatrix-web
sudo systemctl status ledmatrix-web

Issue: DNS not resolving / "Server not found"

Cause: dnsmasq not running or DNS redirection not configured.

Solution:

# Check dnsmasq
sudo systemctl status dnsmasq

# Restart AP mode
cd ~/LEDMatrix
python3 -c "from src.wifi_manager import WiFiManager; wm = WiFiManager(); wm.disable_ap_mode(); wm.enable_ap_mode()"

Issue: Page loads but shows "Connection Error" or blank page

Cause: Web server is running but Flask app has errors.

Solution:

# Check web server logs
sudo journalctl -u ledmatrix-web -n 50 --no-pager

# Restart web server
sudo systemctl restart ledmatrix-web

Issue: Phone connects but browser doesn't open automatically

Cause: Some devices don't automatically detect captive portals.

Solution: Manually open browser and go to:

• http://192.168.4.1:5000/v3
• Or try: http://captive.apple.com (iOS) or http://www.google.com (Android)

Testing Steps

1. Disconnect Ethernet from Pi
2. Wait 30 seconds for AP mode to start
3. Connect phone to "LEDMatrix-Setup" network (password: ledmatrix123)
4. Open browser on phone
5. Try these URLs:
   • http://192.168.4.1:5000/v3 (direct access)
   • http://captive.apple.com (iOS captive portal detection)
   • http://www.google.com (should redirect)

Automated Troubleshooting

Run the troubleshooting script:

cd ~/LEDMatrix
./scripts/troubleshoot_captive_portal.sh

This will check all components and provide specific fixes.

Manual AP Mode Test

To manually test AP mode (bypassing Ethernet check):

cd ~/LEDMatrix
python3 -c "
from src.wifi_manager import WiFiManager
wm = WiFiManager()

# Temporarily disconnect Ethernet check
# (This is for testing only - normally AP won't start with Ethernet)
print('Enabling AP mode...')
result = wm.enable_ap_mode()
print('Result:', result)
"

Note: This will fail if Ethernet is connected (by design). You must disconnect Ethernet first.

Still Not Working?

1. Check all services:

   sudo systemctl status ledmatrix-web hostapd dnsmasq ledmatrix-wifi-monitor
   

2. Check logs:

   sudo journalctl -u ledmatrix-web -f
   sudo journalctl -u ledmatrix-wifi-monitor -f
   

3. Verify network configuration:

   ip addr show wlan0
   ip route show
   

4. Test from Pi itself:

   curl http://192.168.4.1:5000/v3
   

If it works from the Pi but not from your phone, it's likely a DNS or firewall issue.