background image

A Beginner's Guide to the ESP8266

Pieter P, 08-03-2017

Some time ago, I wrote a Beginner's Guide to Arduino that seems to be very popular, so I decided to create a follow-up: A Beginner's
Guide to the ESP8266
. That's right, a tutorial on how to use the world's most popular $3 Wi-Fi board.

This is going to be a very in-depth tutorial, covering some networking concepts as well. If you're a beginner, and just want to go
straight to the more exciting Wi-Fi part, feel free to do so, I included short TL;DR's in the longer, more technical parts.

A short overview of what I'll cover in this article: 

1.  What is an ESP8266? A short overview of what an ESP8266 is, and what you can do with it
2.  Deciding on what board to buy: There's loads of different ESP8266 available these days, finding the one that's best for you

can be hard

3.  Installing the software: you need to install some software to program the ESP8266, and maybe a USB driver
4.  Setting up the hardware: some modules and boards need some external components
5.  The ESP8266 as a microcontroller: the ESP8266 can be used as a normal microcontroller, just like an Arduino
6.  Network protocols: Before we start using the Wi-Fi capabilities of the ESP8266, I'll teach you some of the network protocols

involved

7.  Setting up a Wi-Fi connection: That's probably why you're reading this, right?
8.  Name resolution: Find the ESP8266 on your local network using mDNS
9.  Setting up a simple web server: This enables you to add web pages to the ESP8266, and browse them from your computer or

phone

10.  Setting up an advanced web server: a more advanced server with a real file system that allows you to upload new files over

Wi-Fi

11.  OTA - uploading programs over Wi-Fi: You don't have to upload programs over USB, you can use Wi-Fi instead
12.  Wirelessly controlling your RGB lighting: Change the color of your LED strips using your phone or computer
13.  Getting the time: Connect to a time server using NTP and sync the ESP's clock
14.  Monitoring sensors: log the temperature in your living room, save it in flash memory and show it in a fancy graph in your

browser

15.  Getting email notifications: Turn on a notification light when you've got unread emails
16.  Advanced features: use DNS, captive portals, Wi-Fi connector libraries, OSC ...

This guide expects some basic knowledge of microcontrollers like the Arduino. If that's something you're not already familiar with, I'd
recommend you to read my Beginner's Guide to Arduino first, it covers a lot of the basics that I won't go into in this article.
I really want to focus on the ESP8266-specific things, like Wi-Fi and other network protocols, the ESP's hardware, software, IoT, etc ...

What is an ESP8266?

The ESP8266 is a System on a Chip (SoC), manufactured by the Chinese company Espressif. It consists of a Tensilica L106 32-bit
micro controller unit (MCU) and a Wi-Fi transceiver. It has 11 GPIO pins* (General Purpose Input/Output pins), and an analog
input
 as well. This means that you can program it like any normal Arduino or other microcontroller. And on top of that, you get Wi-Fi
communication, so you can use it to connect to your Wi-Fi network, connect to the Internet, host a web server with real web pages, let
your smartphone connect to it, etc ... The possibilities are endless! It's no wonder that this chip has become the most popular IOT
device available. 

There are many different modules available, standalone modules like the ESP-## series by AI Thinker, or complete development
boards like the NodeMCU DevKit or the WeMos D1. Different boards may have different pins broken out, have different Wi-Fi antennas,
or a different amount of flash memory on board.

(*) The ESP8266 chip itself has 17 GPIO pins, but 6 of these pins (6-11) are used for communication with the on-board flash memory chip.

Programming

There are different ways to program the ESP8266, but I'll only cover the method using the Arduino IDE. This is really easy for
beginners, and it's a very familiar environment if you've used Arduino boards before. 
Just keep in mind that it's not limited to this option: there's also an official SDK available to program it in real C, this is very useful if
you want to optimize your code or do some advanced tricks that aren't supported by the Arduino IDE. Another possibility is to flash it
with a LUA interpreter, so you can upload and run LUA scripts. Or maybe you're more familiar with Python? Then you should check out
the MicroPython firmware to interpret MicroPython scripts. I'm sure there's other languages available as well, so just do a quick Google
search and write your code in the language of your choice.

