MicroPython のリモート制御: mpremote¶
mpremote
コマンドラインツールは、シリアル接続を介して MicroPython デバイスをリモート操作、ファイルシステム管理、自動化するための統合されたユーティリティセットを提供します。
mpremote を使えるようにするには、まず pip
でインストールします:
$ pip install --user mpremote
pipx を使ってもインストールできます:
$ pipx install mpremote
このツールを使う最も簡単な方法は、引数なしで起動することです:
$ mpremote
このコマンドは、最初に利用可能な USB シリアルデバイスを自動的に検出して接続し、REPL アクセスとプログラムの出力先となる対話ターミナルを使える状態にします。シリアルポートはエクスクルーシブモードで開かれるので、 mpremote
の2番目(さらに3番目など)のインスタンスを実行すると、利用可能なシリアルデバイスがあれば、後続のシリアルデバイスに接続します。
さらに、 pipx
を使えば mpremote
をインストールしておかなくても実行できます:
$ pipx run mpremote ...args
コマンド¶
mpremote
は、コマンドラインで与えた一連のコマンドを、リモートの MicroPython デバイス上で様々なアクションを順番に実行することをサポートしています。どのように動作するか、また、いくつかの一般的なコマンドの組み合わせについては、後述の:ref:例の章 を参照してください。
Each command is of the form <command name> [--options] [args...]
. For commands
that support multiple arguments (e.g. a list of files), the argument list can
be terminated with +
.
コマンドを指定しない場合、デフォルトのコマンドは repl
です。さらに、何らかのコマンドがデバイスにアクセスする必要があり、その前に connect
が指定されていない場合、暗黙の connect auto
が追加されます。
(repl
を除いた)任意のアクションコマンドでデバイスを既知の状態にするために、 mpremote
は一度接続すると最初のコマンドを実行する前にデバイスで実行中であったプログラムを停止し、デバイスをソフトリセット状態にします。この動作は、 resume
と soft-reset
コマンドを使って制御できます。詳しくは 自動接続と自動ソフトリセット を参照してください。
複数のコマンドを指定することができ、それらは順次実行されます。
サポートされているコマンドの全リストは以下の通りです:
connect -- 指定した名前のデバイスに接続:
$ mpremote connect <device>
<device>
は以下のいずれかです:list
: 利用可能なデバイスのリストauto
: connect to the first available USB serial portid:<serial>
: USB シリアル番号<serial>
(connect list
コマンドで出力される2番目の項目)を持つデバイスに接続port:<path>
: 指定したパス(connect list
コマンドで出力される1番目の項目)を持つデバイスに接続rfc2217://<host>:<port>
: シリアルオーバー TCP (RFC2217 に基づくネットワークシリアルポートなど)を使ってデバイスに接続します。任意の有効なデバイス名/パスを指定して、そのデバイスに接続
注記:
connect
コマンドを使う代わりに、一般的なデバイスパスのために:ref:事前定義したショートカット をいくつか用意してあります。たとえばa0
ショートカットコマンドはconnect /dev/ttyACM0
(Linux)と同等、c0
は はCOM0
(Windows)と同等などです。注記:
auto
オプションは、USBシリアルポート、すなわち関連するUSB VID/PID を持つシリアルポート(CDC/ACM や FTDI スタイルのデバイスなど)だけを検出します。その他の種類のシリアルポートは自動検出されません。
disconnect* -- 現在のデバイスを切断:"
$ mpremote disconnect
切断後、 auto-soft-reset が有効化されます。
resume -- 後続のコマンドのために既存のインタプリタの状態を維持:
$ mpremote resume
これは auto-soft-reset を無効にします。最初にソフトリセットすることなく、ボード上で後続のコマンドを実行したい場合に便利です。
soft-reset -- デバイスのソフトリセットを実行:
$ mpremote soft-reset
これは Python のヒープをクリアし、インタープリターを再起動します。また、後続のコマンドで o:ref:auto-soft-reset が発動するのを防げます。
repl -- 接続したデバイスの REPL に入る:
$ mpremote repl [--options]
オプションは次のとおりです:
--escape-non-printable
: 表示できないバイト/文字を16進数のコードで表示します--capture <file>
: REPL セッションの出力を指定したファイルにキャプチャーします--inject-code <string>
: REPL で Ctrl-J が押されたときに注入する文字列を指定します。これにより、よく使うコマンドの入力を自動化できます。--inject-file <file>
: Ctrl-K が押されたときに REPL に注入するファイルを指定します。これにより、ファイルを実行できます(たとえば、便利なセットアップコードや、現在作業中のプログラムなど)。
repl
コマンドの実行を終了するにはCtrl-]
またはCtrl-x
を使います。注記: ここで「REPL」という名称は、このコマンドの一般的な利用法がMicroPython デバイス上で実行されている Read Eval Print Loop にアクセスすることであるのを反映しています。厳密には、
repl
コマンドはデバイスにアクセスするためのターミナル(または「シリアルモニター」)として機能しているだけです。このコマンドは auto-reset の動作 を引き起こさないため、現在プログラムが実行されている場合は、まず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 サムを計算
The
cp
command uses a convention where a leading:
represents a remote path. Without a leading:
means a local path. This is based on the convention used by the Secure Copy Protocol (scp) client.たとえば
mpremote fs cp main.py :main.py
はmain.py
をカレントローカルディレクトリからリモートファイルシステムにコピーしますが、mpremote fs cp :main.py main.py
はデバイスからカレントディレクトリに戻すようにコピーします。The
mpremote rm -r
command accepts both relative and absolute paths. Use:
to refer to the current remote working directory (cwd) to allow a directory tree to be removed from the device's default path (eg/flash
,/
). Use-v/--verbose
to see the files being removed.中断の例:
mpremote rm -r :libs
will remove thelibs
directory and all its child items from the device.mpremote rm -rv :/sd
will remove all files from a mounted SDCard and result in a non-blocking warning. The mount will be retained.mpremote rm -rv :/
will remove all files on the device, including any located in mounted vfs such as/sd
or/flash
. After removing all folders and files, this will also return an error to mimic unixrm -rf /
behaviour.
警告
There is no supported way to undelete files removed by
mpremote rm -r :
. Please use with caution.All other commands implicitly assume the path is a remote path, but the
:
can be optionally used for clarity.ファイルシステムのサブコマンドはすべて複数のパス引数を取るので、もしコマンドライン中に別のコマンドがある場合は、引数を終了させるために
+
を使う必要があります。たとえば次のように使います。$ 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>
これは、ローカルホストディレクトリを、あたかもリモートデバイスのファイルシステムのように扱えるようにできます。これは開発時に便利で、作業中にファイルをデバイスにコピーする必要をなくせます。
デバイスはファイルシステムドライバをインストールし、デバイスの device VFS に
/remote
としてマウントし、mpremote
へのシリアル接続をサイドチャネルとして使ってファイルにアクセスします。デバイスのカレント作業ディレクトリは(os.chdir
によって)/remote
に設定され、マウントがアクティブな間はデフォルトのファイルシステムのパスではなく、インポートやファイルアクセスがそこで行われるようになります。注記:
mount
コマンドの後に他のアクションが続かない場合、repl
コマンドが暗黙のうちにコマンドラインの最後に追加されます。使用中に Ctrl-D を入力すると、ソフトリブートを行い、通常は自動的にマウントを再接続します。しかし、起動時に main.py が実行されている場合、再マウントは行われません。この場合、raw モードのソフトリブートを使えます。Ctrl-A Ctrl-D でリブート、Ctrl-B で通常のリプレイに戻り、マウントの準備ができます。
オプションは次のとおりです:
-l
,--unsafe-links
: デフォルトではデバイスがマウントされているローカルディレクトリの外側(1つ以上のディレクトリレベル)にあるファイルやディレクトリにアクセスすると、エラーが発生します。このオプションは、シンボリックリンクのチェックを無効にし、デバイスがローカルディレクトリの外側のシンボリックリンクをたどることを可能にします。
unmount -- リモートデバイスからローカルディレクトリをアンマウント:
$ mpremote umount
これは
mpremote
の終了時に自動的に行われますが、後続のコマンドを実行する前に、以前のマウントをアンマウントする用途でコマンドライン中でも使えます。
romfs -- manage ROMFS partitions on the device:
$ 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
これはデバイスのブートローダに入ります。ブートローダはポートやボードに依存します(例: stm32 の DFU、rp2040/Pico の UF2)。
自動接続とソフトリセット¶
接続と切断は、コマンドに明示的に指定されていなければ、ツールの実行開始時と終了時に自動的に行われます。自動接続では、最初に利用可能な 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>
のエイリアス
追加のショートカットは .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", # IDで指定したデバイスに接続。
"bl": "bootloader", # bootloader の短縮エイリアス。
"double x=4": "eval x*2", # x はデフォルト 4 の引数
"wl_scan": ["exec", """
import network
wl = network.WLAN()
wl.active(1)
for ap in wl.scan():
print(ap)
""",], # 近くの WiFi ネットワークを表示。
"wl_ipconfig": [
"exec",
"import network; sta_if = network.WLAN(network.WLAN.IF_STA); print(sta_if.ipconfig('addr4'))",
""",], # ステーションインタフェースの IP アドレスを表示。
"test": ["mount", ".", "exec", "import test"], # カレントディレクトリをマウントして、test.py を実行。
"demo": ["run", "path/to/demo.py"], # デバイスで demo.py を実行。
}
サンプル¶
mpremote
最初に見つかったデバイスに接続し、暗黙に repl
コマンドを実行します。
mpremote a1
/dev/ttyACM1
(Linux) のデバイスに接続し、暗黙に repl
コマンドを実行します。上記の ショートカット を参照してください。
mpremote c1
COM1
(Windows) のデバイスに接続し、暗黙に repl
コマンドを実行します。上記の ショートカット を参照してください。
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
デバイスをハードリセットし、使えるようになるまで 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 を実行します。
これは、1つのファイルを更新してからプログラムを再スタートさせる一般的な開発ワークフローです。このシナリオでは、デバイス上の main.py
でも import app.py
を実行しています。
mpremote cp utils/driver.py :utils/driver.py + soft-reset repl
デバイス上の utils/driver.py のコピーを更新し、ソフトリセットしてプログラムを再起動し、 repl
コマンドで出力をモニターします。
mpremote cp -r utils/ :utils/ + soft-reset repl
1つ前のものと同じですが、最初に 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
1つ前のものと同じですが、 Ctrl-K
が押されるたびに REPL でローカルファイル demo.py
の内容を実行します。1つ前のものと同様に、最初に 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
ディレクトリにインストールします。パッケージ管理 を参照してください。