An introduction to the ESP8266 microcontroller, a $4 WiFi module with an ARM processor, running the NodeMCU firmware, programmed in the Lua programming language.
This little thing is great because:
- it's cheap: $4, compared to $24 for the more popular arduino
- it comes with WiFi: if you were to get an arduino, you'd also have to get a WiFi module, possibly even an ESP8266!
With it, we can stream data from sensors, control appliances, build armies of robots...all over WiFi...all for $4.
(Logo by Tracy Loi)
This tutorial expects:
- some basic programming knowledge
- you know how to open a terminal, execute scripts and type in a commands
- you can find your way around Github
- a working Java installation
- Java SE version 7 or above
- we won't be using Java directly, but the application that loads software onto the microcontroller is a Java application
We've tested this tutorial on MacOS. It's possible to do with Windows, but there might be subtle differences when it comes to flashing the board and using the tools.
The list of materials is intentionally short; we can get up and running pretty fast.
Hardware:
Software:
- esptool Used to flash NodeMCU devkit
- SiLabs Drivers Used to communicate with the devkit
- ESPlorer IDE used to program the devkit
Binaries:
- NodeMCU firmware Latest release of the NodeMCU firmware
NOTE: installing the drivers requires a reboot - save your work before you start!
To make things easier all dependencies are bundled in the bin directory. We will go over how to install all the different tools.
There is also a bash script to bootstrap via CLI:
$ curl -SLs https://raw.githubusercontent.com/goliatone/wee-things-workshop/master/bin/bootstrap | bash
-
Connect the board to your computer.
-
Install the SiLabs Driver: The image is located in the
driversfolder. Double click to start the installation process. THIS WILL REQUIRE YOU TO RESTART YOUR COMPUTER -
Open up the ESPlorer IDE:
cdinto bin/ESPlorer. runjava -jar "ESPlorer.jar" -
Install esptool to flash the board:
cdinto bin/esptool. runpython setup.py install -
Prep the board to be flashed: Press the board's FLASH button and press the RST button at the same time. You should see an LED blink on the board.
-
Flash the board:
cdinto bin/esptool. runesptool.py --port=/dev/cu.SLAB_USBtoUART write_flash -fm=dio -fs=32m -ff=40m 0x00000 ../nodemcu_integer_0.9.6-dev_20150627.bin -
Unplug the USB cable and plug it again.
-
Woohoo!! Now we are ready to start coding. Open up the ESPlorer IDE (step 2) if you've closed it.
You can download the ESPlorer IDE from here. However, we will be using the version bundled with this tutorial for convenience.
NOTE: ESPlorer requires Java SE version 7 and above installed.
First, we need to un-zip the ESPlorer.zip file.
On Mac to open the IDE you need to do so from terminal. Open a new terminal window, cd to the ESPlorer directory created after uncompressing the zip file, and type this command in your terminal:
java -jar "ESPlorer.jar"
This command wil open up the IDE, it should look something similar to this:
We will be using the ESPlorer to validate our next step, installing the SiLabs Drivers.
NOTE:
Some online resources tell you to sudo the command in order to run the ESPlorer IDE. Most likely you will be able to leave it out.
From the SiLabs driver download page:
The CP210x USB to UART Bridge Virtual COM Port (VCP) drivers are required for device operation as a Virtual COM Port to facilitate host communication with CP210x products.
In order for your computer to communicate with the devkit you need to have installed special drivers. You can find the download link here. The bash script already downloaded the image file into your bin folder so open it up and follow the install instructions.
The ESP8266 runs a Lua interpreter and you can send in commands and read out results over serial.
NOTE:
This requires your computer to restart, save your work.
We will first install esptool in order to flash our boards. It's a python script which can be run using the Mac's default python. Open terminal and cd to the directory esptool directory and run the following command:
python setup.py install
This will install esptool.py system-wide.
If you do not want a global install you can follow the instructions on the repo to use the tool locally. It's really easy.
You can find the latest NodeMCU firmware at their github repository, in the release page following this link.
The ESP8266 chip comes loaded with an AT command set, and it's meant to be used by an external controller like an Arduino driving the chip over serial.
In this step, we are going to flash our devkit with the NodeMCU binaries downloaded before so we can start loading programs to the board. It sounds intimidating, but it's quite simple actually.
We already downloaded the NodeMCU firmware, installed the SiLabs drivers, and have esptool installed.
Connect the board to the computer using the USB cable.
From the project's main directory, open terminal and cd to the bin directory where the nodemcu_float_0.9.6-dev_20150704.bin file is located.
We need to put the board in flash mode. To do so hold down the board's FLASH button and press the RST button at the same time. You should see an LED blink on the board.
From terminal, cd into your project's bin/esptool directory. Then
type the following command in terminal and press enter:
esptool.py --port=/dev/cu.SLAB_USBtoUART write_flash -fm=dio -fs=32m -ff=40m 0x00000 ../nodemcu_integer_0.9.6-dev_20150627.bin
The script should provide some feedback in the terminal window while is executing.
Connecting...
Erasing flash...
Wrote 400384 bytes at 0x00000000 in 38.5 seconds (83.1 kbit/s)...
Leaving...
Now unplug the USB cable and plug it again.
Congratulations, we now have a board properly flashed and we are ready to start uploading code. We will do so using an IDE.
And with this we conclude the boring setup process. We are ready to start coding and making things. We will start by doing the mandatory hello world tutorial which will teach us how to load code into a devkit board. Next, we will do the classical hello world of electronics and get an LED blinking.
If you are not familiar with the Lua programming language you can always follow a quick intro tutorial. Check out the Lua links in the Resources section.
You should also check out NodeMCU's API wiki page. It covers succinctly all the different modules and their methods.
If you are new to programming, there is an online tutorial following the Learn the Hard Way method that uses Lua. Here
Lua has a package manager, LuaRocks. A package manager is a set of tools that help you install, upgrade, configure, and manage software packages, or modules, and their dependencies. From the LuaRocks website:
LuaRocks allows you to create and install Lua modules as self-contained packages called rocks.
If you are using Atom you can install the following plugins:
Sublime:
http://luajit.org/install.html
brew install luajit --with-52compat