In this tutorial, we are going to be discussing how to install and use MicroPython on your HUZZAH32 Feather microcontroller board in order to get you started with your first embedded scripts. The HUZZAH32 Feather features the ESP32 SOC, which has the benefit of being programmable using either the MicroPython language or in the Arduino IDE. If your course requires Arduino, please visit the Flashing Arduino tutorial. Otherwise, strap in and get ready to start programming!

What is MicroPython?

Before we can answer the question of “What is MicroPython?”, we will begin with a little background information on programming languages in the context of microcontrollers. Historically and presently, the most widely used language for programming microcontrollers is C/C++. In fact, the Arduino “programming language” is referred to as a C++ dialect in that it uses C++ syntax and structure. C/C++ offers a tremendous amount of control and speed at the cost of being more tedious in syntax. Alternatively, support for languages like Python has begun to appear more recently in the programming of microcontrollers. Python is a popular programming language due to its user-friendly syntax and its expansive and well-documented libraries.

MicroPython is a derivative of Python that has been optimized to run on resource-constrained microcontrollers with limited memory. The language implements the Python 3.4 syntax with extensions for asynchronous programming introduced in Python 3.5. If you have experience coding in Python, then using MicroPython will be a largely seamless transition! Unlike using your standard Python distribution on a PC, however, programming MicroPython on a microcontroller has some special requirements.

Perhaps the most obvious requirement is getting the MicroPython programs onto the microcontrollers themselves. Since microcontrollers don’t have keyboards or screens, we must rely on a host computer, such as a laptop or your desktop PC, for uploading and running the programs (typically over a USB connection).

In order to access a USB device like a microcontroller from a host computer, you can use the command-line interface (CLI). Depending on your operating system (OS), there might be different types of CLIs. For example, the Windows version of a command-line interface is called the command prompt (or cmd.exe), and the Linux version is the terminal. It’s recommended that you familiarize yourself with some basic commands in your specific OS’s command-line interface to help you navigate the remainder of the tutorial.

To make our lives considerably easier when interfacing with a microcontroller from our host computer, we will be using a custom MicroPython shell program called shell49, which runs from the command line of your host computer. This program will abstract away certain complexities while also adding useful features that make flashing and programming MicroPython a breeze.

Installing MicroPython

Our first step will be to download a special USB driver that is used to by your computer to recognize the HUZZAH32 Feather board. You can find the CP210X USB driver here. Make sure you are selecting the correct download option for your OS and architecture.

The next dependency that we need to take care of is a Python interpreter. There are many options for installing Python distributions such as CPython, Anaconda, Miniconda, and more. We recommend that you install at least Python version 3.6. Again, double check that you are installing the correct version based on your computer’s hardware.

Once you have successfully installed Python, you can verify that it is working correctly by opening a terminal (or other CLI) and typing python into the prompt. It should announce itself and print the version. Type exit() to quit the Python interpreter.

Great! Now, we can finally install shell49. In your terminal, type in the following command.

pip install shell49

If for any reason this process fails, you can visit the shell49 github page for a more verbose discussion on the topic as well as troubleshooting tips.

Otherwise, we can now initiate shell49! Type the following command into your terminal.

shell49 -a

By default, shell49 will automatically attempt to search for available boards and connect over serial. The -a argument tells shell49 to skip that for now.

You should now be greeted with a welcome message and a new prompt in your terminal that ends in a >. This is the shell49 prompt! It’s important to pay attention to what prompt you are currently using. You can exit the shell49 prompt at anytime by pressing CTRL+D.

Connect your microcontroller via the micro USB cable in your kit. In the shell49 prompt, type:

ports

This command will print out all available serial ports that you can attempt to connect to from shell49. If you are on Windows, it will likely be “COM1” or “COM2“. Linux might be “ttyUSB0” or “ttyUSB1“. If you have multiple available Serial ports in your menu and are unsure which to select, you can try disconnecting your microcontroller and observing which option disappears when using the ports command.

Next, we will be configuring some default settings for shell49 to facilitate connecting to your specific board. We will be using the config command to set defaults for the port, board, and time_offset settings. Run the following commands in your shell49 prompt, substituting <port> with your port name.

config --default port <port>
config --default board HUZZAH32
config --default time_offset 0

You can verify that you set everything correctly by typing config and examining the output.

Now, we can finally flash our microcontroller! Type the following command.

flash -e

Make sure to examine the output carefully for error messages. If there are none, press the reset button on the HUZZAH32 Feather board and rerun the ports command. If the serial port you used is no longer listed, disconnect and then reconnect the USB cable and try the ports command again.

