Skip to content

Home

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

Using the MPRemote Visual Studio Code Extension

This is a hands-on tutorial designed to show you how to use the MPRemote VS Code extension. Installation is not covered here. For that, see the README

Prerequisites

To follow along with the tutorial, you'll need the following:

This tutorial was written using an ESP32 microcontroller and MicroPython 1.20

Scanning for devices

All of the MPRemote extension's functionality can be accessed from the VS Code command palette. Just press CTRL + SHIFT + P to access the command palette prompt. You can start typing MPRemote to see all the functions available to you, or you can type a specific shortcut.

Here are two ways you can access the MPRemote devs command to scan for the microcontroller's serial port:

Press CTRL + SHIFT + P and type MPRemote to select from the list of choices...

>MPRemote: Scan for attached devices (devs)

Or type the shortcut at the command palette prompt...

>devs

Try it now and watch the VS Code terminal window to find out which port your microcotroller is using. You'll see the output from the MPRemote VS Code extension telling you about the command it ran and the microcontroller it found.

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

List files on the microcontroller

A fresh installation of MicroPython will come with a boot.py file in the root directory. Try using the MPRemote extension's ls command to verify this.

Start by pressing CTRL + SHIFT + P and then type ls.

>MPRemote: List files on remote filesystem (ls)

Select the command from the list and watch the terminal window.

PS C:\Users\Dave> py.exe -m mpremote connect COM7 fs ls /
ls :/
         149 boot.py

There's boot.py, but what's in it?

Display file contents

MPRemote has a cat command that you can use to show what's in a file. Press CTRL + SHIFT + P and type cat

You'll be prompted with a list of files on the microcontroller's flash filesystem. Choose boot.py from the list and watch the VS Code terminal window.

PS C:\Users\Dave> 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()

This is the standard boot.py on a fresh installation of MicroPython on ESP32. Everything's commented out.

You can't edit the file directly on the microcontroller, but you can download it to the development host and open it in VS Code to make the changes.

Downloading files from the microcontroller

By now, you probably know we're going to access the command palette, so go ahead and press CTRL + SHIFT + P and start typing download at the prompt.

>MPRemote: Download file from remote filesystem

Select the download command and you'll be shown a list of files on the microcontroller. Unlike the ls command in a previous example, this time the files on the microcontroller will be shown in a selection list at the top of the VS Code window. Go ahead and choose boot.py.

After selecting boot.py, you'll be presented with a directory chooser dialog box. This is the filesystem on the local machine. Browse to the directory where you want to put the file and click Select. The file will be downloaded from the microcontroller onto the host where VS Code is running. In the VS Code terminal window, you'll see the MPRemote command that was run to do it.

PS C:\Users\Dave> py.exe -m mpremote connect COM7 fs cp ':/boot.py' 'c:\Users\Dave\Desktop\ESP Labs\boot.py'
cp :/boot.py c:\Users\Dave\Desktop\ESP Labs\boot.py

Making changes using VS Code

Open boot.py in VS Code (either File > Open File or CTRL + O will do it.) The default boot.py has example MicroPython code, but it's all commented out. Let's add a simple print statement with the classic Hello World! message.

The new boot.py will look something like this:

# This file is executed on every boot (including wake-boot from deepsleep)
#import esp
#esp.osdebug(None)
#import webrepl
#webrepl.start()
print("Hello World!")

The example above is from MicroPython on an ESP32 microcontroller. Yours may look slightly different, but as long as you have the print() statement, that's what's important.

But so far, the changes are only on the copy that's saved on the development host.

Running a program from the editor

You don't need to upload the modified boot.py to see the Hello World! message. All you have to do is save it locally and use the MPRemote run command to see the result in the VS Code terminal window.

Start by accessing the VS Code command palette (CTRL + SHIFT + P) then find the run command and select it. The terminal window will look something like this:

PS C:\Users\Dave> py.exe -m mpremote connect COM7 run 'c:\Users\Dave\Desktop\ESP Labs\boot.py'
Hello World!

You can do this with newly created files, too. It doesn't have to be something you downloaded from the microcontroller. Open a new VS Code file (File > New or CTRL + N). Paste the following code into the editor window to test:

from os import uname
version = "MicroPython:{:>8s}".format(uname()[2])
print(version)

Save the file locally, but don't upload it. Use the MPRemote run command to test it (CTRL + SHIFT + P, run). You should see the version of MicroPython displayed in the VS Code terminal window just like you saw Hello World.

