MicroPython 遠端控制：mpremote¶

mpremote 命令列工具提供一整套整合的公用程式，可透過序列連線遠端與 MicroPython 裝置互動、管理其檔案系統並進行自動化操作。它可透過 USB 序列連線與所有 OpenMV Cam 搭配使用，是 OpenMV IDE 在指令碼撰寫與自動化工作流程方面的命令列替代方案。

若要使用 mpremote，請先透過 pip 安裝它：

$ pip install --user mpremote

或透過 pipx 安裝：

$ pipx install mpremote

使用此工具最簡單的方式就是直接執行它而不帶任何引數：

$ mpremote

此命令會自動偵測並連線到第一個可用的 USB 序列裝置，並提供一個互動式終端機，讓你可以存取 REPL 以及你程式的輸出。序列埠以獨佔模式開啟，因此執行第二個（或第三個等）mpremote 實例時，若有其他可用裝置，便會連線到後續的序列裝置。

此外，pipx 也允許你不必先安裝就直接執行 mpremote：

$ pipx run mpremote ...args

命令¶

mpremote 支援在命令列上給定一系列命令，這些命令會在遠端 MicroPython 裝置上依序執行各種動作。請參閱下方的範例章節，以瞭解其運作方式以及一些常見的命令組合。

每個命令的形式為 <command name> [--options] [args...]。對於支援多個引數的命令（例如檔案清單），可以用 + 來終止引數清單。

若未指定任何命令，預設命令為 repl。此外，如果有任何命令需要存取裝置，而先前未指定 connect，則會自動加入一個隱含的 connect auto。

為了讓裝置在執行任何動作命令（repl 除外）時處於已知狀態，mpremote 在連線後會先停止任何正在執行的程式並對裝置進行軟重設，然後才執行第一個命令。你可以使用 resume 和 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 命令外，還有數個針對常見裝置路徑的預先定義捷徑。例如 a0 捷徑命令等同於 connect /dev/ttyACM0（Linux），或 c1 等同於 COM1（Windows）。

注意： auto 選項只會偵測 USB 序列埠，亦即具有相關聯 USB VID/PID 的序列埠（即 CDC/ACM 或 FTDI 類型的裝置）。其他類型的序列埠不會被自動偵測。

resume ¶

在後續命令中維持現有的直譯器狀態：

$ mpremote resume

這會停用自動軟重設。如果你想在開發板上執行後續命令而不先對它進行軟重設，這會很有用。

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 命令只是作為一個終端機（或「序列監視器」）來存取裝置。由於此命令不會觸發自動重設行為，這表示如果目前有程式正在執行，你需要先用 Ctrl-C 中斷它才能進入 REPL，接著就能存取程式狀態。你也可以使用 mpremote soft-reset repl 來取得一個清除所有程式狀態的「乾淨」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 [-rf] <src...> <dest> 複製檔案
rm [-r] <src...> 移除裝置上的檔案或資料夾
mkdir <dirs...> 在裝置上建立目錄
rmdir <dirs...> 移除裝置上的目錄
touch <file..> 建立檔案（若尚不存在）
sha256sum <file..> 計算檔案的 SHA256 雜湊值
tree [-vsh] <dirs...> 列印指定目錄的樹狀結構

cp 命令採用一種慣例，前置的 : 代表遠端路徑。沒有前置 : 則表示本機路徑。這是基於安全複製協定（scp）用戶端所使用的慣例。

舉例來說，mpremote fs cp main.py :main.py 會將 main.py 從目前的本機目錄複製到遠端檔案系統，而 mpremote fs cp :main.py main.py 則會將 main.py 從裝置複製回目前的目錄。

mpremote rm -r 命令同時接受相對路徑和絕對路徑。使用 : 可參照目前的遠端工作目錄（cwd），以允許從裝置的預設路徑（例如 /flash、/）移除某個目錄樹。使用 -v/--verbose 可查看正在移除的檔案。

例如：

mpremote rm -r :libs 會從裝置移除 libs 目錄及其所有子項目。
mpremote rm -rv :/sd 會移除已掛載 SDCard 上的所有檔案，並產生一個非阻擋性警告。掛載點將會保留。
mpremote rm -rv :/ 會移除裝置上的所有檔案，包括位於已掛載 vfs（例如 /sd 或 /flash）中的任何檔案。在移除所有資料夾和檔案後，這還會傳回一個錯誤，以模擬 unix 的 rm -rf / 行為。

警告

目前沒有任何受支援的方式可以還原被 mpremote rm -r : 移除的檔案。請謹慎使用。

tree 命令會列印指定目錄的樹狀結構。使用 --size/-s 選項會列印每個檔案的大小，或使用 --human/-h 以採用較易於閱讀的格式。注意：只有當裝置的檔案系統回報非零大小時，才會列印目錄大小。-v 選項可用於在輸出中加入序列裝置的名稱。

所有其他命令都會隱含地假設路徑為遠端路徑，但仍可選擇性地使用 : 以求清楚。

所有檔案系統子命令都接受多個路徑引數，因此如果序列中還有另一個命令，你必須使用 + 來終止引數，例如：

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

這會將檔案複製到裝置，然後進入 REPL。+ 可防止 "repl" 被解讀為路徑。

cp 命令支援 -r 選項以進行遞迴複製。依預設，如果來源檔案與目標檔案的 SHA256 雜湊值相符，cp 會略過將檔案複製到遠端裝置。若要不論雜湊值如何都強制複製，請使用 -f 選項。

