MicroPython is an implementation of the popular Python® programming language, with a target for microcontrollers (hence the "micro").
Python has become one of the most popular languages worldwide, with one of its key characteristics being an easier language to learn. This makes it suitable for beginners that have little to no experience in writing text-based code but want to achieve great things.
The pins used in MicroPython are very different from what the pin numbering on your board states. In the pinout below, you can see in green, which pins you need to use when using MicroPython.
Why is there a difference in pins? The MicroPython implementation follows the pin numbering on the ESP32-S3, making it compatible with all other boards based on the ESP32-S3.
Therefore it is necessary to keep track on two sets of pins:
MicroPython includes the standard Python API, but also a series of modules that are hardware specific. After you have installed it in your board, commands written in Python that you send to the board will be executed directly.
This is quite different from the "standard" Arduino (C++) way of programming, where you compile your code before sending it to your board. The MicroPython way allows you to change the program instantly.
When using MicroPython, we don't write sketches, we write scripts. A script can be written in a MicroPython compatible editor which can then be saved on the board. To send a script, you need to have the board connected to your computer.
Since MicroPython implements a filesystem, you can access your board similar to how you access a USB drive.
A MicroPython editor is a special code editor with built-in functions for communicating with your board.
There are several editors available, but in this course, we will use the Arduino Lab for MicroPython.
The next chapter is dedicated to using the Arduino Lab for MicroPython editor.
Any time we want to interact and program our Nano ESP32, we need to connect to it. This requires the board to have MicroPython installed, which is covered in the next chapter (installation).
To connect to your board, click on the "Connect" button in the editor.
A MicroPython script is a piece of code that can be run on your board. It could contain just the simplest mathematic equation,
(which is 2), or a script that controls a robotic arm that serves you a cup of tea.
Inside a MicroPython editor, you simply write the code you want to run and click on the "Run" button.
If there is anything wrong with your code, you will receive an error. If not, it will run the instructions in the scripts from top to bottom. To stop the script, you can click on the "Stop" button right next to the Run button.
If you have plenty of experience in Arduino, you will be used to the concept of a loop. If you don't, you can read more about it here. This is not a requirement when using MicroPython. You can write a program that either just runs once, or continues to loop over and over.
To make a program loop continuously, you will need to use a while loop inside your script.
1while(True):2 # code placed here will execute over and over again3 # in a similar fashion to the void loop() function
There are two files that are important to consider in the MicroPython environment:
- a script that will run as the board starts (in other words, boots).
- a script that will run immediately after
You can consider
file to be your "main" script as it will execute any time after the board boots. Inside a MicroPython editor, we can open this file and edit it directly. When we save, we save it to the board, and the instructions are updated. To access your files, click the "Files" button.
This is a bit different if you are used to programming Arduino boards using the Arduino IDE / C++ because there you need to compile and upload for every change you make.
As MicroPython has a file system, it is possible to save your code directly on the board. You can edit your files freely and the changes will not save automatically, but if you click on the "Save" button, this will overwrite anything previously stored in that file.
If you save it on for example the
file, you can disconnect the board, come back another day, connect the board, and your file will be there! It works like a normal file you edit on your computer.
Be cautious with the "Save" option, as it will overwrite everything, and there's no way of recovering it.
The REPL, also often referred to as the terminal, is a command line interface inside your editor. When you input instructions or a message, the interpreter on your Arduino will evaluate it, and return the result.
The REPL / Terminal is accessed by clicking on the "Terminal" button in the top right corner.
In the could for example write
, which the REPL will reply with a
. This computation is performed on your Arduino, and sent back to you!
When we run a script, and don't worry, we will come back to this topic, we can use the
function to print things in the REPL. This is a great way of knowing what goes on on your board. An example is:
1print(1+1)2print("Computation performed, yay!")
As you progress with MicroPython, you will come across a very important term: modules.
Modules are code files that can be imported into your script which provides an additional set of functionalities. For example, the
module allows you to control how often something should occur, or the
module contains hardware specific functions. To use a module, we can simply
it in the script, as follows:
1# import the "time" module2import time34# import the "pin" function from the "machine" module5from machine import Pin
Once the module is imported, you can use it in your script, like:
1import time23# freeze the program for one second4time.sleep(1)
Not all modules are built-in to the MicroPython installation. This would be impossible because we have a very limited memory space.
For example, to use a module for a specific sensor, we need to install it externally. Installing external modules can be done in several different ways, but below we will demonstrate a safe and straightforward approach.
To install an external module, we are going to use a package manager called
, we can install a module on the board by connecting to Wi-Fi® and downloading the module directly to the board. Installing external modules is done in two steps:
Establish a Wi-Fi connection.
Download the module from a specific URL using
To connect to your local Wi-Fi you can upload the following script to
file. We choose
because we want to make sure our board connects to the internet as soon as it boots up.
Connect to Wi-Fi
Please note that you need to add your own Wi-Fi network and password in the
1"""2This script connects to Wi-Fi3"""45import network67WIFI_NETWORK='YOUR_NETWORK_NAME'8WIFI_PASSWORD='YOUR_NETWORK_PASSWORD'910wlan = network.WLAN(network.STA_IF)11wlan.active(True)12wlan.connect(WIFI_NETWORK, WIFI_PASSWORD)1314print()15print("Connected to ",WIFI_NETWORK)
Press run and you should see
being printed inside the REPL.
Connected to <your Wi-Fi>
Install external modules
Next, you need to run a script that installs the external module from a specific URL. Upload the following script to
1'''2This script installs external modules using mip3'''45import mip6mip.install("https://raw.githubusercontent.com/tinypico/tinypico-micropython/master/lis3dh%20library/lis3dh.py")
Press run and you should see the following inside the REPL:
In this case, we will provide a URL to a file stored on GitHub (the raw file). The script installs the
module, which will be used later on in this course.
You can verify that the module was installed correctly by pressing
and checking inside the
folder. You should see a file called
When asked later in the course to install external modules simply paste the provided script into
and press run.
If you want to uninstall a module, you can delete it in the editor using the "Files" tab. This is a good idea to do if you have installed many modules, as eventually you will run out of memory space.
Select the file you want to remove, and click on the "Delete" icon. You will be prompted to remove the file.
1. Invalid URL: if you have specified an invalid URL, you will get an error that looks like this:
1Package not found: https://micropython.org/pi/v2/package/6/<url>/latest.json
Double check to make sure your URL is correct if this occurs.
2. OSError: -202:
The following error can occur when running the installation script.
1Traceback (most recent call last):2 File "<stdin>", line 24, in <module>3 File "mip/__init__.py", line 1, in install4 File "mip/__init__.py", line 1, in _install_package5 File "mip/__init__.py", line 1, in _install_json6 File "urequests.py", line 180, in get7 File "urequests.py", line 76, in request8OSError: -202
Some things to check are:
If the error persists, you can try to "soft-reset" the board, by clicking the "Reset" button, and run the script again.
In this chapter, we learned a little bit about the key components in the MicroPython environment.