MicroPython remote control: mpremote

The mpremote command line tool provides an integrated set of utilities to remotely interact with, manage the filesystem on, and automate a MicroPython device over a serial connection.

To use mpremote, first install it via pip:

$ pip install --user mpremote

Or via pipx:

$ pipx install mpremote

The simplest way to use this tool is just by invoking it without any arguments:

$ mpremote

This command automatically detects and connects to the first available USB serial device and provides an interactive terminal that you can use to access the REPL and your program’s output. Serial ports are opened in exclusive mode, so running a second (or third, etc) instance of mpremote will connect to subsequent serial devices, if any are available.

Additionally pipx also allows you to directly run mpremote without installing first:

$ pipx run mpremote ...args

Commands

mpremote supports being given a series of commands given at the command line which will perform various actions in sequence on a remote MicroPython device. See the examples section below to get an idea of how this works and for some common combinations of commands.

Each command is of the form <command name> [--options] [args...]. For commands that support multiple arguments (e.g. a list of files), the argument list can be terminated with +.

If no command is specified, the default command is repl. Additionally, if any command needs to access the device, and no earlier connect has been specified, then an implicit connect auto is added.

In order to get the device into a known state for any action command (except repl), once connected mpremote will stop any running program and soft-reset the device before running the first command. You can control this behavior using the resume and soft-reset commands. See auto-connection and auto-soft-reset for more details.

Multiple commands can be specified and they will be run sequentially.

The full list of supported commands are:

• connect

• disconnect

• resume

• soft_reset

• repl

• eval

• exec

• run

• fs

• df

• edit

• mip

• mount

• unmount

• rtc

• sleep

• reset

• bootloader

• connect – connect to specified device via name:

  $ mpremote connect <device>
  

  <device> may be one of:

  • list: list available devices

  • auto: connect to the first available USB serial port

  • id:<serial>: connect to the device with USB serial number <serial> (the second column from the connect list command output)

  • port:<path>: connect to the device with the given path (the first column from the connect list command output

  • rfc2217://<host>:<port>: connect to the device using serial over TCP (e.g. a networked serial port based on RFC2217)

  • any valid device name/path, to connect to that device

  Note: Instead of using the connect command, there are several pre-defined shortcuts for common device paths. For example the a0 shortcut command is equivalent to connect /dev/ttyACM0 (Linux), or c0 for COM0 (Windows).

  Note: The auto option will only detect USB serial ports, i.e. a serial port that has an associated USB VID/PID (i.e. CDC/ACM or FTDI-style devices). Other types of serial ports will not be auto-detected.

• disconnect – disconnect current device:

  $ mpremote disconnect
  

  After a disconnect, auto-soft-reset is enabled.

• resume – maintain existing interpreter state for subsequent commands:

  $ mpremote resume
  

  This disables auto-soft-reset. This is useful if you want to run a subsequent command on a board without first soft-resetting it.

• soft-reset – perform a soft-reset of the device:

  $ mpremote soft-reset
  

  This will clear out the Python heap and restart the interpreter. It also prevents the subsequent command from triggering auto-soft-reset.

• repl – enter the REPL on the connected device:

  $ mpremote repl [--options]
  

  Options are:

  • --escape-non-printable, to print non-printable bytes/characters as their hex code

  • --capture <file>, to capture output of the REPL session to the given file

  • --inject-code <string>, to specify characters to inject at the REPL when Ctrl-J is pressed. This allows you to automate a common command.

  • --inject-file <file>, to specify a file to inject at the REPL when Ctrl-K is pressed. This allows you to run a file (e.g. containing some useful setup code, or even the program you are currently working on).

  While the repl command running, you can use Ctrl-] or Ctrl-x to exit.

  Note: The name “REPL” here reflects that the common usage of this command to access the Read Eval Print Loop that is running on the MicroPython device. Strictly, the repl command is just functioning as a terminal (or “serial monitor”) to access the device. Because this command does not trigger the auto-reset behavior, this means that if a program is currently running, you will first need to interrupt it with Ctrl-C to get to the REPL, which will then allow you to access program state. You can also use mpremote soft-reset repl to get a “clean” REPL with all program state cleared.

• eval – evaluate and print the result of a Python expression:

  $ mpremote eval <string>
  

• exec – execute the given Python code:

  $ mpremote exec <string>
  

  By default, mpremote exec will display any output from the expression until it terminates. The --no-follow flag can be specified to return immediately and leave the device running the expression in the background.

• run – run a script from the local filesystem:

  $ mpremote run <file.py>
  

  This will execute the file directly from RAM on the device without copying it to the filesystem. This is a very useful way to iterate on the development of a single piece of code without having to worry about deploying it to the filesystem.

  By default, mpremote run will display any output from the script until it terminates. The --no-follow flag can be specified to return immediately and leave the device running the script in the background.

