pfodWifiConfig^™ for ESP8266
Simple Wifi Network Configuration

by Matthew Ford 13^th March 2016 (originally posted 5^th June 2015)
© Forward Computing and Control Pty. Ltd. NSW Australia
All rights reserved.

How to configure ESP8266
on any WiFi networkwithout re-programming

Important Note: The ESP8266 modules do not need, and should not use, the pfodWifiConfigV1 app.
This page is maintained for historical reasons only
Instead the ESP8266 modules can set up their own Access Point and complete the configuration via a web page.
See see Cheap/Simple Wifi Shield for Arduino and other micros and ESP8266-01 Wifi Shield for examples of this.

Introduction

This page describes how to use pfodWifiConfig to connect your ESP8266 to any Wifi network without re-programming. Two supporting Arduino libraries are needed pfodWifiConfig.zip and pfodWifiConfig_ESP8266.zip

For a general description of pfodWifiConfigV1, see pfodWifiConfig. Read that page first before continuing here.

See Quick Start for using pfodWifiConfigV1 Android App for how config using the free Android app.
See Configuration of pfodWifiConfig™ Wifi devices using Telnet for an example of using telent to configure your device.

Shown above is an ESP8266-01 module but code works for all ESP8266 based modules.

Why use pfodWifiConfig for a ESP8266 module?
Update Do NOT use pfodWifiConfig for ESP8266. Use its access point instead.

i) pfodWifiConfig is open source so you can modify it as you need.
ii) pfodWifiConfig does more then just get you connected to the network.

pfodWifiConfigV1 also allows your user to configure the rest of the device. If your device runs as a Server, you can set the portNo the server listens on. If your device runs as a Client, you can set the host to connect to. If your Client device needs a login username and passwork, pfodWifiConfig prompts the user to set this as well.

Developer Setup to use pfodWifiConfigV1.

This section describes how to prepare your ESP8266 module to use pfodWifiConfigV1. First read the pfodWifiConfig page for detail of how the system works.

Preparing the QR code image

First prepare the QR code that will contain the details of the temporary Wifi network that will be used to configure your ESP8266 module. See pfodQRpsk for details on downloading and running the application.

Here is an example generated QR code.

A sample image is shown below. The file name is pfodWifiConfigV1_the generated key.PNG

pfodWifiConfigV1_plyWtEDk6uZ0yfmAEM5wMc.PNG

The scanned text is from this image is
pfodWifiConfigV1
WPA2-PSK
plyWtEDk6uZ0yfmAEM5wMc
Port:23
www.pfod.com.au

That is
Network SSID: pfodWifiConfigV1
Security: WPA2-PSK
Password: plyWtEDk6uZ0yfmAEM5wMc
Connect to PortNo: 23
website: www.pfod.com.au

Generate your own QR image and attach it to your device and insert the password into your code (see below). This tutorial will use this QR image, and its password as an example.

Coding for ESP8266 module for pfodWifiConfigV1

You need to download and install two libraries, pfodWifiConfig.zip which contains all the common code and the pfodWifiConfig_ESP8266.zip library which has the specialized code for the ESP8266 module. Install these using Arduino's Sketch → Import Library → Add Library function.

Under Examples → pfodWifiConfig_ESP8266 there is an example file pfodWifiConfig_ESP8266_PassThrough.ino This sketch turns the ESP2866 module into a UART-WiFi bridge which can be configured over WiFi by pfodWifiConfig.

At the top of that file you will find the additional code needed.

Include the libraries

#include <EEPROM.h>
#include <ESP8266WiFi.h>
#include "pfodWifiConfig.h"
#include "pfodWifiConfig_ESP8266.h"

Add the settings for pfodWifiConfigV1

pfodWifiConfig_ESP8266 pfodWifiConfig;
// =============== start of pfodWifiConfigionV1 settings ==============
// update this define with the password from your QR code
// http://www.forward.com.au/pfod/pfodWifiConfig/pfodQRpsk.html
#define pfodWifiConfigPASSWORD "plyWtEDk6uZ0yfmAEM5wMc"
// the ssid is "pfodWifiConfigV1" and the port is 23 -- set by pfodQRpsk program

// note pfodSecurity uses 19 bytes of eeprom usually starting from 0 so
// start the eeprom address from 20 for configureWifiConfig
int eepromAddress = 20;
int wifiSetup_pin = 2; // name the input pin for setup mode detection GPIO2 on most ESP8266 boards
// =============== end of pfodWifiConfigionV1 settings ==============

These settings define the password (same one as in your generated QR image) for the temporary pfodWifiConfig network.

The eepromAddress is the starting address in EEPROM where the user's network configuration will be stored. The static constant pfodWifiConfig::EEPROM_USAGE contains the maximum number of EEPROM bytes used by the library starting at eepromAddress.

