This repository contains a demo MicroPython application that can be used as a start point for any project where you want the user to be able to easily configure wifi connection on a Raspberry Pi Pico W. The demo makes use of Pimoroni's Phew! webserver and templating library - a copy of this is contained in this repository in the phew
folder.
The demo works by first exposing a captive wifi access point. The user uses a device such as their phone, tablet or laptop to connect to that access point, and is presented with a web page asking them to input their wifi network SSID and password.
Watch a full walk through of this project on YouTube here. (This video was made before the temperature display was added to the front end).
These credentials are saved as a file on the Pi Pico W which then reboots and attempts to connect to the network. If a connection to the network is made, the device runs your application. If the supplied wifi credentials were incorrect, it retries the connection a few times (sometimes connecting from "cold" can be slow) then goes back into access point mode and the user can try to enter updated credentials.
In this demonstration, the application that the device runs presents a simple web front end with a button on it that the user can use to toggle the Pi Pico W's onboard LED. It also display's the Pico's internal temperature using the (not very accurate) sort of temperature sensor (read about this here).
The user accesses the front end by browsing to the device's IP address. When the device successfully connects to the network, it logs the IP address to the console using a print
statement. Ideally it should show this on a connected display so that the user knows which IP address to use in order to connect to the application's front end. If your application doesn't rely on a web front end, then this bit of information doesn't necessarily need to be communicated to the user.
I created this demo after reading Kevin McAleer's article about how to set up an access point with Phew! (read on Kev's website).
This has been tested using Pimoroni's 1.20.4 MicroPython build (available here) but it should work on any 1.20 build of MicroPython as it doesn't use Pimoroni specific libraries.
To follow along, you'll need some things that cost money, and others that you may already have or which are free:
Connect the Raspberry Pi Pico W to your machine using the USB cable. This powers the Pi Pico W and also provides a data connection to it. Follow the drag and drop instructions here to install MicroPython.
I use VS Code as my editor. If you choose to use Thonny, configure it to work with the Pi Pico W by following the instruction in section 4.1, Using Thonny here.
If you're using VS Code install the Pico-W-Go extension from the marketplace (how to browse and install extensions).
Whichever editor you're using, you'll next want to clone this repository from GitHub and open it in your editor. Here's how to do this with VS Code from the terminal on a Mac:
git clone https://github.com/simonprickett/phewap.git
cd phewap
code .
I'm using VS Code for this. Whichever editor you use, you'll need to have first installed the MicroPython runtime on the Raspberry Pi Pico W (see earlier instructions).
With the folder that you cloned this repository into open in VS Code, plug the micro USB end of your cable into the Raspberry Pi Pico W and the USB A or C end of your cable into the machine that's running VS Code.
Connect to the Pi Pico W from VS Code by clicking the "Pico W Disconnected" button in the editor's footer bar. Wait for this to change to "Pico W Connected".
Now, copy the project files to the Pi Pico W. Click on "All Commands" in the editor's footer bar, and select "Pico-W-Go > Upload project". This copies all of the project files to the device and resets it. It will then start running the project.
To see the logs in VS Code's built in Terminal, click the "Pico W Disconnected" button to reconnect.
When the software first runs, it exposes a wifi access point for the user to connect to. The access point is called "pi pico" (you can change this in the code if you like) and it doesn't require a password.
Using a wifi capable device (your phone, tablet, another computer etc), connect to the "pi pico" wifi network.
Your device may automatically pop up a web page served to it by the Pi Pico W. Use the form on this page to provide your wifi network's SSID and password then click "Save".
If you don't automatically see the web page, open your device's browser and navigate to http://pipico.net
Here's what the page looks like on an iPhone:
Once you hit "Save", the Pi Pico W will reset and attempt to connect to your wifi (here it's attempting to connect to an SSID named "ssmesh"):
If it succeeds, it will log its IP address to the console (connect to the Pi Pico W from VS Code to see this). Using any other device that's connected to the same wifi network, browse to http://<device ip address>
to see the application home page:
Use the "Toggle LED" button to toggle the onboard LED on the Pi Pico W board. The application code now also has access to the internet via your wifi network. The internal temperature displayed updates automatically every few seconds.
Use the "Reset Wifi" button to delete the stored wifi credentials and reboot the Pi Pico W back into access point mode... for example when you are visiting somewhere new and need to change the wifi credentials.
If you made a mistake when providing your wifi credentials, the Pi Pico W will try and connect then swap back to exposing the "pi pico" access point so that you can try again.
Here's a high level run through of how the code works.
When the Pi Pico W starts up, it starts the MicroPython runtime which then runs the code in main.py
. The first thing that happens is that we check for the presence of the wifi configuration file using os.stat
.
If thie file is found, it is assumed to be a JSON file containing keys ssid
and password
. The following actions are then taken:
application_mode
is run. If you are making a device with an attached display, you should show this on the display so that the user can connect to it if your application uses a web display.If the wifi configuration file isn't found, the device is either being started for the first time, or a previous attempt to configure the wifi failed. In this case, the following happens:
setup_mode
is run.AP_NAME
as the SSID for the user to connect to. This is part of the Phew! framework (read about it here)ap_index
ensures that the contents of ap_templates/index.html
are served whenever a browser asks for the root page. This contains a form whose submit acion goes to /configure
and triggers the code in the ap_configure
function. This function saves the values submitted from the form into a file called wifi.json
, tells the user that the credentials have been saved and reboots the device. The device is rebooted in a background thread a second later, allowing time for the page template to be rendered and returned to the user.This is intended as a basic demo of how to get a Pi Pico W up and running on a wifi network, so that you can ship products on them to people who can then connect them to their networks without any coding skills required.
To use this as the basis of your own application, you'll want to:
ap_templates
to ask the user for any additional information that you require from them. For example your application may use an API that requires an access key that the user has to provide.app_templates
for ones that represent your application's web front end. If your application doesn't have a web front end, you can remove these.main.py
so that it:
application_mode
function, including any additional web listener routes. The Phew! documentation will be helpful here./temperature
route in main.py
(function name is app_get_temperature
). Modify this to connect to a real sensor, rename it, make it do what you like! Check out the embedded JavaScript in app_templates/index.html
to see how the front end polls this route periodically./reset
in main.py
(function name is app_reset
). Right now anyone can reset the wifi credentials!What sort of thing could you build? This probably depends on what you plan to attach to your Pi Pico W. for example, you might build a Cheerlights display with an LED matrix, or a weather station with an e-ink screen and various environment sensors.
If you build anything using this, I'd love to see it!