Command Line - Workflow
00:00 Command Line Tools. While interacting with MicroPython via a REPL is a useful feature, there are times when you’ll need to transfer Python scripts and other resources to and from the board. One way to do this is via command line tools, which offer a simple interface to allow transfer to and from a MicroPython board which is connected via USB serial. Two such tools are Ampy and RShell.
Ampy offers a simple interface to MicroPython boards, and it’s easily installed using
pip. It offers a small but useful range of commands to interact with the board, mainly concentrating on file management.
00:41 Let’s see it in action on Windows. Here, you can see a Windows command prompt session. The first thing to note is that it’s a good idea to run any interactive session in Windows inside a virtual environment.
This means that you won’t be struggling with path issues, as the path of your virtual environment will be followed, allowing installed packages to run without a lot of scratching of your head, wailing, and gnashing of teeth. With that out of the way, let’s start taking a look at Ampy. The format of Ampy’s commands is
ampy, then specifying the port with the
--port directive. In this case, the Pyboard has presented itself as
COM5. Finally, the command we actually want to run. Firstly, let’s look at
There, you can see the contents of the
/flash/ folder. Now, one thing you may have noticed already is that specifying the port explicitly each time you run Ampy can get a little bit long-winded, and the way to improve this is to set an environment variable. On Windows, this is done with the
set command, while on Linux and macOS it would use
export. After that, the format is the same—setting
AMPY_PORT to the port in question.
02:11 Each time you run Ampy, it looks for this environment variable if no port has been specified. That makes the syntax of using it much more prosaic. Note that this is not saved permanently, so when your session ends, the variable will be deleted.
Ampy outputs the contents of the file to the console, so if you want to save these contents, you can redirect this output to a file using the greater than symbol (
>) and then the filename that you want to create.
02:56 As you can see, the contents are the same. Transferring files works in a similar manner. In this case, I’m going to specify the local source file first, and the explicit full destination file path second.
AMPY_PORT and the value, which in this case is
COM5. Hitting OK and OK again sets the variable, and any new command line session started will now have the variable present, allowing Ampy to run in a more elegant manner. If you need to change COM port, you can return to this window to edit the value if needs be, or you can temporarily override it by explicitly setting the port value in your
RShell offers a more comprehensive interaction with MicroPython hardware with a fully interactive shell that offers a wide range of commands for controlling MicroPython boards. It’s installed with
So, as you can see here, we are in a terminal on Ubuntu Linux, and running RShell is as simple as typing
rshell. You can see that it’s automatically detected and connected to the Pyboard, which I have connected, and in addition, it’s retrieved the root directory, so you can see that
/sd/ are both present.
/flash/ is the onboard memory on the Pyboard, and
/sd/ is a card which is plugged into it. Listing the contents of those is as easy as typing
ls, and then in this case
/flash to look at the onboard storage.
And checking what’s on the
/sd—as you can see, that’s been used in a camera. Viewing the contents of a file is easily done with
cat, so we can go
cat /flash/—and in this case,
another—and notice that it uses command completion, so once you’ve got to a unique point, you can just hit Tab and it will fill in the rest of it for you, saving quite a bit of typing. So there we can see a simple program which is stored on the Pyboard. You can copy files to and from.
So, for instance, we can copy
/flash/another.py to our present directory. And now if we list the present directory, we can see we’ve got the virtual environment, which I’m running in, and also
another.py, which I’ve just copied from the Pyboard.
Probably the most interesting part of RShell is the fact that you can run a REPL inside it, just by typing
repl. This takes us into the MicroPython REPL, which is running in this case on our Pyboard.
And we can do all of the things we’ve already seen directly, as it’s exactly the same. It’s just the REPL. If you want to quickly execute a program on your board, you can import it into the REPL, and providing it doesn’t contain the magic line of
if __name__ == '__main__', it will get executed. So in this case, I can import
another.py and that will then get run on the board, as you can see here.
07:13 Stopping that can be done with Control + C, and if you want to re-import it, you won’t be able to do it by repeating the command. However, if you reset the board, you can redo it. And resetting the board is dead easy—it’s just Control + D on the keyboard.
You’ll see that, in this case, the Pyboard is now running the default program,
main.py, and to get back to the REPL, Control + C will interrupt that program, and we’re back in the REPL. To exit the REPL and go back into RShell, type Control + X. And after a couple of seconds, you’ll end up back in RShell.
08:02 And there, any Linux shell command—as we’re running on Linux—will execute, and then we’ll be back in RShell. So, that’s a quick tour of the features of RShell. In the next lesson, you’ll see how it’s possible to transfer files and data to some MicroPython devices using your OS graphical user interface.
Become a Member to join the conversation.