If you are interested in contributing to this project please use the https://github.com/txn2/txwifi fork. This version is archived for refrence.

Update 2018-12-01. I am archiving this project. The original use case was to enable the configuration of wifi, over wifi, like many IOT devices on the market. It has worked well for me for this purpose. However, many of the issues people have been reporting as bugs are simply other opinions on how it should work for them, and outside of the original use case. Unfortunately, I don't have the personal resources to help in these requests. If others are willing to be contributors I would be grateful; until then, this project is for reference only.

Update: Looking for contributors / maintainers.

NOTICE: This project is intended to aid in developing "configure wifi over wifi" solutions for IOT projects using the Raspberry Pi. The main use case for this project is to reproduce functionality common to devices like Nest or Echo, where the user turns on the device, connects to it and configures it for wifi. I have over 800 devices running this software in production and all have had their wifi configured using it.

This is not a captive portal project. While I have personaly used it for this, it requires additional networking and can be unstable. I don't support this use and so your millage may vary.

iotwifi is only expected to run properly on stock Raspberry Pis and not tested on any other hardware configurations.

IOT Wifi (Raspberry Pi AP + Client)

IOT Wifi is very small/8MB Docker Container built for the Raspberry Pi 3. IOT Wifi exposes a simple JSON based REST API for controlling the wireless network interface. This container allows the Raspberry Pi to accept wifi connections as an access point (aka AP) while at the same time connecting to an existing wifi network (station mode).

Go (Golang) was used to develop the main application code, to produce a minimal docker image with great performance. The container runs Alpine Linux with small, optimized versions of hostapd, wpa_supplicant and dnsmasq, controlled by the container's API endpoints.

If you have a Raspberry Pi 3 and you want to provide wifi based configuration abilities, all you need is Docker installed and a little over 8MB of free drive space.

Table of Contents

• IOT Wifi (Raspberry Pi AP Client)
  • Background
  • Getting Started
    • Disable wpa_supplicant on Raspberry Pi
    • Install Docker on Raspberry Pi
    • Pull the IOT Wifi Docker Image
    • IOT Wifi Configuration
    • Run The IOT Wifi Docker Container
    • Connect to the Pi over Wifi
    • Connect the Pi to a Wifi Network
    • Check the network interface status
    • Conclusion

TL;DR? If you are not interested in reading all this, you can skip ahead to Getting Started.

IOT Wifi is a Raspberry Pi wifi management REST service written in Go and intended to run in a Docker container on a Raspberry Pi.

IOT Wifi sets up network interfaces, runs hostapd, wpa_supplicant and dnsmasq to run simultaneously, allowing a user (or another service) to connect to the Raspberry Pi via hostapd/dnsmasq and issue commands that configure and connect wpa_supplicant to another AP. IOT Wifi then exposes a small web server on the Pi and offers a JSON based REST API to configure Wifi. The IOT Wifi container allows you to build a custom Captive Portal web page or even programmatically connect from another device and use the exposed API to configure the target device.

Using wifi to configure a wifi connection is often a standard requirement for IOT. As Raspberry Pis are becoming a popular choice as an IOT platform, this helps solve the frequent need to manage AP and Station modes.

Background

Over a year ago I wrote a blog post called RASPBERRY PI 3 - WIFI STATION+AP with my notes on setting up a Raspberry Pi 3 to run as a Wifi Access Point (Hotspot) and a Wifi Client (aka Wifi Station) simultaneously. This old blog post gets a considerable amount of traffic, so it seems there is quite a bit of interest in this. I have come to realize that some of the steps in my old post have changed since newer versions of Raspian (n00bs build) are released.

Since writing the post, I have had a few personal and professional projects requiring a Raspberry Pi to allow wifi setup over wifi. I decided to open source this simple project to help others with similar requirements as well as gain some feedback on where and how I can improve it. I would welcome any contribution and credit any contributors.

Getting Started

You will need a Raspberry Pi 3, running Raspian Stretch. You can use the Noobs release to install the latest version of Raspian.

Disable wpa_supplicant on Raspberry Pi

You do not want the default wpa_supplicant (the software that communicates with the wifi driver and connects to Wifi networks,) running and competing with the IOT Wifi container.

# prevent wpa_supplicant from starting on boot
$ sudo systemctl mask wpa_supplicant.service

# rename wpa_supplicant on the host to ensure that it is not
# used.
sudo mv /sbin/wpa_supplicant /sbin/no_wpa_supplicant

# kill any running processes named wpa_supplicant
$ sudo pkill wpa_supplicant