注意： 為了方便起見，所有檔案系統子命令也都以一般命令的形式設了別名，亦即你可以寫 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>

這讓遠端裝置可以將本機主機目錄視為自己的檔案系統。這對開發很有用，並可避免在處理檔案時還需將它們複製到裝置。

裝置會安裝一個檔案系統驅動程式，接著它會被掛載在裝置 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 終止時自動發生，但也可在序列中使用它，以在後續命令執行之前卸載先前的掛載。

romfs ¶

管理裝置上的 ROMFS 分割區：

$ mpremote romfs <sub-command>

<sub-command> 可以是：

romfs query 列出所有可用的 ROMFS 分割區及其大小
romfs [-o <output>] build <source> 從指定的來源目錄建立 ROMFS 映像；預設的輸出檔案為來源名稱後加上 .romfs
romfs [-p <partition>] deploy <source> 將 ROMFS 映像部署到裝置；若來源是目錄，也會建立一個暫時的 ROMFS 映像

build 和 deploy 子命令都支援 -m/--mpy 選項，可在建立 ROMFS 映像時自動將 .py 檔案編譯為 .mpy。此選項依預設為啟用，但僅在已安裝 mpy_cross Python 套件時（例如透過 pip install mpy_cross）才有效。如果未安裝該套件，則會列印警告，且 .py 檔案維持原樣。編譯 .py 檔案的功能可用 --no-mpy 選項停用。

rtc ¶

設定／取得裝置時鐘（RTC）：

$ mpremote rtc

這會向裝置 RTC 查詢目前時間，並將它以 datetime 元組的形式列印出來。

$ mpremote rtc --set

這會將裝置 RTC 設為主機 PC 的目前時間。

sleep ¶

在執行下一個命令前先休眠（延遲）：

$ mpremote sleep 0.5

這會將命令序列的執行暫停指定的秒數，例如用於等待裝置完成某項操作。

reset ¶

對裝置進行硬重設：

$ mpremote reset

注意： 硬重設等同於 machine.reset()。

bootloader ¶

進入開機載入程式：

$ mpremote bootloader

這會讓裝置進入其開機載入程式。開機載入程式因開發板而異——詳情請參閱你開發板的快速參考中的 Recovery and debug pins 章節。

自動連線與軟重設¶

如果未明確給定連線和中斷連線命令，這些操作會在工具執行的開始與結束時自動完成。自動連線會搜尋第一個可用的 USB 序列裝置。

一旦連線到裝置，mpremote 會在需要時自動對裝置進行軟重設。這會清除 Python 堆積並重新啟動直譯器，以確保後續的 Python 程式碼在全新的環境中執行。自動軟重設會在首次執行下列其中一個命令時進行：mount、eval、exec、run、fs。首次進行軟重設後，便不會再自動進行，直到發出 disconnect 命令為止。

自動軟重設行為可由 resume 命令控制。這在使用 eval 命令檢查裝置狀態時可能很有用。soft-reset 命令則可用於在一系列命令的中途執行明確的軟重設。

捷徑¶

捷徑可使用巨集系統來定義。內建的捷徑有：

devs：connect list 的別名
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> 的別名

可以在使用者組態檔 mpremote/config.py 中定義額外的捷徑，該檔案位於使用者組態目錄中。每個作業系統的正確位置會使用 platformdirs 模組來判定。

這通常是：- $XDG_CONFIG_HOME/mpremote/config.py - $HOME/.config/mpremote/config.py - $env:LOCALAPPDATA/mpremote/config.py

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 multiply 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_ipconfig": [
"exec",
"import network; sta_if = network.WLAN(network.WLAN.IF_STA); print(sta_if.ipconfig('addr4'))",
], # 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 命令。請參閱上方的捷徑。

mpremote c1

連線到位於 COM1（Windows）的裝置，並隱含地執行 repl 命令。請參閱上方的捷徑。

mpremote connect /dev/ttyUSB0

明確指定要連線的裝置，並如上所述，隱含地執行 repl 命令。

mpremote a1 ls

連線到位於 /dev/ttyACM1 的裝置，然後執行 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

對裝置進行硬重設，等待 500ms 讓它變為可用，然後進入開機載入程式。

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-D 來重設直譯器狀態（這會保留掛載點），然後才按 Ctrl-J 以重新匯入 demo.py。

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

將 aioble 套件從 micropython-lib 安裝到裝置。請參閱套件管理。

mpremote mip install github:org/repo@branch

從 GitHub 上 org/repo 的指定分支安裝套件到裝置。請參閱套件管理。

mpremote mip install gitlab:org/repo@branch

從 GitLab 上 org/repo 的指定分支安裝套件到裝置。請參閱套件管理。

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

將 functools 套件從 micropython-lib 安裝到裝置上的 /flash/third-party 目錄。請參閱套件管理。

MicroPython 遠端控制：mpremote¶

命令¶

connect ¶

disconnect ¶

resume ¶

soft-reset ¶

repl ¶

eval ¶

exec ¶

run ¶

fs ¶

df ¶

edit ¶

mip ¶

mount ¶

unmount ¶

romfs ¶

rtc ¶

sleep ¶

reset ¶

bootloader ¶

自動連線與軟重設¶

捷徑¶

範例¶