Setup Printer Wi-Fi

Fallback Wi-Fi provisioning for a Raspberry Pi with one wireless interface.

Normal behaviour:

1. NetworkManager attempts to connect to a saved Wi-Fi network.
2. If no Wi-Fi connection is available, the Pi broadcasts SETUP-PRINTER.
3. A phone connects to that hotspot and opens the captive portal.
4. The user enters the destination Wi-Fi credentials.
5. The Pi stops the hotspot, creates a NetworkManager connection, and connects.
6. If the connection fails, the setup hotspot returns.

Designed for Raspberry Pi OS Bullseye on a Raspberry Pi 3 A+, using:

• NetworkManager for normal Wi-Fi
• hostapd for setup access-point mode
• dnsmasq for setup DHCP and captive DNS
• Python 3 standard library for the portal
• systemd for orchestration

Install

git clone <repository-url>
cd setup-printer-wifi
sudo ./install.sh

The installer prompts for:

• Hotspot SSID, default SETUP-PRINTER
• Hotspot password
• Wi-Fi country, default GB
• Fallback timeout, default 45 seconds

Reboot after installation:

sudo reboot

Test setup mode

Remove all saved Wi-Fi profiles and start setup mode:

sudo setup-printer-reset

This disconnects Wi-Fi immediately. Do not run it over Wi-Fi SSH unless you have local console access.

Diagnostics

sudo setup-printer-status

Detailed logs:

sudo journalctl -u setup-printer-controller.service -b --no-pager
sudo journalctl -u setup-printer-portal.service -b --no-pager

Manual setup-mode start

sudo setup-printer-hotspot start

Return to client mode:

sudo setup-printer-hotspot stop
sudo systemctl restart NetworkManager

Configuration

Edit:

sudo nano /etc/setup-printer/config

Then restart:

sudo systemctl restart setup-printer-controller.service

Uninstall

sudo ./uninstall.sh

Important

This setup deliberately stops NetworkManager while the hotspot is active because the Raspberry Pi 3 A+ has one Wi-Fi interface. NetworkManager is restarted before applying submitted credentials.

The portal listens on TCP port 8080. dnsmasq redirects captive-portal HTTP traffic from port 80 to port 8080 using nftables or iptables. This avoids conflicts with nginx or Apache already using port 80 outside setup mode.