The wifiSetup_pin is the digital input to check to see if we should start in configuration mode. If that pin is LOW, the sketch starts pfodWifiConfigionV1 otherwise it uses the configuration parameters stored in EEPROM to connect to the real network.

Then at the top of setup() add the following lines

  EEPROM.begin(512); // allocate some EEPROM space
  pinMode(wifiSetup_pin, INPUT_PULLUP);
  Serial.begin(115200);
  delay(10);
  Serial.println();
  for (int i = 20; i >0; i--) {
   if (digitalRead(wifiSetup_pin) == LOW) {
     break; // continue to config mode
   }
   // else wait for 20sec to let the user press the config button
    delay(1000);
  }

  //============ pfodWifiConfigV1 config ====================
  // see if config button is pressed
  pinMode(wifiSetup_pin, INPUT_PULLUP);
  if (digitalRead(wifiSetup_pin) == LOW) {
    if (LED >= 0) {
      digitalWrite(LED, LOW); // show we are in setup mode
    }
#ifdef DEBUG
    Serial.println(F("Starting pfodWifiConfigV1"));
#endif
    // connect to temporary wifi network for setup
    // the features determine the format of the {set...} command
    uint16_t ipSources = pfodFeatures::DHCP|pfodFeatures::STATIC_IP; // bit or these together
    uint16_t security = pfodFeatures::WPA2; // bit or these together e.g. pfodFeatures::OPEN | pfodFeatures::WPA
    pfodWifiConfig.configureWifiConfig(eepromAddress,"pfodWifiConfigV1",pfodWifiConfigPASSWORD,23,
    pfodFeatures::SERVER, security, ipSources );
    // configureWifiConfig never returns.  Need to reboot afterwards
  }
  //============ end pfodWifiConfigV1 config ====================

This code sets the wifiSetup_pin as an input with a pullup and then checks if it is pulled to GND within 20 seconds of powering up.

There are not many pins available on the ESP8266-01 module and GPIO2 is used as the wifiSetup_pin. However the ESP8266-01 does not setup normally is GPIO2 is held LOW when power is applied, so
it is important to first apply power and then connect GPIO2 to GND later.

If GPIO2 is connected to GND within 20sec of applying power then configureWifiConfig() is called to connect to the temporary pfodWifiConfig network using the settings which should match those in the QR code image and to start a server on listening on port 23 for the configuration message.

The pfodFeatures class (in pfodWifiConfig.h) defines the various constants for the mode, security and ipSources.

NOTE: The call to configureWifiConfig() never returns. So the user needs to power cycle the device after configuration to run it normally.

Below this setup code add the lines

  // else button was not pressed continue to load the stored network settings
  if (LED >= 0) {
    digitalWrite(LED, HIGH);
  }
  //else use configured setttings from EEPROM
  // use these local vars
  char ssid[pfodWifiConfig::MAX_SSID_LEN + 1]; // allow for null
  char password[pfodWifiConfig::MAX_PASSWORD_LEN + 1];
  char staticIP[pfodWifiConfig::MAX_STATICIP_LEN + 1];
  uint16_t portNo = 0;
  uint16_t security = 0;
  uint16_t ipSource = 0;
  byte mode = 0;

  pfodWifiConfig.loadNetworkConfigFromEEPROM(eepromAddress, &mode,
      (char*)ssid, pfodWifiConfig::MAX_SSID_LEN + 1, (char*)password,  pfodWifiConfig::MAX_PASSWORD_LEN + 1,
      &security, &portNo, &ipSource, (char*)staticIP,  pfodWifiConfig::MAX_STATICIP_LEN + 1);

  server = WiFiServer(portNo);
  // Initialise wifi module
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
  }
etc …

This code, and the rest of the sketch, is run if the wifiSetup_pin is not grounded within 20sec after power is applied. It calls loadNetworkConfigFromEEPROM() to load the user configured network settings from EEPROM and connect to their network.

The complete code for sketch is here. That is all that is required by the developer.

Conclusion

That's all that is required to set up your ESP8266 as a UART-WiFi bridge and configure your ESP8266 module on any user's network without re-programming it each time.

pfodWifiConfig^™ and pfodQRpsk^™are trademarks of Forward Computing and Control Pty. Ltd.
Android^TM is a trademark of Google Inc. For use of the Arduino name see http://arduino.cc/en/Main/FAQ

The General Purpose Android/Arduino Control App.
pfodDevice™ and pfodApp™ are trade marks of Forward Computing and Control Pty. Ltd.

pfodWifiConfig™ for ESP8266 Simple Wifi Network Configuration

How to configure ESP8266on any WiFi networkwithout re-programming