mpremote — MicroPython latest documentation (2024)

Commands¶

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

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

If no command is specified, the default command is repl. Additionally, ifany command needs to access the device, and no earlier connect has beenspecified, 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 programand soft-reset the device before running the first command. You can controlthis 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 listcommand output)

  • port:<path>: connect to the device with the given path (the first columnfrom 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 severalpre-defined shortcuts for common device paths. Forexample the a0 shortcut command is equivalent toconnect /dev/ttyACM0 (Linux), or c0 for COM0 (Windows).

  Note: The auto option will only detect USB serial ports, i.e. a serialport that has an associated USB VID/PID (i.e. CDC/ACM or FTDI-styledevices). 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 youwant 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 alsoprevents the subsequent command from triggering auto-soft-reset.

• repl – enter the REPL on the connected device:

  $ mpremote repl [--options]

  See Also

  Roku TV Universal Remote Codes & Program Instructions - Universal Remote Codes

  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 givenfile

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

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

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

  Note: The name “REPL” here reflects that the common usage of this commandto access the Read Eval Print Loop that is running on the MicroPythondevice. Strictly, the repl command is just functioning as a terminal(or “serial monitor”) to access the device. Because this command does nottrigger the auto-reset behavior, this means that ifa program is currently running, you will first need to interrupt it withCtrl-C to get to the REPL, which will then allow you to access programstate. You can also use mpremote soft-reset repl to get a “clean” REPLwith 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 itterminates. The --no-follow flag can be specified to return immediately and leavethe 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 itto the filesystem. This is a very useful way to iterate on the development ofa single piece of code without having to worry about deploying it to thefilesystem.

  By default, mpremote run will display any output from the script until itterminates. The --no-follow flag can be specified to return immediately and leavethe 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 remotepath. Without a leading : means a local path. This is based on theconvention used by the Secure Copy Protocol (scp) client. All other commandsimplicitly assume the path is a remote path, but the : can be optionallyused for clarity.

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

  All of the filesystem sub-commands take multiple path arguments, so if thereis another command in the sequence, you must use + to terminate thearguments, 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 alsoaliased as regular commands, i.e. you can writempremote 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 devicefilesystem, 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 temporarydirectory and then launch your editor for each file (defined by the environmentvariable $EDITOR). If the editor exits successfully, the updated file willbe 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 wereits own filesystem. This is useful for development, and avoids the need tocopy files to the device while you are working on them.

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

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

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

  Options are:

  • -l, --unsafe-links: By default an error will be raised if the deviceaccesses a file or directory which is outside (up one or more directory levels) thelocal directory that is mounted. This option disables this check for symboliclinks, 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 usedin 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 datetimetuple.

  $ 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 durationin 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- andboard-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 ofthe execution of the tool, if such commands are not explicitly given. Automaticconnection will search for the first available USB serial device.

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

Auto-soft-reset behaviour can be controlled by the resume command. Thismight be useful to use the eval command to inspect the state of of thedevice. The soft-reset command can be used to perform an explicit softreset 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 islocated at .config/mpremote/config.py. This file should define adictionary named commands. The keys of this dictionary are the shortcutsand 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 networkwl = network.WLAN()wl.active(1)for ap in wl.scan(): print(ap)""",], # Print out nearby WiFi networks. "wl_ipconfig": ["exec","import network; sta_if = network.WLAN(network.STA_IF); print(sta_if.ipconfig('addr4'))",""",], # 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 therepl command. See shortcuts above.

mpremote c1

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

mpremote connect /dev/ttyUSB0

Explicitly specify which device to connect to, and as above, implicitly run therepl 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 totyping 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 thedevice 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 theprint_state_info() function (e.g. to find out information about the currentprogram 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 thebootloader.

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

Update the copy of utils/driver.py on the device, then execute the localtest.py script on the device. test.py is never copied to the devicefilesystem, 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 thedevice.

This is a common development workflow to update a single file and then re-startyour program. In this scenario, your main.py on the device would also doimport 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 torestart 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 arepl session which will use /remote as the working directory.

mpremote mount . exec "import demo"

After mounting the current local directory, executes demo.py from themounted 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 withoutcopying it to the filesystem.

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

After mounting the current local directory, executes demo.py from themounted 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-importdemo.py.

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

Same as above, but executes the contents of the local file demo.py at the REPLevery time Ctrl-K is pressed. As above, use Ctrl-D to reset the interpreterstate 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 therepl 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 thedevice. See Package management.

mpremote mip install gitlab:org/repo@branch

Install the package from the specified branch at org/repo on GitLab to thedevice. 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.