mpremote - MicroPython remote control

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 serial device.  If no action is specified then the REPL will be entered.

       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. And the soft-reset command can be used
       to perform an explicit soft reset.

Commands

For REPL access, running mpremote without any arguments is usually all that is needed. mpremote also
supports a set of commands given at the command line which will perform various actions on remote
MicroPython devices.

For commands that support multiple arguments (e.g. a list of files), the argument list can be terminated
with +. The full list of supported commands are:

connect [device]
Connect to a specified device via a device-name shortcut. device may be one of:

auto connect to the first available device

list list the available devices

id:serial
connect to the device with USB serial number serial (the second entry in the output from
the connectlist command)

port:path
connect to the device with the given path

If the device is not specified, auto is assumed.

disconnect
Disconnects the current device. After a disconnect, auto soft-reset is enabled (see AUTO-CONNECTIONANDSOFT-RESET below).

resume Resume a previous mpremote session. This disables auto soft-reset (see AUTO-CONNECTIONANDSOFT-RESET below).

soft-reset
Perform a soft-reset of the device. This will clear out the Python heap and restart the
interpreter. It also disables auto soft-reset (see AUTO-CONNECTIONANDSOFT-RESET below).

repl [options]
Enter the REPL on the connected device. The available options are:

--capturefile
to capture output of the REPL session to the given file

--inject-codestring
to specify characters to inject at the REPL when Ctrl-J is pressed

--inject-filefile
to specify a file to inject at the REPL when Ctrl-K is pressed

evalstring
Evaluate ahd print the result of a Python expression.

execstring
Execute the given Python code.

runfile
Run a script from the local filesystem.

fssubcommand
Execute filesystem commands on the device. subcommand may be:

catfiles...
to show the contents of a file or files on the device

lslsdirs...
to list the current, or specified directories

cp [-r] src...dest
to copy files; use ":" as a prefix to specify a file on the device

rmsrc...
to remove files on the device

mkdirdirs...
to create directories on the device

rmdirdirs...
to remove directories on the device

touchfiles...
to create empty files (if they don't already exist)

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

mipinstall [options] packages...
Install packages from micropython-lib (or GitHub) using the mip tool. The available options are:

--targetpath
Install under path instead of the default location (the first entry in sys.path ending in
/lib). Please note that mustexistinsys.path for you to be able to subsequently import
the package.

--no-mpy
Install the source version .py files rather than .mpy).--indexURL
Use the specified URL instead of the default package index at https://micropython.org/pi.

mount [options] local-dir
Mount a local directory on the remote device (under the path /remote). During usage, Ctrl-D will
soft-reboot and normally reconnect the mount automatically. 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-ACtrl-D to reboot, then Ctrl-B to get back to normal repl at which point the mount will be ready.

The available 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.

umount Unmount the local directory from the remote device.

Description

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

       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  serial  device  and  provides  an
       interactive  REPL.   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.

Examples

mpremote
              Launch a repl on the automatically detected device.

       mpremotea1
              Launch a repl on the device connected to port /dev/ttyACM1 (using the built-in a1 shortcut).

       mpremoteconnect/dev/ttyUSB0repl
              Launch a repl on the device connect to port /dev/ttyUSB0.

       mpremotels
              List files on the automatically detected device.

       mpremotea1ls
              List files on the device connected to port /dev/ttyACM1 (using the built-in a1 shortcut).

       mpremoteexecimportmicropython;micropython.mem_info()
              Execute some Python code on the remote board to obtain various memory statistics.

       mpremoteeval1/2eval3/4
              Execute  (and show the output of) two simple Python statements on the remote board. Note that no +
              was required because eval accepts a single string argument.

       mpremotemount.
              Mount the local directory under /remote on the automatically detected device.

       mpremotemount.exec"importlocalscript"
              Mount the local directory under /remote on the MicroPython board, then  import  the  "localscript"
              module

       mpremotecatboot.py
              Show the contents of boot.py on the MicroPython board.

       mpremotecp:main.py.
              Copy the main.py file from the (remote) MicroPython board to the current (local) directory.

       mpremotecpmain.py:
              Copy the main.py from the current (local) directory to the (remote) MicroPython board.

       mpremotecp:a.py:b.py
              On the MicroPython board, copy a.py to b.py.

       mpremotecp-rdir/:
              Recursively copy the local directory dir/ to the root directory of the (remote) MicroPython board.

       mpremotecpa.pyb.py:+repl
              Copy  the  local files a.py and b.py to the root directory of the (remote) MicroPython board, then
              launch a repl.  Note that the + terminator is required here as the cp command takes  an  arbitrary
              number of parameters.

       mpremotemipinstallaioble
              Install the asyncio-based wrapper for the Bluetooth API.

       mpremotemipinstallgithub:org/repo@branch
              Install the branch of the MicroPython package located under org/repo on GitHub.

       mpremotemipinstall--target/flash/third-partyfunctools
              Install the functools package under the /flash/third-party directory on the MicroPython board.

Name

       mpremote - MicroPython remote control

Options

--help Show a help message and exit.

       --version
              Show the program version and exit.

Shortcuts

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

              devs   list available devices (shortcut for connectlist)

              a0, a1, a2, a3
                     connect to /dev/ttyACMnu0, u1, u2, u3
                     connect to /dev/ttyUSBnc0, c1, c2, c3
                     connect to COMncat, ls, cp, rm, mkdir, rmdir, touch, df
                     filesystem commands (mostly aliases for the fs equivalent)

              reset  reset the device

              bootloader
                     make the device enter its bootloader

       Any   user   configuration,   including   user-defined   shortcuts,   can   be   placed   in   the   file
       ~/.config/mpremote/config.py.  For example:

              commands = {
                  "c33": "connect id:334D335C3138",
                  "bl": "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)
              """,],
                  "test": ["mount", ".", "exec", "import test"],
              }

Synopsis

mpremote command [options] [+command ...]mpremote [--help]

       mpremote [--version]