Time to complete: 2–10min; Level of difficulty: Beginner
This guide will show you how to start programming the ESP8266 Serial to Wi-Fi module using a development board with a ESP-12E module and built-in USB to Serial adapter. Simply connect the board to a computer and start programming it using one of the firmware options: AT+Commands, NodeMCU, or your own via the Arduino IDE.
List of Materials
- 1 x ESP8266 (ESP-12E) Development Board
- 1 x ESP8266 ESP-01 Serial to Wi-Fi Module
- 1 x ESP8266 ESP-12E Serial to Wi-Fi SMD Module
- 1 x ESP8266 WeMos D1 Mini Development Board
What Is The ESP8266?
We've written a very detailed account of the ESP8266 System On a Chip (SoC), if you want to find out the full story behind this little chip we invite you to read it:
The ESP8266 Serial to Wi-Fi SoC, released in the summer of 2014, has become a center point in the development of inexpensive IoT applications. Given that Wi-Fi chips have been available for around a decade, you may be wondering what makes the ESP8266 special. Besides being released at the 'right' time, meaning as Internet Of Things (IoT) have entered everyday speak among developers and tech entrepreneurs, there are a few reasons behind its meteoric rise in popularity:
- Very capable microcontroller (32-bit 80MHz, built-in Wi-Fi, adequate I/O buses and peripherals; full specs below)
- Extremely low-cost; ~$1 in moderate volumes)
- Open SDK that works with GCC
- Arduino IDE integration
Because the ESP8266 was only released in a tiny-sized, tough-to-solder, QFN package, a market was opened for inexpensive breakout and adapter boards that facilitated working with the chip. The most popular were a series of modules branded ESP-NN – where NN is a 2 digit number sometimes followed by a letter.
The ESP-12E Development Board (aka NodeMCU DevKit)
Out of the many ESP-NN modules that have been released, ourselves alongside the rest of the ESP8266 community became fond of the FCC-certified ESP-12E, also known as the ESP-12F given that the first versions of the ESP-12E weren't FCC-certified!
The ESP-12E module breaks out all the available ESP8266 pins, and it includes a visible LED for indicating the status of the SoC's Tx pin, which is very useful during programming. In addition, under the tin can, the ESP-12E a 4MB SPI flash storage IC – typically the Winbond W25Q32FV, and all the necessary components needed for the onboard ESP8266 to operate properly (e.g., crystal, capacitors, resistors). It also includes an onboard antenna with a reasonable range (–70~–80 dBm at 50 feet).
The ESP-12E is a great breakout for the ESP8266, however, in order to maintain a small footprint it's been designed without any holes for pin headers. Rather than a breadboard-able module, the ESP-12E is meant to be mounted on a PCB. Moreover, to further increase the usability of the ESP-12E during rapid prototyping, some power regulation and USB connectivity are necessary. This is what ourselves and other US-based DIY Electronics vendors have contributed to the ESP8266 ecosystem. In our case we've developed a board that includes, among other passive components and discrete ICs, a Silicon Labs CP2102 USB to Serial UART adapter, a NCP1117 3.3VDC Voltage Regulator, a micro-USB connector, and through-hole (male) pin headers.
Our implementation closely follows the Open-Source design of the NodeMCU Team, the board breaks out all the (available) ESP8266 pins to through-hole headers for easy breadboarding. The board also includes additional GND, Vin, 3.3VDC signals for easy access during development. This development board for the ESP8266 SoC inside the ESP-12E module is out-of-the-box ready for you to connect it to your computer, install USB drivers, and start writing programs that connect to your Wi-Fi network!
Please note that only one firmware option can be running on your ESP8266 at a time. For instance, if you have the the factory firmware (AT+Commands interpreter) and upload the Blink program from the Arduino IDE, you'll need to re-flash the AT+Commands firmware to be able to use it once again. The process is painless, so we encourage you to try all options available.
AT+Command Processor (Default)
The quickest way to get started with the ESP8266 is to use its factory firmware, which allows it to process any AT+Commands that it receives over its Serial UART interface. The biggest advantage of this option is that we need not be familiar with any specific language or framework to use the module. We can simply send it a series of commands to achieve our goal. The downside to this is that we need either an additional microcontroller involved or a USB to Serial adapter to send the necessary commands. Some of the basic AT+Commands available are:
For the full list, please see the document: https://acrobotic.com/datasheets/ESP8266_at_commands.pdf.
Whereas the AT+Commands are a standard way of communicating with RF chips (since the 80s!), they pose the limitation of needing an additional (host) device to run application code that, when needed, sends AT+Commands to specify the behavior of the RF interface. However, one aspect that made the ESP8266 stand out is its ability to store application code alongside the Wi-Fi code inside its own memory space, or in a separate SPI flash memory IC. This was further aided by Espressif willingness to open most of its Software Development Kit (SDK), which allowed developers to implement a toolchain (including the GNU Compiler Collection) to flash different firmware options.
NodeMCU is, at the moment, the most popular alternative firmware that runs on the ESP8266. Based on the eLua project, it runs a Lua interpreter onboard the ESP8266, which is able to execute commands written in the Lua scripting language. The commands are sent to the ESP8266 via the Serial UART interface.
NodeMCU is a great starting point for Makers as it provides an interactive environment that allows running commands not only for controlling the ESP8266's wireless interface, but also its GPIO and hardware functionality such as PWM. In addition, we have access to the full scope of the Lua programming language for writing our applications. In the case of the default firmware (AT+Commands Interpreter), the application code would have to be developed using a programming language suited to the host microcontroller or SoC that would be sending the commands over Serial (e.g., C/C++ for the Atmel/ARM microcontrollers on Arduino boards).
Not only does the NodeMCU firmware allows us to execute commands interactively, but we can save our applications as a script in the ESP-12E's flash memory, and instruct it to run the application code every time it restarts! Even though this is a convenient option, our preferred method of working with the ESP8266 is to write our own firmware using the Arduino framework (details below).
Custom Firmware (using the Arduino IDE)
Whereas custom firmware can be compiled and flashed onto the ESP8266 directly, the easiest way of loading your own firmware is by using the Arduino IDE. Although some users might find cumbersome to use the Arduino program structure to write their application code, we certainly favor this option in most of our projects. Even though this method erases any existing firmware on the ESP8266's flash memory, it is a straight-forward process to re-flash any of the other options!
For advanced users, there is the esp-open-sdk toolchain which allows us to progam the ESP8266 directly (more info at the esp8266.com wiki) without having to use the Arduino IDE for uploading the code to it.
Installing The USB Drivers
No matter what firmware option we choose, we first need to communicate with the ESP-12E Development Board using a computer's USB interface. The USB to Serial UART module included on the board is Silicon Labs' CP2012, for which we usually need to install the readily available Virtual COM Port (VCP) drivers for your specific Operating System.
Once installed, we should verify that the CP2102 is recognized by the computer.
After connecting the USB cable to both the USB port on the computer and the board, we can open a terminal window and list the available devices by:
The device file created to communicate with the CP2102 has the name tty.SLAB_USBtoUART.
Luckily for Linux users, the CP2102 is recognized without the need for installing drivers! Similar to OS X we can open up a Terminal window, and issue the same command:
ls /dev/tty* | grep 'USB\|ACM'
On Linux, boards carrying USB to Serial adapters (e.g., CH340, CP2102, FT232R) are listed as either
/dev/tty.USB where is a number. Issuing the command once prior to connecting the USB is a quick way to narrow down which entry corresponds to the board.
Once the driver is installed, we can connect the USB cable to both the USB port on the computer and the board. After doing so we should see the message:
Device driver software installed successfully.
Also, we can manually verify that everything is in working order by following these steps:
- Open the
Device Manager(available through
Control Panel → System & Security → Device Managerin the
- Under the
Ports (COM & LPT)entry, there should be an open port named
USB-SERIAL CP2102 (COM )where
Now that we're ready to communicate with our ESP8266 via the CP2102, we can explore a few of the different firmware options available.
AT+Commands Firmware Interpreter
The company behind the ESP8266 SoC, Espressif Systems, has made available the necessary device information for developers to come up with the necessary toolchain to program the device. For loading any firmware to the ESP8266 we need two things: a flashing tool and an image to flash. Bear in mind that in this context, the term 'flashing' means writing data to a flash memory storage device.
There are a few different options for tools that are able to flash firmware onto the ESP8266. Our preference is towards those that work on any Operating System (i.e., cross-platform). In this case we'll use esptool, a Python-based ESP8266 flashing tool developed by Fredrik Ahlberg.
From our terminal, we clone the entire repository by:
git clone https://github.com/themadinventor/esptool
With the flashing tool downloaded, the next step is to download the image we want to flash. Same as before, we have a few different options for which image (containing the AT+Commands Interpreter) to use. In our case, we'll use the one made available by Ai-Thinker, which wer're curating in a shared folder on Google Drive. To download the file, access the ESP8266 on Google Drive (no need to have a Google account or sign in) and then download the .bin file:
Firmware → AT+Commands (Ai-Thinker) → v1111ATFirmware.bin
Flashing the firmware to the ESP8266
Before being able to use esptool, we need to install the Python module pySerial on our system. This can be done in a few ways depending on your Operating System. One way is to download the module's source code:
git clone https://github.com/pyserial/pyserial
And install it by running the following command in the Terminal (or PowerShell for Windows users):
sudo python setup.py install
With the module installed, we can now flash the image we downloaded using the esptool program. We'll need to know the location of the file in our system as well as the name of the device file or COM port, which in our case are "~/Downloads/v0.9.5.2\ AT\ Firmware.bin" and "/dev/tty.SLAB_USBtoUART" respectively. Then, we can run the esptool program by:
python esptool.py --port /dev/tty.SLAB_USBtoUART write_flash 0x00000 ~/Downloads/v1111ATFirmware.bin
Once this is done, we can start AT+Commands to communicate with the ESP8266 .
From the different ways of sending messages over the computer's USB, we're going to use the Arduino IDE's Serial Monitor for this purpose. We only need to choose the appropriate option from
Tools → Serial Port → yourserialport (in our case /dev/cu.SLAB_USBtoUART) and opening up the Serial Monitor window. Because we're not going to upload firmware to the board with the IDE, we need not worry about the selected Board, the default Arduino Uno selection is okay.
In the Serial Monitor window we need to first adjust two settings. We set the line ending drop down menu to "Both NL & CR" and also the baud rate to 115200. Once that's done, we can enter the test AT+Command:
This simply returns an OK message, which serves as a quick check for knowing that the ESP8266 is listening to the AT+Commands received on its Serial UART port. Another simple check is to ask for the firmware version:
Then, for instance, we can try out some of the Wi-Fi capabilities by first making the ESP8266 go into station mode:
And then scanning for nearby networks:
See the entire list of available commands on the "Firmware Options" step of this tutorial!
NodeMCU Firmware And Lua
Similar to what we did before, we want to download an image for the NodeMCU firmware, so that we can use the esptool program to flash it. The latest version of NodeMCU can be downloaded from the project's Github repository.
Flashing the firmware to the ESP8266
Once downloaded, we can use esptool as we did before, remembering to change the name of the image file and device:
python esptool.py --port /dev/tty.SLAB_USBtoUART write_flash 0x00000 ~/Downloads/nodemcu_float_0.9.6-dev_20150704.bin
Because the NodeMCU firmware is a Lua interpreter we're need to make use of the fantastic Java-based tool written by Victor Brutskiy, the ESPlorer. For a comprehensive getting started guide covering the ESPlorer tool, refer to Rui Santos' documentation.
After making sure that the latest Java Runtime Environment (JRE) and the Java Development Kit (JDK) are installed (and their versions match), we can simply double-click the ESPlorer.jar file inside the .zip archive we downloaded. The first thing we want to do in ESPlorer is configure the baud rate to 9600 and select the correct device from the drop-down menu (in our case /dev/u.SLAB_USBtoUART). We can then click on
Open to start communicating with the ESP8266.
After we've established communication with the device we can start running code written using Lua. In the ESPlorer's editor we can write the simple script:
-- print ap list function listap(t) for k,v in pairs(t) do print(k.." : "..v) end end wifi.sta.getap(listap)
Once we're done, we can click on the "Send to ESP" buttons in order to send the code to the NodeMCU Lua Interpreter running on the ESP8266. After the code runs, the ESP8266 sends back a response that is displayed in the output window of ESPlorer containing a list of the nearby Wi-Fi networks.
In a follow-up tutorial featuring the ESP8266, we'll show you how to make the code run automatically, every time the ESP8266 starts.
Custom Firmware With The Arduino IDE
For those of us who want to use the ESP8266 as a regular microcontroller such as the ATmega328 in the Arduino UNO, then it's possible to write custom firmware and load it on the chip. As is typical in programming microcontrollers, the custom firmware will replace anything previously stored in the chip's flash memory.
Although we can use the manufacturer's SDK to develop our custom firmware, it is much easier to use the good ol' Arduino IDE. If you don't have it installed, please look at our detailed tutorial on how to get it on your system.
In the Arduino IDE open the Preferences window and enter the URL below into the Additional Boards Manager URLs field, and select OK.
Select the menu option
Tools → Board → Boards Manager... and scroll down and to locate the option esp8266 by ESP8266 Community which should be the last item on the list, and click
After restarting the Arduino IDE we can now select the board we're using from the menu option
Tools → Board → NodeMCU 1.0 (ESP-12E Module). Then, we specify the correct CPU Frequency (
Tools → CPU Frequency: "" → 80MHz) and Upload Speed (
Tools → Upload Speed: "" → 115200). Finally, the last step is to select the correct option for the Port (
Tools → Port → /dev/cu.SLAB_USBtoUART).
At this point we can write our own firmware and upload it. To get started we can try one of the examples
File → Examples → ESP8266WiFi → WiFiScan. After uploading it, we can open the Serial Monitor window and observe the results. Note that we need to match the baud rate, so check that 115200 is selected from the drop down menu!
Other Firmware Options
You can also run many other firmware options on your ESP8266 Development Board. Remember, however, that only one firmware will run at a time. Do not be discouraged, though, as you can see in these tutorials switching among them isn't difficult at all!
See our detailed tutorial right here: link
We've made a set of videos on how to get started with the different firmware options above. These should guide you on your way, describing each option step by step:
Programming the ESP8266 (ESP-12E) from Arduino IDE
Python on the ESP8266 (ESP-12E) using MicroPython
- Unsupported major.minor version 51.0 error?
You need matching versions for your Java Runtime Environment (JRE) and Java Development Kit (JDK).
- Can't autodetect firmware, because proper answer not received.
You typically receive this message after flashing the NodeMCU firmware as the
init.lua file is not created by default. In consequence, the message
lua: cannot open init.lua is generated during the startup sequence of NodeMCU firmware, which isn't the answer that the ESPlorer program expects. Once you save the file to the ESP8266, the warning goes away.
- "Communication with MCU" message idles
You may need to press the reset button on your board.
- Can't upload firmware to the ESP8266.
Trying to upload firmware gives the error:
xtensa-lx106-elf-g++ No such file or directory
Update the IDE to the latest version (1.6.5). Remove the installed boards from
Tools → Board → Boards Manager... by scrolling down to the esp8266 by ESP8266 Community option and clicking on Remove. Restart the Arduino IDE and re-install the esp8266 boards package. Restart the application once again, and everything should be in order!
- Memory dump/reset issue:
If your program uses
setTCPNoDelay(true) try commenting out that line or setting the parameter to false!