MicroPython远程控制: mpremote

mpremote 命令行工具提供了一组集成的实用程序，用于通过串行连接与MicroPython设备进行远程交互、管理文件系统和自动化。

要使用mpremote，首先通过 pip 安装:

$ pip install --user mpremote

或通过 pipx:

$ pipx install mpremote

使用这个工具最简单的方法就是不带任何参数地调用它:

$ mpremote

该命令自动检测并连接到第一个可用的USB串行设备，并提供一个交互式终端，您可以使用该终端访问REPL和程序的输出。串行端口以独占模式打开，因此运行 mpremote 的第二个(或第三个等) 实例将连接到后续的串行设备，如果有可用的话。

此外，pipx 还允许您直接运行 mpremote 而无需先安装:

$ pipx run mpremote ...args

命令

mpremote 支持在命令行中给出一系列命令，这些命令将在远程MicroPython设备上依次执行各种操作。请参阅下面的:ref:examples section ，了解它是如何工作的，以及一些常见的命令组合。

每个命令的形式是 <command name> [--options] [args...]。对于支持多个参数的命令(例如文件列表)，参数列表可以用 + 结束。

如果未指定命令，则默认命令为 repl。此外，如果任何命令需要访问设备，并且之前没有指定 connect，则会添加隐式的 connect auto。

为了使设备进入任何操作命令(除了 repl)的已知状态，一旦连接 mpremote 将停止任何正在运行的程序并在运行第一个命令之前软复位设备。您可以使用 resume 和 soft-reset 命令控制此行为。参见:ref:auto-connection and auto-soft-reset 了解更多细节。

可以指定多个命令，它们将依次运行。