Requirements

You'll need a couple of things in order to follow this guide:

An ESP8266 board
A computer that can run the Arduino IDE (Windows, Mac or Linux)
A USB-to-Serial converter, it is very important that you use a 3.3V model*
A USB cable
A 3.3V power supply or voltage regulator*
A Wi-Fi network to connect to

(*) Your board may already include these. More information can be found in the next chapter.

Содержание ESP8266 SDK

Страница 1: ... d recommend you to read my Beginner s Guide to Arduino first it covers a lot of the basics that I won t go into in this article I really want to focus on the ESP8266 specific things like Wi Fi and other network protocols the ESP s hardware software IoT etc What is an ESP8266 The ESP8266 is a System on a Chip SoC manufactured by the Chinese company Espressif It consists of a Tensilica L106 32 bit ...

Страница 2: ...ith some of the most popular ESP8266 development boards and their features Board GPIO 3 3V Vreg USB to Serial Auto Reset Auto Program Flash ADC range Extra SparkFun ESP8266 Thing 11 512KB 4Mb 0 1V Battery charger crypto element temperature sensor light sensor SparkFun ESP8266 Thing Dev Board 11 512KB 4Mb 0 1V Node MCU 11 4MB 32Mb 0 3 3V Adafruit Feather HUZZAH with ESP8266 11 4MB 32Mb 0 1V Battery...

Страница 3: ... by connecting the RST reset pin to VCC through a 10KΩ resistor 5 Make sure you don t have anything connected to GPIO2 more information in the next chapter Adding reset and program buttons If your ESP8266 board doesn t have a reset button you could add one by connecting a push button to between the RST pin and ground To put the chip into programming mode you have to pull GPIO0 low during startup T...

Страница 4: ......

Страница 5: ... mind is that the ESP8266 can only source or sink 12mA per output pin compared to 20 40mA for most Arduinos The ESP8266 has one analog to digital converter but it has a strange voltage range 0 1V voltages above 1V might damage the board One last thing to keep in mind is that the ESP8266 has to share the system resources and CPU time between your sketch and the Wi Fi driver Also features like PWM i...

Страница 6: ... 2 3 0 You can check out the official install guide here Drivers If you are using a board with the CH340 G USB to Serial chip like the NodeMCU you ll probably have to install the USB drivers for it They can be found on GitHub If you are using a board with the CP2104 USB to Serial chip like the Adafruit Feather HUZZAH board you ll probably have to install USB drivers as well You can find them on th...

Страница 7: ...manufacturer of your board added them for you This has some implications however GPIO15 is always pulled low so you can t use the internal pull up resistor You have to keep this in mind when using GPIO15 as an input to read a switch or connect it to a device with an open collector or open drain output like I C GPIO0 is pulled high during normal operation so you can t use it as a Hi Z input GPIO2 c...

Страница 8: ...alogWriteRange new_range The frequency can be changed by using analogWriteFreq new_frequency new_frequency should be between 100 and 1000Hz Analog input Just like on an Arduino you can use analogRead A0 to get the analog voltage on the analog input 0 0V 1023 1 0V The ESP can also use the ADC to measure the supply voltage VCC To do this include ADC_MODE ADC_VCC at the top of your sketch and use ESP...

Страница 9: ... that could take longer than say 100ms Sources This is where I got most of my information to writ this article there s some more details on the GitHub pages if you re into some more advanced stuff like EEPROM or deep sleep etc https github com esp8266 Arduino issues 2942 https github com esp8266 Arduino pull 2533 files https github com esp8266 Arduino blob master doc libraries md https github com ...

Страница 10: ...ions e g a laptop and a smartphone can also communicate with each other The ESP can be used in AP only station only or AP station mode TL DR The link layer is the physical link between devices in the case of the ESP8266 this is a WiFi connection The ESP can act as a station and connect to an access point or act as an access point and let other devices connect to it The Internet or Network layer Al...

