これは MicroPython バージョン v1.27.0 のドキュメンテーションです。 このページの最新開発版 の方が、より新しい内容になっています。

クラス USBDevice -- USB デバイスドライバー

注釈

machine.USBDevice は現在のところ esp32, rp2, samd ポートのみでサポートしています。ネイティブの USB サポートが必要となりますが、すべてのボードがネイティブで USB をサポートしているわけではありません。

USBDevice は、Python コードで USB デバイス機能を実装するための低レベル Python API を提供します。

警告

この低レベル API は、USB 標準に精通していることを前提としています。高レベル API である usb driver modules in micropython-lib があり、より簡単なインターフェースとより多くの組み込み機能を提供しています。

用語

  • 「ランタイム」 - USB デバイスインタフェースまたはドライバーは、MicroPython の初期スタートアップの後、この Python API を使って定義されるものです。

  • 「組込み」 - USB デバイスインタフェースまたはドライバーは、MicroPython ファームウェアにコンパイルされ、常に利用可能です。例としては、通常デフォルトで有効になっている USB-CDC (シリアルポート)があります。組み込み USB-MSC (マスストレージ)は一部のポートでオプションとして利用できます。

ライフサイクル

ランタイム USB インタフェース を管理するのは難しい場合があり、特に同じ USB デバイスの一部である組込み USB-CDC シリアルポートを介して MicroPython と通信している場合がそうです。

  • MicroPython の ソフトリセット は常にすべてのランタイム USB インタフェースをクリアし、結果として USB デバイス全体がホストから切断されます。MicroPython が組み込みの USB-CDC シリアルポートも提供している場合、これはソフトリセット後に再び現れます。

    これは、ランタイム USB インタフェースがアクティブな場合、USB-CDC シリアルポートを対象とする一部の機能(たとえば mpremote run など)が、すぐに失敗する可能性があることを意味します。なぜなら mpremote がソフトリセットをトリガーするとポートが消えるからです。ソフトリセット後はもはやランタイム USB インタフェースが存在しないため、2回目の試行で操作が成功するはずです。

  • 起動時にランタイム USB デバイスを設定するには、構成コードを デバイスの VFS 上の boot.py ファイルに配置することが推奨されます。各リセット時にこのファイルは USB サブシステムが初期化される前(および main.py の前に)に実行されます。したがって、ボードを即座にランタイム USB デバイスで起動できます。

  • 開発またはデバッグのために、ハードウェアシリアル REPL を接続して組込み USB-CDC シリアルポートを完全に無効にすることが便利なこともあります。すべてのポートがこれをサポートしているわけではありません(現在は rp2 のみ)。カスタムビルドは #define MICROPY_HW_USB_CDC (0) と #define MICROPY_HW_ENABLE_UART_REPL (1) で構成する必要があります。

コンストラクタ

class machine.USBDevice

USBDevice オブジェクトを構築します。

注釈

このオブジェクトはシンゲルトンです。このコンストラクタを呼び出すたびに同じオフジェクトへの参照を返します。

メソッド

USBDevice.config(desc_dev, desc_cfg, desc_strs=None, open_itf_cb=None, reset_cb=None, control_xfer_cb=None, xfer_cb=None)

