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.

00:28 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.

00:55 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 ls.

01:29 Here, you can see Ampy has shown us that the two root directories on the Pyboard are /flash and /sd, and we can list those by extending that original command.

01:42 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.

02:26 It’s possible to make this a permanent environment variable, as we’ll see at the end of this section. Ampy can output the contents of a file to the console, as seen here.

02:39 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.

03:15 It’s also possible to use Ampy to run a local file on the board with a command like this.

03:23 In this case, this is a simple for loop that prints out each number. Ampy redirects the output of the script to the console so you can see it working straight away.

03:35 As you can imagine, this can greatly speed up your development, allowing you to work locally and execute remotely, and seeing the effects of your program in near real time.

03:47 If you want to permanently set the AMPY_PORT variable in Windows, this is how it’s done. Firstly, tap the Windows key and type “environ”.

03:58 This is a quick way to filter Start menu entries, and in this case, we want to set the variable for the account rather than for the system, so we’re going to take this top option.

04:10 In the window that appears, you can click New… and enter the variable name

04:16 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 ampy command.

04:45 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 pip.

04:58 It has a wide range of commands, with some of them shown onscreen here. Let’s see it in action on Linux.

05:07 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 /flash/ and /sd/ are both present.

05:28 /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.

05:44 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.

06:12 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.

06:31 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.

06:44 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.

07:31 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.

07:53 So, another useful command in RShell is typing shell and then the command that you would run in the environment you’re in, such as ls.

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.