|
| 1 | +.. _pyboard_py: |
| 2 | + |
| 3 | +The pyboard.py tool |
| 4 | +=================== |
| 5 | + |
| 6 | +This is a standalone Python tool that runs on your PC that provides a way to: |
| 7 | + |
| 8 | +* Quickly run a Python script or command on a MicroPython device. This is useful |
| 9 | + while developing MicroPython programs to quickly test code without needing to |
| 10 | + copy files to/from the device. |
| 11 | + |
| 12 | +* Access the filesystem on a device. This allows you to deploy your code to the |
| 13 | + device (even if the board doesn't support USB MSC). |
| 14 | + |
| 15 | +Despite the name, ``pyboard.py`` works on all MicroPython ports that support the |
| 16 | +raw REPL (including STM32, ESP32, ESP8266, NRF). |
| 17 | + |
| 18 | +You can download the latest version from `GitHub |
| 19 | +<https://github.com/micropython/micropython/blob/master/tools/pyboard.py>`_. The |
| 20 | +only dependency is the ``pyserial`` library which can be installed from PiPy or |
| 21 | +your system package manager. |
| 22 | + |
| 23 | +Running ``pyboard.py --help`` gives the following output: |
| 24 | + |
| 25 | +.. code-block:: text |
| 26 | +
|
| 27 | + usage: pyboard [-h] [--device DEVICE] [-b BAUDRATE] [-u USER] |
| 28 | + [-p PASSWORD] [-c COMMAND] [-w WAIT] [--follow] [-f] |
| 29 | + [files [files ...]] |
| 30 | +
|
| 31 | + Run scripts on the pyboard. |
| 32 | +
|
| 33 | + positional arguments: |
| 34 | + files input files |
| 35 | +
|
| 36 | + optional arguments: |
| 37 | + -h, --help show this help message and exit |
| 38 | + --device DEVICE the serial device or the IP address of the |
| 39 | + pyboard |
| 40 | + -b BAUDRATE, --baudrate BAUDRATE |
| 41 | + the baud rate of the serial device |
| 42 | + -u USER, --user USER the telnet login username |
| 43 | + -p PASSWORD, --password PASSWORD |
| 44 | + the telnet login password |
| 45 | + -c COMMAND, --command COMMAND |
| 46 | + program passed in as string |
| 47 | + -w WAIT, --wait WAIT seconds to wait for USB connected board to become |
| 48 | + available |
| 49 | + --follow follow the output after running the scripts |
| 50 | + [default if no scripts given] |
| 51 | + -f, --filesystem perform a filesystem action |
| 52 | +
|
| 53 | +Running a command on the device |
| 54 | +------------------------------- |
| 55 | + |
| 56 | +This is useful for testing short snippets of code, or to script an interaction |
| 57 | +with the device.:: |
| 58 | + |
| 59 | + $ pyboard.py --device /dev/ttyACM0 -c 'print(1+1)' |
| 60 | + 2 |
| 61 | + |
| 62 | +Running a script on the device |
| 63 | +------------------------------ |
| 64 | + |
| 65 | +If you have a script, ``app.py`` that you want to run on a device, then use:: |
| 66 | + |
| 67 | + $ pyboard.py --device /dev/ttyACM0 app.py |
| 68 | + |
| 69 | +Note that this doesn't actually copy app.py to the device's filesystem, it just |
| 70 | +loads the code into RAM and executes it. Any output generated by the program |
| 71 | +will be displayed. |
| 72 | + |
| 73 | +If the program app.py does not finish then you'll need to stop ``pyboard.py``, |
| 74 | +eg with Ctrl-C. The program ``app.py`` will still continue to run on the |
| 75 | +MicroPython device. |
| 76 | + |
| 77 | +Filesystem access |
| 78 | +----------------- |
| 79 | + |
| 80 | +Using the ``-f`` flag, the following filesystem operations are supported: |
| 81 | + |
| 82 | +* ``cp src [src...] dest`` Copy files to/from the device. |
| 83 | +* ``cat path`` Print the contents of a file on the device. |
| 84 | +* ``ls [path]`` List contents of a directory (defaults to current working directory). |
| 85 | +* ``rm path`` Remove a file. |
| 86 | +* ``mkdir path`` Create a directory. |
| 87 | +* ``rmdir path`` Remove a directory. |
| 88 | + |
| 89 | +The ``cp`` command uses a ``ssh``-like convention for referring to local and |
| 90 | +remote files. Any path starting with a ``:`` will be interpreted as on the |
| 91 | +device, otherwise it will be local. So:: |
| 92 | + |
| 93 | + $ pyboard.py --device /dev/ttyACM0 -f cp main.py :main.py |
| 94 | + |
| 95 | +will copy main.py from the current directory on the PC to a file named main.py |
| 96 | +on the device. The filename can be omitted, e.g.:: |
| 97 | + |
| 98 | + $ pyboard.py --device /dev/ttyACM0 -f cp main.py : |
| 99 | + |
| 100 | +is equivalent to the above. |
| 101 | + |
| 102 | +Some more examples:: |
| 103 | + |
| 104 | + # Copy main.py from the device to the local PC. |
| 105 | + $ pyboard.py --device /dev/ttyACM0 -f cp :main.py main.py |
| 106 | + # Same, but using . instead. |
| 107 | + $ pyboard.py --device /dev/ttyACM0 -f cp :main.py . |
| 108 | + |
| 109 | + # Copy three files to the device, keeping their names |
| 110 | + # and paths (note: `lib` must exist on the device) |
| 111 | + $ pyboard.py --device /dev/ttyACM0 -f cp main.py app.py lib/foo.py : |
| 112 | + |
| 113 | + # Remove a file from the device. |
| 114 | + $ pyboard.py --device /dev/ttyACM0 -f rm util.py |
| 115 | + |
| 116 | + # Print the contents of a file on the device. |
| 117 | + $ pyboard.py --device /dev/ttyACM0 -f cat boot.py |
| 118 | + ...contents of boot.py... |
| 119 | + |
| 120 | +Using the pyboard library |
| 121 | +------------------------- |
| 122 | + |
| 123 | +You can also use ``pyboard.py`` as a library for scripting interactions with a |
| 124 | +MicroPython board. |
| 125 | + |
| 126 | +.. code-block:: python |
| 127 | +
|
| 128 | + import pyboard |
| 129 | + pyb = pyboard.Pyboard('/dev/ttyACM0', 115200) |
| 130 | + pyb.enter_raw_repl() |
| 131 | + ret = pyb.exec('print(1+1)') |
| 132 | + print(ret) |
| 133 | + pyb.exit_raw_repl() |
0 commit comments