USBDevice のシンゲルトンオブジェクトを USB ランタイムデバイスの状態とコールバック関数で構成します:

  • desc_dev - 新しい USB デバイス記述子(USB Device Descriptor)の値を含むバイト列ライクなオブジェクト。

  • desc_cfg - 新しい USB 構成記述子(USB Configuration Descriptor)を含むバイト列ライクなオブジェクト。

  • desc_strs - USB 文字列記述子(USB String Descriptor)を含む文字列またはバイト列オブジェクトの値を持つオプションのオブジェクト。

    リスト、辞書、整数型のキー(USB 文字列記述子インデックス)を持つ任意のオブジェクトを指定できます。

    文字列はオプションの USB 特性であり、デバイス記述子と構成記述子で参照されていない場合、または組込み文字列のみを使用する場合、このパラメータを設定解除できます(デフォルト)。

    インデックス 0 以外のすべての文字列値はプレーンな ASCII である必要があります。インデックス 0 は特別な "languages" USB記述子であり、USB 標準で定義されたカスタムフォーマットを持つバイト列オブジェクトとして表されます。デフォルトの "English" 言語記述子を使うためには、インデックス 0 で None を返す必要があります。

    特定のインデックスのために組み込みの文字列値を提供するようフォールバックするには、添字によるルックアップが None を返すか、 KeyError を発生させるか、 IndexError を発生させるかのいずれかです。

  • open_itf_cb - このコールバックは、USB ホストからの Set Configuration リクエストに応答して、USB デバイスがホストに利用可能になる直前の最終段階で、各インタフェースまたはインタフェース関連記述子ごとに1回呼び出されます。

    このコールバックは、ホストが受け入れているインタフェースまたは IAD 記述子のメモリビュー(関連するすべての記述子を含む)を単一の引数として取ります。これは、この関数に個別の引数として提供された同じ desc_cfg オブジェクトへのビューです。メモリビューは、コールバック関数が戻るまでの間のみ有効です。

  • reset_cb - このコールバックは、USBホストがバスリセットを実行するときに呼び出されます。このコールバックは引数を取りません。進行中の転送は完了しません。USB ホストはたいてい、ディスクリプタコールバックおよびその後 open_itf_cb() を呼び出すことによってUSBデバイスを再列挙します。

  • control_xfer_cb - このコールバックは、各 USB コントロール転送(デバイスエンドポイント 0)ごとに1回以上呼び出されます。2つの引数を取ります。

    第１引数は、コントロール転送のステージです。次のいずれかです:

    • 1: SETUP ステージ

    • 2: DATA ステージ

    • 3: ACK ステージ

    第2引数は、このステージの USB コントロールリクエストデータを読み込むためのメモリビューです。メモリビューは、コールバック関数が戻るまでの間のみ有効です。このメモリビュー内のデータは、単一転送の3つのステージで同一です。

    成功した転送は、このコールバックが3つのステージに対して順次呼び出されることで成り立ちます。一般的に、デバイスが制御要求に応答して何かを行う場合、ホストコントローラーが転送を期待通りに完了したことを確認するために、ACKステージまで待つのが最善です。

    コールバックは、次のいずれかの値を返す必要があります:

    • エンドポイントをストールして転送を拒否するためには False を返します。これにより残りのステージには進まなくなります。

    • 次のステージに転送を継続するためには True を返します。

    • 転送が追加のデータを送信または受信する場合、SETUP ステージでバッファオブジェクトを返せます。これはリクエストの wLength フィールドがゼロ以外の値を持つ場合に発生します。 OUT 方向の転送の場合は書出し可能なバッファである必要がありますし、 IN 方向の転送の場合はデータを持つ読込み可能なバッファである必要があります。

  • xfer_cb - このコールバックは USBDevice.submit_xfer() を呼び出して送信された非制御転送が完了するたびに呼び出されます。

    コールバックには3つの引数があります:

    1. 完了した転送のエンドポイント番号。

    2. 結果値: 転送が成功した場合は True 、それ以外は False 。

    3. 成功したバイト数。 "short" 転送の場合、結果は True であり、 xferred_bytes は転送のために提出されたバッファの長さよりも小さくなります。

    注釈

    バスのリセットが発生した場合(USBDevice.reset() を参照)、 xfer_cb がまだ完了していない転送に対しては呼び出されません。

USBDevice.active(self, [value] /)

このランタイム USB デバイスの現在のアクティブ状態を真偽値として返します。USB ランタイムデバイスは、ホストとのやり取りが可能な場合に「アクティブ」ですが、USB ホストが実際に存在していることを意味するわけではありません。

オプションの value 引数が真の値に設定されている場合、USBデバイスはアクティブになります。

オプションの value 引数が偽の値に設定されている場合、USB デバイスは非アクティブになります。USBデバイスが非アクティブの間は、USB ホストによって検出されません。

USB デバイスの切断と再接続をシミュレートするには active(False) を呼び出してから active(True) を呼び出します。これは、ランタイムデバイスの構成が変更された場合、すなわちホストが新しいデバイスを認識した場合に、必要な場合があります。

USBDevice.builtin_driver

この属性は、現在の組み込みドライバー構成を保持し、このオブジェクトで定義された USBDevice.BUILTIN_ 名前付き定数のいずれかに設定する必要があります。

デフォルトでは USBDevice.BUILTIN_NONE の値が保持されます。

ランタイム USB デバイスは、このフィールドを設定するときに非アクティブでなければなりません。設定が必要な場合(設定後に再度アクティブにする)には、設定する前に USBDevice.active() 関数を呼び出して非アクティブにしてください。

この値が USBDevice.BUILTIN_NONE 以外の値に設定されている場合、次の制限が USBDevice.config() の引数に適用されます:

  • desc_cfg は USBDevice.builtin_driver 属性 desc_cfg を介してアクセス可能な組込み USB インタフェース記述子データで始まる必要があります。組込み構成記述子の後に追加される記述子は USBDevice.builtin_driver 属性 itf_max, str_max, ep_max で定義された最大組込み値を開始として、インタフェース、文字列、エンドポイント番号を使用する必要があります。

  • desc_cfg の末尾に新しいインターフェースが追加された場合、組込み構成記述子内の bNumInterfaces フィールドも更新する必要があります。

  • desc_strs は None または USBDevice.builtin_driver.str_max よりも小さいインデックス値が欠落しているか、値が None であるリスト/辞書である必要があります。これにより、これらの文字列インデックスが組み込みドライバー用に予約されます。これらのインデックスのいずれかに異なる文字列を配置すると、組込みドライバーのその文字列がオーバーライドされます。

USBDevice.remote_wakeup(self)

ホストがサスペンドモードにあり、リモートウェイクアップ機能がホストによって有効にされている場合、ホストを起動します。これはUSB属性で有効にし、ホスト側でも有効にする必要があります。リモートウェイクアップが有効でアクティブであり、ホストが起動された場合は True を返します。

USBDevice.submit_xfer(self, ep, buffer /)

エンドポイント番号 ep に対してUSB転送を送信します。 buffer は IN エンドポイントに対して読込みアクセスを持ち、 OUT エンドポイントに対して書出しアクセスを持つバッファインタフェースを実装するオブジェクトでなければなりません。

注釈

ep は制御エンドポイント番号0にすることはできません。制御転送は control_xfer_cb を連続して実行することによって構築されます(上記を参照)。

成功した場合は True を返し、転送をキューに入れることができなかった場合は False を返します(USB デバイスがホストによって構成されていないか、このエンドポイントに別の転送がキューに入れられているため)。

USB ホストが転送を完了すると xfer_cb コールバックが呼び出されます(上記を参照)。

USB デバイスがアクティブでない場合 OSError が発生し、理由として MP_EINVAL が指定されます。

USBDevice.stall(self, ep, [stall] /)

この関数を呼び出すと、デバイスのエンドポイントの STALL 状態を取得または設定します。

ep はエンドポイントの番号です。

オプションの stall パラメータが設定されている場合、これは STALL 状態のブールフラグです。

戻り値は、この関数によって行われた変更前のエンドポイントの現在の stall 状態です。

STALL に設定されたエンドポイントは、この関数が再度呼び出されるか、USBホストによって自動的にクリアされるまで、STALL のままである可能性があります。

USB デバイスがアクティブでない場合 OSError が発生し、理由として MP_EINVAL が指定されます。

定数

USBDevice.BUILTIN_NONE
USBDevice.BUILTIN_DEFAULT
USBDevice.BUILTIN_CDC
USBDevice.BUILTIN_MSC
USBDevice.BUILTIN_CDC_MSC

これらの定数オブジェクトは、MicroPython ファームウェアにコンパイルされた組み込みディスクリプタデータを保持します。 USBDevice.BUILTIN_NONE と USBDevice.BUILTIN_DEFAULT は常に存在します。ファームウェアのビルド構成と実際の組み込みドライバによって、追加のオブジェクトが存在する場合があります。

注釈

現在 USBDevice.BUILTIN_CDC, USBDevice.BUILTIN_MSC, USBDevice.BUILTIN_CDC_MSC のいずれか1つが定義され、 USBDevice.BUILTIN_DEFAULT と同じオブジェクトになります。これらの定数は、(もしあれば)組み込みドライバをランタイムで検出するために定義されています。将来的には、複数の組み込みドライバ構成のうちの1つを選択するサポートが追加されるかもしれません。

これらの値は、組み込み構成を取得/設定するために USBDevice.builtin_driver に割り当てられます。

各オブジェクトには、次の読込み専用フィールドが含まれています:

  • itf_max - 組込み構成記述子で使用されるbInterfaceNumber値の最大値より1大きい値。

  • ep_max - 組込み構成記述子で使用される bEndpointAddress 値の最大値より1大きい値。 IN フラグビット(0x80)は含まれません。

  • str_max - 任意の組込み記述子で使用される最大の文字列記述子インデックス値より1大きい値。

  • desc_dev - 組込み USB デバイス記述子を含むbytesオブジェクト。

  • desc_cfg - 完全な組込み USB 構成記述子を含む bytes オブジェクト。