Install Docker on Raspberry Pi

Ssh into the Pi or use the terminal application from the desktop on the Pi to get a Bash shell.

# Docker install script
$ curl -sSL https://get.docker.com | sh

# add pi user to Docker user group
$ sudo usermod -aG docker pi

Reboot the Pi and test Docker.

$ sudo reboot

After reboot, ensure Docker is installed correctly by running a Hello World Docker container.

# run the Docker Hello World container and remove the container
# when finished (the --rm flag)
$ docker run --rm hello-world

Pull the IOT Wifi Docker Image

You can optionally clone and build the entire project, however, to get started quickly I'll show you how to use a pre-built Docker Image. At only 16MB this little image contains everything you need. The image is based on Alpine Linux and contains hostapd, wpa_supplicant and dnsmasq, along with a compiled wifi management utility written in go, the source is found in this repository: https://github.com/cjimti/iotwifi.

# Pull the IOT Wifi Docker Image
$ docker pull cjimti/iotwifi

IOT Wifi Configuration

You will need a configuration JSON file. You can download a default as a template or just it unmodified for testing. You can mount the configuration file into the container or specify a location with an environment variable.

Use the default configuration file and location for testing:

# Download the default configuration file

$ wget https://raw.githubusercontent.com/cjimti/iotwifi/master/cfg/wificfg.json

The default configuration looks like this:

{
    "dnsmasq_cfg": {
      "address": "/#/192.168.27.1",
      "dhcp_range": "192.168.27.100,192.168.27.150,1h",
      "vendor_class": "set:device,IoT"
    },
    "host_apd_cfg": {
       "ip": "192.168.27.1",
       "ssid": "iot-wifi-cfg-3",
       "wpa_passphrase":"iotwifipass",
       "channel": "6"
    },
      "wpa_supplicant_cfg": {
        "cfg_file": "/etc/wpa_supplicant/wpa_supplicant.conf"
    }
}

You may want to change the ssid (AP/Hotspot Name) and the wpa_passphrase to something more appropriate to your needs. However, the defaults are fine for testing.

Run The IOT Wifi Docker Container

The following docker run command will create a running Docker container from the cjimti/iotwifi Docker image we pulled in the steps above. The container needs to run in a privileged mode and have access to the host network (the Raspberry Pi device) to configure and manage the network interfaces on the Raspberry Pi. We will also need to mount the configuration file.

We will run it in the foreground to observe the startup process. If you want it to run the background, you need to remove the --rm and pass the -d flag. If you want to it restart on reboot or failure, you can pass the flag --restart=unless-stopped.

Read more on the docker run command.

$ docker run --rm --privileged --net host \
      -v $(pwd)/wificfg.json:/cfg/wificfg.json \
      cjimti/iotwifi

Optionally, you can also provide a wpa_supplicant.conf, like so:

$ docker run --rm --privileged --net host \
      -v $(pwd)/wificfg.json:/cfg/wificfg.json \
      -v <HOST_PATH>/wpa_supplicant.conf:<CONTAINER_PATH>/wpa_supplicant.conf \
      cjimti/iotwifi

Where <CONTAINER_PATH> is the path to wpa_supplicant.conf specified in wificfg.json.

The IOT Wifi container outputs logs in the JSON format. While this makes them a bit more challenging to read, we can feed them directly (or indirectly) into tools like Elastic Search or other databases for alerting or analytics.

You should see some initial JSON objects with messages like Starting IoT Wifi...:

{"hostname":"raspberrypi","level":30,"msg":"Starting IoT Wifi...","name":"iotwifi","pid":0,"time":"2018-03-15T20:19:50.374Z","v":0}

Keeping the current terminal open, you can log in to another terminal and take a look the network interfaces on the Raspberry Pi.

# use ifconfig to view the network interfaces
$ ifconfig

You should see a new interface called uap0:

uap0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
        inet 192.168.27.1  netmask 255.255.255.0  broadcast 192.168.27.255
        inet6 fe80::6e13:d169:b00b:c946  prefixlen 64  scopeid 0x20<link>
        ether b8:27:eb:fe:c8:ab  txqueuelen 1000  (Ethernet)
        RX packets 111  bytes 8932 (8.7 KiB)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 182  bytes 24416 (23.8 KiB)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

The standard wifi interface wlan0 should be available, yet unconfigured since we have not yet connected to an external wifi network (access point).

