148 lines
5.2 KiB
ReStructuredText
148 lines
5.2 KiB
ReStructuredText
.. _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: cp local :device | cp
|
|
:device local | cat path | ls [path] | rm path | mkdir
|
|
path | rmdir path
|
|
|
|
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:
|
|
|
|
* ``cat path`` Print the contents of a file on the device.
|
|
* ``cp src [src...] dest`` Copy files to/from the device.
|
|
* ``ls [path]`` List contents of a directory (defaults to current working directory).
|
|
* ``mkdir path`` Create a directory.
|
|
* ``rm path`` Remove a file.
|
|
* ``rmdir path`` Remove a directory.
|
|
* ``touch path`` Create a file if it doesn't already exist.
|
|
|
|
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()
|