197 lines
4.8 KiB
ReStructuredText
197 lines
4.8 KiB
ReStructuredText
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``:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ pip install mpremote
|
|
|
|
The simplest way to use this tool is just by invoking it without any arguments:
|
|
|
|
.. code-block:: bash
|
|
|
|
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:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ mpremote <device-shortcut>
|
|
|
|
- connect to specified device via name:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ mpremote connect <device>
|
|
|
|
``<device>`` may be one of:
|
|
|
|
- ``list``: list available devices
|
|
- ``auto``: connect to the first available device
|
|
- ``id:<serial>``: connect to the device with USB serial number
|
|
``<serial>`` (the second entry in the output from the ``connect 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:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ mpremote disconnect
|
|
|
|
- enter the REPL on the connected device:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ 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:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ mpremote eval <string>
|
|
|
|
- execute the given Python code:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ mpremote exec <string>
|
|
|
|
- run a script from the local filesystem:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ mpremote run <file>
|
|
|
|
- execute filesystem commands on the device:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ mpremote fs <command>
|
|
|
|
``<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; use ":" as a prefix to specify
|
|
a file on the device
|
|
- ``rm <src...>`` to remove files on the device
|
|
- ``mkdir <dirs...>`` to create directories on the device
|
|
- ``rmdir <dirs...>`` to remove directories on the device
|
|
|
|
- mount the local directory on the remote device:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ mpremote mount <local-dir>
|
|
|
|
Multiple commands can be specified and they will be run sequentially.
|
|
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.
|
|
|
|
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
|
|
commands
|
|
|
|
- ``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:
|
|
|
|
.. code-block:: python3
|
|
|
|
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
|
|
--------
|
|
|
|
.. code-block:: bash
|
|
|
|
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/ :
|