Never get locked out of your Raspberry Pi again. PiFi automatically creates a WiFi hotspot with a web-based configuration portal whenever your Pi can't connect to a known network. Perfect for headless setups, IoT projects, and taking your Pi on the go.
✨ Zero configuration • 🔄 Auto AP fallback • 📱 Captive portal • 🎯 Built for Pi OS Bookworm
- 🔄 Automatic Mode Switching - Seamlessly switches between WiFi client and access point modes
- 📱 Captive Portal - Mobile-friendly web interface that auto-opens on connection
- 🔍 Network Scanner - Shows available WiFi networks with signal strength
- 💾 Multi-Network Support - Remembers and auto-connects to known networks
- 🔒 Secure - Optional WPA2 password protection for AP mode
- ⚡ Fast Activation - AP mode ready in 20-30 seconds
- 🛠️ Reliable - Built on NetworkManager with comprehensive error handling
- 📊 Monitoring Tools - Built-in utilities for status checking and diagnostics
- Headless Pi Projects - No keyboard or monitor needed
- IoT Deployments - Self-configuring remote devices
- Mobile Projects - Robots, drones, portable devices
- Multi-Location Setups - Home, office, workshop
- Education - Easy setup for students and workshops
- Gifts - Non-technical users can configure easily
git clone https://github.com/arnold256/pifi.git
cd pifi
sudo ./install.shThen reboot:
sudo reboot- Wait 20-30 seconds after boot
- Connect to WiFi network:
PiConfigAP(from your phone/laptop) - Configure - Browser opens automatically to http://192.168.4.1
- Enter your WiFi credentials and click "Save & Connect"
- Done! Pi connects to your WiFi, AP disappears
┌─────────────────────────────────────────────────────────┐
│ Boot → Check for WiFi → Found? → Connect → Monitor │
│ │ │
│ ↓ Not Found │
│ Create Access Point │
│ │ │
│ ↓ │
│ User Connects to AP │
│ │ │
│ ↓ │
│ Portal Opens Automatically │
│ │ │
│ ↓ │
│ User Enters WiFi Credentials │
│ │ │
│ ↓ │
│ Pi Connects → AP Stops → Success! │
│ │ │
│ Connection Lost? ─┐ │
│ │ │
│ ┌────────────────────────┘ │
│ └──→ Start AP Again (Automatic) │
└─────────────────────────────────────────────────────────┘
- Raspberry Pi with WiFi (Zero 2 W, 3B+, 4B, 5)
- SD card with 100MB+ free space
- Power supply
- Raspberry Pi OS Bookworm (2023+)
- NetworkManager 1.42+
- Python 3.9+
- Installation Guide - Detailed installation instructions
- Quick Start Guide - Get running in 5 minutes
- User Guide - Complete usage documentation
- Troubleshooting - Common issues and solutions
- API Reference - For advanced users and developers
# Set custom AP name and password
sudo AP_SSID="MyPiAP" AP_PASSWORD="MySecurePass123" ./install.sh# Check status
./scripts/pifi-status.sh
# Watch logs
sudo journalctl -u wifi-manager -f
# Run diagnostics
sudo ./scripts/pifi-verify.sh# Start AP manually
sudo nmcli connection up pi-hotspot
# Connect to specific network
sudo nmcli device wifi connect "SSID" password "PASSWORD"
# List saved networks
nmcli connection showPiFi consists of two main components:
-
WiFi Manager (
wifi_manager.py)- Monitors WiFi connection state
- Manages automatic switching between modes
- Handles connection attempts and retries
-
Configuration Portal (
config_portal.py)- Flask-based web server
- Network scanning and display
- WiFi credential management
- Captive portal detection endpoints
Both services run as systemd daemons and use NetworkManager for all network operations.
| OS Version | Status | Notes |
|---|---|---|
| Bookworm (Debian 12) | ✅ Fully Supported | Recommended |
| Hardware | Status | Notes |
|---|---|---|
| Pi Zero 2 W | ✅ Tested | Primary test platform |
sudo systemctl status wifi-manager
sudo journalctl -u wifi-manager -n 50
sudo nmcli connection up pi-hotspotsudo systemctl restart config-portal
curl http://192.168.4.1nmcli connection show
sudo journalctl -u wifi-manager -fSee Troubleshooting Guide for more details.
See CHANGELOG.md for version history.
This project is licensed under the MIT License - see the LICENSE file for details.