wlan0: flags=4099<UP,BROADCAST,MULTICAST>  mtu 1500
        ether b8:27:eb:fe:c8:ab  txqueuelen 1000  (Ethernet)
        RX packets 0  bytes 0 (0.0 B)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 0  bytes 0 (0.0 B)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

Connect to the Pi over Wifi

On your laptop or phone, you should now see a Wifi Network named iot-wifi-cfg-3 assuming you did not change it from the default. The default password for this network is iotwifipass. Once connected to this network you should get an IP address assigned to the range specified in the config: 192.168.27.100,192.168.27.150,1h.

Once connected open a web browser and go to http://192.168.27.1:8080/status. You can access this API endpoint on the Raspberry Pi device itself from localhost*. On on Pi try the curl command curl http://localhost:8080/status.

You should receive a JSON message similar to the following:

{"status":"OK","message":"status","payload":{"address":"b8:27:eb:fe:c8:ab","uuid":"a736659a-ae85-5e03-9754-dd808ea0d7f2","wpa_state":"INACTIVE"}}

From now on I'll demonstrate API calls to the new container with the curl command on the device. If you were developing a Captive Portal or configuration web page, you could translate these calls into Javascript and control the device Wifi with AJAX.

You can use my simple static web server IOT Web container for hosting a Captive Portal or configuration web page. See https://github.com/cjimti/iotweb.

To get a list of Wifi Networks the device can see, issue a call to the scan endpoint:

curl http://localhost:8080/scan

Connect the Pi to a Wifi Network

The device can connect to any network it can see. After running a network scan curl http://localhost:8080/scan you can choose a network and post the login credentials to IOT Web.

# post wifi credentials
$ curl -w "\n" -d '{"ssid":"home-network", "psk":"mystrongpassword"}' \
     -H "Content-Type: application/json" \
     -X POST localhost:8080/connect

You should get a JSON response message after a few seconds. If everything went well you will see something like the following:

{"status":"OK","message":"Connection","payload":{"ssid":"straylight-g","state":"COMPLETED","ip":"","message":""}}

You can get the status at any time with the following call to the status endpoint. Here is an example:

# get the wifi status
$ curl -w "\n" http://localhost:8080/status

Sample return JSON:

{"status":"OK","message":"status","payload":{"address":"b7:26:ab:fa:c9:a4","bssid":"50:3b:cb:c8:d3:cd","freq":"2437","group_cipher":"CCMP","id":"0","ip_address":"192.168.86.116","key_mgmt":"WPA2-PSK","mode":"station","p2p_device_address":"fa:27:eb:fe:c9:ab","pairwise_cipher":"CCMP","ssid":"straylight-g","uuid":"a736659a-ae85-5e03-9754-dd808ea0d7f2","wpa_state":"COMPLETED"}}

Check the network interface status

The wlan0 is now a client on a wifi network. In this case, it received the IP address 192.168.86.116. We can check the status of wlan0 with ifconfig*

# check the status of wlan0 (wireless interface)
$ ifconfig wlan0

Example return.

wlan0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
        inet 192.168.86.116  netmask 255.255.255.0  broadcast 192.168.86.255
        inet6 fe80::9988:beab:290e:a6af  prefixlen 64  scopeid 0x20<link>
        ether b8:27:eb:fe:c8:ab  txqueuelen 1000  (Ethernet)
        RX packets 547  bytes 68641 (67.0 KiB)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 36  bytes 6025 (5.8 KiB)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

We can also check the connection by issuing a ping command from the device and specify the network interface to use:

# ping out from the wlan0 interface
$ ping -I wlan0 8.8.8.8

Hit Control-C to stop the ping and get calculations.

PING 8.8.8.8 (8.8.8.8) from 192.168.86.116 wlan0: 56(84) bytes of data.
64 bytes from 8.8.8.8: icmp_seq=1 ttl=57 time=20.9 ms
64 bytes from 8.8.8.8: icmp_seq=2 ttl=57 time=23.4 ms
64 bytes from 8.8.8.8: icmp_seq=3 ttl=57 time=16.0 ms
^C
--- 8.8.8.8 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2002ms
rtt min/avg/max/mdev = 16.075/20.138/23.422/3.049 ms

Conclusion

Wrapping the all complexity of wifi management into a small Docker container, accessible over a web-based REST API reduces the dependencies on the device to only require Docker.

There are many ways to handle security using middleware or IP tables. A separate container can also manage security.

Check out the project IOT Web to get started with tiny a static web container suitable for building user interfaces for wifi management or captive portals.

Submit a Github issue or pull request if there are features or bug fixes you would like added to the project.