How to Add a Setup Portal to ESP8266 Projects

A quick tutorial on how to use ESP8266 Access Point to server a web page to configure the device: an example and walk through. Arduino and HTML code provided.

ESP8266 Wemos D1 Mini

Amazon.com - https://amzn.to/3jLR1Qd
Amazon.ca - https://amzn.to/3fx28Lq
AliExpress - https://s.click.aliexpress.com/e/_dXcNTYU

Let say we created an ESP8266 project for a smart device. And now we want the user to provide some data after the code has been flashed to a ESP8266 project. How do we do that?

One way is by using a soft access point with a portal and a form. This form can be used to gather any data we need from the user. Like wifi credentials or the PIN # of a sensor.

There are libraries out there you can use ,like WifiManager, but here, we will try to code it without one. But don't worry, it is simpler than you think.

For this exercise, we will create a way to ask for the user for their WIFI ssid and password to connect to their network.

We will start with the form and work our way back.

Download the sample code here and follow along.

To start, we will need to host a web page that will handle the requests:

• We include the server library.
• Then create an instance that will handle the portal web page
• Start the server
• In the portal function, we serve the HTML code
• When the user submits the form, we catch the post parameters

To be able to serve this page, the ESP8266 needs to act as an access point. This can be done by setting wifi to 'AP' mode and start a soft access point by giving it a name and a password.

So far we have built the form, started an access point and served a form to ask the user to provide their home network credentials.

But once we get the credentials, we need to store them somewhere. One way of doing this is by creating a structure and save it to EEPROM.

So we :

• include the EERPOM library
• create a structure with ssid and password and give them a length of 30 characters each. That should be plenty
• initiate the EEPROM with the size of the structure ( here it will be 60) and use EEPROM.begin in setup

Now we go back to the handlePortal function to modify it by copying the data into the structure. We use strncpy and pass it the structure element, the parameter and the length. Since we are dealing with strings, we need to terminate them with a NULL.

We prepare the EEPROM with the put function, give it the starting address ( it will be 0 since we don’t have anything else to save in the EEPROM) and the structure instance. Last, we do EEPROM commit to write and save.

The ssid and password are now permanently saved in EEPROM and can be retrieved any time.

On boot, if we want get these values from EEROM, we use EEPROM.get, pass it the start address, which we set to 0 earier if you remember, and then the structure instance. This will load the data into the structure for us.

To connect to the user's wifi, we set the wifi mode to 'station' and use wifi.being to connect using the saved data.

Almost there!

There is one last thing we need to adjust: if we leave everything as is the access point will start every time the device boots. But we don't want that! We only need it if we are not able to connect to the wi-fi.

Let's add a counter and when the wi-fi fails to connect more than, let's say, 30 seconds, we start the access point. We can do this by adding a retry's variable and increment it each time the wi-fi tries to connect unsuccessfully with one second delay.

And there you have it!

The device will create its own access point when it fails to connect to the wi-fi and serve this setup portal on 192.168.4.1 for our users. I told you this was going to be easy!

If you found this useful, please consider subscribing to my YouTube channel and give me a LIKE - It helps a lot.

* Much of the information contained is based on personal knowledge and experience. It is the responsibility of the viewer to independently verify all information.