circuitpython/docs/reference/pyboard.py.rst

145 lines
5.0 KiB
ReStructuredText
Raw Normal View History

.. _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] [-d DEVICE] [-b BAUDRATE] [-u USER] [-p PASSWORD]
[-c COMMAND] [-w WAIT] [--follow | --no-follow] [-f]
[files [files ...]]
Run scripts on the pyboard.
positional arguments:
files input files
optional arguments:
-h, --help show this help message and exit
-d DEVICE, --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
If you are often interacting with the same device, you can set the environment
variable ``PYBOARD_DEVICE`` as an alternative to using the ``--device``
command line option. For example, the following is equivalent to the previous
example::
$ export PYBOARD_DEVICE=/dev/ttyACM0
$ pyboard.py -c 'print(1+1)'
Similarly, the ``PYBOARD_BAUDRATE`` environment variable can be used
to set the default for the `--baudrate` option.
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()