10000 docs/reference: Add docs describing use of pyboard.py. · rlangoy/micropython@d7dbd26 · GitHub
[go: up one dir, main page]

Skip to content

Commit d7dbd26

Browse files
jimmodpgeorge
authored andcommitted
docs/reference: Add docs describing use of pyboard.py.
1 parent 90c524c commit d7dbd26

File tree

2 files changed

+134
-0
lines changed

2 files changed

+134
-0
lines changed

docs/reference/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,4 @@ implementation and the best practices to use them.
2626
constrained.rst
2727
packages.rst
2828
asm_thumb2_index.rst
29+
pyboard.py.rst

docs/reference/pyboard.py.rst

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
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

Comments
 (0)
0