• fs – execute filesystem commands on the device:

  $ mpremote fs <sub-command>
  

  <sub-command> may be:

  • cat <file..> to show the contents of a file or files on the device

  • ls to list the current directory

  • ls <dirs...> to list the given directories

  • cp [-r] <src...> <dest> to copy files

  • rm <src...> to remove files on the device

  • mkdir <dirs...> to create directories on the device

  • rmdir <dirs...> to remove directories on the device

  • touch <file..> to create the files (if they don’t already exist)

  The cp command uses a convention where a leading : represents a remote path. Without a leading : means a local path. This is based on the convention used by the Secure Copy Protocol (scp) client. All other commands implicitly assume the path is a remote path, but the : can be optionally used for clarity.

  So for example, mpremote fs cp main.py :main.py copies main.py from the current local directory to the remote filesystem, whereas mpremote fs cp :main.py main.py copies main.py from the device back to the current directory.

  All of the filesystem sub-commands take multiple path arguments, so if there is another command in the sequence, you must use + to terminate the arguments, e.g.

  $ mpremote fs cp main.py :main.py + repl
  

  This will copy the file to the device then enter the REPL. The + prevents "repl" being interpreted as a path.

  Note: For convenience, all of the filesystem sub-commands are also aliased as regular commands, i.e. you can write mpremote cp ... instead of mpremote fs cp ....

• df – query device free/used space

  $ mpremote df
  

  The df command will print size/used/free statistics for the device filesystem, similar to the Unix df command.

• edit – edit a file on the device:

  $ mpremote edit <files...>
  

  The edit command will copy each file from the device to a local temporary directory and then launch your editor for each file (defined by the environment variable $EDITOR). If the editor exits successfully, the updated file will be copied back to the device.

• mip – install packages from micropython-lib (or GitHub) using the mip tool:

  $ mpremote mip install <packages...>
  

  See Package management for more information.

• mount – mount the local directory on the remote device:

  $ mpremote mount [options] <local-dir>
  

  This allows the remote device to see the local host directory as if it were its own filesystem. This is useful for development, and avoids the need to copy files to the device while you are working on them.

  The device installs a filesystem driver, which is then mounted in the device VFS as /remote, which uses the serial connection to mpremote as a side-channel to access files. The device will have its current working directory (via os.chdir) set to /remote so that imports and file access will occur there instead of the default filesystem path while the mount is active.

  Note: If the mount command is not followed by another action in the sequence, a repl command will be implicitly added to the end of the sequence.

  During usage, Ctrl-D will trigger a soft-reset as normal, but the mount will automatically be re-connected. If the unit has a main.py running at startup however the remount cannot occur. In this case a raw mode soft reboot can be used: Ctrl-A Ctrl-D to reboot, then Ctrl-B to get back to normal repl at which point the mount will be ready.

  Options are:

  • -l, --unsafe-links: By default an error will be raised if the device accesses a file or directory which is outside (up one or more directory levels) the local directory that is mounted. This option disables this check for symbolic links, allowing the device to follow symbolic links outside of the local directory.

• unmount – unmount the local directory from the remote device:

  $ mpremote umount
  

  This happens automatically when mpremote terminates, but it can be used in a sequence to unmount an earlier mount before subsequent command are run.

• rtc – set/get the device clock (RTC):

  $ mpremote rtc
  

  This will query the device RTC for the current time and print it as a datetime tuple.

  $ mpremote rtc --set
  

  This will set the device RTC to the host PC’s current time.

• sleep – sleep (delay) before executing the next command

  $ mpremote sleep 0.5
  

  This will pause execution of the command sequence for the specified duration in seconds, e.g. to wait for the device to do something.

• reset – hard reset the device

  $ mpremote reset
  

  Note: hard reset is equivalent to machine.reset().

• bootloader enter the bootloader

  $ mpremote bootloader
  

  This will make the device enter its bootloader. The bootloader is port- and board-specific (e.g. DFU on stm32, UF2 on rp2040/Pico).

Auto connection and soft-reset

Connection and disconnection will be done automatically at the start and end of the execution of the tool, if such commands are not explicitly given. Automatic connection will search for the first available USB serial device.

Once connected to a device, mpremote will automatically soft-reset the device if needed. This clears the Python heap and restarts the interpreter, making sure that subsequent Python code executes in a fresh environment. Auto soft-reset is performed the first time one of the following commands are executed: mount, eval, exec, run, fs. After doing a soft-reset for the first time, it will not be done again automatically, until a disconnect command is issued.

Auto-soft-reset behaviour can be controlled by the resume command. This might be useful to use the eval command to inspect the state of of the device. The soft-reset command can be used to perform an explicit soft reset in the middle of a sequence of commands.

Shortcuts

Shortcuts can be defined using the macro system. Built-in shortcuts are:

• devs: Alias for connect list

• a0, a1, a2, a3: Aliases for connect /dev/ttyACMn

• u0, u1, u2, u3: Aliases for connect /dev/ttyUSBn

• c0, c1, c2, c3: Aliases for connect COMn

• cat, edit, ls, cp, rm, mkdir, rmdir, touch: Aliases for fs <sub-command>

Additional shortcuts can be defined by in user-configuration files, which is located at .config/mpremote/config.py. This file should define a dictionary named commands. The keys of this dictionary are the shortcuts and the values are either a string or a list-of-strings:

"c33": "connect id:334D335C3138",

