Browser-friendly Linux service that makes it easy for users to get headless Raspberry Pis onto their own WiFi
C Python Makefile C++ Shell Java Other
Switch branches/tags
Nothing to show
Clone or download


Installation directory: /etc/rpi-softap

This software makes it easy to create a Raspberry Pi-based product that can be connected to any WiFi network without any keyboards or screens by establishing a browser-friendly SoftAP HTTP service.

  • If the RPi is not online (or at the touch of a GPIO-connected button) it will create its own WiFi SSID (a "SoftAP") that users can connect to from their smartphone or computer.
  • While connected to this network, the RPi will provide a simple REST server at that provides end points to GET a list nearby WiFi networks, or to POST an SSID/password combo that the RPi will then remember and automatically connect to.
  • Also included is logic that will control a neopixel WS121* strip which will automatically indicate the state of the WiFi connection (i.e. not configured, working, connecting, online).


Command Action
sudo systemctl start rpi-softap.service Manually start the SoftAP daemon
sudo systemctl stop rpi-softap.service Manually stop the SoftAP daemon
sudo systemctl enable rpi-softap.service Run rpi-softap on boot (default)
sudo systemctl disable rpi-softap.service Do not run rpi-softap on boot
  • If there are existing WiFi credentials saved, the RPi will attempt to connect using those.
  • If the RPi connection attempt goes on infinitely, you either entered incorrect password or the WiFi network is not in range. Press the SETUP button to enter setup mode.


First, make sure the RPi is online already. The installation script will need to reach the internet to get some linux packages as well as some node modules from NPM.

Then, on the RPi:

git clone
sudo cp -r rpi-softap /etc/rpi-softap
sudo /etc/rpi-softap/scripts/install

Note that installation can take a while as the GPIO node modules must be compiled and NodeJS is installed.



Almost all configuration parameters are defined by the file settings.json.

Settings Property Purpose
server.port The port that the RPi's HTTP setup server will listen on while in SoftAP mode.
server.ssid This string specifies the name of the AP SSID that the RPi will broadcast during setup.
neopixels.enabled A boolean; if false, you can optionally disable neopixels.
neopixels.size This is the number of pixels in the Neopixels WS281x strip connected to GPIO pin 12.
setup_button_pin This is the GPIO pin that the SETUP button is connected to. Default is pin 2.


The actions setting object provides you the option of running scripts once the RPi is online, or immediately before setup.


This script should launch your application code -- the stuff you are actually interested in running once the RPi is online! This script is executed as soon as the RPi has acquired a valid IP address from the WiFi access point.


This script is run right after the SETUP button is pressed, and immediately before SoftAP is configured. You can use this opportunity to e.g. kill any processes that might throw errors or crash if the network interfaces are changed and/or reconfigured (as will happen during SoftAP config).

Notes on Drivers

If you are using a wireless chipset that doesn't seem to be working well with Raspbian's default nl80211 drivers, read on for more information.

A general guide to compiling hostapd against various drivers can be found here:

This information is largely based off the following advice and tutorials.

Realtek - 8188CUS (Default Rpi dongle)

Get Driver

These guys require a special version of the hostapd driver for their chipset. The necessary driver has already been downloaded into the resources folder of this repo and decompressed.

The original is available at the Realtek website -- make sure to pick the 8188CUS chipset.

Install Driver

cd resources/RTL8188C_8192C_USB_linux_v4.0.2_9000.20130911/wpa_supplicant_hostapd/wpa_supplicant_hostapd-0.8_rtw_r7475.20130812/hostapd
sudo make install