Sample ESP32 Workflow
This document will take you through flashing a new ESP32 with MicroPython and uploading a few simple programs. The device will be flashed a few times, so you'll want to use one that doesn't contain anything important.
You will need Visual Studio Code installed on your development host, obviously. You will also need the following:
- Python
- The Python module ESPTool
- The Python module MPRemote
- An new ESP32 dev board (or one you don't care about overwriting)
- The latest MicroPython firmware file for your ESP32
As a test, try running ESPTool and MPRemote, each with the --help option, just to ensure everything works.
On Windows:
PS C:\> py.exe -m esptool --help
PS C:\> py.exe -m mpremote --help
On Linux:
$ python3 -m esptool --help
$ python3 -m mpremote --help
If you can't run these commands successfully from your host's shell prompt, the VS Code extension will likely fail as well. Troubleshoot any problems before moving on.
The VS Code extensions for ESPTool and MPRemote both use context menus (right-click) to perform tasks. Operations on the microcontroller are done via the context menu on the microcontroller's serial port.
Access the VS Code Explorer pane by clicking the files icon or using the Ctrl+Shift+E keyboard shortcut. Look toward the bottom for a heading of SERIAL PORTS. Expand SERIAL PORTS (if it's not already) and look for your device's port. On Windows it will be COM3 or similar. Linux uses a path like /dev/ttyS0.
Right-click on the serial port to see the available options on the context menu.
With the ESPTool VS Code extension installed, one of the options on the serial port context menu is Write firmware file (write_flash) . Choose this option to prepare the ESP32 with a new MicroPython firmware image.
First, you will see a file chooser dialog box asking you to select the firmware image. Once you have chosen the image file, you'll see a prompt to select flash offset address. Choices are either 0x0 or 0x1000 and depends on the microcontroller hardware. Original ESP32s use an offset of 0x1000 and that's what is chosen in this example.
Next, you'll see a confirmation dialog asking you to confirm overwriting the device. Choose Overwrite to start the flash process.
Finally, you will see the command running in the Terminal window along with the progress of the flash erase and write steps.
Once you have MicroPython on your ESP32, you can interact with it using the commands provided by MPRemote. To do this with the VS Code extension, use the serial port context menu, just like you did when flashing the device.
Start with something simple, like Get MicroPython firmware version. Select this option from the context menu choices and watch the Terminal. You will see the MPRemote command running along with its output telling you the version of MicroPython.
Next, try the List files on remote filesystem (ls) menu option. Watch the Terminal output and you'll see a directory listing. On a freshly flashed microcontroller, you will probably only see boot.py
To see the contents of boot.py, choose the context menu option for Show contents of a remote file (cat). This command requires a filename, so the VS Code extension will prompt you to select one from a list of files in the current directory. Since there's only boot.py, the choice is simple. Just click on boot.py in the dropdown selection. Watch the Terminal window to see the contents displayed.
Most of the commands work this way. You right-click the serial port to access the context menu and choose what you want to do. If more information is needed, you'll be prompted to select from a list of choices. If an operation is potentially dangerous, you may be asked to say yes to a confirmation dialog.
The MPRemote VS Code extension is designed such that it assumes the primary copy of your code will always reside on the development. Files will be uploaded to the microcontroller as needed for testing, but the "golden copy" will always be in a directory on the development host.
This is different than other code editors (particularly Thonny) that allow you to edit files directly stored on the device's flash file system.
With the MPRemote VS Code extension, it works best to create the file on the development host, save it there, and then copy it to the microcontroller when it's ready to test.
The first step in development is to create a directory to hold your MicroPython source code and other files that are needed for your project. Later on, the entire contents of this directory will be copied up to the ESP32's flash file system using the Upload all project files to remote filesystem (sync) context menu option. But for now, we need to create the directory and something to upload.
Here are the steps to get started:
- Use VS Code's menu to select File > Open Folder.
- Click the New Folder button and name your directory with the project's name.
- Select the folder to open it in VS Code.
This is where all your MicroPython source files will be stored. When you later use Upload all project files... from the context menu, the entire cntents of this directory will be recursively uploaded.
For now, you can name the project folder test or some other temporary name.
With an empty project folder, there is a mismatch between what's stored on the development host and what's on the microcontroller's flash file system. It's only one file, boot.py. It was created automatically when MicroPython was flashed to the device. For the sake of consistency, we'll start by copying that file to the development host's project directory.
You should already have the project folder open in VS Code from the previous step, but if not, open it now.
Next, we'll copy boot.py. Here's how:
- Access the serial port context menu by right-clicking the port name.
- Choose Download a file from remote filesystem (cp) from the menu selections.
- When prompted to choose a file from the flash filesystem, click on boot.py.
- Use the dialog to navigate to the project folder and select it as the destination.
You should now see boot.py in VS Code's Explorer pane under the name of your project folder. If you repeat the List files on remote filesystem (ls) menu choice used earlier, you can compare the flash file system contents with the project folder contents.
Operating on single files like this is very inefficient and error prone. In the next section, we'll learn how to copy everything from the project folder to the flash file system with one click.
Most MicroPython projects will have a boot.py, main.py, and possibly other files. As the example project folder stands right now, it already contains boot.py. So let's create a main.py and then we'll use Upload all project files to remote filesystem (sync) from the context menu to copy it up to the microcontroller.
First, create a new Python file in VS Code like the example below.
print("Hello World!")
Then, save the file in your project folder as main.py.
Finally, use the serial port context menu to select Upload all project files to remote filesystem (sync).
Click OK on the confirmation dialog and watch the Terminal window. You'll see a message saying boot.py is up to date and another one showing your main.py being copied.
Now choose List files on remote filesystem (ls) and if you want, Show contents of a remote file (cat), to verify the files are the same.
There are two ways to run your MicroPython code.
For simple projects like the Hello World example that only contains main.py, you can right-click on anywhere in the VS Code editor pane and choose MPRemote > Run file on demote device (run) from the context menu. Do this now and watch the Terminal window for output.
For more complex project that make use of multiple files, you can start a REPL prompt and reset the microcontroller. Try it by following the steps below.
- Choose Enter REPL prompt (repl) from the serial port context menu.
- Note how the Terminal window indicates you are connected to MicroPython on the serial port.
- Reset your microcontroller with the reset button.
- Watch the Terminal window for boot-up messages and the Hello World output.
After the program runs, control returns to the REPL prompt. Exit the REPL with CTRL+X before selecting any additional commands from the MPRemote extension menus. If you forget, you're going to see syntax errors, because the REPL doesn't understand the operating system commands being sent.
My whole motivation for creating the MPRemote VS Code extension was to use VS Code's built-in Git functionality with my MicroPython projects. To see how this works, we'll clone a MicroPython project from GitHub.
Start by closing the folder for the current Test project. (File > Close Folder)
Next, follow these steps to clone a repository.
- Select the source control navigation icon or use Ctrl+Shift+G to open the source control pane.
- Click Clone Repository.
- For the repository URL, enter https://github.com/DavesCodeMusings/mpremote-vscode-practice.git
- Select a directory on your development to hold the cloned files.
Now you have a copy of all file from the GitHub repo in the local project folder. You can see them in the Explorer pane of VS Code.
With these files on your development workstation, you can use Upload all project files to remote filesystem (sync) to copy everything to the microcontroller flash file system.
There's a lot of extra junk, like a README file, a LICENSE file, and a couple of directories, but bear with me for now.
When the sync is done, enter the REPL prompt with Enter REPL prompt (repl) and reset the microcontroller. You'll be treated to some tongue-in-cheek metric to imperial conversions.
Exit the REPL with Ctrl+X and run List files on remote filesystem (ls) from the serial port context menu.
Look at all the files!
We really only need main.py and freedom.py to develop and test the module code on the microcontroller. But instead, we've polluted our flash file system with all sorts of non-Python junk from the repository.
We can remedy this by creating a directory to hold just the Python source files and setting an option in the MPRemote extension to only upload from that directory.
Start by creating a directory named src under your project folder.
Next, move freedom.py and main.py into that directory.
Once that's done, open the VS Code options for the MPRemote extension. (Press Ctrl+Shift+x and type MPRemote in the search box, then click the gear icon to access settings.)
Enter src in the Src Subdirectory field.
Now, run the Upload all project files to remote filesystem (sync) again and watch the Terminal window. Notice how the project subdirectoy src is used and only the two files: freedom.py and main.py are considered for uploading.
Be aware that once the Src Directory option is set for the extension, it will affect all projects. It's not possible to mix and match some with the src subdirectory and some without.
We're done with the mpremote-vscode-practice project, so you can close the folder in VS Code and delete the underlying directory if you wish. In the next section we'll use a project that already has the src subdirectory, so leave the extension option set.
In this section, we'll start with another cloned GitHub project on a freshly flashed ESP32. This is a good chance to review and test your understanding of what you've learned so far.
Here's what you need to do:
- Re-flash your ESP32 with MicroPython firmware to erase all previous files.
- Clone the repository https://github.com/DavesCodeMusings/BTHome-MicroPython.git
- Sync all Python files in the project folder's src directory to the ESP32.
- Start a REPL prompt.
- Reset the ESP32 and watch the output.
Ope!
Instead of a running program, you'll see a lovely error message that says, "ImportError: no module named 'aioble'."
The reason for the error is because the project uses Bluetooth and requires the aioble module to be installed. But on this freshly flashed ESP32, there is only the code we've uploaded, nothing else.
Installation of aoible is easy though, using MicroPython's MIP package manager.
Here's how:
- Exit the REPL prompt with Ctrl+X.
- Choose Install a package on remote filesystem (mip) from the serial port context menu.
- Enter aioble when prompted for the package name.
- Watch the Terminal window for installation progress.
Now, start another REPL prompt and reset the microcontroller. You should see messages about Constructing advertising payload, and Packing data. After a minute there will be a message about Going to sleep.
What you're seeing is the debug output from a Bluetooth beacon sending out mocked-up data for temperature and humidity readings. This will repeat every few minutes.
If you have a Bluetooth scanner app like nRF connect and you're curious, you can see the beacon on your mobile phone as the device DIY-sensor. The sensor becomes unavailable when it goes to sleep, so time your scans accordingly.
Reset the microcontroller and press CTRL+C from the REPL prompt to break out of the program.
That was the last sample project. You can reflash your ESP32 and delete any VS Code project folders you created for the exercises. Hopefully you've learned how to use the MPRemote VS Code extension to give you an easy, point and click workflow for your MicroPython projects.
If you find bugs or have suggestions for enhancements, open a GitHub issue for the project.
Happy coding!