The command c33 is replaced by connect id:334D335C3138.

"test": ["mount", ".", "exec", "import test"],

The command test is replaced by mount . exec "import test".

Shortcuts can also accept arguments. For example:

"multiply x=4 y=7": "eval x*y",

Running mpremote times 3 7 will set x and y as variables on the device, then evaluate the expression x*y.

An example config.py might look like:

commands = {
    "c33": "connect id:334D335C3138", # Connect to a specific device by ID.
    "bl": "bootloader", # Shorter alias for bootloader.
    "double x=4": "eval x*2",  # x is an argument, with default 4
    "wl_scan": ["exec", """
import network
wl = network.WLAN()
wl.active(1)
for ap in wl.scan():
    print(ap)
""",], # Print out nearby WiFi networks.
    "wl_ifconfig": [
"exec",
"import network; sta_if = network.WLAN(network.STA_IF); print(sta_if.ifconfig())",
""",], # Print ip address of station interface.
    "test": ["mount", ".", "exec", "import test"], # Mount current directory and run test.py.
    "demo": ["run", "path/to/demo.py"], # Execute demo.py on the device.
}

Examples

mpremote

Connect to the first available device and implicitly run the repl command.

mpremote a1

Connect to the device at /dev/ttyACM1 (Linux) and implicitly run the repl command. See shortcuts above.

mpremote c1

Connect to the device at COM1 (Windows) and implicitly run the repl command. See shortcuts above.

mpremote connect /dev/ttyUSB0

Explicitly specify which device to connect to, and as above, implicitly run the repl command.

mpremote a1 ls

Connect to the device at /dev/ttyACM0 and then run the ls command.

It is equivalent to mpremote connect /dev/ttyACM1 fs ls.

mpremote exec "import micropython; micropython.mem_info()"

Run the specified Python command and display any output. This is equivalent to typing the command at the REPL prompt.

mpremote eval 1/2 eval 3/4

Evaluate each expression in turn and print the results.

mpremote a0 eval 1/2 a1 eval 3/4

Evaluate 1/2 on the device at /dev/ttyACM0, then 3/4 on the device at /dev/ttyACM1, printing each result.

mpremote resume exec "print_state_info()" soft-reset

Connect to the device without triggering a soft reset and execute the print_state_info() function (e.g. to find out information about the current program state), then trigger a soft reset.

mpremote reset sleep 0.5 bootloader

Hard-reset the device, wait 500ms for it to become available, then enter the bootloader.

mpremote cp utils/driver.py :utils/driver.py + run test.py

Update the copy of utils/driver.py on the device, then execute the local test.py script on the device. test.py is never copied to the device filesystem, rather it is run from RAM.

mpremote cp utils/driver.py :utils/driver.py + exec "import app"

Update the copy of utils/driver.py on the device, then execute app.py on the device.

This is a common development workflow to update a single file and then re-start your program. In this scenario, your main.py on the device would also do import app.

mpremote cp utils/driver.py :utils/driver.py + soft-reset repl

Update the copy of utils/driver.py on the device, then trigger a soft-reset to restart your program, and then monitor the output via the repl command.

mpremote cp -r utils/ :utils/ + soft-reset repl

Same as above, but update the entire utils directory first.

mpremote mount .

Mount the current local directory at /remote on the device and starts a repl session which will use /remote as the working directory.

mpremote mount . exec "import demo"

After mounting the current local directory, executes demo.py from the mounted directory.

mpremote mount app run test.py

After mounting the local directory app as /remote on the device, executes the local test.py from the host’s current directory without copying it to the filesystem.

mpremote mount . repl --inject-code "import demo"

After mounting the current local directory, executes demo.py from the mounted directory each time Ctrl-J is pressed.

You will first need to press Ctrl-D to reset the interpreter state (which will preserve the mount) before pressing Ctrl-J to re-import demo.py.

mpremote mount app repl --inject-file demo.py

Same as above, but executes the contents of the local file demo.py at the REPL every time Ctrl-K is pressed. As above, use Ctrl-D to reset the interpreter state first.

mpremote cat boot.py

Displays the contents of boot.py on the device.

mpremote edit utils/driver.py

Edit utils/driver.py on the device using your local $EDITOR.

mpremote cp :main.py .

Copy main.py from the device to the local directory.

mpremote cp main.py :

Copy main.py from the local directory to the device.

mpremote cp :a.py :b.py

Copy a.py on the device to b.py on the device.

mpremote cp -r dir/ :

Recursively copy the local directory dir to the remote device.

mpremote cp a.py b.py : + repl

Copy a.py and b.py from the local directory to the device, then run the repl command.

mpremote mip install aioble

Install the aioble package from micropython-lib to the device. See Package management.

mpremote mip install github:org/repo@branch

Install the package from the specified branch at org/repo on GitHub to the device. See Package management.

mpremote mip install gitlab:org/repo@branch

Install the package from the specified branch at org/repo on GitLab to the device. See Package management.

mpremote mip install --target /flash/third-party functools

Install the functools package from micropython-lib to the /flash/third-party directory on the device. See Package management.