At this point, you could use the ls command to verify the file was not uploaded to the microcontroller, or you could take my word for it. (Go ahead and check. I won't be offended.)

Uploading files from the development host

Once you've edited a file and tested it, the next logical step is to upload it to the microcontroller. You can do that with the MPRemote cp command. You've probably already guessed it's CTRL + SHIFT + P and then typing cp. But, there are a few things to watch out for.

  1. You don't get to choose the destination file name. Whatever the file is called on the development host is the name it'll have on the microcontroller.
  2. If the file already exists on the microcontroller, it will be overwritten. Not a problem for new files, but be careful with boot.py and other important files.
  3. The file will go into the root directory of the microcontroller's filesystem unless you change directory first.

Other than that, it's just a matter of watching the VS Code terminal window to see what's going on.

PS C:\Users\Dave> py.exe -m mpremote connect COM7 fs cp 'c:\Users\Dave\Desktop\ESP Labs\version.py' ':/version.py'
cp c:\Users\Dave\Desktop\ESP Labs\version.py :/version.py

Installing modules with mip

Not every bit of code on you microcontroller needs to be written by you. Many times you'll want to use code in modules developed for MicroPython. MPRemote introduced the mip command and the MPRemote VS Code extension lets you access it with the command palette.

mip stands for 'mip installs packages'. Another fine example of the recursive acronym tradition.

By this point in the tutorial, I'm guessing I don't even have to tell you how to access mip from within VS Code. (It's CTRL + SHIFT + P, mip in case you weren't paying attention.) All you really need to know is the source of the package. Here's an example:

github:DavesCodeMusings/repl-buddy

Run the mip command inside VS Code and enter the package name shown above when prompted. Look in your terminal window and you'll see the package was downloaded into the /lib directory.

PS C:\Users\Dave> py.exe -m mpremote connect COM7 mip install github:DavesCodeMusings/repl-buddy
Install github:DavesCodeMusings/repl-buddy
Installing github:DavesCodeMusings/repl-buddy/package.json to /lib
Installing: /lib/ansi.py
Installing: /lib/command.py
Installing: /lib/text_buffer.py
Installing: /lib/atto.py
Done

Run the ls command and you'll see the /lib directory was added to your microcontroller's filesystem.

PS C:\Users\Dave> py.exe -m mpremote connect COM7 fs ls /
ls :/
         149 boot.py
           0 lib/

But, how do you see what's in the /lib directory. The answer is to use the chdir command.

Changing directory

You might think it's silly to have a section on changing directories. After all, it's a pretty basic concept. But there are some differences to be aware of.

  1. Nothing changes on the microcontroller. The only thing that changes is the path the VS Code extension uses when it constructs remote file names.
  2. Only the file name from the development host is used. It doesn't matter if your local copy of the file is in C:\ESP, C:\ESP\lib, or on your Desktop, it will get uploaded using the path remembered by the VS Code extension.

Let's look at an example using the version.py sample program we created previously. When it was uploaded, it went into the root of the filesystem.

PS C:\Users\Dave> py.exe -m mpremote connect COM7 fs ls /
ls :/
         149 boot.py
           0 lib/
          85 version.py

But, it could go into another directory if you want. Here's how:

  1. Find the chdir command in the VS Code command palette.
  2. Choose the /lib directory from the selection list.
  3. Notice the output in the terminal window showing you what's in the directory.
PS C:\Users\Dave> py.exe -m mpremote connect COM7 fs ls /lib
ls :/lib
        8610 ansi.py
       13964 atto.py
        5862 command.py
        5063 text_buffer.py

After changing directory to /lib, this is the directory the MPRemote extension will remember for the microcontroller. Any uploads, downloads, or listing of files will be relative to this directory. Go ahead and use the cp command to upload version.py and then verify it's in the /lib directory using ls.

PS C:\Users\Dave> py.exe -m mpremote connect COM7 fs cp 'c:\Users\Dave\Desktop\ESP Labs\version.py' ':/lib/version.py'
cp c:\Users\Dave\Desktop\ESP Labs\version.py :/lib/version.py
PS C:\Users\Dave> py.exe -m mpremote connect COM7 fs ls /lib
ls :/lib
        8610 ansi.py
       13964 atto.py
        5862 command.py
        5063 text_buffer.py
          85 version.py

But, this was just an example. version.py isn't a MicroPython module, so it doesn't belong in /lib. In the next section, we'll delete it.

Removing files

Removing files is done with the rm command. You'll be prompted to choose from a list of files gathered from the current working directory on the microcontroller (either the filesystem root or the result of your last chdir).

Keep in mind...

  • There is no recycle bin. When it's deleted, it's gone.
  • You can cancel the rm command by pressing ESC when the selection list comes up.
  • You will also be prompted to confirm the delete.

You can access the rm command using the VS Code command palette and the shortcut name rm.

Here's an example of the terminal window after changing directory to /lib and removing version.py.

PS C:\Users\Dave> py.exe -m mpremote connect COM7 fs ls /lib 
ls :/lib
        8610 ansi.py
       13964 atto.py
        5862 command.py
        5063 text_buffer.py
          85 version.py
PS C:\Users\Dave> py.exe -m mpremote connect COM7 fs rm /lib/version.py
rm :/lib/version.py

Creating new directories

The 'mkdir' command can be used to create a new directory. You know how it works by now. Press CTRL + SHIFT + P and type mkdir to access the command from the palette. You'll be prompted for the name of the new directory.

Keep in mind the new directory will be created under the current directory and you can only create one level of new directory at a time. So if you wanted to create /temp/test, you'd do it like this:

  • USe chdir to get to the / directory
  • Use mkdir to create /temp
  • Use mkdir again, this time entering /temp/test

Now you can use the cp command to upload version.py into /temp/test, but don't forget to use chdir before you do.

A sample workflow

You've just opened the mailbox to find a shiny new ESP32 and you're anxious to start writing some code. Plug your device into a USB port and open up VS Code. The following scenario will show you how to create a small REST API on an ESP32 using VS Code extensions and the techniques you learned above.

Coming soon!

Clone this wiki locally