diff options
Diffstat (limited to 'docs/reference')
| -rw-r--r-- | docs/reference/index.rst | 1 | ||||
| -rw-r--r-- | docs/reference/mpremote.rst | 196 |
2 files changed, 197 insertions, 0 deletions
diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 8cd5f03df..853bbe7e3 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -21,6 +21,7 @@ implementation and the best practices to use them. glossary.rst repl.rst + mpremote.rst mpyfiles.rst isr_rules.rst speed_python.rst diff --git a/docs/reference/mpremote.rst b/docs/reference/mpremote.rst new file mode 100644 index 000000000..7a7d787a5 --- /dev/null +++ b/docs/reference/mpremote.rst @@ -0,0 +1,196 @@ +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/ : |