支持的命令的完整列表包括：

  • connect – 通过名称连接到指定设备:

    $ mpremote connect <device>

    <device> 可以是以下其中之一:

    • list: 列表可用设备

    • auto:连接到第一个可用的USB串行端口

    • id:<serial>:连接到USB序列号为 <serial> 的设备(从 connect list 命令输出的第二列)

    • port:<path>:连接到给定路径的设备(从 connect list 命令输出的第一列)

    • rfc2217://<host>:<port>:通过TCP使用串口连接到设备(例如基于rfc2217的网络串口)

    • 任何有效的设备名称/路径，以连接到该设备

    **注意:**不使用 connect 命令，有几个 pre-defined shortcuts 用于常见的设备路径。例如， a0 快捷方式命令相当于 connect /dev/ttyACM0 (Linux)，或 c0 用于 COM0 (Windows)。

    注: auto 选项将只检测USB串行端口，即具有关联USB VID/PID的串行端口(即CDC/ACM或ftdi风格的设备)。其他类型的串行端口将不会被自动检测。

  • disconnect – 断开当前设备：

    $ mpremote disconnect

    断开连接后，启用:ref:auto-soft-reset。

  • resume – 为后续命令维护现有解释器状态：

    $ mpremote resume

    这会禁用 auto-soft-reset。如果您想在板上运行后续命令，而不首先对其进行软重置，这将非常有用。

  • 软复位–执行设备的软复位：

    $ mpremote soft-reset

    这将清除Python堆并重新启动解释器。它还可以防止后续命令触发:ref:auto-soft-reset。

  • repl – 在连接的设备上输入REPL：

    $ mpremote repl [--options]

    选项有：

    • --escape-non-printable，用于将不可打印的字节/字符打印为其十六进制代码

    • --capture <file>，捕获到给定文件的REPL会话的输出

    • --inject-code <string>, 指定按 Ctrl-J 时要在REPL中注入的字符。这允许您自动执行一个常用命令。

    • --inject-file <file>，指定按 Ctrl-K 时要在REPL中注入的文件。这允许你运行一个文件(例如，包含一些有用的设置代码，甚至是你目前正在处理的程序)。

    在运行 repl 命令时，您可以使用 Ctrl-] 或 Ctrl-x 退出。

    **注意:**此处的名称 “REPL” 反映了该命令用于访问MicroPython设备上运行的Read Eval Print Loop的常用用法。严格地说，repl 命令只是作为终端(或“串行监视器”)来访问设备。因为这个命令不会触发:ref:auto-reset behavior，这意味着如果一个程序当前正在运行，您将首先需要用 Ctrl-C 中断它以进入REPL，这将允许您访问程序状态。您还可以使用 mpremote soft-reset repl 来获得清除所有程序状态的 “clean” repl。

  • eval– 计算并打印Python表达式的结果:

    $ mpremote eval <string>

  • exec – 执行给定的Python代码:

    $ mpremote exec <string>

    默认情况下，mpremote exec 将显示表达式的任何输出，直到它终止。可以指定 --no-follow 标志来立即返回，并让设备在后台运行表达式。

  • run – 从本地文件系统运行脚本:

    $ mpremote run <file.py>

    这将直接从设备上的RAM执行文件，而不将其复制到文件系统中。这是一种非常有用的方法，可以迭代开发一段代码，而不必担心将其部署到文件系统中。

    默认情况下， mpremote run 将显示脚本的任何输出，直到脚本终止。可以指定 --no-follow 标志来立即返回并让设备在后台运行脚本。

  • fs – 在设备上执行文件系统命令：

    $ mpremote fs <sub-command>

    <sub-command> 可以是：

    • cat <file..> 显示设备上一个或多个文件的内容

    • ls 列出当前目录

    • ls <dirs...> 列出给定的目录

    • cp [-r] <src...> <dest> 复制文件

    • rm <src...> 删除设备上的文件

    • mkdir <dirs...> 在设备上创建目录

    • rmdir <dirs...> 删除设备上的目录

    • touch <file..> 创建文件（如果文件不存在）

    cp 命令使用一个约定，其中前导 : 表示远程路径。没有前导 : 表示本地路径。这是基于 Secure Copy Protocol (scp) client 使用的约定。所有其他命令都隐式地假设路径是远程路径，但是为了清晰起见，可以选择使用 : 。

    例如，mpremote fs cp main.py :main.py 将 main.py 从当前本地目录复制到远程文件系统，而 mpremote fs cp :main.py main.py 将 main.py 从设备复制回当前目录。

    所有的文件系统子命令都接受多个路径参数，所以如果序列中有另一个命令，您必须使用 + 来终止参数，例如。

    $ mpremote fs cp main.py :main.py + repl

    这将把文件复制到设备上，然后输入REPL。+ 防止 "repl" 被解释为路径。

    **注意:**为了方便起见，所有的文件系统子命令也是:ref:aliased as regular commands，即你可以写 mpremote cp ... 而不是 mpremote fs cp ...。

  • df – 查询设备空闲/已用空间

    $ mpremote df

    df 命令将打印设备文件系统的大小/已使用/空闲统计信息，类似于Unix的 df 命令。

  • edit – 编辑设备上的文件：

    $ mpremote edit <files...>

    edit 命令将每个文件从设备复制到本地临时目录，然后为每个文件启动编辑器(由环境变量 $EDITOR 定义)。如果编辑器成功退出，更新后的文件将被复制回设备。

  • mip —— 使用 mip 工具从 micropython-lib (或 GitHub)安装包:

    $ mpremote mip install <packages...>

    参见 包管理 了解更多信息。

  • mount – 将本地目录挂载到远端设备上：

    $ mpremote mount [options] <local-dir>

    这允许远程设备查看本地主机目录，就好像它是自己的文件系统一样。这对开发很有用，并且避免了在处理文件时将文件复制到设备上的需要。

    设备安装一个文件系统驱动程序，然后将其挂载在:ref:device VFS 中作为 /remote，它使用到 mpremote 的串行连接作为访问文件的侧通道。设备将把其当前工作目录(通过 os.chdir)设置为 /remote ，以便在挂载活动时在那里进行导入和文件访问，而不是默认的文件系统路径。

    **注意:**如果 mount 命令后面没有其他操作，那么 repl 命令将隐式地添加到序列的末尾。

    在使用过程中， Ctrl-D 将像往常一样触发软复位，但是挂载将自动重新连接。如果单元在启动时运行main.py，但是无法进行重新加载。在这种情况下，可以使用原始模式软重启：按 Ctrl-A按 Ctrl-D 重新启动，然后按 Ctrl-B恢复到正常repl，此时装入将准备好。

    选项有：

    • -l, --unsafe-links: 默认情况下，如果设备访问的文件或目录位于挂载的本地目录之外(在一个或多个目录级别上)，将引发错误。该选项禁用对符号链接的检查，允许设备跟踪本地目录之外的符号链接。

  • unmount——从远端设备上卸载本地目录:

    $ mpremote umount

    当 mpremote 终止时将自动发生，但它可以在序列中使用，以在运行后续命令之前卸载之前的挂载。

  • rtc – 设置/获取设备时钟（RTC）：

    $ mpremote rtc

    这将查询设备RTC的当前时间，并将其打印为日期时间元组。

    $ mpremote rtc --set

    这将设置设备RTC为主机PC的当前时间。

  • sleep – 在执行下一个命令之前休眠(延迟)

    $ mpremote sleep 0.5

    这将暂停命令序列的执行，持续指定的秒数，例如等待设备执行某些操作。

  • bootloader 输入引导加载程序

    $ mpremote bootloader

    这将使设备进入其引导加载程序。引导加载程序是特定于移植版本和主板的(例如stm32上的DFU, rp2040/Pico上的UF2)。

