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
这将暂停命令序列的执行，持续指定的秒数，例如等待设备执行某些操作。
reset – 硬复位设备
$ mpremote reset
**注:**硬复位相当于
machine.reset()。
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 gitlab:org/repo@branch
将包从 GitLab 上 org/repo 的指定分支安装到设备。请参见:ref:包管理。
mpremote mip install --target /flash/third-party functools
将 micropython-lib 中的 functools 包安装到设备上的 /flash/third-party 目录下。请参见 包管理。