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 is 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

Table Of Contents

Prerequisites

This tutorial expects:

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.

Materials

The list of materials is intentionally short; we can get up and running pretty fast.

Hardware:

Software:

Quick Start

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.

  1. Install the SiLabs Drivers: The disk image ,with a dmg extension, is located in the drivers folder. Double click to start the installation process. THIS WILL REQUIRE YOU TO RESTART YOUR COMPUTER AFTER INSTALLING THE DRIVER

  2. Ensure you have Node.js installed.

  3. From terminal, use npm to install node-esp: npm i -g node-esp.

  4. Set the node-esp port: esp port set /dev/cu.SLAB_USBtoUART

  5. Connect the board to your computer.

  6. Prep the board to flash the NodeMCU firmware:

    • From terminal, cd into bin.

  7. Flash the board: from terminal run esp flash nodemcu_integer_0.9.6-dev_20150704.bin

  8. Unplug the USB cable and plug it again.

Woohoo!! Now we are ready to start coding.

Set up

SiLabs Drivers

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.

Node.js

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

NodeMCU firmware

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.

Flashing the NodeMCU

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.

Tutorials

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:

Resources

ESP8266

The ESP8266 is a microcontroller with 2.4 GHz WiFi capabilities supporting the WPA/WPA2 protocols, general-purpose input/output (GPIO), Inter-Integrated Circuit (I2C), analog-to-digital conversion (ADC), Serial Peripheral Interface (SPI), and pulse-width modulation (PWM). The chip operates at 80Mhz, has a 64KB boot ROM, 64KB instruction RAM, and 96KB data RAM.

NodeMCU

Lua

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

Wiring Diagrams

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

Thank you.

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

Disclosure

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.