Страница 11: ...s sending email uploading files etc UDP on the other hand doesn t guarantee that every packet reaches its destination it does check for errors however but when it finds one it just destroys the packet without re sending it This means that it s not as reliable as TCP but it s faster and has a much lower latency because it doesn t require an open connection to send messages like TCP does That s why ...

Страница 12: ...Name System As mentioned before you can only send a message to another computer if you know its IP address But when you browse the Internet you only know a website s domain name e g www google com Your computer uses the Domain Name System to translate this domain name to the right IP address More on this later Sources https en wikipedia org wiki Internet_protocol_suite https en wikipedia org wiki ...

Страница 13: ...hat the DTR pin stays low To solve this we re going to build a crude edge detector circuit using a capacitor Take a look at the following schematic You might recognize that this is basically a low cut filter In normal conditions DTR is high 3 3V and the reset line is also high because of the pull up resistor R2 This means that the voltage across the capacitor is 0V When DTR suddenly drops to 0V th...

Страница 14: ...pacitor it shouldn t change anything so it should be reverse biased just a fancy way of saying that it s not conducting any current because the polarity is the other way around and while the capacitor is discharging it should discharge the capacitor immediately Here s what that looks like Let s run the simulation again to check if our problem is solved ...

Страница 15: ... in the Arduino Uno for example Note if you followed the instructions in the hardware step correctly you should already have added R2 to your ESP How to use Auto reset To use this auto reset circuit connect it to the DTR line of your USB to Serial converter and to the reset line of the ESP as shown in the diagram Then click compile just because the first compilation can take quite some time Go to ...

Страница 16: ...boot in program mode 4 release the program button 5 upload the sketch If you want to get out of program mode without uploading just press reset without pressing the program button Board options If your specific board is in the Tools Board list e g NodeMCU SparkFun and Adafruit boards you can just select it and you will get the right settings When your board isn t in the list you ll have to select ...

Страница 17: ...Disabled If you do wish to receive debug messages you can select the port to send them to Serial on pins 1 and 3 or Serial1 on pin 2 Debug level This allows you to choose what kind of debug messages you want to show Reset Method As mentioned in the paragraphs above there are different methods for auto reset and auto program If you re using the first method using the edge detector you should use ck...

Страница 18: ...erial monitor If you re on Mac or Linux use CTRL C to stop it after a couple of lines The output should look something like this user computername ping 192 168 1 3 PING 192 168 1 3 192 168 1 3 56 84 bytes of data 64 bytes from 192 168 1 3 icmp_seq 1 ttl 128 time 6 38 ms 64 bytes from 192 168 1 3 icmp_seq 2 ttl 128 time 45 2 ms 64 bytes from 192 168 1 3 icmp_seq 3 ttl 128 time 69 1 ms 64 bytes from...

Страница 19: ...e Wi Fi networks for example the Wi Fi at home and the Wi Fi at the office it won t work To solve this problem we ll use the Wi Fi Multi library You can add as many networks as you like and it automatically connects to the one with the strongest signal include ESP8266WiFi h Include the Wi Fi library include ESP8266WiFiMulti h Include the Wi Fi Multi library ESP8266WiFiMulti wifiMulti Create an ins...

Страница 20: ... of the ESP8266 to the computer void loop To see if it works open the Wi Fi settings on your computer look for a network called ESP8266 Access Point enter the password thereisnospoon and connect to it Then open a terminal and ping to 192 168 4 1 this is the default IP address of our ESP AP You ll see that the ESP responds to your pings However if you try to go to an online website you ll get a tim...

Страница 21: ...s mDNS include ESP8266WiFi h Include the Wi Fi library include ESP8266WiFiMulti h Include the Wi Fi Multi library include ESP8266mDNS h Include the mDNS library ESP8266WiFiMulti wifiMulti Create an instance of the ESP8266WiFiMulti class called wifiMulti void setup Serial begin 115200 Start the Serial communication to send messages to the computer delay 10 Serial println n wifiMulti addAP ssid_from...

