Introduction: Build a Custom ESP8266 Arduino WiFi Library

Picture of Build a Custom ESP8266 Arduino WiFi Library

The ESP8266 development board is a lot of fun to work with. This small and inexpensive WiFi capable microprocessor has rapidly become a very popular platform for prototyping and building IoT solutions.

Naturally, I've got in on the action with the latest version - the ESP8266 12-E Dev Kit. As I already have an Arduino IDE installed, I decided to make it my IDE of choice in order to quickly on-board myself and get familiar with the ESP8266 microprocessor.

The WiFi capability is no doubt (one of) the most appealing features of this board. But during the learning process, it became obvious that I had to make a few, not-so-hard changes to the Arduino-ESP8266 development environment in order to make my Wifi sketches a bit more manageable.

In this IBLE, we'll build a simple Arduino library to achieve the following objectives:

  1. Centrally configure and manage WiFi settings
  2. Use the library within a sketch that makes use of the WiFi capabilities of the ESP8266
  3. Avoid monotonous repetitions when configuring WiFi settings within Arduino sketches
  4. Avoid exposing the WiFi SSID and password settings via the Arduino sketches

Let's get started!

Step 1: Setting Up the Arduino-ESP8266 Development Environment

Picture of Setting Up the Arduino-ESP8266 Development Environment

There are many sites on the web that talk about Arduino and/or the ESP8266. However, the resources listed below have been immensely helpful in getting me started.

  1. The latest ESP8266 12-E Dev Kit Development Board
    • available from Amazon and other popular online retailers
  2. Acrobotic Industries has a nice tutorial on integrating the ESP8266 custom firmware with the Arduino IDE
  3. The latest version of the Arduino IDE
    • this IBLE uses the latest version 1.8.0 for Windows 10 downloaded from the Arduino page
  4. A micro-USB cable to communicate and program the ESP8266 from a computer running the Arduino IDE

If all the steps have been completed without any errors, the Arduino IDE should have the ESP8266 board listed and also have access to all the related libraries and examples as shown in one of the screen shots.

Arduino Port Settings:

Note that the port identifier "COM3" may be different on your computer - make sure that the port indicated in the Windows Device Manager matches the port selected in the Arduino IDE.

NOTE:

  1. Windows 7/10 computers usually download and install the SiliconLabs CP2102 USB to UART driver when the ESP8266 is connected to the computer via the micro-USB cable
  2. Linux and Mac computers may require explicit installation of this driver downloadable from Silcon Labs

IMPORTANT:

Get a proper micro-USB "data" cable - a wrong type of cable will leave you stranded for hours wondering why your computer won't recognize the ESP8266 despite installing the proper USB driver.

A cable that can work with an SD card reader is a better choice than the one that is primarily used just for charging phones or headsets.

Although this IBLE presumes that readers are familiar with developing projects on the Arduino platform, helpful beginner level hints have been incorporated wherever possible.

Step 2: Working With Arduino ESP8266 WiFi Code Samples

Picture of Working With Arduino ESP8266 WiFi Code Samples

The images illustrate a standard WiFiWebServer example sketch that comes with the ESP8266 installation . Each of these WiFi examples requires that you update the WiFi settings before the code can be compiled and flashed to the ESP8266 board. Personally, this approach has the following issues:

Monotonous and repetitive WiFi settings
Needs no further explanation as you'll feel the monotony once you've worked through a few code samples!

Vulnerable WiFi Password
Leaves WiFi settings open and visible in code - I run the risk of accidentally (and unintentionally) publishing my WiFi settings to public domain should I carelessly share this code online (not very good!)

Scattered Password Management
I periodically keep changing my WiFi password - this means that I have to remember to carry these changes over to each and every one of my Arduino sketch files that uses WiFi settings

For these reasons, I decided to make my code base a bit more manageable thus enabling me to focus on learning how to program the ESP8266 instead of having to manage WiFi settings in code.

NOTE:

There may be other solutions - this is just one way of making life easier

Subsequent steps described in this IBLE are optional - you can still manage your WiFi settings in each of the Arduino sketches

Regardless, coding standards in the software industry are rapidly tightening - keeping information such as passwords separate and invisible from program code, once considered a best practice is fast becoming part of the secure and required coding practice guidelines!

Step 3: Separating WiFi Settings From Code

To keep things simple, we'll integrate our WiFi settings within a simple custom Arduino library and deploy it into the IDE.

The Arduino website has resources in case readers want to get started with the basics on custom libraries.Therefore, the depth of this subject is not within the scope of this IBLE.

Besides, the next steps demonstrated here are simple and do not require additional resources other than a humble text editor such as Notepad (on Windows).

