An introduction to the ESP8266, how to program it, and tools to help us do so.
The ESP8266 microcontroller is a WiFi module with an ARM processor, we will use the NodeMCU firmware and will program 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: Arduino need separate modules to be "connected", possibly even an ESP8266!
With the ESP8266, we can stream data from sensors, control appliances, build armies of robots...all over WiFi...
(Logo by Tracy Loi)
This tutorial expects:
- you have 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
- you have Node.js installed in your machine
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.
Software:
- SiLabs Drivers Used to communicate with the devkit
- node-esp Command line interface to program the devkit. Binaries:
- NodeMCU firmware Latest release of the NodeMCU firmware
The quick setup consists of 8 steps. Below you can find a more detailed set of instructions.
Clone this repo or download the zip archive. The following steps are relative to the projects main directory.
-
Install the SiLabs Drivers: The disk image ,with a dmg extension, is located in the
driversfolder. Double click to start the installation process. THIS WILL REQUIRE YOU TO RESTART YOUR COMPUTER AFTER INSTALLING THE DRIVER -
Ensure you have Node.js installed.
-
From terminal, use npm to install node-esp:
npm i -g node-esp. -
Set the node-esp port:
esp port set /dev/cu.SLAB_USBtoUART -
Connect the board to your computer.
-
Prep the board to flash the NodeMCU firmware:
- From terminal,
cdinto bin.
- From terminal,
-
Flash the board: from terminal run
esp flash nodemcu_integer_0.9.6-dev_20150704.bin -
Unplug the USB cable and plug it again.
Woohoo!! Now we are ready to start coding.
NOTE: This requires your computer to restart, save your work.
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 ESP8266 runs a Lua interpreter and you can send in commands and read out results over serial.
If you don't have Node.js installed in your computer, download the installer from here.
We will be using node's package manager, npm, to install our CLI tool.
Once you know you have node then npm should be available from terminal as well.
$ npm i -g node-esp
To ensure we the utility installed correctly, open a terminal window and type esp --help. It should display the help dialog.
The first time you use the esp tool you need to configure the port to talk to the NodeMCU board:
$ esp port set /dev/cu.SLAB_USBtoUART
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, think of it as upgrading the operating system on a computer.
We already downloaded the NodeMCU firmware, installed the SiLabs drivers, and have esp installed.
Connect the board to the computer using the USB cable.
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 directory. Then
type the following command in terminal and press enter:
esp flash nodemcu_integer_0.9.6-dev_20150704.bin
The script should provide some feedback in the terminal window while it 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 setup and we are ready to start uploading code.
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.
Now you can proceed with the next tutorials:
- NodeMCU wiki
- The unoficial NodeMCU FAQ
- MQTT on the NodeMCU
- NodeMCU iot 1
- NodeMCU iot 2
- Custom NodeMCU builds
If you are new to programming, there is an online tutorial following the Learn the Hard Way method that uses Lua.
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:
If you are using Sublime Text you can install the following plugins:
Some of this plugins might require you to install Lua JIT compiler, on Mac use brew:
brew install luajit --with-52compat
All wiring diagrams in the tutorials were made using the amazing fritzing open-source project.
The fritzing NodeMCU board part used here was done by Daniel Eichhorn
A lot of people have contributed directly and indirectly to this workshop, and in different capacities. Thank you all.
- Aurelia Moser
- Alan Jackson
- Angus Gratton
- Daniel Eichhorn
- David Mills
- Marcel Stör
- Grace Tan
- Tracy Loi
This page has two Amazon associate links, one for the USB cable and one for the ESP8266. The money collected through the links will be matched- out of my pocket- and donated to Girl Develop It.