diff options
Diffstat (limited to 'docs/reference')
| -rw-r--r-- | docs/reference/index.rst | 1 | ||||
| -rw-r--r-- | docs/reference/pyboard.py.rst | 133 |
2 files changed, 134 insertions, 0 deletions
diff --git a/docs/reference/index.rst b/docs/reference/index.rst index d0c7f69de..4dd52b9c8 100644 --- a/docs/reference/index.rst +++ b/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 diff --git a/docs/reference/pyboard.py.rst b/docs/reference/pyboard.py.rst new file mode 100644 index 000000000..60d7509af --- /dev/null +++ b/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() |