Introduction: Get Started With ESP8266 Using AT Commands, NodeMCU, or Arduino (ESP-12E)
This Instructable will show you the steps needed to get started with the ESP8266 using a fantastic little development board for the ESP-12E module.
For more like this, please visit our Learning Resources!
The board includes everything needed including a USB to Serial adapter, surface-mount LED, and voltage regulator. In addition, it is easily mountable on a breadboard for developing your own IoT project(s)!
Edit: we now have the steps in this tutorial in video form!
The main goal of the Instructable is to cover all the different options you can use in terms of firmware for developing applications that use the ESP8266 to connect to the web. The content, although available, is scattered throughout various sites around the web thus we decided to condense it in one place.
Excited? Let's get started!
Step 1: What Is the ESP8266?
Since the summer of 2014, the ESP8266 has seen a wide adoption as a cost-effective solution for IoT and WiFi-capable devices. The ESP8266 was developed by Shangai-based Espressif Systems, as a Serial (UART) to Wi-Fi SoC (System On a Chip) based around a Tensilica Xtensa LX3 DPU. This tiny IC includes an RF front end, RAM, and (usually) an onboard TCP/IP stack that allows it ready to connect to a nearby Access Point, to act as an Access Point itself, or both.
Family of Breakout Boards (ESP-NN)
Quickly after launch, a variety of breakout boards for the ESP8266 started becoming available. The most popular ones have been the ESP-NN series, which typically integrate the SoC along with Flash RAM, a crystal, and even an onboard antenna. The most salient distinction between different ESP-NN models are the pins that are broken out from the ESP8266 (for a full list see http://www.esp8266.com/wiki/doku.php?id=esp8266-module-family).
As the ESP8266 was developed as a Serial to Wi-Fi adapter, its firmware implemented an intertrepeter for AT commands. Thus initial usage of the IC was limited to using a either a USB to Serial adapter, or a separate microcontroller (e.g., ATmega328) to issue AT commands over the ESP8266's Serial UART interface. For this reason, the ESP-01 board quickly became popular amongst the ESP8266 community becaue of its 2×4, 0.1in-pitch connector that can be easily wired to a USB to Serial adapter. The connector gave access to the pins used for serial communication, namely RX and TX, as well as 4 control pins, GPIO0, GPIO2, CH_PD and RST (reset), along with VCC and GND.
However, other ESP-NN boards offer access to a wider variety of pins, although their packaging is of a custom Surface-Mount Device, with castellated pins as seen in the documentation page linked above. From the different ESP-NN boards, we began to experiment with the ESP-12E. The main reason is that this module was the one chosen by the developers of the NodeMCU project for their hardware DevKit 1.0 (see Firmware Options for details about NodeMCU).
Because the ESP8266 provides a cost-effective solution to the rapidly growing market of internet-connected projects and devices (i.e., the so-called Internet Of Things), it has become one of the most popular development platforms over the past year and a half. In consequence, a dedicated community has formed around the platform (http://esp8266.com), which has been focused on improving its functionality. For starters, different firmware options have been ported to run on the ESP8266, effectively taking it from a simple Serial to Wi-Fi adapter into a fully functional microcontroller with access to its GPIO and hardware-based functions like PWM, I2C, 1-Wire communication, and ADC; all this, of course, in addition to maintaining its Wi-Fi capabilities.
Step 2: List of Materials
For this Instructable we'll be using the following materials:
1 x ESP8266 (12-E) Development Board with onboard USB-to-Serial
Step 3: Firmware Options
A few different firmware options are available for the ESP8266. These allow us to access the module in different ways, as you can see below.
AT Command Processor (Default)
The quickest way to get started with the ESP8266 is to use its original 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.
For the full list, please see the documentation (https://learn.acrobotic.com/datasheets/ESP8266_AT_Commands.pdf).
Whereas the AT commandsare the standard way of communicating with wireless-capable ICs (e.g., Bluetooth, Wi-Fi, GSM), they pose the limitation of needing another module to run the application that specifies these commands accordingly. However, if we could run the application within the ESP8266 itself then we'd have everything self-contained by a single IC. Fortunately, Espressif made a Software Development Kit (SDK) available that allowed users to flash different firmware options.
NodeMCU
NodeMCU is, at the moment, the most popular alternative for firmware running 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 i2c and 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 microcontroller or SoC we use to develop the interface for sending the commands over Serial (e.g., C/C++ for microcontrollers in the Arduino boards).
Finally, not only does the NodeMCU firmware allows us to execute commands interactively, but we can save our applications as a script in the ESP8266'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 the NodeMCU Development Board is shipped with the latest version of the NodeMCU firmware, we can very easily replace it using the Arduino IDE. This allows us to run our own firmware on the ESP8266, which executes every time the module is powered. Even though this method erases the NodeMCU firmware from the ESP8266's flash memory, it is a straight-forward process to go back to using it!
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 availab
Step 4: Installing the USB Drivers
The USB to Serial UART module included on the NodeMCU Development Board is Silicon Labs' CP2012, for which we usually need to install the readily available Virtual COM Port (VCP) drivers.
Once installed, we can 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:
ls /dev/tty.*
The device file created to communicate with the CP2102 has the name tty.SLAB_USBtoUART. Now that we're ready to communicate with our ESP8266 via the CP2102, we can explore a few different firmware options.
Step 5: The AT Commands Interpreter
The developers of the fantastic ESP8266 SoC have made available the necessary tools to update the firmware on the module. In our case, we need to use these tools to be able to use the AT Commands Interpreter. As mentioned above, our NodeMCU Development Board comes loaded with the NodeMCU firmware. Similarly, if you're using this guide with other development boards and modules, you might also need to replace their firmware so this will be good practice.
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 typical preference leans towards solutions 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 Electrodragon (as recommended in their wiki). Navigate to their shared folder ESP8266 (Google Drive) and then download the .bin file:
Firmware → AT_Bin files → 0.952 support SmartLink → v0.9.5.2 AT Firmware.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/v0.9.5.2\ AT\ Firmware.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.
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
which simply returns an OK message. Then, for instance, we can try to scan for nearby networks by entering:
AT+CWLAP
See the entire list of available commands on the "Firmware Options" step of this tutorial.
Step 6: 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.
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.
Step 7: 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_esp8266c...
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.
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