OpenA3XX Hardware WiFi Portal

A minimal WiFi onboarding portal for OpenA3XX devices. When provisioning is required, the device switches to Access Point (AP) mode, hosts a simple web portal, captures WiFi credentials, writes /etc/wpa_supplicant/wpa_supplicant.conf, and reboots into client mode.

The stack is based on hostapd (AP), dnsmasq (DHCP/DNS with captive-style redirect), and a small Flask app for the portal UI.

Features

• AP onboarding flow: Boot into AP mode when WiFi is not configured or when a marker file exists.
• Captive-style DNS redirect: All DNS queries resolve to 10.0.0.1 while in AP mode.
• Simple web portal: Collects country code, SSID, and password; persists to wpa_supplicant and reboots.
• Systemd integration: Services automatically manage AP/client mode transitions on boot.

Requirements

• OS: Debian/Ubuntu/Raspberry Pi OS or other systemd-based Debian derivative
• Network interface: A wireless interface named wlan0 with nl80211 compatible driver
• Privileges: Root access for installation and service management

Packages installed by the installer: hostapd, dnsmasq, python3-flask, wireless-tools, iproute2.

Quick Start

1. Install (as root):

   sudo bash install.sh

2. Trigger provisioning mode and reboot:

   sudo touch /boot/PROVISION_WIFI && sudo reboot

3. Connect to the AP:
   • SSID: OpenA3XX_Setup
   • Password: opena3xx
4. Open http://10.0.0.1 in a browser. Submit your WiFi credentials. The device will reboot and attempt to join the configured WiFi.

How It Works

• systemd services

  • opena3xx-boot.service: Runs on boot and decides the mode based on presence of /boot/PROVISION_WIFI or an empty /etc/wpa_supplicant/wpa_supplicant.conf.
  • wifi-portal.service: Runs the Flask portal on port 80 when in AP mode.

• Boot decision logic (opt/opena3xx-provision/scripts/boot_selector.sh)

  • If provisioning is required, starts AP mode via start_ap.sh.
  • Otherwise ensures client mode (stops hostapd/dnsmasq, starts dhcpcd/wpa_supplicant).

• AP setup (opt/opena3xx-provision/scripts/start_ap.sh)

  • Stops wpa_supplicant/dhcpcd, configures wlan0 as 10.0.0.1/24.
  • Ensures hostapd reads /etc/hostapd/hostapd.conf.
  • Restarts dnsmasq, hostapd, and wifi-portal.service.

• Portal (opt/opena3xx-provision/wifi_portal.py and templates/index.html)

  • Serves a form on / (port 80) to collect country, ssid, and password.
  • Writes /etc/wpa_supplicant/wpa_supplicant.conf (mode 600), removes /boot/PROVISION_WIFI if present, and reboots.

• Network services configuration

  • etc/hostapd/hostapd.conf: AP config (default SSID OpenA3XX_Setup, passphrase opena3xx, country MT).
  • etc/dnsmasq.d/opena3xx-setup.conf: DHCP range 10.0.0.2–10.0.0.50 and DNS override to 10.0.0.1.

Files Installed by install.sh

• opt/opena3xx-provision/scripts/start_ap.sh → /opt/opena3xx-provision/scripts/start_ap.sh
• opt/opena3xx-provision/scripts/boot_selector.sh → /opt/opena3xx-provision/scripts/boot_selector.sh
• opt/opena3xx-provision/wifi_portal.py → /opt/opena3xx-provision/wifi_portal.py
• opt/opena3xx-provision/templates/index.html → /opt/opena3xx-provision/templates/index.html
• opt/opena3xx-provision/systemd/wifi-portal.service → /etc/systemd/system/wifi-portal.service
• opt/opena3xx-provision/systemd/opena3xx-boot.service → /etc/systemd/system/opena3xx-boot.service
• etc/hostapd/hostapd.conf → /etc/hostapd/hostapd.conf
• etc/dnsmasq.d/opena3xx-setup.conf → /etc/dnsmasq.d/opena3xx-setup.conf

Installer actions:

• Installs required packages
• Appends denyinterfaces wlan0 to /etc/dhcpcd.conf (if not present)
• Unmasks/enables hostapd
• Enables wifi-portal.service and opena3xx-boot.service

Service Management

Check status:

sudo systemctl status opena3xx-boot.service
sudo systemctl status wifi-portal.service
sudo systemctl status hostapd dnsmasq

Start/stop/restart:

sudo systemctl restart wifi-portal.service
sudo systemctl restart hostapd dnsmasq

Logs:

sudo journalctl -u opena3xx-boot.service -b | cat
sudo journalctl -u wifi-portal.service -b | cat

Customization

• AP SSID/passphrase: Edit /etc/hostapd/hostapd.conf (ssid, wpa_passphrase, country_code, channel). Restart hostapd.
• DHCP/DNS: Edit /etc/dnsmasq.d/opena3xx-setup.conf (IP range, address=/#/10.0.0.1). Restart dnsmasq.
• Default country code: Change default_country in templates/index.html or the fallback in wifi_portal.py.
• Provision marker: The portal and boot logic use /boot/PROVISION_WIFI. You can change this path in the scripts/python if desired.
• Interface name: The scripts assume wlan0. If your interface differs, update scripts/configs accordingly.

Troubleshooting

• Cannot see the AP:
  • Ensure hostapd is enabled and running; check sudo systemctl status hostapd.
  • Verify your wireless chipset supports AP mode with nl80211.
• Connected to AP but no portal:
  • Browse directly to http://10.0.0.1.
  • Check wifi-portal.service status and logs.
• Device doesn’t join WiFi after submit:
  • Verify /etc/wpa_supplicant/wpa_supplicant.conf contents and permissions (600).
  • Confirm SSID/password and country code are correct.
  • Recreate marker and retry: sudo touch /boot/PROVISION_WIFI && sudo reboot.

Uninstall

sudo systemctl disable --now wifi-portal.service opena3xx-boot.service
sudo rm -f /etc/systemd/system/wifi-portal.service /etc/systemd/system/opena3xx-boot.service
sudo rm -rf /opt/opena3xx-provision
sudo rm -f /etc/dnsmasq.d/opena3xx-setup.conf /etc/hostapd/hostapd.conf
sudo systemctl daemon-reload

Security Notes

• Default AP credentials are public (OpenA3XX_Setup / opena3xx). Change them for production.
• The portal runs over HTTP in AP mode; use only on the isolated setup network.
• WPA passphrase is written to wpa_supplicant.conf with restrictive permissions (600). Ensure the device remains physically secure.

Project Layout

• install.sh: Installer script
• etc/hostapd/hostapd.conf: AP configuration
• etc/dnsmasq.d/opena3xx-setup.conf: DHCP/DNS captive-style config
• opt/opena3xx-provision/scripts/start_ap.sh: Sets up AP mode and restarts services
• opt/opena3xx-provision/scripts/boot_selector.sh: Chooses AP or client mode on boot
• opt/opena3xx-provision/wifi_portal.py: Flask app serving the portal
• opt/opena3xx-provision/templates/index.html: Portal UI template
• opt/opena3xx-provision/systemd/*.service: Systemd service units

License

This project is licensed under CC0 1.0 Universal (Public Domain Dedication). See LICENSE for details.