自动连接和软复位

如果没有明确给出这样的命令，将在工具执行的开始和结束时自动完成连接和断开连接。自动连接将搜索第一个可用的USB串行设备。

一旦连接到设备，mpremote 将自动软复位设备，如果需要的话。这将清除Python堆并重新启动解释器，确保后续Python代码在新的环境中执行。首次执行 mount 、 eval 、 exec 、 run 、 fs 等命令之一时，会自动软复位。第一次软复位后，在发出 disconnect 命令之前，不会自动重新复位。

自动软复位行为可以通过 resume 命令控制。这可能是有用的使用 eval 命令检查设备的状态。soft-reset 命令可用于在命令序列的中间执行显式软复位。

快捷键

可以使用宏系统定义快捷方式。内置快捷方式有:

  • devs: 连接列表 的别称

  • a0, a1, a2, a3: connect /dev/ttyACMn 的别称

  • u0, u1, u2, u3: connect /dev/ttyUSBn 的别称

  • c0, c1, c2, c3: connect COMn 的别称

  • cat, edit, ls, cp, rm, mkdir, rmdir, touch: fs <sub-command> 的别称

其他快捷方式可以在用户配置文件中定义，该文件位于 .config/mpremote/config.py。这个文件应该定义一个名为 commands 的字典。这个字典的键是快捷键，值是字符串或字符串列表:

"c33": "connect id:334D335C3138",

命令 c33 替换为 connect id:334D335C3138。

"test": ["mount", ".", "exec", "import test"],

命令 test 已替换为 mount . exec "import test"。

快捷方式也可以接受参数。例如：

"multiply x=4 y=7": "eval x*y",

运行 mpremote times 3 7 将设置 x 和 y 作为设备上的变量，然后计算表达式 x*y。

一个示例 config.py 文件可能如下所示：

