ACROBOTIC Industries ACROBOTIC Industries

DevKit (ESP8266): Getting Started

Overview

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


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:

http://learn.acrobotic.com/tutorials/post/what-is-the-esp8266

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
  • Demonstrated ability to run Lua (NodeMCU), JavaScript (Espruino), and Python (MicroPython) interpreters!
  • Arduino IDE integration

ESP8266 System On a Chip

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).

ESP8266 ESP-12E Module

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 GNDVin3.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!

ESP-12E Development Board Pinout

Priced under 10 USD, this board has everything you need to get started with building your next IoT project.  Following the different tutorials on this site, you can try out different firmware including Python and JavaScript interpreters!


Firmware Options

Thanks to concerted efforts of the community around the ESP8266, there are now a few different firmware options for the chip.  From custom firmware loaded directly onto the chip, to interpreters for processing commands through peripheral interfaces (e.g., SPI, UART) for languages such as Lua, JavaScript, and Python.  We outline the most popular options in this step, and we show you how to get started with each one further down this document.

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:

ESP8266 Basic AT Commands Specification

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

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.

ESPlorer tool for ESP8266

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!

ESP8266 development in the Arduino IDE

Other

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.

This neat little SoC has also received the attention from the Espruino and MicroPython communitites.  Both MicroPython and Espruino are fantastic interpreters (Python for the former and JavaScript for the latter) that can run on embedded platforms.  However, both of these options are still in very early stages of development for the ESP8266 and not all functionality is available!


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.

OS X

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:

ls /dev/tty.*

The device file created to communicate with the CP2102 has the name tty.SLAB_USBtoUART.  

Listing device files for USB to Serial UART module CP2012 on the NodeMCU development board

Linux

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.ACM   or /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.

Windows

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 Manager in the System section)
  • Under the Ports (COM & LPT) entry, there should be an open port named USB-SERIAL CP2102 (COM  ) where    is a number typically greater or equal than 3.

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.

Flashing tool

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
Firmware image

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 .

Usage

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.

Selecting Serial port option in the Arduino IDE for the ESP8266 Development Kit

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:

AT

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:

AT+GMR

Then, for instance, we can try out some of the Wi-Fi capabilities by first making the ESP8266 go into station mode:

AT+CWMODE=1

And then scanning for nearby networks:

AT+CWLAP

Using the Arduino IDE Serial Monitor for sending AT commands to the ESP8266

See the entire list of available commands on the "Firmware Options" step of this tutorial!


NodeMCU Firmware And Lua

Firmware image

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
Usage

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.

Configuring the ESPlorer program for 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.

Simple Lua script for scanning nearby wireless netowrks

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.

http://arduino.esp8266.com/stable/package_esp8266com_index.json

Arduino IDE preferences for ESP8266

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 Install.

Arduino IDE boards manager selection for ESP8266

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).

Arduino IDE options for ESP8266 

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!

Arduino IDE WiFi scan results with ESP8266


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!

ESP8266 Runs JavaScript Programs Using Espruino Firmware

See our detailed tutorial right here: link


Step-by-step Videos

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

JavaScript on the ESP8266 (ESP-12E) using Espruino

Python on the ESP8266 (ESP-12E) using MicroPython


Troubleshooting

NodeMCU
  • Unsupported major.minor version 51.0 error?

You need matching versions for your Java Runtime Environment (JRE) and Java Development Kit (JDK).

ESPlorer
  • 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.

Arduino IDE
  • 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!

Other

- Memory dump/reset issue:

If your program uses setTCPNoDelay(true) try commenting out that line or setting the parameter to false!


Comments, questions, or concerns? Drop us a line!.