Headless WiFi Setup for Raspberry Pi 5

Easy WiFi configuration for Raspberry Pi 5 (Bookworm OS) without keyboard, mouse, or monitor.

⚠️ IMPORTANT: Recommended Solution

We now recommend using Comitup - a production-grade, battle-tested WiFi provisioning system instead of the custom solution in this repository.

Why Comitup?

• ✅ Stable - Years of production use
• ✅ Actively maintained - Regular updates
• ✅ Simple - Native Debian package
• ✅ Reliable - No connection loops or stability issues

Quick Installation (Comitup - Recommended)

# Clone the repository
git clone https://github.com/mokcontoro/headless_wifi_connect.git
cd headless_wifi_connect

# Install Comitup (production-grade solution)
sudo bash install_comitup.sh

Alternative: Custom Solution

If you prefer the custom solution (not recommended for production):

# Install custom WiFi portal
sudo bash install.sh

Note: The custom solution may experience stability issues. See MIGRATION_TO_COMITUP.md for details.

User Instructions

1. Power on your Raspberry Pi
2. Wait 30 seconds for the WiFi network to appear
3. Connect to the network named wifi_connect_cam-XXXX (password: smartcam)
4. Web portal opens automatically (or visit http://192.168.4.1)
5. Enter your WiFi credentials and click Connect
6. Done! The Pi will connect to your network

Features

• ✅ Raspberry Pi 5 Bookworm OS compatible
• ✅ No additional hardware required
• ✅ Works with any smartphone or tablet
• ✅ Automatic captive portal
• ✅ Supports hidden networks
• ✅ Network priority management
• ✅ Automatic fallback to AP mode on WiFi failure

How It Works

1. On first boot (or if WiFi fails), Pi creates a WiFi hotspot
2. Users connect and configure WiFi through a web interface
3. Pi connects to the configured network
4. If connection fails, AP mode is restored automatically

Project Structure

headless_wifi_connect/
├── install.sh                 # Installation script
├── setup_ap.sh               # AP mode setup script
├── wifi_portal/              # Web portal application
│   ├── app.py               # Flask backend
│   ├── templates/           # HTML templates
│   │   └── index.html      # Configuration page
│   └── static/             # CSS/JS assets
├── systemd/                 # System services
│   ├── wifi-portal.service # Web portal service
│   └── wifi-check.service  # WiFi watchdog service
└── scripts/                # Utility scripts
    ├── check_wifi.sh       # WiFi connection checker
    └── configure_wifi.sh   # NetworkManager config script

Requirements

• Raspberry Pi 5
• Raspberry Pi OS Bookworm (64-bit recommended)
• NetworkManager (pre-installed in Bookworm)
• Python 3.11+
• Flask (python3-flask)

Advanced Configuration

Customizing AP Network Name

Edit setup_ap.sh and change the SSID:

AP_SSID="YourCustomName-${DEVICE_ID}"

Customizing AP Password

Edit setup_ap.sh and change the password:

AP_PASSWORD="smartcam"

Network Priority

The system assigns priority 200 to user-configured networks (higher than default). To modify, edit scripts/configure_wifi.sh.

Troubleshooting

Portal doesn't open automatically

Visit http://192.168.4.1 in your browser manually.

Can't connect to hotspot

• Check if WiFi interface is enabled
• Run: sudo nmcli radio wifi on
• Restart the service: sudo systemctl restart wifi-portal

WiFi credentials not working

• Verify password is correct
• Check if network is in range
• View logs: sudo journalctl -u wifi-portal -f

Connection Loop (AP connects/disconnects repeatedly)

If your Pi is stuck in a connection loop:

# Run diagnostic script
sudo bash diagnose_wifi.sh

# Or run emergency fix
sudo bash emergency_fix.sh

Common causes:

• AP connection has autoconnect enabled (should be disabled)
• WiFi checker service switching too quickly
• Race condition between services

Manual fix:

# Stop services
sudo systemctl stop wifi-check

# Fix AP settings
sudo nmcli connection modify WiFi-Setup-AP connection.autoconnect no

# Clean state
sudo rm -f /var/run/wifi-checker.state
sudo rmdir /var/lock/wifi-checker.lock 2>/dev/null || true

# Restart
sudo systemctl start wifi-portal
sudo systemctl start wifi-check

System stuck in emergency mode

The system enters emergency mode if it detects rapid connection loops (protection mechanism).

• Emergency mode lasts 10 minutes
• AP will remain active for reconfiguration
• Check logs: sudo journalctl -u wifi-check --since "15 minutes ago"
• Wait for emergency mode to expire, or manually clear: sudo rm -f /var/run/wifi-checker.state.emergency_until

Diagnostic Tools

Run comprehensive diagnostic:

sudo bash diagnose_wifi.sh > diagnostic_report.txt

Check service status:

sudo systemctl status wifi-portal wifi-check

View real-time logs:

# WiFi checker
sudo journalctl -u wifi-check -f

# NetworkManager
sudo journalctl -u NetworkManager -f

# Configuration attempts
sudo tail -f /var/log/wifi-config.log

License

MIT License - See LICENSE file for details

Contributing

Contributions welcome! Please open an issue or pull request.