このドキュメンテーションは、MicroPython の最新開発ブランチのためのものです。 リリースバージョンでは利用できない機能に言及することがあります。

特定のリリースのドキュメントをお探しの場合は、左側のドロップダウンメニューを使って、 望みのバージョンを選択します。

MicroPython のリモート制御: mpremote

mpremote コマンドラインツールは、シリアル接続を介して MicroPython デバイスをリモート操作、ファイルシステム管理、自動化するための統合されたユーティリティセットを提供します。

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

$ pip install --user mpremote

pipx を使ってもインストールできます:

$ pipx install mpremote

このツールを使う最も簡単な方法は、引数なしで起動することです:

$ mpremote

このコマンドは、最初に利用可能な USB シリアルデバイスを自動的に検出して接続し、REPL アクセスとプログラムの出力先となる対話ターミナルを使える状態にします。シリアルポートはエクスクルーシブモードで開かれるので、 mpremote の２番目(さらに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

• disconnect

• resume

• soft_reset

• repl

• eval

• exec

• run

• fs

• df

• edit

• mip

• mount

• unmount

• romfs

• rtc

• sleep

• reset

• bootloader

• connect -- 指定した名前のデバイスに接続:

  $ mpremote connect <device>
  

  <device> は以下のいずれかです:

  • list: 利用可能なデバイスのリスト

  • auto: connect to the first available USB serial port

  • id:<serial>: USB シリアル番号 <serial> (connect list コマンドで出力される２番目の項目)を持つデバイスに接続

  • port:<path>: 指定したパス(connect list コマンドで出力される１番目の項目)を持つデバイスに接続

  • 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 the libs 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 unix rm -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 を実行します。

これは、１つのファイルを更新してからプログラムを再スタートさせる一般的な開発ワークフローです。このシナリオでは、デバイス上の 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

１つ前のものと同じですが、最初に 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 が押されるたびに 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 で指定されたブランチからパッケージを端末にインストールします。 パッケージ管理 を参照してください。

mpremote mip install gitlab:org/repo@branch

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

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

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