Let’s attempt to connect to our freshly flashed microcontroller over a serial connection.

connect serial

You should now see that your shell49 prompt has a nameless board specifier indicating that you have connected successfully!

At this point, we have flashed the microcontroller with MicroPython and are communicating with it over a serial connection. Why don’t we try testing out MicroPython? To do so from the command line, we will need to start REPL.

The term REPL stands for read-evaluate-print-loop. Think of it as a way to feed code to an interpreter piece by piece (as opposed to writing a whole script). It’s a useful way to prototype functionality from the command line. In the shell49 prompt, type:

repl

We are now in the REPL prompt! You can tell because the prompt should now look like >>>. Yes, it is yet another type of prompt to keep track of. However, we can now try some fun Python commands! Enter the following.

1+1
2**100
for i in range(4):
    print(i, i**2)

Your microcontroller is reading your inputs, evaluating them, and then printing the result back to your terminal! Pretty cool, right? Let’s try some hardware commands now in the form of an LED blink!

Blink!

As customary for any introduction to microcontroller programming, we will attempt to blink an LED. Consider the following commands.

from machine import Pin
from board import LED
led = Pin(LED, mode=Pin.OUT)

The first two lines are pretty common Python syntax. You are telling Python to import a module from a certain package. In this case, we are importing Pin and LED modules from the machine and board packages respectively.

Then, we use the Pin function to create a pin object, which takes two arguments. The first argument is the pin location. We assign this pin to be the pin connected to the onboard LED of the HUZZAH32 Feather board. It just so happens that the LED module allows us to point directly to that onboard LED!

The second argument sets the mode of the pin we have specified in the first argument. In this case, we use the Pin module’s OUT by specifying Pin.OUT. The Pin function assigns this new pin object to the name led.

We can now use the pin object led to turn the LED on and off!

led(1)

You should see a new LED on your microcontroller turn on. Now turn it off.

led(0)

You did it! But let’s say you want to write something more complex (and perhaps would rather not type out your script line by line in a terminal each time). How do you run a script? First, exit from the REPL prompt by pressing CTRL+X.

For the next step, you will need an editor or integrated development environment (IDE). There are countless options depending on personal preference and coding style. For now, you can just open a blank file in a simple text editor. Type the following code.

from machine import Pin
from board import LED
from time import sleep

led = Pin(LED, mode=Pin.OUT)
while True:
    led(1)
    sleep(1)
    led(0)
    sleep(1)

Pay particularly close attention to the number of spaces before the last four lines. Python is quite nit-picky with spacing and indents because it uses white space to delimit code structure (a whole bag of worms we won’t get into right now).

Notice that we have added some new lines. We have a while loop that will loop continuously because its condition has been set to just a constant True.

Inside this while loop we have a sequence of alternating calls to led and a new function called sleep. As the name implies, sleep will tell the microcontroller to wait for a certain time interval. Here, we are waiting in one second intervals. Make sure you remember to include the correct sleep module on line three!

We are going to save this file. But when we do, we are going to save it as “blink.py”. We use the “.py” extension to identify this file as a Python script. Make sure you know where you have saved the Python script.

Next, return to your terminal and navigate to the directory where you saved “blink.py”. Start shell49. You can leave out the -a argument this time so that it automatically connects to your board.

Now type the command ls to list the items in your current directory. If you are in the correct directory, you should see your “blink.py” script. Let’s run it by using the run command.

run blink.py

Amazing! It works! You now have the ability to run scripts. Press CTRL+C to exit the script and return to the shell49 prompt. Ok, but you might be wondering why we are still using the command line if this is supposed to be an embedded system. How do we get it run independently?

Easy! We can upload this script right onto the microcontroller itself so that it runs on boot. From the shell49 prompt, type this command.

ls /flash/

This command will list items in the directory /flash, which just so happens to be located on your microcontroller! You should see a file named “boot.py”. This is the script that your microcontroller runs on startup.

Let’s take our “blink.py” script and copy it to “boot.py” using the cp command.

cp blink.py /flash/boot.py

Note that copying a new script into “boot.py” (even if it has a different name like “blink.py”) will simply replace the original “boot.py” but retain the name “boot.py” so that the microcontroller always knows where to find its boot script. Now, every time that the microcontroller turns on it will run our new “boot.py” script.

Go ahead and close your terminal and disconnect the USB cable. Now, reconnect it. After a moment, your new boot script will run, and you should see the LED start blinking!

You did it! Now, you’ve successfully learned how to flash MicroPython to your HUZZAH32 Feather board.