Страница 22: ......

Страница 23: ...nt parts of a GET request are the request line and the host header Let s take a look at an example If you click the following link https www w3 org Protocols rfc2616 rfc2616 sec5 html your browser will send out the following HTTP request GET Protocols rfc2616 rfc2616 sec5 html HTTP 1 1 Host www w3 org Connection keep alive Pragma no cache Cache Control no cache Upgrade Insecure Requests 1 User Age...

Страница 24: ...e com Content Type multipart form data boundary WebKitFormBoundaryQNEJOasMvgAOg8Kt As you can see the request line now has the POST method in it and is still followed by a URI login php and the HTTP version 1 1 The host header still contains just the domain name The real difference is the request body a GET request has no payload while you can add a lot of data to the body of a POST request This d...

Страница 25: ... found 500 Internal Server Error The server encountered an unexpected condition and couldn t fulfill the request TCP UDP Ports In most cases one device has many different services for example a web server an email server an FTP server a Spotify streaming service If the device had just an IP address it would be impossible to know which application a packet was sent to That s why every service has a...

Страница 26: ...e request There s a lot of code that s the same as in the Wi Fi and mDNS examples The actual server code is pretty straightforward First we create a server instance that listens for HTTP requests on port 80 This is the default port for web servers In the setup we tell the server what to do with certain HTTP requests If the URI is requested the server should reply with a HTTP status code of 200 Ok ...

Страница 27: ...function when a client requests URI server on LED HTTP_POST handleLED Call the handleLED function when a POST request is made to URI LED server onNotFound handleNotFound When a client requests an unknown URI i e something other than call function handleNotFound server begin Actually start the server Serial println HTTP server started void loop void server handleClient Listen for HTTP requests from...

Страница 28: ...ate an instance of the ESP8266WiFiMulti class called wifiMulti ESP8266WebServer server 80 Create a webserver object that listens for HTTP request on port 80 void handleRoot function prototypes for HTTP handlers void handleLogin void handleNotFound void setup void Serial begin 115200 Start the Serial communication to send messages to the computer delay 10 Serial println n wifiMulti addAP ssid_from_...

Страница 29: ...ccessful p else Username and password don t match server send 401 text plain 401 Unauthorized void handleNotFound server send 404 text plain 404 Not found Send HTTP status 404 Not Found when there s no handler for the URI in the request The HTML in handleRoot is form action login method POST input type text name username placeholder Username br input type password name password placeholder Passwor...

Страница 30: ... size under Tools Flash Size or delete some files Even if your computer says that the files are smaller than the selected SPIFFS size you can still get this error this has to do with block sizes and metadata like file and folder names that take up space as well If you change the SPIFFS size you have to reupload your sketch because when you change the SPIFFS size the memory location will be differe...

Страница 31: ...ion x gzip return text plain This example is adapted from the FSBrowser example by Hristo Gochkov Compressing files The ESP8266 s flash memory isn t huge and most text files like html css etc can be compressed by quite a large factor Modern web browsers accept compressed files as a response so we ll take advantage of this by uploading compressed versions of our html and icon files to the SPIFFS in...

Страница 32: ...It automatically detected that it had to send the compressed versions of index html and favicon ico ...

Страница 33: ...ent if it exists void handleFileUpload upload a new file to the SPIFFS void setup Serial begin 115200 Start the Serial communication to send messages to the computer delay 10 Serial println n wifiMulti addAP ssid_from_AP_1 your_password_for_AP_1 add Wi Fi networks you want to connect to wifiMulti addAP ssid_from_AP_2 your_password_for_AP_2 wifiMulti addAP ssid_from_AP_3 your_password_for_AP_3 Seri...

