Supplemental Guides


You Will Need

ESP8266 NodeMCU
MicroUSB Cable
Computer running Windows, Linux, or MacOSX


Background

In the process of learning MicroPython for myself, I have used many different setups for programming microcontrollers. Through my journey, I found that the most streamlined and simple way of programming a microcontroller with MicroPython is through a program called Thonny. Thonny is a Python IDE that keeps the process of programming a microcontroller simple, which is great for beginners.

The rest of this guide will go over setting up Thonny for an ESP8266 NodeMCU, flashing the MicroPython firmware, and lastly, writing and running a simple program for an ESP8266 microcontroller.


Downloads

Thonny

If you are using Linux, I recommend installing Thonny using pip. If you are using Windows or MacOSX, then I recommend installing Thonny through the download links on the Thonny website.


Install Thonny from Thonny.org

Download the Thonny installer from thonny.org and run it.

Download Thonny from its website.
Download Thonny from its website.


Install Thonny using Pip

Open a terminal and enter pip install thonny. If the process fails, try running the same command again with elevated privileges (sudo).


Acquiring Micropython Firmware

In order to run MicroPython scripts, our device will need to be flashed with the MicroPython firmware.

From the Micropython website, download the binary (.bin) file for ESP8266 microcontrollers tagged as “latest”. Take note of its location in your filesystem.

Download the latest MicroPython firmware for ESP8266 microcontrollers.
Download the latest MicroPython firmware for ESP8266 microcontrollers.


Thonny Setup

Plug in your ESP8266 NodeMCU microcontroller to your computer using a microUSB cable and launch Thonny.

Immediately navigate to “Tools > Manage plug-ins…” and enter “esptool” into the search bar. Then click on the “Find packages from PyPI” button. An entry for esptool should appear in the space below. Click on the “Install” button to install it. After it is finished installing the plug-ins window can be closed. Then close and reopen Thonny.

Install the esptool plug-in for Thonny.
Install the esptool plug-in for Thonny.

Next navigate to “Run > Select Interpreter”. Under the “Which interpreter or device should Thonny use for running your code?” label, select “MicroPython (ESP8266)”. Select your NodeMCU’s port under “Port”. If you do not know how to find your device’s port, learn here

Set the interpreter and the port.
Set the interpreter and the port.

After setting the interpreter and the port, click on the button that says “Open the dialog for installing or upgrading MicroPython on your device”. Select your device’s port again, and browse for the MicroPython firmware that you downloaded earlier for the “Firmware” field. Make sure that “Erase flash before installing” is checked, then click “Install”.

Set the correct parameters for flashing the MicroPython firmware to an ESP8266 microcontroller.
Set the correct parameters for flashing the MicroPython firmware to an ESP8266 microcontroller.

Thonny will now erase any existing firmware and then flash the MicroPython firmware on your NodeMCU. This may take a few minutes. After the firmware has finished installing, you may close all of the open dialogs.

Thonny has completed flashing the firmware on the microcontroller.
Thonny has completed flashing the firmware on the microcontroller.

At the bottom of the Thonny window in the tab labeled “Shell” you should see text that resembles the image below.

MicroPython repl ready for input.
MicroPython repl ready for input.

If the last line of the repl is not >>> then your REPL is not ready for input. To fix this press the stop button at the top of the Thonny window. This often means that the microcontroller is running something and needs to be stopped before being given REPL commands.

Issue stop command to microcontroller.
Issue stop command to microcontroller.

To test that the firmware is installed correctly, enter the following lines of code into the repl:

>>> import esp
>>> esp.check_fw()

You should get output that looks like the following image.

Verify MicroPython firmware on the ESP8266.
Verify MicroPython firmware on the ESP8266.

If you get to this point, then you are ready to start programming your ESP8266 with MicroPython!


Hello World

Lets write a quick “Hello World” program to demonstrate MicroPython running on the ESP8266 NodeMCU. Copy the following code into the editor area in Thonny.

from machine import Pin
from time import sleep

led = Pin(16, Pin.OUT)

for _ in range(10):
    led.value(0)
    sleep(1)
    led.value(1)
    sleep(1)
A blinking LED program is the hardware version of a 'Hello World' program.
A blinking LED program is the hardware version of a 'Hello World' program.

After putting the code into the editor, navigate to “File > Save As”. You will then get a window asking whether to save the file to your computer or the microcontroller. Select “MicroPython device”.

Select the option to save the file to the 'MicroPython device'.
Select the option to save the file to the 'MicroPython device'.

Now name the file “main.py” and click “Ok”. It is important to name the file “main.py” because the MicroPython always runs “boot.py” first, and then looks for “main.py” to run second.

Name the file 'main.py'.
Name the file 'main.py'.

To run the program on the microcontroller press the play button at the top of Thonny.

Run the file on the microcontroller by pressing the play button.
Run the file on the microcontroller by pressing the play button.

You should now see that the microcontroller runs the program in ‘main.py’ and blinks the built in LED ten times.

The NodeMCU running a blink script.
The NodeMCU running a blink script.

You have now written and run your first program using MicroPython. I encourage you to experiment by testing your own code in ‘main.py’.

Next guide: Basic GPIO Input and Output with a NodeMCU and Micropython