Custom Library Prerequisites:

The first step is to decide on a name for our custom library - we'll call ours MyWifiCentral.

With the name decided, we'll design and build the following required components of this library:

  1. MyWifiCentral.h - the header file
  2. MyWifiCentral.cpp - the c plus plus (or cpp) file
  3. Save both files to a library folder by name MyWifiCentral

Both files will be coded using some of the simplest concepts of C++.

IMPORTANT:

You can name your library anything as long as it conforms with the Arduino naming guidelines, but the names of the header file, the CPP file, and the folder must match with the name of the library

Keep in mind that too specific a library name can cause unintended name collisions at the time of deploying a custom library

Example:

Naming the library ESP8266Wifi will be in direct conflict with the fact that an Arduino library with that name already exists!

On the other hand, a name such as MyWifiCentral eliminates collisions by the very personal nature of how it sounds thus making it more suited for your personal development environment.

In addition, the fact that the name does not contain "ESP8266" indicates that this is a library designed for general use, not specifically for the ESP8266. There are other Arduino WiFi libraries that can benefit from such a general feature.

Step 4: Building the Header File

Picture of Building the Header File

Very simply, a header (or H) file is a bare bones representation of the library you plan to build. The code markers <1 through <6 describe the various components of the header file.

  1. The features of this library are collectively referred to as variables and methods
  2. The resources this library will have access to (Example Arduino.h) will also be listed in this header file

NOTE:

  • The Notepad editor does not support formatting - the easiest way to format the code is to type it in the Arduino editor and then copy-paste it into Notepad
  • When saving the .H file in Notepad, make sure that the file type is set to "All files(*.*)" to prevent the file from being saved with a ".txt" extension

SAVING LIBRARY FILES:

  • Create a new folder at a convenient location on your computer and name it MyWifiCentral
  • As described in the preceding steps, the name of this folder must be a (case-sensitive) match with the name of the library

The completed header file has been attached here below.

Next, on to the CPP file.

Step 5: Building the CPP File

Picture of Building the CPP File

The CPP (or c plus plus) file materializes the actual custom library. All attributes and resources listed in the header file created in the previous step are fully defined in the CPP file.

The visual contains full comments that help describe each part of the library.

The attached file contains the code that can be deployed to the Arduino environment in subsequent steps.

NOTE:

  • Each method in the .CPP file is prefixed with the "MyWifiCentral::" identifer indicating that all methods are part of the MyWifiCentral custom library
  • As noted in the previous step, make sure that the file is formatted right and that the file is saved with a ".cpp" extension
  • Save the .CPP file alongside the .H file in the MyWifiCentral library folder created in the previous step

NOT TO FORGET!

  • Make sure to set the WiFi settings to match with your WiFi network before proceeding further

Step 6: Deploying the Library to the Arduino IDE

Picture of Deploying the Library to the Arduino IDE

To deploy the custom library into the Arduino environment, follow these steps:

  1. Close all open Arduino IDE windows
  2. Locate the Arduino libraries folder under the Arduino program folder:
    • If Arduino has been installed as a Windows program, the path is usually C:\Program Files\Arduino\libraries
    • In this case, the Arduino program has been downloaded as a non-admin install and unzipped to the My Documents folder
  3. Once the location has been determined, simply move the entire MyWifiCentral folder under the libraries folder

The accompanying visual illustrates the custom library deployment. At this point, the library has become part of your Arduino environment.

The next step is to confirm that the library is available for active use via the Arduino IDE.

Step 7: Including the Custom WiFi Library in a Sketch

Picture of Including the Custom WiFi Library in a Sketch

Begin by opening up the Arduino IDE. We'll need an Arduino sketch to use our custom library. For that, we'll start of with a standard example named WiFiWebServer that comes with the ESP8266 firmware installation.

Open this sketch by navigating through the File menu item like so:

File > Examples > ESP8266WiFi > WiFiWebServer

The example sketch will open up in a new Arduino window.

Next, include the custom library into the example sketch using the Sketch menu item:

Sketch > Include Library > MyWifiCentral

A new line will be automatically added to the top of the sketch and the header file MyWifiCentral.h built in the preceding steps will be included in the sketch.

#include <MyWifiCentral.h>

The include statement confirms that the sketch has access to the methods of the MyWifiCentral library

Step 8: Utilizing the Custom Library Methods

Picture of Utilizing the Custom Library Methods

To put the custom library to real use, we'll replace the standard WiFi connection code with the methods from our custom library.

The first visual compares changes to the code alongside definitions in the header file.

On line #13 we load the library into memory my declaring an object instance:

MyWifiCentral myWifiCentral;