Страница 34: ...ntSize Write the received bytes to the file else if upload status UPLOAD_FILE_END if fsUploadFile If the file was successfully created fsUploadFile close Close the file again Serial print handleFileUpload Size Serial println upload totalSize server sendHeader Location success html Redirect the client to the success page server send 303 else server send 500 text plain 500 couldn t create file The h...

Страница 35: ..._from_AP_3 your_password_for_AP_3 Serial println Connecting int i 0 while wifiMulti run WL_CONNECTED Wait for the Wi Fi to connect delay 250 Serial print Serial println n Serial print Connected to Serial println WiFi SSID Tell us what network we re connected to Serial print IP address t Serial println WiFi localIP Send the IP address of the ESP8266 to the computer ArduinoOTA setHostname ESP8266 Ar...

Страница 36: ...while you might get an error saying ERROR No Answer If this happens just enter the password and try again Serial Monitor OTA Using the Serial Monitor over Wi Fi is not possible yet When you try to open it you ll be prompted a password entering the password won t work because there is no SSH support to access the ESP s console You can use a different program to get debug output from the physical Se...

Страница 37: ...r even to different files In the following example the setup was very long and cluttered so I split it up into several different functions one to connect to the Wi Fi one to start the OTA update service one to start the SPIFFS and so on Downloading WebSockets for Arduino We ll be using the arduinoWebSockets library by Links2004 Download it from GitHub and install it Sketch Include Library Add ZIP ...

Страница 38: ...A connection WiFi softAP ssid password Start the access point Serial print Access Point Serial print ssid Serial println started r n wifiMulti addAP ssid_from_AP_1 your_password_for_AP_1 add Wi Fi networks you want to connect to wifiMulti addAP ssid_from_AP_2 your_password_for_AP_2 wifiMulti addAP ssid_from_AP_3 your_password_for_AP_3 Serial println Connecting while wifiMulti run WL_CONNECTED WiFi...

Страница 39: ...pathWithGz path gz if SPIFFS exists pathWithGz SPIFFS exists path If the file exists either as a compressed archive or normal if SPIFFS exists pathWithGz If there s a compressed version available path gz Use the compressed verion File file SPIFFS open path r Open the file size_t sent server streamFile file contentType Send it to the client file close Close the file again Serial println String tSen...

Страница 40: ...8x48 href favicon ico link rel manifest href manifest json meta name theme color content 00878f meta content width device width initial scale 1 0 maximum scale 1 0 user scalable 0 name viewport script src WebSocket js type text javascript script head body center header h1 LED Control h1 header div table tr td style width 14 4px text align right R td td input class enabled id r type range min 0 max...

Страница 41: ... to convert bytes to KB and MB to determine file types based on file extensions and to convert a hue angle to RGB values String formatBytes size_t bytes convert sizes in bytes to KB and MB if bytes 1024 return String bytes B else if bytes 1024 1024 return String bytes 1024 0 KB else if bytes 1024 1024 1024 return String bytes 1024 0 1024 0 MB String getContentType String filename determine the fil...

Страница 42: ...more files later you should set it higher Upload the sketch over Serial and then upload the SPIFFS files using Tools ESP8266 Sketch Data Upload Wait for it to connect to a Wi Fi network or connect to the ESP8266 Access Point using the password thereisnospoon and go to http esp8266 local You should get a page that looks like this Use the sliders to adjust the color levels of the LED and press the R...

Страница 43: ...at uses UDP to request the time from a NTP server Libraries constants and globals include ESP8266WiFi h include ESP8266WiFiMulti h include WiFiUdp h ESP8266WiFiMulti wifiMulti Create an instance of the ESP8266WiFiMulti class called wifiMulti WiFiUDP UDP Create an instance of the WiFiUDP class to send and receive IPAddress timeServerIP time nist gov NTP server address const char NTPServerName time ...

Страница 44: ...lay 250 Serial print Serial println r n Serial print Connected to Serial println WiFi SSID Tell us what network we re connected to Serial print IP address t Serial print WiFi localIP Send the IP address of the ESP8266 to the computer Serial println r n void startUDP Serial println Starting UDP UDP begin 123 Start listening for UDP messages on port 123 Serial print Local port t Serial println UDP l...

