4. Software and Firmware Install¶
We are now ready to start installing software on our board, over the USB connection. For this, you will need a Mac, Linux PC, or Windows PC. We have only tested the firmware procedure on Mac and Linux, so those systems are recommended. However, others have successfully installed MicroPython from Windows, so it should work.
In the instructions that follow, we will use the term “host computer” to mean your PC/Mac/Linux box and “ESP8266” to mean the ESP8266-based system you have assembled on the breadboard.
Software Prerequisites¶
Python¶
On your host computer, you will need an installation of Python 3, version 3.4 or later. As described below, you will be adding a few packages to your Python install. Rather than add these packages to your system-wide Python install, we recommend installing them into a virtual environment. See the Python documentation page for venv for details.
Erasing and flashing the firmware is done through a utility called
esptool.py
[1]. You can install it via pip
with the command:
pip install --upgrade esptool
If pip
on your system defaults to Python 2, then use pip3
instead.
We will also use mpfshell
, a shell-like utility for moving files between the
ESP8266 and the host computer. [2] It is available on GitHub: https://github.com/wendlers/mpfshell.
Install it with:
pip install git+https://github.com/wendlers/mpfshell
We will use the ThingFlow framework for writing some of the software running on
the ESP8266. Please download or clone the ThingFlow repository on GitHub:
https://github.com/mpi-sws-rse/thingflow-python. Note that we will not be using
the packaged version of ThingFlow available on pypi.python.org. That version is only for
the standard CPython implementation. We will be using the code in the
micropython
subdirectory of the ThingFlow source tree.
MicroPython Firmware¶
You can download the latest version of the MicroPython firmware for ESP8266 from
here: http://micropython.org/download#esp8266. You will want the latest stable
firmware version [3]. Since the name of the firmware file will change over time,
we will refer to it as esp8266-YYYYMMDD-vX.Y.Z.bin
in any commands. Just substitute
with name of your image file.
Mac-specific¶
If you are using a Mac, you will need to download a USB to UART bridge driver from Silicon Labs. This will allow your Mac to send serial communications for the Silicon Labs USB adapter chip on your ESP8266 board. The driver is available from their website: https://www.silabs.com/products/mcu/Pages/USBtoUARTBridgeVCPDrivers.aspx
For interacting with the Python REPL running on the ESP8266, you will use the
screen
program. It comes pre-installed on MacOS.
Linux-specific¶
You should not need any drivers for the serial connection. You will want to add
your user to the dialout
group so it can access the tty device for the serial
connection. Replacing MYUSER
with your user id, the command is:
sudo adduser MYUSER dialout
We will be using the GNU screen
program to interact with the Python REPL
running on the ESP8266. If it is not already installed, you will need to do so.
If you are running a Debian-based distribution (Debian, Ubuntu, Raspbian), then
you can install it via:
sudo apt-get install screen
Windows-specific¶
You will need the PuTTY
program to interact with the Python REPL running
on the ESP8266. It is free and available at http://www.putty.org.
As stated above, we have not attempted this process with a Windows host. We suggest that you follow the instructions here: http://www.instructables.com/id/The-Super-Easy-Micropython-ESP8266-Guide-No-Guessw/?ALLSTEPS.
The rest of the instructions below are for Mac and Linux. You should be able to
follow along using the Instructables guide as a reference. You will use PuTTY
instead of screen
. Of course, the command options will be slightly
different.
Testing Your Connection¶
With the prerequisite software installed, you can now connect your ESP8266 and
verify that it can talk to your host system. Using the microUSB to USB cable,
plug it into the USB port. Now, look for a new serial tty device in your
/dev
directory. On Mac, it should be called /dev/tty.SLAB_USBtoUART
.
On Linux, it should be called /dev/ttyUSB0
. The device will only be
present when your ESP8266 board is plugged in.
Now, run screen
as follows (substituting TTYDEVICE
with ttyUSB0
or
tty.SLAB_USBtoUART
):
screen /dev/TTYDEVICE 115200
The 115200
is the baud rate. Now, press the reset key. You should see some
characters, either a prompt or some garbage. If you get garbage, you might
try a baud rate of 9600. Do not be worried at this point if you only see garbage,
we are going to rewrite the firmware anyway. As long as you saw the tty device,
you should be OK.
Now, exit screen
(pressing Control-A k and then “y”), and run the reset
command in your terminal session. You are ready to install the firmware.
Installing the Firmware and Testing the REPL¶
We will use esptool.py
to erase the old firmware and install the latest
version of MicroPython [4]. Plug your ESP8266 back into the USB port and run
the following from the command line:
esptool.py --port /dev/TTYDEVICE erase_flash
Now, install the new firmware with the following (substituting in the device name and MicroPython image file name):
esptool.py --port /dev/TTDEVICE --baud 460800 write_flash \
--flash_size=detect --verify -fm dio 0 esp8266-YYYYMMDD-vX.Y.Z.bin
If this step fails, you might try lowering the baud rate (e.g. from 460800 to 115200).
Next, we will use screen
to connect to our board. From the command line:
screen /dev/TTYDEVICE 115200
Now, press the reset button on your ESP8266 board [5]. In your screen
session,
you should see some garbage characters followed by a version string and a
prompt. For example:
You should now be able to type Python code in at the prompt:
>>> print("Hello, world")
Hello, world
>>>
Congratulations, you have MicroPython running on your ESP8266! If you had problems, you might try looking at the troubleshooting hints provided in the MicroPython documentation [6].
Next, let’s write an application for our board.
[1] | https://pypi.python.org/pypi/esptool/1.3 |
[2] | MicroPython has a web-based interface for transferring files
over the WiFi network. However, we have seen some problems with using it
and recommend using mpfshell |
[3] | At the time this is being written, the latest stable version is 1.8.7,
and the firmware image filename is
esp8266-20170108-v1.8.7.bin . |
[4] | You can also find instructions for this in the MicroPython documentation. The relevant section is at https://docs.micropython.org/en/latest/esp8266/esp8266/tutorial/intro.html |
[5] | On both the NodeMCU and Adafruit boards, the reset button is labeled “RST”. You can use this button to force a reboot of the system. This is useful to get it to a known state (recommended after plugging into the USB connection). |
[6] | https://docs.micropython.org/en/latest/esp8266/esp8266/tutorial/intro.html#troubleshooting-installation-problems |