This is the v1.20.0 version of the MicroPython documentation. The latest development version of this page may be more current.

The pyboard.py tool

This is a standalone Python tool that runs on your PC that provides a way to:

  • Quickly run a Python script or command on a MicroPython device. This is useful while developing MicroPython programs to quickly test code without needing to copy files to/from the device.

  • Access the filesystem on a device. This allows you to deploy your code to the device (even if the board doesn’t support USB MSC).

Despite the name, pyboard.py works on all MicroPython ports that support the raw REPL (including STM32, ESP32, ESP8266, NRF).

You can download the latest version from GitHub. The only dependency is the pyserial library which can be installed from PiPy or your system package manager.

Running pyboard.py --help gives the following output:

usage: pyboard [-h] [-d DEVICE] [-b BAUDRATE] [-u USER] [-p PASSWORD]
               [-c COMMAND] [-w WAIT] [--follow | --no-follow] [-f]
               [files [files ...]]

Run scripts on the pyboard.

positional arguments:
  files                 input files

optional arguments:
  -h, --help            show this help message and exit
  -d DEVICE, --device DEVICE
                        the serial device or the IP address of the pyboard
  -b BAUDRATE, --baudrate BAUDRATE
                        the baud rate of the serial device
  -u USER, --user USER  the telnet login username
  -p PASSWORD, --password PASSWORD
                        the telnet login password
  -c COMMAND, --command COMMAND
                        program passed in as string
  -w WAIT, --wait WAIT  seconds to wait for USB connected board to become
                        available
  --follow              follow the output after running the scripts
                        [default if no scripts given]
  -f, --filesystem      perform a filesystem action: cp local :device | cp
                        :device local | cat path | ls [path] | rm path | mkdir
                        path | rmdir path

Running a command on the device

This is useful for testing short snippets of code, or to script an interaction with the device.:

$ pyboard.py --device /dev/ttyACM0 -c 'print(1+1)'
2

If you are often interacting with the same device, you can set the environment variable PYBOARD_DEVICE as an alternative to using the --device command line option. For example, the following is equivalent to the previous example:

$ export PYBOARD_DEVICE=/dev/ttyACM0
$ pyboard.py -c 'print(1+1)'

Similarly, the PYBOARD_BAUDRATE environment variable can be used to set the default for the --baudrate option.

Running a script on the device

If you have a script, app.py that you want to run on a device, then use:

$ pyboard.py --device /dev/ttyACM0 app.py

Note that this doesn’t actually copy app.py to the device’s filesystem, it just loads the code into RAM and executes it. Any output generated by the program will be displayed.

If the program app.py does not finish then you’ll need to stop pyboard.py, eg with Ctrl-C. The program app.py will still continue to run on the MicroPython device.

Filesystem access

Using the -f flag, the following filesystem operations are supported:

  • cat path Print the contents of a file on the device.

  • cp src [src...] dest Copy files to/from the device.

  • ls [path] List contents of a directory (defaults to current working directory).

  • mkdir path Create a directory.

  • rm path Remove a file.

  • rmdir path Remove a directory.

  • touch path Create a file if it doesn’t already exist.

The cp command uses a ssh-like convention for referring to local and remote files. Any path starting with a : will be interpreted as on the device, otherwise it will be local. So:

$ pyboard.py --device /dev/ttyACM0 -f cp main.py :main.py

will copy main.py from the current directory on the PC to a file named main.py on the device. The filename can be omitted, e.g.:

$ pyboard.py --device /dev/ttyACM0 -f cp main.py :

is equivalent to the above.

Some more examples:

# Copy main.py from the device to the local PC.
$ pyboard.py --device /dev/ttyACM0 -f cp :main.py main.py
# Same, but using . instead.
$ pyboard.py --device /dev/ttyACM0 -f cp :main.py .

# Copy three files to the device, keeping their names
# and paths (note: `lib` must exist on the device)
$ pyboard.py --device /dev/ttyACM0 -f cp main.py app.py lib/foo.py :

# Remove a file from the device.
$ pyboard.py --device /dev/ttyACM0 -f rm util.py

# Print the contents of a file on the device.
$ pyboard.py --device /dev/ttyACM0 -f cat boot.py
...contents of boot.py...

Using the pyboard library

You can also use pyboard.py as a library for scripting interactions with a MicroPython board.

import pyboard
pyb = pyboard.Pyboard('/dev/ttyACM0', 115200)
pyb.enter_raw_repl()
ret = pyb.exec('print(1+1)')
print(ret)
pyb.exit_raw_repl()