commands = {
    "c33": "connect id:334D335C3138", # Connect to a specific device by ID.
    "bl": "bootloader", # Shorter alias for bootloader.
    "double x=4": "eval x*2",  # x is an argument, with default 4
    "wl_scan": ["exec", """
import network
wl = network.WLAN()
wl.active(1)
for ap in wl.scan():
    print(ap)
""",], # Print out nearby WiFi networks.
    "wl_ifconfig": [
"exec",
"import network; sta_if = network.WLAN(network.STA_IF); print(sta_if.ifconfig())",
""",], # Print ip address of station interface.
    "test": ["mount", ".", "exec", "import test"], # Mount current directory and run test.py.
    "demo": ["run", "path/to/demo.py"], # Execute demo.py on the device.
}

示例

mpremote

连接到第一个可用的设备并隐式运行 repl 命令。

mpremote a1

连接到设备 /dev/ttyACM1 (Linux) 并隐式运行 repl 命令。参阅上面的 shortcuts 。

mpremote c1

在 COM1 连接到设备(Windows)并隐式运行 repl 命令。参阅上面的 shortcuts。

mpremote connect /dev/ttyUSB0

显式指定要连接到哪个设备，并像上面一样隐式运行 repl 命令。

mpremote a1 ls

在 /dev/ttyACM0 处连接到设备，然后运行 ls 命令。

它相当于 mpremote connect /dev/ttyACM1 fs ls。

mpremote exec "import micropython; micropython.mem_info()"

运行指定的Python命令并显示输出结果。这相当于在REPL提示符下输入命令。

mpremote eval 1/2 eval 3/4

依次计算每个表达式并打印结果。

mpremote a0 eval 1/2 a1 eval 3/4

在位于 /dev/ttyACM0 的设备上计算 1/2 ，然后在位于 /dev/ttyACM1 的设备上计算 3/4 ，打印每个结果。

mpremote resume exec "print_state_info()" soft-reset

在不触发软复位的情况下连接设备，并执行 print_state_info() 函数(例如，查找有关当前程序状态的信息)，然后触发软复位。

mpremote reset sleep 0.5 bootloader

硬复位设备，等待500毫秒使其可用，然后进入引导加载程序。

mpremote cp utils/driver.py :utils/driver.py + run test.py

更新设备上的utils/driver.py副本，然后在设备上执行本地 test.py 脚本。 test.py 永远不会复制到设备文件系统，而是从RAM运行。

mpremote cp utils/driver.py :utils/driver.py + exec "import app"

更新设备上utils/driver.py的副本，然后在设备上执行app.py。

这是更新单个文件然后重新启动程序的常见开发工作流。在这种情况下，设备上的 main.py 也会执行 import app。

mpremote cp utils/driver.py :utils/driver.py + soft-reset repl

更新设备上的utils/driver.py副本，然后触发软重置以重新启动程序，然后通过 repl 命令监视输出。

mpremote cp -r utils/ :utils/ + soft-reset repl

与上面相同，但首先更新整个utils目录。

mpremote mount .

将当前本地目录挂载到设备上的 /remote ，并启动 repl 会话，该会话将使用 /remote 作为工作目录。

mpremote mount . exec "import demo"

挂载当前本地目录后，从挂载的目录执行 demo.py 。

mpremote mount app run test.py

在设备上将本地目录 app 挂载为 /remote 后，从主机的当前目录执行本地 test.py ，而不将其复制到文件系统中。

mpremote mount . repl --inject-code "import demo"

挂载当前本地目录后，每次按 Ctrl-J 时，从挂载的目录执行 demo.py 。

在按 Ctrl-J 重新导入 demo.py 之前，您首先需要按 Ctrl-D 重置解释器状态(这将保留挂载)。

mpremote mount app repl --inject-file demo.py

与上面相同，但每次按下 Ctrl-K 时，在REPL中执行本地文件demo.py的内容。如上所述，首先使用Ctrl-D重置解释器状态。

mpremote cat boot.py

在设备上显示 boot.py 的内容。

mpremote edit utils/driver.py

使用本地的 $EDITOR 在设备上编辑 utils/driver.py 。

mpremote cp :main.py .

将 main.py 从设备复制到本地目录。

mpremote cp main.py :

将 main.py 从本地目录复制到设备。

mpremote cp :a.py :b.py

将设备上的 a.py 复制到设备上的 b.py 。

mpremote cp -r dir/ :

递归地将本地目录 dir 复制到远程设备。

mpremote cp a.py b.py : + repl

将 a.py 和 b.py 从本地目录复制到设备，然后运行 repl 命令。

mpremote mip install aioble

从 micropython-lib 中安装 aioble 包到设备。请参见 包管理。

mpremote mip install github:org/repo@branch

从GitHub上的指定分支org/repo安装包到设备。请参见:ref:包管理。

mpremote mip install --target /flash/third-party functools

将 micropython-lib 中的 functools 包安装到设备上的 /flash/third-party 目录下。请参见 包管理。