On lines #14 and #15 we replace the hard coded placeholders for ssid and password with our library methods ssid() and passcode() respectively:

char* ssid = myWifiCentral.ssid();
char* password = myWifiCentral.passcode();


Next, we remove the const (short for constant) keyword on both these lines .

Why?

Because the very purpose of the custom library is to make the WiFi settings variable and subject to future changes. Therefore, the library methods ssid() and passcode() return char*. Assigning char* to const char* will result in an error when the Sketch is compiled. Therefore, the const keyword has to be removed!

That's it! All we need to do now is to save and compile the sketch to confirm that there are no errors. You can give the sketch any name as long as it does not begin with a number. In this case the new name begins with an underscore followed by a number.

To compile the sketch, simply click on the Check mark button on the menu bar as shown. If all steps have been followed correctly, the status bar at the bottom of the IDE window should display a "Done Compiling" message.

Next, we'll flash the compiled sketch to the ESP8266 board.

Step 9: Flashing the Sketch to the ESP8266

Picture of Flashing the Sketch to the ESP8266

Before flashing the sketch, make sure that:

  1. the ESP8266 board is firmly connected to the computers' USB port via the micro-USB cable
  2. the port is correctly selected from the Tools > Port menu item

In this case the port is set to COM3, but it may be different on your machine.

To flash the sketch to the board, click on the Compile button as shown. If the computer is connected to ESP8266, the sketch should be downloaded to the board in a few seconds. During this time, the Blue LED on the ESP8266 will flash rapidly.

In addition, the window at the bottom of the Arduino IDE will indicate the progress of the flashing process.

Now we're ready to test the functionality of the Sketch and the custom WiFi library!

Step 10: Testing the Wifi Capability

Picture of Testing the Wifi Capability

Before proceeding further, refer to the documentation at the top of the sketch. This sketch makes the ESP8266 perform the following functions:

  • Connect to the Internet via the configured WiFi settings (provided our custom library has no errors!)
  • Get an IP address and start up a basic web server that becomes accessible via your favorite browser

Once the IP is assigned, we can open up the browser and toggle the on board Blue LED by typing in a couple of URLs

To view this test in progress, open the Serial Monitor window using the Ctrl+Shift+M combination on your keyboard. On the bottom right of this window, make sure that the baud rate is set to 115200.

If the WiFi settings have been configured correctly in the custom library, the ESP8266 should be able to connect to the internet and get an IP assigned to it.

Using the IP, you can toggle the LED ON or OFF by typing in the URLs in your browser window .

The testing sequence is illustrated by markers <1 through <6 in the visual above.

Step 11: Observations, Standard Code Vs. Managed Custom Library

Picture of Observations, Standard Code Vs. Managed Custom Library

Finally, we summarize our observations by running a side by side comparison of the standard code and the managed custom library.

The most significant observation is password security:

  • Standard code lays bare your WiFi credentials whilst managed code has no direct references to it - makes the solution a lot cleaner!

Next thing absent is the repetitive WiFi code:

  • Should the WiFi settings change, every one of your sketches will need manual edits
  • With managed code, all you do is change your WiFi settings in the CPP file just once, restart your Arduino IDE, compile and flash the sketch once more into the ESP8266!

The Counter argument would be:

I'll be using one sketch at a time! What's the big deal?

But which one? What if you have 20 sketches and only two of them are actively in service on a couple of ESP8266 chips? Will you make changes to just these 2 only to forget the remaining 18?

Conclusion:

Easier a change in one central location than hunting down each and every WiFi related sketch!

Happy coding, have fun and thanks for reading my IBLE!

Comments

OneHappyMan (author)2017-07-04

Worked great. Thanks for the post.

andymenon (author)OneHappyMan2017-07-05

Awesome! Thanks for giving this a shot!

Zachary Avenger (author)2017-05-22

This will be useful for a project of mine, awesome dude!

Cool!

MamunEdt (author)2017-04-09

Yes This Is Working ...windows 8 ...

i Need to know more About This Module ...

Thanks for ur Easy Step By Step Indication ...

andymenon (author)MamunEdt2017-04-10

You're welcome! :-)

MamunEdt (author)andymenon2017-04-11

Im intersted about rover ... Rc.control ... I want to use wifi to control ..now.im using df robot rober wirh flysky hobby controller.with arduino

MosesN1 (author)2017-01-08

Still can't connect to my WiFi.Will keep trying; I'm using the ESP8266 MOD AI-Thinker

andymenon (author)MosesN12017-01-08

