docs/reference: Add docs describing use of pyboard.py.

docs/reference/index.rst

@@ -26,3 +26,4 @@ implementation and the best practices to use them.
    constrained.rst
    packages.rst
    asm_thumb2_index.rst
+   pyboard.py.rst

docs/reference/pyboard.py.rst

@@ -0,0 +1,133 @@
+.. _pyboard_py:
+
+The pyboard.py tool
+===================
+
+This is a standalone Python tool that runs on your PC that provides a way to:
+
+* Quickly run a Python script or command on a MicroPython device. This is useful
+  while developing MicroPython programs to quickly test code without needing to
+  copy files to/from the device.
+
+* Access the filesystem on a device. This allows you to deploy your code to the
+  device (even if the board doesn't support USB MSC).
+
+Despite the name, ``pyboard.py`` works on all MicroPython ports that support the
+raw REPL (including STM32, ESP32, ESP8266, NRF).
+
+You can download the latest version from `GitHub
+<https://github.com/micropython/micropython/blob/master/tools/pyboard.py>`_. The
+only dependency is the ``pyserial`` library which can be installed from PiPy or
+your system package manager.
+
+Running ``pyboard.py --help`` gives the following output:
+
+.. code-block:: text
+
+    usage: pyboard [-h] [--device DEVICE] [-b BAUDRATE] [-u USER]
+                   [-p PASSWORD] [-c COMMAND] [-w WAIT] [--follow] [-f]
+                   [files [files ...]]
+
+    Run scripts on the pyboard.
+
+    positional arguments:
+      files                 input files
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      --device DEVICE       the serial device or the IP address of the
+                            pyboard
+      -b BAUDRATE, --baudrate BAUDRATE
+                            the baud rate of the serial device
+      -u USER, --user USER  the telnet login username
+      -p PASSWORD, --password PASSWORD
+                            the telnet login password
+      -c COMMAND, --command COMMAND
+                            program passed in as string
+      -w WAIT, --wait WAIT  seconds to wait for USB connected board to become
+                            available
+      --follow              follow the output after running the scripts
+                            [default if no scripts given]
+      -f, --filesystem      perform a filesystem action
+
+Running a command on the device
+-------------------------------
+
+This is useful for testing short snippets of code, or to script an interaction
+with the device.::
+
+    $ pyboard.py --device /dev/ttyACM0 -c 'print(1+1)'
+    2
+
+Running a script on the device
+------------------------------
+
+If you have a script, ``app.py`` that you want to run on a device, then use::
+
+    $ pyboard.py --device /dev/ttyACM0 app.py
+
+Note that this doesn't actually copy app.py to the device's filesystem, it just
+loads the code into RAM and executes it. Any output generated by the program
+will be displayed.
+
+If the program app.py does not finish then you'll need to stop ``pyboard.py``,
+eg with Ctrl-C. The program ``app.py`` will still continue to run on the
+MicroPython device.
+
+Filesystem access
+-----------------
+
+Using the ``-f`` flag, the following filesystem operations are supported:
+
+* ``cp src [src...] dest`` Copy files to/from the device.
+* ``cat path`` Print the contents of a file on the device.
+* ``ls [path]`` List contents of a directory (defaults to current working directory).
+* ``rm path`` Remove a file.
+* ``mkdir path`` Create a directory.
+* ``rmdir path`` Remove a directory.
+
+The ``cp`` command uses a ``ssh``-like convention for referring to local and
+remote files. Any path starting with a ``:`` will be interpreted as on the
+device, otherwise it will be local. So::
+
+    $ pyboard.py --device /dev/ttyACM0 -f cp main.py :main.py
+
+will copy main.py from the current directory on the PC to a file named main.py
+on the device. The filename can be omitted, e.g.::
+
+    $ pyboard.py --device /dev/ttyACM0 -f cp main.py :
+
+is equivalent to the above.
+
+Some more examples::
+
+    # Copy main.py from the device to the local PC.
+    $ pyboard.py --device /dev/ttyACM0 -f cp :main.py main.py
+    # Same, but using . instead.
+    $ pyboard.py --device /dev/ttyACM0 -f cp :main.py .
+
+    # Copy three files to the device, keeping their names
+    # and paths (note: `lib` must exist on the device)
+    $ pyboard.py --device /dev/ttyACM0 -f cp main.py app.py lib/foo.py :
+
+    # Remove a file from the device.
+    $ pyboard.py --device /dev/ttyACM0 -f rm util.py
+
+    # Print the contents of a file on the device.
+    $ pyboard.py --device /dev/ttyACM0 -f cat boot.py
+    ...contents of boot.py...
+
+Using the pyboard library
+-------------------------
+
+You can also use ``pyboard.py`` as a library for scripting interactions with a
+MicroPython board.
+
+.. code-block:: python
+
+    import pyboard
+    pyb = pyboard.Pyboard('/dev/ttyACM0', 115200)
+    pyb.enter_raw_repl()
+    ret = pyb.exec('print(1+1)')
+    print(ret)
+    pyb.exit_raw_repl()