Skip to content

README.md

Latest commit

 

History

History
197 lines (145 loc) · 10.5 KB

README.md

File metadata and controls

197 lines (145 loc) · 10.5 KB

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.