From 135339ce3ab8a50ae5160d1d84062475baeb1798 Mon Sep 17 00:00:00 2001 From: NitiKaur Date: Thu, 5 Aug 2021 08:57:22 +0530 Subject: [PATCH] docs/reference/mpremote.rst: Add docs for mpremote. --- docs/reference/index.rst | 1 + docs/reference/mpremote.rst | 196 ++++++++++++++++++++++++++++++++++++ 2 files changed, 197 insertions(+) create mode 100644 docs/reference/mpremote.rst diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 8cd5f03df4..853bbe7e36 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 0000000000..7a7d787a5a --- /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 + +- connect to specified device via name: + + .. code-block:: bash + + $ mpremote connect + + ```` may be one of: + + - ``list``: list available devices + - ``auto``: connect to the first available device + - ``id:``: connect to the device with USB serial number + ```` (the second entry in the output from the ``connect list`` + command) + - ``port:``: 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 ``, to capture output of the REPL session to the given + file + - ``--inject-code ``, to specify characters to inject at the REPL when + Ctrl-J is pressed + - ``--inject-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 + +- execute the given Python code: + + .. code-block:: bash + + $ mpremote exec + +- run a script from the local filesystem: + + .. code-block:: bash + + $ mpremote run + +- execute filesystem commands on the device: + + .. code-block:: bash + + $ mpremote fs + + ```` may be: + + - ``cat `` to show the contents of a file or files on the device + - ``ls`` to list the current directory + - ``ls `` to list the given directories + - ``cp [-r] `` to copy files; use ":" as a prefix to specify + a file on the device + - ``rm `` to remove files on the device + - ``mkdir `` to create directories on the device + - ``rmdir `` to remove directories on the device + +- mount the local directory on the remote device: + + .. code-block:: bash + + $ mpremote mount + +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/ :