6.6 KiB
MicroPython remote control: mpremote
The mpremote
command line tool provides an integrated
set of utilities to remotely interact with and automate a MicroPython
device over a serial connection.
To use mpremote install it via pip
:
$ pip 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 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.
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.
The full list of supported commands are:
connect to a specified device via a device-name shortcut:
$ mpremote <device-shortcut>
connect to specified device via name:
$ mpremote connect <device>
<device>
may be one of:list
: list available devicesauto
: connect to the first available deviceid:<serial>
: connect to the device with USB serial number<serial>
(the second entry in the output from theconnect list
command)port:<path>
: connect to the device with the given path- any valid device name/path, to connect to that device
disconnect current device:
$ mpremote disconnect
After a disconnect, auto soft-reset is enabled.
resume a previous
mpremote
session:$ mpremote resume
This disables auto 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 disables auto soft-reset.
enter the REPL on the connected device:
$ mpremote repl [options]
Options are:
--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--inject-file <file>
, to specify a file to inject at the REPL when Ctrl-K is pressed
evaluate and print the result of a Python expression:
$ mpremote eval <string>
execute the given Python code:
$ mpremote exec <string>
run a script from the local filesystem:
$ mpremote run <file>
execute filesystem commands on the device:
$ mpremote fs <command>
<command>
may be:cat <file..>
to show the contents of a file or files on the devicels
to list the current directoryls <dirs...>
to list the given directoriescp [-r] <src...> <dest>
to copy files; use ":" as a prefix to specify a file on the devicerm <src...>
to remove files on the devicemkdir <dirs...>
to create directories on the devicermdir <dirs...>
to remove directories on the device
mount the local directory on the remote device:
$ mpremote mount [options] <local-dir>
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-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 the local directory from the remote device:
$ mpremote umount
Multiple commands can be specified and they will be run sequentially.
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.
Shortcuts
Shortcuts can be defined using the macro system. Built-in shortcuts are:
- ``devs``: list available devices (shortcut for ``connect list``)
a0
,a1
,a2
,a3
: connect to /dev/ttyACM?u0
,u1
,u2
,u3
: connect to /dev/ttyUSB?c0
,c1
,c2
,c3
: connect to COM?cat
,ls
,cp
,rm
,mkdir
,rmdir
,df
: filesystem commandsreset
: reset the devicebootloader
: 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"],
}
Examples
mpremote
mpremote a1
mpremote connect /dev/ttyUSB0 repl
mpremote ls
mpremote a1 ls
mpremote exec "import micropython; micropython.mem_info()"
mpremote eval 1/2 eval 3/4
mpremote mount .
mpremote mount . exec "import local_script"
mpremote ls
mpremote cat boot.py
mpremote cp :main.py .
mpremote cp main.py :
mpremote cp -r dir/ :