Страница 45: ...ending NTP request NTP response 1488378234 UTC time 14 24 53 Sending NTP request NTP response 1488378294 UTC time 14 25 53 You should see the time update every second and Sending NTP request should show up every minute If you don t have an Internet connection the DNS lookup of the time server will fail Connecting Connected to Wi Fi SSID IP address 192 168 1 2 Starting UDP Local port 123 DNS lookup...

Страница 46: ...arily store the received file ESP8266WiFiMulti wifiMulti Create an instance of the ESP8266WiFiMulti class called wifiMulti const char OTAName ESP8266 A name and a password for the OTA service const char OTAPassword esp8266 const char mdnsName esp8266 Domain name for the mDNS responder WiFiUDP UDP Create an instance of the WiFiUDP class to send and receive UDP messages IPAddress timeServerIP The ti...

Страница 47: ...1000 The actual time is the last NTP time plus the time that has elapsed since the last NTP response tmpRequested false float temp tempSensors getTempCByIndex 0 Get the temperature from the sensor temp round temp 100 0 100 0 round temperature to 2 digits Serial printf Appending temperature to file lu actualTime Serial println temp File tempLog SPIFFS open temp csv a Write the time and the temperat...

Страница 48: ...FS File index html gz size 795B FS File manifest json size 169B FS File favicon ico gz size 1 91KB mDNS responder started http esp8266 local HTTP server started Starting UDP Local port 123 Time server IP 216 229 0 179 Sending NTP request NTP response 1488666586 Temperature requested Appending temperature to file 1488666627 20 00 Temperature requested Appending temperature to file 1488666687 19 94 ...

Страница 49: ...ecure connection to the server and send a secure HTTPS request with our email address and password Gmail will then respond with an XML document containing all kinds of information like parts of your most recent messages and the number of unread emails To make sure we don t send our Google password to a malicious server we have to check the server s identity using the SHA 1 fingerprint of the SSL c...

Страница 50: ......

Страница 51: ...rks you want to connect to wifiMulti addAP ssid_from_AP_2 your_password_for_AP_2 wifiMulti addAP ssid_from_AP_3 your_password_for_AP_3 Serial println Connecting int i 0 while wifiMulti run WL_CONNECTED Wait for the Wi Fi to connect scan for Wi Fi networks and connect to the strongest of the networks above delay 250 Serial print Serial println n Serial print Connected to Serial println WiFi SSID Te...

Страница 52: ...ll process our request and send the feed as a response over the same HTTPS connection This response is an XML document that consists of tags with angled brackets just like HTML If you need a lot of data it s recommended to use a proper XML parser library but we only need one tag so we can just skim through the response text until we find the fullcount x fullcount tag The number inside this tag is ...

Страница 53: ...dentials ZW1haWwuYWRkcmVzc0BnbWFpbC5jb206cGFzc3dvcmQ Other APIs Many services send their data in JSON format If you just need one piece of information you may be able to use the same approach of scanning the entire JSON text for a certain word but it s much easier to use a JSON parser like the ArduinoJson library It will deserialize the JSON text and create a JSON object you could compare it to an...

Страница 54: ...an just check out the example that comes with the ESP8266 Arduino Core Examples DNSServer CaptivePortalAdvanced I S The ESP8266 has an I S bus on the RXD pin It can run at 80MHz and has DMA direct memory access so it s really fast Its main purpose is to connect an I S DAC Digital to Analog Converter to have an audio output but you can use it for other things as well For example CNLohr managed to t...

Страница 55: ... the basics of the ESP8266 I hope this was interesting to you and that you ll use this knowledge for your own DIY projects If you have any remarks or if you want to help improve this guide don t hesitate to leave a comment or to send me a message Thank you for reading Pieter 8 3 2017 ...

Отзывы: