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

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

パッケージ管理

mip によるパッケージのインストール

ネットワークに対応したボードには micropython-lib とサードパーティのサイト(GitHub や GitLab)からパッケージをインストールできる mip モジュールがあります。

mip ("mip installs packages")は、Python の pip ツールとコンセプトが同じものですが、PyPI インデックスを使わず、デフォルトのインデックスとして micropython-lib を使います。 mip は micropython-lib からダウンロードする際に、コンパイルされた .mpy ファイル を自動的に取得します。

mip を使う最も一般的な方法は REPL からです:

>>> import mip
>>> mip.install("pkgname")  # "pkgname" (と依存するもの)の最新バージョンをインストール
>>> mip.install("pkgname", version="x.y")  # "pkgname" のバージョン x.y をインストール
>>> mip.install("pkgname", mpy=False)  # ソース版 (つまり .mpy ではなく .py ファイル)をインストール

mip は /lib で終わる最初のエントリを sys.path から検索することにより、ファイルシステム上のインストール場所を適切に検出します。 target を使ってインストール場所を上書きすることもできますが、後でインポートできるようにするには上書きしたパスが sys.path にあるようにしておく必要があります:

>>> mip.install("pkgname", target="third-party")
>>> sys.path.append("third-party")

mip は micropython-lib インデックスからパッケージをダウンロードするだけでなく、サードパーティのライブラリもインストールできます。最も簡単な方法は、直接ファイルをダウンロードすることです:

>>> mip.install("http://example.com/x/y/foo.py")
>>> mip.install("http://example.com/x/y/foo.mpy")

ファイルを直接インストールする場合でも target 引数をサポートしていますが、 mpy と version 引数は無視します。

The URL can also start with github: or gitlab: as a simple way of pointing to content hosted on GitHub or GitLab:

>>> mip.install("github:org/repo/path/foo.py")  # デフォルトブランチを使用
>>> mip.install("github:org/repo/path/foo.py", version="branch-or-tag")  # ブランチまたはタグを指定するオプション
>>> mip.install("gitlab:org/repo/path/foo.py")  # デフォルトブランチを使用
>>> mip.install("gitlab:org/repo/path/foo.py", version="branch-or-tag")  # ブランチまたはタグを指定するオプション

より複雑なパッケージ(つまり、複数のファイルまたは依存関係を持つパッケージ)は、その package.json へのパスを指定することでダウンロードできます。

>>> mip.install("http://example.com/x/package.json")
>>> mip.install("github:org/user/path/package.json")
>>> mip.install("gitlab:org/user/path/package.json")

json ファイルが指定されていない場合、 "package.json" が暗黙的に追加されます。

>>> mip.install("http://example.com/x/")
>>> mip.install("github:org/repo")  # デフォルトのブランチを使用
>>> mip.install("github:org/repo", version="branch-or-tag")
>>> mip.install("gitlab:org/repo")  # デフォルトのブランチを使用
>>> mip.install("gitlab:org/repo", version="branch-or-tag")

Unixポートでの mip の使い方

Unix ポートでは上記のように REPL で mip を使えます。また -m でも使えます:

$ ./micropython -m mip install pkgname-or-url
$ ./micropython -m mip install pkgname-or-url@version

--target path 、 --no-mpy 、 --index 引数を指定できます:

$ ./micropython -m mip install --target third-party pkgname
$ ./micropython -m mip install --no-mpy pkgname
$ ./micropython -m mip install --index https://host/pi pkgname

mpremote を使ったパッケージのインストール

mpremote ツールには mip と同様の機能があり、ホストPCからローカルに(USB または UART などで)接続されたデバイスにパッケージをインストールするために使えます:

$ mpremote mip install pkgname
$ mpremote mip install pkgname@x.y
$ mpremote mip install http://example.com/x/y/foo.py
$ mpremote mip install github:org/repo
$ mpremote mip install github:org/repo@branch-or-tag
$ mpremote mip install gitlab:org/repo
$ mpremote mip install gitlab:org/repo@branch-or-tag

--target=path 、 --no-mpy 、 --index 引数を指定できます:

$ mpremote mip install --target=/flash/third-party pkgname
$ mpremote mip install --no-mpy pkgname
$ mpremote mip install --index https://host/pi pkgname

mpremote は、ホストのローカルファイルシステムに保存されているファイルからもパッケージをインストールできます。

$ mpremote mip install path/to/pkg.py
$ mpremote mip install path/to/app/package.json
$ mpremote mip install \\path\\to\\pkg.py

これは特に、開発中のパッケージのテストや GitHub リポジトリのローカルクローンからパッケージをインストールする際に便利です。なお package.json ファイル内の URL では、Windows 上でもディレクトリの区切りとしてスラッシュ("/")を使う必要があります。これは Web からのインストールとの互換性を確保するためです。

手動でのパッケージのインストール

パッケージのインストールは、(.py または .mpy 形式のいずれかの)ファイルを手動でデバイスにコピーすることでも可能です。ボードによって、USB Mass Storage 、mpremote ツール(たとえば mpremote fs cp path/to/package.py :package.py)、 webrepl などを介してコピーできます。

パッケージの作成と公開

micropython-lib に公開することは、MicroPython ユーザーに広くアクセス可能にする最も簡単な方法であり、 mip や mpremote から自動的に利用可能になり、バイトコードにコンパイルされます。詳細については https://github.com/micropython/micropython-lib を参照してください。

mip または mpremote からダウンロードできる "self-hosted" パッケージを作成するには、静的Webサーバー(または GitHub)を用意して、単一の .py ファイル、または複数の .py ファイルと一緒にした package.json ファイルをホストする必要があります。

GitHub にホストされている mlx90640 ライブラリの例は、次のようにインストールできます:

$ mpremote mip install github:org/micropython-mlx90640

GitHub 上のパッケージのレイアウトは次のようになります:

https://github.com/org/micropython-mlx90640/
    package.json
    mlx90640/
        __init__.py
        utils.py

package.json には、インストールするファイルの場所や他の依存関係を指定します:

{
  "urls": [
    ["mlx90640/__init__.py", "mlx90640/__init__.py"],
    ["mlx90640/utils.py", "mlx90640/utils.py"]
  ],
  "deps": [
    ["collections-defaultdict", "latest"],
    ["os-path", "latest"],
    ["github:org/micropython-additions", "main"],
    ["gitlab:org/micropython-otheradditions", "main"]
  ],
  "version": "0.2"
}

urls リストには、次にしたがってインストールするファイルを指定します:

"urls": [
    [destination_path, source_url]
    ...

destination_path には、デバイス上にインストールするファイルの保存場所および名前を指定します。 source_url にはインストールするファイルの URL を指定します。通常、source_url は package.json ファイルを含むディレクトリからの相対パスとして指定しますが、絶対URL(例: https://example.com/path/to/file.py)でも指定できます。

["mlx90640/utils.py", "github:org/micropython-mlx90640/mlx90640/utils.py"]

このパッケージは collections-defaultdict と os-path に依存しており、これらは micropython-lib から自動的にインストールされます。3つ目の依存関係は、GitHub リポジトリ org/micropython-additions の main ブランチの package.json ファイルで定義されている内容をインストールします。

パッケージの凍結

Python のモジュールやパッケージをデバイスのファイルシステムからインポートすると、VMで実行できるように RAM 上で バイトコード にコンパイルされます。 .mpy ファイル の場合、この変換はすでに行われていますが、それでもバイトコードは RAM 上にあります。

小メモリのデバイスや大規模なアプリケーションでは、バイトコードを ROM (フラッシュメモリ)から実行する方が有利です。これは、バイトコードを MicroPython ファームウェアに「凍結」してから、デバイスにフラッシュすることで実現できます。ランタイムパフォーマンスは同じですが(ただし、インポートはより高速です)、プログラムが使う RAM を大幅に解放できます。

このアプローチの欠点は、パッケージを変更たびにファームウェアをフラッシュしなければならないので開発がはるかに遅くなることですが、頻繁に変更されない依存パッケージを凍結することは依然として有用です。

マニフェストファイルを作成して、それをビルドで使うことで、通常はカスタムボード定義の一部として凍結を行います。詳細については MicroPython マニフェストファイル のガイドを参照してください。