Show me: a library for easy WiFi setup for non-dev end-users

General discussions and questions abound development of code with MicroPython that is not hardware specific.
Target audience: MicroPython Users.
Post Reply
User avatar
ghawkins
Posts: 5
Joined: Wed Mar 11, 2020 10:00 pm
Location: Zurich, Switzerland
Contact:

Show me: a library for easy WiFi setup for non-dev end-users

Post by ghawkins » Wed Jun 10, 2020 11:42 am

I'm a hobbyist and sometimes I create devices that I want to give away to non-developer friends. I created the library micropython-wifi-setup to allow them to connect such devices to their home WiFi networks without having to first connect a USB cable, configure things via the REPL or worry about things like IP addresses. Now they can do the setup with their smartphone or laptop, without needing to download an app first and the process is as easy as connecting to well setup public WiFi.

First some code then a walkthru, with screenshots, of the end-user experience...

1. Install this library on your MicroPython device and add the following to the start of your main.py:

Code: Select all

from wifi_setup.wifi_setup import WiFiSetup

# You should give every device a unique name (to use as its access point name).
ws = WiFiSetup("ding-5cd80b5")
sta = ws.connect_or_setup()
print("WiFi is setup")
Once the device is restarted, you're ready to connect it to the same WiFi network that you use with your phone and other devices.

2. Currently, your phone is on your home network Foobar Net.

Image

3. You go to WiFi settings.

Image

4. You look at your MicroPython device, which you labeled with the name you gave it in the Python code above.

Image

The eagle-eyed will notice the mismatch between "ding-5cd80b1" here and "ding-5cd80b5" seen elsewhere - I haven't updated this photo to match.

5. You plug in your device and see it appear as an open network in your WiFi settings.

Image

6. You select it and, like a network in a coffee shop or airport, you're told you have to log in.

Image

7. However, instead of a login screen, you're presented with a list of networks that your MicroPython device can see. You should select the network, i.e. Foobar Net, to which you want to connect your device.

Image

8. Once you select your network, you have to enter the network's WiFi password.

Image

9. By default the password is hidden.

Image

10. But you can click the visibility icon if you prefer the password to be visible as you type it.

Image

11. Once you click connect, it whirrs away for a while as your device attempts to connect to the network with the credentials you entered.

Image

12. If all goes well, it tells you that it has connected and displays the IP address (or anything you want) that the device now has on that network. You press the copy icon, to hang onto the IP address, and click the OK button.

Image

13. The device now shuts down the temporary WiFi network that was created for this setup process.

Image

14. With the temporary network now gone, the usual behavior of your phone is to automatically return you to your previous network, i.e Foobar Net.

Image

15. Now you return to your phone's main screen and select your web browser application, i.e. usually Chrome or Safari.

Image

16. You paste the IP address, that you copied earlier, into the web address field.

Image

17. For the purposes of this demo, your MicroPython device just serves up a web page of a cute little ghost hovering up and down.

Image

The entered credentials are stored on the device and the next time it is restarted it will reconnect to the network rather than starting the temporary WiFi network seen here for setup.

That's it. I hope others find the library useful. You can find the library, along with an in-depth README and more documentation, here on GitHub.

Credits: as with most projects, this one wouldn't have been possible without being able to build on the work done by others. In particular, this means the whole MicroPython development team and the creators of the libraries I've used, such as MicroWebSrv2 and MicroDNSSrv from Jean-Christophe Bos. For more credits and license details (this library, and all libraries it depends on, use the MIT license), see the project's README.

Notes

No other device or service is involved other than your phone and your MicroPython device, i.e. your MicroPython device serves the web pages involved to your phone and manages the whole login process.

You may notice a red lock icon in some of the screenshots, this indicates that the network involved is using WPA2 Enterprise which is not currently supported.

By default the IP address of your device is displayed when it successfully connects to the chosen network however, you can configure the code involved to return whatever you want, e.g. an MQTT topic name.

The dialog that presents you with the IP address uses a kind of dead man's switch logic in the background that keeps the temporary WiFi network alive as long as it's showing. So the temporary WiFi network will shut down if you explicitly close the dialog (by pressing OK) or if you e.g. simply manually switch back to your normal WiFi network.

The ghost is a tiny CSS demo by Helen V. Holmes and was found here.

kevinkk525
Posts: 755
Joined: Sat Feb 03, 2018 7:02 pm

Re: Show me: a library for easy WiFi setup for non-dev end-users

Post by kevinkk525 » Wed Jun 10, 2020 6:02 pm

This looks really nice and useful!
Kevin Köck
Micropython Smarthome Firmware (with Home-Assistant integration): https://github.com/kevinkk525/pysmartnode

User avatar
tve
Posts: 214
Joined: Wed Jan 01, 2020 10:12 pm
Location: Santa Barbara, CA
Contact:

Re: Show me: a library for easy WiFi setup for non-dev end-users

Post by tve » Thu Jun 11, 2020 4:33 am

Nice! Thanks for sharing!

User avatar
ghawkins
Posts: 5
Joined: Wed Mar 11, 2020 10:00 pm
Location: Zurich, Switzerland
Contact:

Re: Show me: a library for easy WiFi setup for non-dev end-users

Post by ghawkins » Thu Jun 11, 2020 7:42 pm

Thanks, Kevin and Thorsten. I put a really surprising amount of effort into making the whole thing feel as much like an app while being completely HTML based. At the start, I thought I'd have it all done in a weekend but, as the commit history shows, I rather underestimated the effort. It was interesting learning about the DNS redirection and other tricks involved in implementing the captive portals that trigger the login process that one sees when connecting to WiFi in coffee shops and airports. I really hope people find it useful and I'd love to hear about other people's experiences with it.

If anyone is trying out the setup steps using their laptop/desktop (rather than a phone), note that the captive portal behavior depends on the MicroPython board being able to redirect all DNS requests. This works very well with phones, but on laptops a lot of people (particularly the dev audience found here, I'd guess) have set their primary DNS to be something like Google's 8.8.8.8 or Cloudflare's 1.1.1.1, which means they bypass the DNS provided by the MicroPython board. For more on this (and what one can do in such a situation) see here. As noted there, one could spoof replies but this would require capabilities that are not currently exposed in MicroPython.

For those who don't know what a captive portal is (it was new to me), it's the behavior that makes the difference between your phone nicely popping up a sign-in notification (see picture) and just declaring that the network you're on has no internet connectivity - it's where things usually go wrong if you're connecting to badly setup hotel WiFi and the like.

Image

Post Reply