Skip to content

Sample Workflow 1

Jump to bottom
Dave edited this page May 28, 2023 · 28 revisions

This tutorial is a work in progress

Managing a One-File Project with VS Code and MPRemote

This example consists of a single file (main.py) that is created and tested using Visual Studio Code and the MPRemote extension. The purpose is to a simple example of managing a project. To follow along, you will need the following:

The example was written using an ESP32-C3-DevKitC-02 and MicroPython 1.20

Preparing the ESP32-C3

We'll start from a fresh install of MicroPython, so grab an ESP32-C3 you don't mind overwriting and flash it with the latest version of MicroPython.

Flashing firmware

I have another VS Code extension called ESPTool that provides a wrapper around esptool, letting you flash ESP from inside VS Code. But, you can always use the traditional command-line method if that's what you're used to. If you choose to install and use the ESPTool VS Code extension, here's how you use it to flash:

  1. Press CTRL + SHIFT + P and start typing write_flash to access
  2. Navigate the file selection dialog to find the MicroPython download
  3. Choose the address based on the model of ESP you're flashing.
  4. Choose Overwrite when prompted and watch the progress in the terminal window

If you get an error that says, Wrong boot mode detected, you may need to press and hold the BOOT button on the microcontroller as you begin flashing.

Testing

Restart the microcontroller and use MPRemote's devs command to verify it's attached and working. Then use the ls and cat commands to inspect the boot.py that comes preinstalled.

Press CTRL + SHIFT + P to access the command palette. Start typing devs to find the list files command.

>MPRemote: Scan for attached devices

You should see a line of information about the ESP32-C3 in the terminal window.

PS C:\Users\Dave\Desktop\ESP Labs\neopixel> py.exe -m mpremote devs
COM7 ABCD1234DEF056789ABCD1234DEF0567 10c4:ea60 Silicon Labs None

Use the MPRemote ls command to show the files on the ESP32-C3's flash filesystem and then cat to display the contents of boot.py.

PS C:\Users\Dave\Desktop\ESP Labs\neopixel> py.exe -m mpremote connect COM7 fs ls /
ls :/
         431 boot.py
C:\Users\Dave\Desktop\ESP Labs\neopixel> py.exe -m mpremote connect COM7 fs cat /boot.py
# This file is executed on every boot (including wake-boot from deepsleep)
#import esp
#esp.osdebug(None)
#import webrepl
#webrepl.start()

Now that the ESP32-C3 has been flashed and you've had a quick refresher on accessing MPRemote commands, the next step is to start coding.

Creating main.py

Open a new file in VS Code (File > New File...) and select Python from the available language selections. Then paste the following code into the window.

from machine import Pin
from neopixel import NeoPixel

GPIO = 8  # Check ESP32-C3 board silkscreen for the NeoPixel's GPIO number.

rgb = NeoPixel(Pin(GPIO), 1)
rgb[0] = (0, 0, 8)  # Red, Green, Blue intensities ranging from 0..255
rgb.write()

This short bit of MicroPython will light up the ESP32-C3's built-in NeoPixel with a dim blue color.

Saving locally

Before going further, you'll need to save the program locally on the development host. You can choose any directory you want, but you'll need to name the file main.py.

MicroPython will always execute main.py right after boot.py when starting up, so using this name ensures the program will run whenever the device is reset.

Testing

Before uploading main.py to the ESP32-C3, you can test it using the copy that's saved locally.

  1. In VS Code, press CTRL + SHIFT + P to access the command palette.
  2. Type run to find the command MPRemote: Run file shown in the active editor (run).
  3. Select the command and watch the terminal window for any errors.

If all goes well, you'll see the NeoPixel light up blue. Otherwise, you'll need to debug.

Uploading

If you're satisfied with the way your program runs, you can copy it to the ESP32-C3's flash filesystem. The command is MPRemote: Upload file to remote filesystem (cp) Select it from the command palette and main.py will be copied from the development host up to the root of the ESP32-C3's flash.

Now, when you restart the device, main.py will run and your NeoPixel will light up.

Finishing with a final test

You may want to restart the ESP32-C3 and watch the debug output before detaching from the development host. This way you won't have any surprises later on. You can do this by starting a REPL prompt and pressing the ESP32-C3's RESET button.

  1. Access the command palette in VS Code.
  2. Select MPRemote: Enter REPL prompt (repl) from the list
  3. Watch the terminal window as you reset the ESP32-C3

You should see the blue NeoPixel and the terminal window should look something like this:

PS C:\Users\Dave\Desktop\ESP Labs\neopixel> py.exe -m mpremote connect COM7 repl
Connected to MicroPython at COM7
Use Ctrl-] or Ctrl-x to exit this shell
...
MicroPython v1.20.0 on 2023-04-26; ESP32C3 module with ESP32C3
Type "help()" for more information.
>>>

Some output has been removed for brevity. The important thing to verify is there are no errors.

Summarizing the advantages of the workflow

Here are some important points to note about the development process used in this tutorial.

  • Code is created and saved on the development host.
  • Code can be tested without uploading.
  • Once tested, code is copied to the microcontroller's flash filesystem.

Following this workflow ensures the "golden copy" of any file is always found on the development host. If a microcontroller is lost, destroyed, or reflashed, no code is lost. Simply recopy the file(s).

Clone this wiki locally