MicroPython リモートコントロール: mpremote

mpremote コマンドラインツールは、シリアル接続を介して MicroPython デバイスをリモートで操作し、デバイス上のファイルシステムを管理し、自動化するための統合ユーティリティ群を提供します。すべての OpenMV Cam で USB シリアル接続を通じて動作し、スクリプト作成や自動化のワークフローにおいて OpenMV IDE の代替となるコマンドラインツールです。

mpremote を使用するには、まず pip でインストールします:

$ pip install --user mpremote

あるいは pipx を使用します:

$ pipx install mpremote

このツールを使用する最も簡単な方法は、引数を付けずに起動することです:

$ mpremote

このコマンドは、最初に利用可能な USB シリアルデバイスを自動的に検出して接続し、REPL とプログラムの出力にアクセスできる対話型ターミナルを提供します。シリアルポートは排他モードで開かれるため、2 つ目（または 3 つ目など）の 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 コマンド出力の 2 列目）を持つデバイスに接続します

  • port:<path>: 指定したパス（connect list コマンド出力の 1 列目）を持つデバイスに接続します

  • rfc2217://<host>:<port>: TCP 上のシリアル（例: RFC2217 に基づくネットワーク経由のシリアルポート）を使用してデバイスに接続します

  • 任意の有効なデバイス名/パスを指定して、そのデバイスに接続します

注: connect コマンドを使用する代わりに、一般的なデバイスパス用にいくつかの 事前定義されたショートカット が用意されています。たとえば a0 ショートカットコマンドは connect /dev/ttyACM0（Linux）に相当し、c1 は COM1（Windows）に相当します。

注: auto オプションは USB シリアルポート、つまり USB VID/PID が関連付けられたシリアルポート（CDC/ACM や FTDI スタイルのデバイス）のみを検出します。その他の種類のシリアルポートは自動検出されません。

disconnect

現在のデバイスから切断します:

$ mpremote disconnect

切断後は 自動ソフトリセット が有効になります。

resume

後続のコマンドのために既存のインタープリタの状態を維持します:

$ mpremote resume

これは 自動ソフトリセット を無効にします。これは、ボードを最初にソフトリセットせずに後続のコマンドを実行したい場合に便利です。

soft-reset

デバイスのソフトリセットを実行します:

$ mpremote soft-reset

これは Python ヒープをクリアしてインタープリタを再起動します。また、後続のコマンドが 自動ソフトリセット をトリガーするのも防ぎます。

repl

接続したデバイス上で REPL に入ります:

$ mpremote repl [--options]

オプションは次のとおりです:

  • --escape-non-printable: 印字不可能なバイト/文字をその 16 進コードとして表示します

  • --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 コマンドは、先頭の : がリモートパスを表すという慣例を使用します。先頭に : がない場合はローカルパスを意味します。これは Secure Copy Protocol (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 :/ は、/sd や /flash などのマウントされた vfs にあるものを含め、デバイス上のすべてのファイルを削除します。すべてのフォルダとファイルを削除した後、unix の rm -rf / の動作を模倣してエラーも返します。

警告

mpremote rm -r : で削除されたファイルを復元するサポートされた方法はありません。注意して使用してください。

tree コマンドは、指定したディレクトリのツリーを表示します。--size/-s オプションを使用すると各ファイルのサイズが表示され、--human/-h を使用するとより人間が読みやすい形式になります。注: ディレクトリのサイズは、デバイスのファイルシステムがゼロ以外のサイズを報告した場合にのみ表示されます。-v オプションを使用すると、出力にシリアルデバイスの名前を含めることができます。

その他のすべてのコマンドは暗黙的にパスをリモートパスと見なしますが、明確にするために任意で : を使用できます。

ファイルシステムのサブコマンドはすべて複数のパス引数を取るため、シーケンス内に別のコマンドがある場合は、引数を終端するために + を使用する必要があります。例:

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

これはファイルをデバイスにコピーしてから REPL に入ります。+ は "repl" がパスとして解釈されるのを防ぎます。

cp コマンドは、再帰的なコピーを行うための -r オプションをサポートしています。デフォルトでは、cp はソースファイルと宛先ファイルの SHA256 ハッシュが一致する場合、リモートデバイスへのファイルのコピーをスキップします。ハッシュに関係なく強制的にコピーするには -f オプションを使用します。

注: 利便性のため、すべてのファイルシステムサブコマンドは 通常のコマンドとしてもエイリアスされています。つまり、mpremote fs cp ... の代わりに mpremote 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 を持っている場合、再マウントは行われません。この場合、raw モードのソフトリブートを使用できます: Ctrl-A Ctrl-D で再起動し、Ctrl-B で通常の repl に戻ると、その時点でマウントの準備が整います。

オプションは次のとおりです:

  • -l, --unsafe-links: デフォルトでは、デバイスがマウントされたローカルディレクトリの外部（1 つ以上上のディレクトリレベル）にあるファイルまたはディレクトリにアクセスすると、エラーが発生します。このオプションはシンボリックリンクに対するこのチェックを無効にし、デバイスがローカルディレクトリ外のシンボリックリンクをたどることを許可します。

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 サブコマンドはどちらも、ROMFS イメージの作成時に .py ファイルを自動的に .mpy にコンパイルするための -m/--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> のエイリアス

追加のショートカットは、User Configuration Directory にあるユーザー設定ファイル mpremote/config.py で定義できます。各 OS の正しい場所は 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 にマウントし、/remote を作業ディレクトリとして使用する repl セッションを開始します。

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 が押されるたびにローカルファイル demo.py の内容を REPL で実行します。上記と同様に、まず 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 の指定したブランチからパッケージをデバイスにインストールします。パッケージ管理 を参照してください。

mpremote mip install gitlab:org/repo@branch

GitLab 上の org/repo の指定したブランチからパッケージをデバイスにインストールします。パッケージ管理 を参照してください。

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

micropython-lib から functools パッケージをデバイス上の /flash/third-party ディレクトリにインストールします。パッケージ管理 を参照してください。