.. _pyboard_py:

The pyboard.py tool
pyboard.py工具
===================

This is a standalone Python tool that runs on your PC that provides a way to:
这是一个独立的Python工具，运行在您的PC上，提供了一种方式:

* 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.
* 在MicroPython设备上快速运行Python脚本或命令。这是非常有用的
  在开发微python程序时，无需快速测试代码
  复制文件到/从设备。

* 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).
* 访问设备上的文件系统。这允许您将代码部署到
  设备(即使董事会不支持USB MSC)。

Despite the name, ``pyboard.py`` works on all MicroPython ports that support the
raw REPL (including STM32, ESP32, ESP8266, NRF).
尽管名字，``pyboard.py``的所有MicroPython端口上都可以工作
原始REPL(包括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.
你可以从GitHub下载最新版本
<https://github.com/micropython/micropython/blob/master/tools/pyboard.py>`_。的
唯一依赖的是``pyserial``库，它可以从PiPy或
您的系统包管理器。

Running ``pyboard.py --help`` gives the following output:
运行``pyboard.py --help``会给出以下输出:

.. 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.
    在pyboard上运行脚本。

    positional arguments:
    位置参数:
      files                 input files

    optional arguments:
      -h, --help            show this help message and exit
      -h, --help            显示此帮助信息并退出
      --device DEVICE       the serial device or the IP address of the
      --device DEVICE       的串行设备或IP地址
                            pyboard
      -b BAUDRATE, --baudrate BAUDRATE
                            the baud rate of the serial device
                            串行设备的波特率
      -u USER, --user USER  the telnet login username
      -u USER, --user USER  telnet登录用户名
      -p PASSWORD, --password PASSWORD
                            the telnet login password
                            telnet登录密码
      -c COMMAND, --command COMMAND
                            program passed in as string
                            作为字符串传入的程序
      -w WAIT, --wait WAIT  seconds to wait for USB connected board to become
      -w WAIT, --wait WAIT  秒等待USB连接板成为
                            available
                            可用
      --follow              follow the output after running the scripts
      --follow              运行脚本后按照输出进行操作
                            [default if no scripts given]
      -f, --filesystem      perform a filesystem action
      -f, --filesystem      执行文件系统操作

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::
如果你有一个脚本，``app.py``，然后使用::

    $ 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.
注意，这实际上并没有将app.py复制到设备的文件系统，它只是
将代码加载到RAM中并执行。程序生成的任何输出
将显示出来。

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.
如果程序app.py没有完成，那么您需要停止 ``pyboard.py``，
例如,ctrl - c。程序的应用``app.py``仍将继续运行
MicroPython设备。

Filesystem access
文件系统访问
-----------------

Using the ``-f`` flag, the following filesystem operations are supported:
使用``-f``标志，支持下列文件系统操作:

* ``cp src [src...] dest`` Copy files to/from the device.
* ``cp src [src...] dest`` 复制文件到/从设备。
* ``cat path`` Print the contents of a file on the device.
* ``cat path`` 打印设备上文件的内容。
* ``ls [path]`` List contents of a directory (defaults to current working directory).
* ``ls [path]`` 列出目录的内容(默认为当前工作目录)。
* ``rm path`` Remove a file.
* ``rm path`` 移动一个文件
* ``mkdir path`` Create a directory.
* ``mkdir path`` 创建一个目录
* ``rmdir path`` Remove a directory.
* ``rmdir path`` 删除一个目录。

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::
``cp`` 命令使用类似``ssh``的约定来引用本地和
远程文件。任何以``:``开头的路径都将被解释为on
设备，否则将是本地的。所以::

    $ 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.::
是否将main.py从PC上的当前目录复制到名为main.py的文件
在设备上。文件名可以省略，例如::

    $ 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.
    # 将main.py从设备复制到本地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)
    # 和路径(注意:`lib`必须存在于设备上)
    $ 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
使用pyboard库
-------------------------

You can also use ``pyboard.py`` as a library for scripting interactions with a
MicroPython board.
你也可以使用``pyboard.py``作为一个库，用于脚本化与
MicroPython董事会。

.. 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()