Hi Moses, Sorry to hear that you're having issues. This isn't unexpected. I use Windows 10 and have researched several other firmwares'. NodeMCU for example didn't work for me whilst Mongoose OS and Arduino did without skipping a beat! I'm still trying to determine if Windows 10 is the reason why NodeMCU didn't work for me. You may be having a similar problem. Have you tried an alternate firmware?

bigo72 (author)2017-01-07

Mate, sorry to say that, but I didn't understand what it's for. What this thing does? Could you explain, thinking you have your grandmother in front of you? Appreciated

andymenon (author)bigo722017-01-07

Hello, I have added links to Step 2 of this article that talks about Getting started. It'll lead you to more information on ESP8266.

Hope this helps.

JeffM15 (author)2017-01-05

Nice job. Great Idea. I did the same thing with LuaLoader

Cheers,

Jeff

andymenon (author)JeffM152017-01-05

Thanks Jeff! I did give Lua a shot. But the default firmware (v0.96 i think?) was hopelessly outdated. I don't know if it's a Windows 10 thing, but I even tried building the custom version from the online builder service recommended in the NodeMCU documentation. No matter what I did, I wasn't able to get my WiFi off the ground.

I'm yet to identify the root cause why NodeMCU fails to work on machine. But, I believe it's a Windows 10 thing because I was able to use another firmware called Mongoose IoT, and it worked flawlessly. And the result was no different with the Arduino stack.

JeffM15 (author)andymenon2017-01-05

Very kool. I will check out Mongoose.

Thanks

craiglindley (author)2017-01-05

While you were at it why didn't you include the code that connects to the WiFi so all of the Wifi code is always in one place and you would never have to mess with SSIDs or Passwords in your main sketch? You could add a method to your library called connect and just call it when you want WiFi

andymenon (author)craiglindley2017-01-05

This was a 10 minute solution. More improvements to follow.
I have another home automation project to complete and didn't want make a long detour in the process of setting this up.
I'm also looking into how I can incorporate encryption around the Wifi credentials.

Thanks for the suggestions! :-)

andymenon (author)andymenon2017-01-05

I've been thinking about this a little bit. Let's suppose I put in the code to connect to the Wifi network inside the library. It means that I have to include the header file that actually makes the WiFi connection into the library. This would make my library too "esp8266 specific".

What if I want to use this custom library with another processor?

Is my reasoning correct?

treii28 (author)2017-01-05

I finally broke the ice on building my own modified library recently for a ESP based power relay controller recently so thanks for the added info. Just curious, have they added support for grabbing the wifi device mac addresses yet? I noticed that it was in the old C code and many of the old C routines have wrappers in the arduino C++ library but that one wasn't yet included and I didn't know enough about C++ yet to try adding it myself.

andymenon (author)treii282017-01-05

I don't know if that support exists as of today. In fact I'm researching on that for my Garage door project - The idea is to make a white list of all mac addresses that are allowed access to the WifiWebServer to open/close the garage door.

I will post an update should I get hold of something.

thanks!

kalya made it! (author)2017-01-05

a much simplernetwork setup

andymenon (author)kalya2017-01-05

Awesome! Thanks for trying this out! :-)

ghismo (author)2017-01-05

Thanks for sharing.

Well as you said it's one way to deal with changing Wifi environments.

But if I understand well your code, you still need to send your sketch to all of your ESPs every time you're changing your Wifi credentials ? So to have a computer with your modules...

I'm using the kentaylor's WiFiManager library for that purpose :

https://github.com/kentaylor/WiFiManager/

With this library, no need to send the sketches to your ESPs, but you have to set ESPs in configuration mode, connect to them with your phone and set the proper credentials (and eventually other parameters). This have also the advantage to exclude totally wifi password in your code.

This is another approach, that works better for me (as i'm taking with me my modules and need to connect to different Wifi env without the need of a computer), but yours sure have other advantages.

There is another solution related to this problem, that I've haven't tested yet, but that allows you to send your sketch over the air that also makes use of WifiManager (as far as I can tell) :

http://iotappstory.com/

andymenon (author)ghismo2017-01-05


As of now my assumptions on code management was limited to my personal dev environment. For a broader use, more improvements have to be incorporated.

Thanks for the leads!

AlbertZeroK (author)2017-01-05

Checkout WifiManager, I've been looking at extending it for use with all my projects as a drop in for wifi.

About This Instructable

25,901views

325favorites

License:

Bio: I'm a Mechanical Engineer turned IT Professional . I came into the Information Technology world because someone challenged me to. But at heart, I'm ... More »
More by andymenon:An Unconventional 3D Printed Retropie Arcade - Part 2 of 2A 3D Printed Model Car Display CaseOctoPrint Webcam Bracket for Creality CR-10
Add instructable to: