Welcome to pyusb's documentation!¶

PyUSB 1.0 - Pythonからの容易なUSBアクセス¶

はじめに¶

PyUSBモジュールは、ホストマシンのユニバーサルシリアルバス(USB)システムへのPythonからの容易なアクセスを提供します。

0.4バージョンまで、PyUSBはlibusbの薄いラッパーでした。 1.0バージョンでは、状況が大幅に変更されています。PyUSBは、APIが豊富で、バックエンドに依存せず容易にに使えるPythonUSBモジュールです。

ほとんどのPythonモジュールと同様に、PyUSBのドキュメントはPython docstringに基づいているため、pydocなどのツールで操作できます。

チュートリアルもご覧ください docs/tutorial.rst

PyUSBはLinuxとWindowsで開発およびテストされています。Python>= 3.6 かつ ctypes かつ組み込みバックエンドの少なくとも1つが走るすべてのプラットフォームで正常に動作するはずです。

PyUSBはlibusb 1.0、libusb 0.1、OpenUSBをサポートしています。一部の特別な場合を除いて、ユーザーはそのことを気にする必要はありません。

あなたがPyUSBについて質問がある場合は、 docs/faq.rst のFAQまたはSourceForgeでホストされているPyUSBメーリングリストを参照してください。 PyUSB website で、メーリングリストに登録する方法の説明を見つけることができます。

インストール¶

PyUSBは pip でインストールします:

pip install pyusb

あなたのシステムではlibusb(1.0または0.1)またはOpenUSBをが走っている必要があることに注意してください。 Windowsユーザーの場合、libusb 1.0 DLLは releases で提供されます(7zアーカイブを参照)。libusb Webサイトで更新を確認してください( http://www.libusb.info )。 MacOSユーザーの場合 brew install libusb が正しく実行するために必要です。

PyUSB 1.0 を使ってプログラミング¶

手前味噌ですが…¶

PyUSB 1.0は、容易なる USB アクセスを可能にする Python ライブラリです。 PyUSBはいくつかの機能を提供します:

100% Python で書かれています:: Cで記述された0.xバージョンとは異なり、1.0バージョンはPythonで記述されています。これにより、CのバックグラウンドがないPythonプログラマーはPyUSBがどのように機能するかをよりよく理解できます。
特定のプラットフォームに偏らず、中立です:: 1.0バージョンは、フロントエンド-バックエンドスキーム実装です。これにより、システム固有の実装の詳細とAPIが分離されています。 2つの層の間の接着剤は IBackend インターフェースです。 PyUSBには、libusb 1.0、libusb 0.1、OpenUSB用の組み込みバックエンドが付属しています。必要に応じて、独自のバックエンドを作成することもできます。
ポータビリティ:: PyUSBは、Python>=3.6 かつ ctypes かつサポートされている組み込みバックエンドの少なくとも1つを備えたすべてのプラットフォームで実行可能です。
最強に簡単:: USB デバイスとの通信がこれまでになく簡単になりました。 USBは複雑なプロトコルですが、PyUSBにはほとんどの一般的な構成に適したデフォルトの構成があります。
アイソクロナス転送(isochronous transfers)のサポート:: 基礎となるバックエンドがアイソクロナス転送(isochronous transfers)をサポートしている場合、PyUSBはアイソクロナス(isochronous transfers)転送をサポートします。

PyUSBはUSBプログラミングの苦痛を軽減しますが、このチュートリアルでは、最小限のUSBプロトコルの予備知識があることを前提としています。 USBについて何も知らない場合は、優れたJan Axelsonの著書 USB Complete をお勧めします。(訳注: USB Complete: The Developer's Guide (Complete Guides series) (English Edition) https://www.amazon.co.jp/dp/B00U58R0FA/ 日本語版もあるが版数が古そう)

もうお話は充分、さぁコーディングしましょう！¶

紳士録¶

まず、PyUSBモジュールの概要を説明します。 PyUSBモジュールは usb パッケージの下にあり、以下のモジュールがあります:

モジュール	説明
core	メイン USB モジュール。
util	ユーティリティ関数。
control	Standard control requests.
legacy	バージョン 0.x 系互換レイヤ。
backend	組み込みのバックエンドを含むサブパッケージ。

たとえば、coreモジュールをインポートするには、次のように入力します:

>>> import usb.core
>>> dev = usb.core.find()

それじゃあ初めましょう¶

以下は、見つかった最初のOUTエンドポイント(OUT endpoint)に 'test' 文字列を送信する単純際まわりないプログラムです:

import usb.core
import usb.util

# find our device
dev = usb.core.find(idVendor=0xfffe, idProduct=0x0001)

# was it found?
if dev is None:
    raise ValueError('Device not found')

# set the active configuration. With no arguments, the first
# configuration will be the active one
dev.set_configuration()

# get an endpoint instance
cfg = dev.get_active_configuration()
intf = cfg[(0,0)]

ep = usb.util.find_descriptor(
    intf,
    # match the first OUT endpoint
    custom_match = \
    lambda e: \
        usb.util.endpoint_direction(e.bEndpointAddress) == \
        usb.util.ENDPOINT_OUT)

assert ep is not None

# write the data
ep.write('test')

最初の2行でPyUSBパッケージモジュールをインポートします。 usb.core がメインモジュールで、 usb.util はユーティリティ関数です。その次の命令はデバイスを検索し、見つかった場合はインスタンスオブジェクトを返します。なければ None が返されます。その後、使用する構成(configuration)を設定します。必要な構成(configuration)を示す引数が指定されていないことに注意してください。ご覧のとおり、多くのPyUSB関数には、ほとんどの一般的なデバイスのデフォルトがあります。この場合、その構成セット(configuration set)は最初に見つかったものです。

次に、私たちが関心のあるエンドポイント(endpoint)を探します。私たちは最初のインターフェース(interface)内で検索します。エンドポイント(endpoint)を見つけたら、データをエンドポイント(endpoint)に送信します。

私たちがエンドポイントアドレス(endpoint address)を事前に知っている場合は、デバイス(device)オブジェクトから write 関数を呼び出すだけです。

dev.write(1, 'test')

ここでは、私たちはエンドポイントアドレス(endpoint address) 1 に文字列 'test' を書き込みます。これらすべての機能については、次節で詳しく説明します。

問題は何？¶

エラー発生時、PyUSBの全ての関数は1つの例外を発生させます。Python標準例外に加えて、PyUSBはUSB関連エラーの usb.core.USBError を定義しています。

あなたはPyUSBログ機能を使用することもできます。 logging モジュールを使用します。これを有効にするには、環境変数 PYUSB_DEBUG をレベル名 critical、 error、 warning、info、 debug のいずれかで定義します。

デフォルトでは、メッセージは sys.stderr に送信されます。必要に応じて、 PYUSB_LOG_FILENAME 環境変数を定義することで、ログメッセージをファイルにリダイレクトできます。その値が有効なファイルパスである場合、メッセージはそれに書き込まれ、そうでない場合は、 sys.stderr に送信されます。

あなたはそこにいますか？¶

core モジュールの find() 関数は、システムに接続されたデバイスを見つけて列挙するために使用されます。たとえば、デバイスのvendor ID(ベンダーID)が 0xfffe 、 product ID(製品ID)が 0x0001 であるとします。それを探したい場合は、次のように進めます:

import usb.core

dev = usb.core.find(idVendor=0xfffe, idProduct=0x0001)
if dev is None:
    raise ValueError('Our device is not connected')

以上で、関数はデバイスを表す usb.core.Device オブジェクトを返します。デバイスが見つからない場合、 None を返します。実際には、デバイス・デスクリプタ( Device Descriptor )の任意のフィールドを使用できます。たとえば、システムにUSBプリンターが接続されているかどうかを確認するにはどうすればよいでしょうか。これはとても簡単です:

# actually this is not the whole history, keep reading
if usb.core.find(bDeviceClass=7) is None:
    raise ValueError('No printer found')

7は、USB仕様によるプリンタークラスのコードです。ちょっと待てや！存在するすべてのプリンターを列挙したい場合はどうなりますか？問題ありません:

# this is not the whole history yet...
printers = usb.core.find(find_all=True, bDeviceClass=7)

# Python 2, Python 3, to be or not to be
import sys
sys.stdout.write('There are ' + len(printers) + ' in the system\n.')

何が起きたのでしょう？少々説明する時がきたようです。 find には find_all というパラメータがあり、デフォルトはFalseです。 false 1 の場合、 find は指定された基準に一致する最初に見つかったデバイスを返します(詳細はもうちょい後で)。もしあなたが true の値を与えると、 find は代わりに基準に一致するすべてのデバイスのイテレータを返します。以上です！簡単でしょ？

これで終わり？いいえ。私はあなたにすべての歴史を話したわけではありません。多くのデバイスは実際にはクラス情報をデバイス・デスクリプタ( Device Descriptor )ではなくインターフェイス・デスクリプタ( Interface Descriptor )に入れます。したがって、システムに接続されているすべてのプリンターを本当に見つけるには、すべての構成、次にすべてのインターフェイスを渡り歩き、いずれかのインターフェイスの bInterfaceClass フィールドが7に等しいかどうかを確認する必要があります。私のようなプログラマーなら、もっと簡単な方法があるのか疑問に思うでしょう。もちろん答えはYES。まず、接続されているすべてのプリンターを見つけるための最終的なコードを見てみましょう。

import usb.core
import usb.util
import sys

class find_class(object):
    def __init__(self, class_):
        self._class = class_
    def __call__(self, device):
        # first, let's check the device
        if device.bDeviceClass == self._class:
            return True
        # ok, transverse all devices to find an
        # interface that matches our class
        for cfg in device:
            # find_descriptor: what's it?
            intf = usb.util.find_descriptor(
                                        cfg,
                                        bInterfaceClass=self._class
                                )
            if intf is not None:
                return True

        return False

printers = usb.core.find(find_all=1, custom_match=find_class(7))

custom_match パラメータは、デバイスオブジェクトを受け取る呼び出し可能なオブジェクトを受け入れます。一致するデバイスの場合はtrueを返し、一致しないデバイスの場合はfalseを返す必要があります。必要に応じて、 custom_match とデバイスフィールドを組み合わせることもできます:

# find all printers that belongs to our vendor:
printers = usb.core.find(find_all=1, custom_match=find_class(7), idVendor=0xfffe)

今ここでは、0xfffe ベンダーのプリンターのみに関心があります。

お主、何者じゃ！¶

やった！デバイスを見つけました。が、そのデバイス君とお話をする前に、構成、インターフェース、エンドポイント、転送タイプなどについて詳しく知りたいと思います…

あなたがデバイスを持っている場合は、あなたはオブジェクトのプロパティとして任意のデバイス・デスクリプタ・フィールドにアクセスできます:

>>> dev.bLength
>>> dev.bNumConfigurations
>>> dev.bDeviceClass
>>> # ...

デバイスで有効な構成にアクセスするときは、あなたはデバイスを反復処理(iterate)できます:

for cfg in dev:
    sys.stdout.write(str(cfg.bConfigurationValue) + '\n')

同様に、構成を反復(iterate)してインターフェイスにアクセスしたり、インターフェイスを反復(iterate)してエンドポイントにアクセスしたりできます。各種類のオブジェクトには、それぞれのデスクリプタのフィールドが属性として含まれています。例を見てみましょう:

for cfg in dev:
    sys.stdout.write(str(cfg.bConfigurationValue) + '\n')
    for intf in cfg:
        sys.stdout.write('\t' + \
                         str(intf.bInterfaceNumber) + \
                         ',' + \
                         str(intf.bAlternateSetting) + \
                         '\n')
        for ep in intf:
            sys.stdout.write('\t\t' + \
                             str(ep.bEndpointAddress) + \
                             '\n')

次のように、添え字を使用してデスクリプタにランダムにアクセスすることもできます:

>>> # access the second configuration
>>> cfg = dev[1]
>>> # access the first interface
>>> intf = cfg[(0,0)]
>>> # third endpoint
>>> ep = intf[2]

ご覧のとおり、インデックスはゼロベースです。ちょっと待って！私がインターフェイスにアクセスする方法に奇妙な点があります…はい、そうです、構成の添え字は2つのアイテムのシーケンスを受け入れます。最初のアイテムはインターフェイスのインデックスで、2番目のアイテムは代替設定です。したがって、最初のインターフェイスにアクセスするが、2番目の代替設定には、 cfg[(0,1)] と書き込みます。

それでは、デスクリプタを見つける強力な方法である find_descriptor ユーティリティ関数について学びましょう。私たちはプリンター検索の例でそれをすでに見ています。 find_descriptor は find とほぼ同じように動作しますが、2つの例外があります:

find_descriptor は、最初のパラメータとして、あなたが検索したいデスクリプタの親デスクリプタを受け取ります。
backend 2 パラメータはありません。

たとえば、構成デスクリプタ cfg があり、インターフェース1のすべての代替設定を検索したい場合は、次のようにします:

import usb.util
alt = usb.util.find_descriptor(cfg, find_all=True, bInterfaceNumber=1)

find_descriptor は usb.util モジュールにあることに注意してください。また、前述の custom_match パラメータも受け入れます。

同じデバイスを複数扱うには¶

コンピューター同じデバイスが2接続されていることがあります。それらをどのように区別すればよいでしょうか？ Device オブジェクトには、USB仕様の一部ではないが、非常に便利な2つの追加属性があります。それは bus と address 属性です。ただし、これらの属性はバックエンドからのものであり、バックエンドがそれらをサポートしないことは自由です。その場合、それらは None に設定されます。そうじゃない場合は、これらの属性はデバイスのバス番号とバスアドレスを表し、あなたのご想像どおり、同じ idVendor と idProduct 属性を持つ2つのデバイスを区別するために使用できます。

私はどのようにすればいいですか？¶

接続されたUSBデバイスは、いくつかの標準的なリクエストを使って構成する必要があります。私は USB 仕様の調査を始めたとき、デスクリプタ(descriptors)、構成(configurations)、インターフェイス(interfaces)、代替設定(alternate settings)、転送タイプ(trannsfer types)、その他もろもろで混乱していました。そして最悪なことに、たったひとつの構成設定でも無視したら動かないのです。 PyUSBはあなたがこれをできるだけ簡単にできるようにすることを目指します。たとえば、デバイス・オブジェクトを取得した後、それと通信する前に最初に行う必要があることの1つは、 set_configuration リクエストを発行することです。このリクエストのパラメータは、あなたが関心のある構成(configuration)にある bConfigurationValue です。ほとんどのデバイスには構成(configuration)が1つしかなく、使用する構成値を追跡するのは面倒です(私が見たほとんどは単純にハードコーディングしています)。それゆえ PyUSBでは、あなたが引数なしで set_configuration を呼び出すだけで済むようにしてあります。この場合、最初に見つかった構成(configuration)が設定されます(デバイスに1つしかない場合は、その構成値を気にする必要はありません)。たとえば、 bConfigurationValue フィールドが5 3 に等しい構成(configuration)デスクリプタが1つあるデバイスがあるとします。以下の呼び出しはいずれも同様に機能します:

>>> dev.set_configuration(5)
# or
>>> dev.set_configuration() # we assume the configuration 5 is the first one
# or
>>> cfg = util.find_descriptor(dev, bConfigurationValue=5)
>>> cfg.set()
# or
>>> cfg = util.find_descriptor(dev, bConfigurationValue=5)
>>> dev.set_configuration(cfg)

えっへん！ Configuration オブジェクトを set_configuration のパラメータとして使用できます！はい、そしてそれ自身を当座(current)の構成(configuration)として設定するための set メソッドもあります。

構成する必要がある場合と必要ない場合があるもう1つの設定は、インターフェイスの代替設定です。各デバイスは一度に1つのアクティブ化された構成(configration)のみを持つことができ、各構成(configuration)には複数のインターフェイスがあり、すべてのインターフェイスを同時に使用できます。インターフェイスを論理デバイスと考えると、この概念をよりよく理解できます。たとえば、多機能プリンターを想像してみましょう。これは同時にプリンターとスキャナーです。物事をシンプルに(または少なくともできるだけシンプルに)保つために、構成(configuration)が1つしかないと考えてみましょう。プリンターとスキャナーがあるため、構成には2つのインターフェースがあり、1つはプリンター用、もう1つはスキャナー用です。複数のインターフェースを持つデバイスは、複合デバイスと呼ばれます。多機能プリンターをコンピューターに接続すると、オペレーティングシステムは2つの異なるドライバーをロードします。すなわち、あなたがお持ちの「論理」機器ごとに1つです。 4

じゃあ代替設定(alternate setting)の方はどうなの？ええ、インターフェイスには1つ以上の代替設定があります。代替設定が1つしかないインターフェイスは、代替設定がないと見なされます( 5 )。代替設定(alternate setting)はインターフェイス用であり、構成(configuration)はデバイス用です。つまり、各インターフェイス対して、アクティブにできる代替設定(alternate setting)は1つだけです。たとえば、USB仕様では、デバイスのプライマリ代替設定(alternate setting)にアイソクロナス・エンドポイント(isochronous endpoint)を含めることはできないため( 6 ) 、ストリーミングデバイスには少なくとも2つの代替設定(alternate setting)が必要で、2番目の設定にはアイソクロナス・エンドポイント(isochronous endpoint)があります。ただし、構成(configuration)とは異なり、代替設定(alternate setting)が1つだけのインターフェイスを設定する必要はありません( 7 )。 set_interface_altsetting 関数でインターフェイスの代替設定(alternate setting)を選択します:

>>> dev.set_interface_altsetting(interface = 0, alternate_setting = 0)

警告

USB仕様では、追加の代替設定(alternate settings)のないインターフェイスに対するSET_INTERFACEリクエストを受信した場合、デバイスはエラーを返すことが許可されているとされています。したがって、インターフェースに複数の代替設定(alternate settings)があるか、またはSET_INTERFACEリクエストを受け入れるかどうか不明な場合は、次のようにtry-exceptブロック内で set_interface_altsetting を呼び出すのが最も安全な方法です:

try:
    dev.set_interface_altsetting(...)
except USBError:
    pass

あなたは関数のパラメータとして Interface オブジェクトを使用することもでき、その際、 interface と alternate_setting パラメータは bInterfaceNumber と bAlternateSetting フィールドから自動的に推論されます。例えば:

>>> intf = find_descriptor(...)
>>> dev.set_interface_altsetting(intf)
>>> intf.set_altsetting() # wow! Interface also has a method for it

警告

その Interface オブジェクトはアクティブな構成(configuration)デスクリプタに属している必要があります。

私とお話して頂戴¶

いよいよUSBデバイスと通信する方法を学ぶ時が来ました。 USBには、バルク(bulk)と割り込み(interrupt)とアイソクロナス(isochronous)と制御(control)の、4種類の転送方法があります。私は各転送方法の目的とそれらの間の違いを説明するつもりはありません。私は、あなたが少なくともUSB転送の基本を知っているものとして扱います。

制御(control)転送は、仕様に記載されている構造化データを持つ唯一の転送です。他の転送は、USBの観点からは生データを送受信するだけです。そのため、制御(control)転送を処理するためだけに別の関数があり、他のすべての転送は同じ関数によって管理されます。

あなたは ctrl_transfer メソッドを介して制御(control)転送を発行します。それはOUT転送とIN転送の両方に使用されます。転送方向は bmRequestType パラメータによって決定されます。

ctrl_transfer パラメータは制御要求構造(control request structure)とほとんど同じです。以下は、制御(control)転送を行う方法の例です(8):

>>> msg = 'test'
>>> assert dev.ctrl_transfer(0x40, CTRL_LOOPBACK_WRITE, 0, 0, msg) == len(msg)
>>> ret = dev.ctrl_transfer(0xC0, CTRL_LOOPBACK_READ, 0, 0, len(msg))
>>> sret = ''.join([chr(x) for x in ret])
>>> assert sret == msg

この例では、デバイスがループバック・パイプとして機能する2つのカスタム制御要求(custom control request)を実装していると想定しています。 CTRL_LOOPBACK_WRITE メッセージで書き込んだものは、 CTRL_LOOPBACK_READ メッセージで読み取ることができます。

最初の4つのパラメータは、標準制御転送構造(standard control transfer)のフィールド bmRequestType、 bmRequest、 wValue、 wIndex です。 5番目のパラメーター(訳注:data_or_wLength=None)は、OUT転送のデータ・ペイロード、またはIN転送で読み取るバイト数です。データペイロードは、array __init__ メソッドのパラメーターとして使用できる任意のシーケンス型にすることができます。データ・ペイロードがない場合、パラメータは None (またはIN転送の場合は0)でなければなりません。操作のタイムアウトを指定する最後のオプションパラメータ(訳注:timeout=None)が1つあります。指定しない場合は、デフォルトのタイムアウトが使用されます(詳しくは後で説明します)。 OUT転送では、戻り値は実際にデバイスに送信されたバイト数です。IN転送では、戻り値はデータが読み込まれた array オブジェクトです。

他の転送については、メソッド write と read を使用して、データの書き込みと読み取りを行います。転送タイプを気にする必要はありません。転送タイプはエンドポイント・アドレスから自動的に決定されます。エンドポイント1にループバック・パイプがあると想定したループバックの例を以下に示します:

>>> msg = 'test'
>>> assert len(dev.write(1, msg, 100)) == len(msg)
>>> ret = dev.read(0x81, len(msg), 100)
>>> sret = ''.join([chr(x) for x in ret])
>>> assert sret == msg

最初(endpoint)と3番目(timeout)のパラメーターはread/write両方のメソッドで等しくそれぞれエンドポイント・アドレスとタイムアウトです。 2番目のパラメーターは、データ・ペイロード(write)または読み取るバイト数(read)です。 read メソッドの戻り値は array オブジェクトのインスタンスで、write メソッドの戻り値はで書き込んだバイト数です。

ベータ2バージョン以降、バイト数の代わりに、データが読み込まれる array オブジェクトを read と ctrl_transfer に渡すこともできます。この場合、読み込むバイト数は、配列の長さと array.itemsize 値の積になります。

ctrl_transfer と同様に、 timeout パラメータはオプションです。 timeout が省略された場合、操作のタイムアウト値として Device.default_timeout プロパティが使用されます。

自分自身を制御する¶

転送関数に加えて、モジュール usb.control は、標準のUSB制御要求(standard USB control request)を実装する関数を提供し、 usb.util モジュールには、文字列デスクリプタを返すための便利な関数 get_string があります。

オマケ¶

優れた抽象化の背後には、優れた実装があります¶

初期の頃は libusb しかありませんでした。次にlibusb 1.0が登場し、libusb 0.1と1.0がリリースされました。その後、OpenUSB が開発され、現在私たちは、USBライブラリのバベルの塔( Tower of Babel )に住んでいます(9) 。 PyUSBはそれをどのように扱いますか？ええ、PyUSBは民主的なライブラリです。あなたは好きなライブラリを選択できます。実際、独自のUSBライブラリを最初から作成して、PyUSBに使用するように指示することができます。しかし、あなたはたぶんlibusb 1.0を使用するのがいいでしょう。

find 関数には、まだ説明していないパラメータがあります。これは backend パラメータです。指定しない場合は、組み込みのバックエンドの1つが使用されます。バックエンドは usb.backend.IBackend から継承されたオブジェクトで、オペレーティング・システム固有のUSBの実装を担当します。ご想像のとおり、既にPyUSBに組み込み済なのはlibusb 1.0(デフォルト)とlibusb 0.1とOpenUSB(非推奨)バックエンドです。

あなたは独自のバックエンドを作成・使用することができます。 IBackend から継承し、必要なメソッドを実装するだけです。方法については、 usb.backend パッケージのドキュメントをご覧ください。

ホンマわがままやなぁ…¶

Pythonには、自動メモリ管理 (automatic memory management)と呼ばれるものがあります。これは、仮想マシンがオブジェクトをメモリから解放するタイミングを決定することを意味します。内部的には、PyUSBは動作する必要のあるすべての低レベルのリソース(インターフェイスの要求、デバイス・ハンドルなど)を管理し、ほとんどのユーザーはそのことを心配する必要はありません。ただし、Pythonのオブジェクトの自動破棄には非決定的(nondetrministic)な性質があるため、ユーザーは割り当てられたリソースがいつ解放されるかを予測できません。一部のアプリケーションは、確定的にリソースを割り当てて解放する必要があります。これらの種類のアプリケーションのために、 usb.util モジュールはリソース管理を扱うための一連の関数を持っています。

あなたがインターフェイス(interface)を手動で要求(claim)および解放(release)したい場合、あなたは claim_interface 関数と release_interface 関数を使用できます。 claim_interface は、デバイスが、あなたが指定したインターフェイスをまだ要求していない場合、それを要求します。デバイスが既にインターフェイスを要求済であある場合は何もしません。同様に、 release_interface は、あなたが指定のインターフェイスが既に要求(claim)済の場合、それを解放します。まだインターフェイスが要求されていない場合は何もしません。あなたはこの手動インターフェイス要求(manual interface claim)を使用して、libusb のドキュメントに記載されている構成選択の問題( configuration selection problem )を解決できます。

あなたが、デバイス・オブジェクトによって割り当てられたすべてのリソース(要求済のインターフェースを含む)を解放したい場合は、 dispose_resources 関数を使用できます。割り当てられたすべてのリソースを解放し、デバイス・オブジェクト(デバイス・ハードウェア自体ではない)を、find 関数呼び出しから戻ってきた直後の状態にします。

ライブラリを手動で指定する¶

一般に、バックエンドは、USBアクセスAPIを実装する共有ライブラリのラッパーです。デフォルトでは、バックエンドは find_library() ctypes 関数を使用します。 Linuxや他のUNIX風オペレーティングシステムでは、 find_library は外部プログラム( /sbin/ldconfig や gcc や objdump など)を実行してライブラリファイルを見つけようとします。

これらのプログラムがないか、ライブラリ・キャッシュが無効になっているシステムでは、この機能は使用できません。この制限を克服するために、PyUSBではカスタムの find_library() 関数をバックエンドに提供できます。

このようなシナリオの例です:

>>> import usb.core
>>> import usb.backend.libusb1
>>>
>>> backend = usb.backend.libusb1.get_backend(find_library=lambda x: "/usr/lib/libusb-1.0.so")
>>> dev     = usb.core.find(..., backend=backend)

get_backend() 関数の find_library 引数に注意してください。この引数では、バックエンドの正しいライブラリを見つける責任がある関数を指定します。

古臭いルール¶

あなたが古いPyUSB API(バージョン 0.X 系統)を使用してアプリケーションを作成していた場合、新しいAPIを使用するようにコードを更新する必要があるかどうかを悩んでいるかもしれません。まあ、できればそうすべきですが、そうする必要はありません。 PyUSB 1.0には usb.legacy 互換モジュールが付属しています。新しいAPIの上に古いAPIを実装します。「では、アプリケーションを機能させるために、import usb を import usb.legacy as usb に置き換えるだけでよいですか？」答えは「はい」です。これでうまくいきますが、でも、これすらも必要はありません。アプリケーションをそのまま実行すると、 usb.legacy からすべてのパブリック・シンボルが import usb ステートメントによってインポートされるため、そのまま機能します。問題が発生した場合は、おそらくあなたは何かしらバグを発見したということです。(訳注:とは言え、互換なのはあくまでPyUSBだけであってPyUSBが参照するPython標準ライブラリが変更になっていることがある。手元ではUSBError.messageをUSBError.strerrorに修正する必要があった。USBErrorがIOErrorを継承しているため。)

1: TrueまたはFalse（先頭大文字）とは、Python言語のそういう値を意味します。そして私がtrueやfalseを言うとき、それはtrueとfalseに評価されるPythonのあらゆる表現を意味します。
2: 各々のバックエンドのドキュメントを参照してください。
3: USB仕様では、構成(configuration)に順番になるような値を義務付けていません(訳注:次の値が+1で得られると期待するな、飛び飛びバラバラを覚悟せよということ)。インターフェイスと代替設定(alternate setting)番号についても同様です。
4: 実際はもう少し複雑ですが、ここでの説明はとしては十分です。
5: 私もそれが奇妙に聞こえることは知っています。
6: これは、デバイスの構成(configuration)時にアイソクロナス転送用の帯域幅がない場合、デバイスを成功裏に列挙できるためです。
7: デバイスは未構成の状態(unconfigured state)であることが許可されているため、これは構成(configration)では発生しません。
8: PyUSBでは、制御(control)転送はエンドポイント0でのみ発行されます。代替制御エンドポイント(alternate control endpoint)を持つデバイスは非常に非常にまれです（私はそのようなデバイスを全く見たことがありません）。
9: 単なる冗談です。真剣に受け止めないでください。でも、多くの選択肢は、選択肢がないよりも優れています。

FAQ¶

"No backend available" エラーを修正するにはどうすればいいですか?¶

通常、この問題には次の4つの原因が考えられます:

あなたが libusb ライブラリをインストールしていない場合。
あなたが libusb ライブラリを標準の共有ライブラリパス置いてない場合。
あなたの libusb のバージョンがとても古い場合。
あなたの PyUSB バージョンがとても古い場合。

何が問題なのかをデバッグするには、あなたの環境で以下のスクリプトを実行します:

import os
os.environ['PYUSB_DEBUG'] = 'debug'
import usb.core
usb.core.find()

これにより、デバッグメッセージがコンソールに出力されます。それでも何が起こっているのか分からないときは、当該のデバッグ出力を掲載して、メーリングリストに助けを求めてください。

Windowsにlibusbをインストールするにはどうすればいいですか?¶

libusb または libusb-win32 をWindowsにインストールするには、 zadig を使用してください。

Zadigはlibusb-1.0.dllをインストールしないため、libusb 1.0バックエンドを使用するには、Pythonインストールの適切な場所にlibusb-1.0.dllを配置する必要があることに注意してください。

指定のバックエンドの使用を強制するにはどうすればいいですか？¶

libusb1 バックエンド使用例:

>>> import usb.core
>>> from usb.backend import libusb1
>>> be = libusb1.get_backend()
>>> dev = usb.core.find(backend=be)

libusb ライブラリ・パスをバックエンドに渡すにはどうすればよいですか？¶

tutorial の Specify libraries by hand (邦訳:ライブラリを手動で指定する) を参照。

選択した構成(configuration)の、すでに構成(configured)されているデバイスで set_configuration() を呼び出す/呼び出さない方法は？¶

通常、 set_configuration() はデバイスの初期化中に呼び出されます。 libusb documentation の libusb_set_configuration() は次のように述べています:

あなたが、選択した構成(configuration)で既に構成(configure)されているデバイスでこの関数を呼び出すと、この関数は軽量のデバイスリセット(lightweight device reset)として機能します。すなわち、当座(current)の構成(configuration)を使用してSET_CONFIGURATIONリクエストを発行し、ほとんどのUSB関連デバイスの状態をリセットします(altsettingをゼロにリセットし、エンドポイントをクリアし停止、resetをトグル)。

したがって、その後 write() を呼び出すと、タイムアウトエラーが発生します。

この動作に対する解決策の一つは、 configuration selection and handling (構成(configuration)の選択と処理)で説明されているように、現在アクティブな構成を検討することです。 "必要な構成(configuration)が既にアクティブである場合、構成(configuration)を選択する必要はありません"

try:
    cfg = dev.get_active_configuration()
except usb.core.USBError:
    cfg = None
if cfg is None or cfg.bConfigurationValue != cfg_desired:
    dev.set_configuration(cfg_desired)

API Reference¶

This page contains auto-generated API reference documentation 1.

`usb`¶

PyUSB - Pythonから簡単にUSBにアクセスできるようにします。

本パッケージはイカのモジュールとサブバッケージをエクスポートします:

usb.core - the main USB implementation
usb.legacy - the compatibility layer with 0.x version
usb.backend - the support for backend implementations.
usb.control - USB standard control requests.
usb.libloader - helper module for backend library loading.

バージョン1.0以降では、メインのPyUSB実装は「usb.core」モジュールにあります。新しいアプリケーションではそれを使用することをお勧めします。

サブパッケージ¶

`usb.backend`¶

usb.backend - バックエンド・インターフェイス

本モジュールからは以下がエスクポートされます:

IBackend - バックエンド・インターフェイス

バックエンド(backend)は、IBackendインターフェイスを実装するPythonオブジェクトです。これを行う最も簡単な方法は、IBackendから継承することです。

PyUSBはすでにlibusbバージョン0.1と1.0、およびOpenUSBライブラリのバックエンドを提供しています。 PyUSBに含まれるバックエンド・モジュールは、バックエンド・オブジェクトのインスタンスを返すget_backend()関数をエクスポートする必要があります。必要に応じて、独自にカスタマイズしたバックエンドを提供できます。以下に、バックエンド実装モジュールのスケルトンを示します:

import usb.backend

class MyBackend(usb.backend.IBackend):
    pass

def get_backend():
    return MyBackend()

あなたは、あなたがカスタマイズしたバックエンドを usb.core.find() 関数のバックエンド・パラメータとして渡すことで使用できます。例えば:

import custom_backend
import usb.core

myidVendor = 0xfffe
myidProduct = 0x0001

mybackend = custom_backend.get_backend()

dev = usb.core.find(backend = mybackend, idProduct=myidProduct,
                    idVendor=myidVendor)

カスタム・バックエンドの場合、アプリケーション・コードがバックエンドをインスタンス化するため、あなたは get_backend()関数を提供する必要はありません。

find()関数にバックエンドを指定しない場合、内部ルールに従ってデフォルトのバックエンドの1つを使用します。詳細については、find()関数のドキュメントを参照してください。

サブモジュール¶

usb.backend.libusb0¶

Module Contents¶

Functions¶

usb.backend.libusb0.get_backend

usb.backend.libusb0.get_backend(find_library=None)¶

usb.backend.libusb1¶

Module Contents¶

Functions¶

usb.backend.libusb1.get_backend

Attributes¶

usb.backend.libusb1.LIBUSB_SUCCESS = 0¶

usb.backend.libusb1.LIBUSB_ERROR_IO¶

usb.backend.libusb1.LIBUSB_ERROR_INVALID_PARAM¶

usb.backend.libusb1.LIBUSB_ERROR_ACCESS¶

usb.backend.libusb1.LIBUSB_ERROR_NO_DEVICE¶

usb.backend.libusb1.LIBUSB_ERROR_NOT_FOUND¶

usb.backend.libusb1.LIBUSB_ERROR_BUSY¶

usb.backend.libusb1.LIBUSB_ERROR_TIMEOUT¶

usb.backend.libusb1.LIBUSB_ERROR_OVERFLOW¶

usb.backend.libusb1.LIBUSB_ERROR_PIPE¶

usb.backend.libusb1.LIBUSB_ERROR_INTERRUPTED¶

usb.backend.libusb1.LIBUSB_ERROR_NO_MEM¶

usb.backend.libusb1.LIBUSB_ERROR_NOT_SUPPORTED¶

usb.backend.libusb1.LIBUSB_ERROR_OTHER¶

usb.backend.libusb1.LIBUSB_TRANSFER_COMPLETED = 0¶

usb.backend.libusb1.LIBUSB_TRANSFER_ERROR = 1¶

usb.backend.libusb1.LIBUSB_TRANSFER_TIMED_OUT = 2¶

usb.backend.libusb1.LIBUSB_TRANSFER_CANCELLED = 3¶

usb.backend.libusb1.LIBUSB_TRANSFER_STALL = 4¶

usb.backend.libusb1.LIBUSB_TRANSFER_NO_DEVICE = 5¶

usb.backend.libusb1.LIBUSB_TRANSFER_OVERFLOW = 6¶

usb.backend.libusb1.get_backend(find_library=None)¶

usb.backend.openusb¶

Package Contents¶

Classes¶

usb.backend.IBackend

class usb.backend.IBackend¶

Bases: usb._objfinalizer.AutoFinalizedObject

バックエンド・インターフェイス

IBackendは、バックエンド実装の基本的なインターフェイスです。デフォルトでは、インターフェイスのメソッドはNotImplementedError例外を発生させます。バックエンド実装は、必要な機能を提供するためにメソッドを置き換える必要があります。

Pythonは動的型付き言語であるため、IBackendから継承する義務はありません。IBackendのように動作するものはすべてIBackendです。ただし、IBackendから継承することをことを強くお勧めします。IBackendから継承すると、一貫したデフォルトの動作が提供されます。

enumerate_devices(self)¶

この関数は、システムで検出された各USBデバイスの実装定義のデバイスIDを生成する反復可能(iterable)なオブジェクトを返すために必要です。

デバイス識別オブジェクト(device identification object)は、インターフェイスの他のメソッドへの引数として使用されます。

get_parent(self, dev)¶: 与えたデバイスの親デバイスを返します。

get_device_descriptor(self, dev)¶

与えたデバイスのデバイス・デスクリプタを返します。

返されるオブジェクトには、すべてのデバイス・デスクリプタ・フィールドをメンバー変数としてアクセス可能にする必要があります。これらは、int型に変換可能である必要があります(等しい必要はありません)。

devは、enumerate_devices()メソッドによって返されるイテレータによって生成されるオブジェクトです。

get_configuration_descriptor(self, dev, config)¶

与えたデバイスの構成(configuration)デスクリプタを返します。

返されるオブジェクトには、メンバー変数としてアクセス可能なすべての構成(configuration)デスクリプタ・フィールドが必要です。これらは、int型に変換可能である必要があります(等しい必要はありません)。

devパラメータはデバイス識別オブジェクトです。configは構成(congigure)の論理インデックスです(bConfigurationValueフィールドではありません)。「論理インデックス」とは、GET_DESCRIPTORリクエストの結果としてペリフェラルによって返される構成の相対的な順序を意味します。

get_interface_descriptor(self, dev, intf, alt, config)¶

与えたデバイスのインターフェイス・デスクリプタを返します。

返されるオブジェクトには、すべてのインターフェイス・デスクリプタ・フィールドをメンバー変数としてアクセスできるようにする必要があります。これらは、int型に変換可能である必要があります(等しい必要はありません)。

devパラメータはデバイス識別オブジェクトです。 intfパラメータは(bInterfaceNumberフィールドではなく)インターフェイスの論理インデックスであり、altは(bAlternateSetting値ではなく)代替設定(alternate setting)の論理インデックスです。すべてのインターフェイスに複数の代替設定(alternate setting)があるわけではありません。この場合、altパラメータはゼロにする必要があります。configは構成(configuration)の論理インデックスです(bConfigurationValueフィールドではありません)。

get_endpoint_descriptor(self, dev, ep, intf, alt, config)¶

与えたデバイスのエンドポイント・デスクリプタを返します。

返されるオブジェクトには、メンバー変数としてアクセス可能なすべてのエンドポイント・デスクリプタ・フィールドが必要です。これらは、int型に変換可能である必要があります(等しい必要はありません)。

epパラメーターは、必要なエンドポイント・デスクリプタのエンドポイント論理インデックス(bEndpointAddressフィールドではない)です。 dev、intf、alt、configは、get_interface_descriptor()メソッドですでに説明済のものと同じ値です。

open_device(self, dev)¶

データ交換(data exchange)のためにデバイスを開きます。

このメソッドは、通信のためにdevパラメーターで識別されたデバイスを開きます。このメソッドは、転送メソッドなどの通信関連メソッドを呼び出す前に呼び出す必要があります。

通信インスタンス(communication instance)を識別するハンドルを返します。このハンドルを通信メソッド(communication method)に渡す必要があります。

close_device(self, dev_handle)¶

デバイス・ハンドルをクローズする。

このメソッドは、デバイスの通信チャネルを閉じ、それに関連するすべてのシステムリソースを解放します。

set_configuration(self, dev_handle, config_value)¶

アクティブなデバイス構成(configurtion)をセットする。

このメソッドは、デバイスのアクティブな構成を設定するために呼び出す必要があります。 dev_handleパラメータはopen_device()メソッドによって返される値であり、config_valueパラメータは関連する構成(configure)デスクリプタのbConfigurationValueフィールドです。

get_configuration(self, dev_handle)¶

当座(current)のアクティブなデバイス構成(configuration)を取得。

このメソッドは、現在アクティブな構成(configuration)のbConfigurationValueを返します。バックエンドとOSに応じて、キャッシュされた値が返されるか、制御要求(control request)が発行されます。dev_handleパラメータは、open_deviceメソッドによって返される値です。

set_interface_altsetting(self, dev_handle, intf, altsetting)¶

インターフェイス代替設定(alternate setting)をセットする。

このメソッドは、インターフェイスに複数の代替設定(alternate setting)がある場合にのみ呼び出す必要があります。dev_handleは、open_device()メソッドによって返される値です。intfとaltsettingは、それぞれ関連するインターフェイス(interface)のbInterfaceNumberフィールドとbAlternateSettingフィールドです。

claim_interface(self, dev_handle, intf)¶

指定のインターフェイスを要求(claim)します。

インターフェイスの要求(claim)はUSB仕様自体には関係ありませんが、通常はUSBライブラリに必要な呼び出しです。システム上のインターフェイスへの排他的アクセスを要求(request)します。このメソッドは、いずれかの転送(transfer)メソッドを使用する前に呼び出す必要があります。

dev_handleはopen_device()メソッドによって返された値で、intfは欲しいインターフェイスのbInterfaceNumberフィールドです。

release_interface(self, dev_handle, intf)¶

要求済のインターフェイス(claimed interface)を開放する。

dev_handleとintfは、claim_interfaceメソッドと同様のパラメーターです。

bulk_write(self, dev_handle, ep, intf, data, timeout)¶

一括書き込み(bulk write)を実行します。

dev_handleは、open_device()メソッドによって返される値です。 epパラメータは、データが送信されるエンドポイントのbEndpointAddressフィールドです。 intfは、エンドポイントを含むインターフェイスのbInterfaceNumberフィールドです。 dataパラメータは、送信されるデータです。これは、array.arrayクラスのインスタンスでなければなりません。 timeoutパラメータは、操作のタイムアウトをミリ秒単位で指定します。

本メソッドは書き込んだバイト数を返します。

bulk_read(self, dev_handle, ep, intf, buff, timeout)¶

一括読み取り(bulk read)を実行します。

dev_handleは、 open_device()メソッドによって返される値です。 epパラメーターは、データの受信元となるエンドポイントのbEndpointAddressフィールドです。 intfは、エンドポイントを含むインターフェイスのbInterfaceNumberフィールドです。 buffパラメータは、読み取られたデータを受け取るためのバッファです。バッファの長さのバイト数だけデータが読み取られます。timeoutパラメータは、操作のタイムアウトをミリ秒単位で指定します。

本メソッドは実際に読み取ったバイト数を返します。

intr_write(self, dev_handle, ep, intf, data, timeout)¶

割り込み書き込み(interrupt write)を実行します。

dev_handleは、open_device()メソッドによって返される値です。 epパラメータは、データが送信されるエンドポイントのbEndpointAddressフィールドです。 intfは、エンドポイントを含むインターフェイスのbInterfaceNumberフィールドです。 dataパラメータは、送信されるデータです。これは、array.arrayクラスのインスタンスでなければなりません。 timeoutパラメータは、操作のタイムアウトをミリ秒単位で指定します。

本メソッドは書き込んだバイト数を返します。

intr_read(self, dev_handle, ep, intf, size, timeout)¶

読み取りの割込転送(interrupt read)を実行します。

dev_handleは、open_device()メソッドによって返される値です。epパラメーターは、データの受信元となるエンドポイントのbEndpointAddressフィールドです。intfは、エンドポイントを含むインターフェイスのbInterfaceNumberフィールドです。buffパラメータは、読み取られたデータを受け取るためのバッファです。バッファの長さのバイト数だけデータが読み取られます。timeoutパラメータは、操作のタイムアウトをミリ秒単位で指定します。

本メソッドは実際に読み取ったバイト数を返します。

iso_write(self, dev_handle, ep, intf, data, timeout)¶

アイソクロナス書き込みを実行します。

dev_handleは、open_device()メソッドによって返される値です。 epパラメータは、データが送信されるエンドポイントのbEndpointAddressフィールドです。 intfは、エンドポイントを含むインターフェイスのbInterfaceNumberフィールドです。 dataパラメータは、送信されるデータです。これは、array.arrayクラスのインスタンスでなければなりません。 timeoutパラメータは、操作のタイムアウトをミリ秒単位で指定します。

本メソッドは書き込んだバイト数を返します。

iso_read(self, dev_handle, ep, intf, size, timeout)¶

アイソクロナス読み取りを実行します。

dev_handleは、open_device()メソッドによって返される値です。epパラメーターは、データの受信元となるエンドポイントのbEndpointAddressフィールドです。intfは、エンドポイントを含むインターフェイスのbInterfaceNumberフィールドです。buffパラメータは、読み込まれたデータを受け取るためのバッファであり、バッファの長さのバイト数だけデータが読み込まれます。timeoutパラメータは、操作のタイムアウトをミリ秒単位で指定します。

本メソッドは実際に読み取ったバイト数を返します。

ctrl_transfer(self, dev_handle, bmRequestType, bRequest, wValue, wIndex, data, timeout)¶

エンドポイント0(ゼロ)で制御(control)転送を実行します。

転送の方向は、セットアップパケットのbmRequestTypeフィールドから推測されます。

dev_handleは、 open_device() メソッドによって返される値です。 bmRequestTypeとbRequestとwValueとwIndexは、セットアップパケットの同名のフィールドです。 dataは配列オブジェクトです。OUTリクエストの場合はデータ・ステージで送信するバイトを格納しており、INリクエストの場合は読み取ったデータを保持するバッファです。送信または受信が要求されたバイト数は、配列の長さにdata.itemsizeフィールドを掛けたものと同じです。 timeoutパラメータは、操作のタイムアウトをミリ秒単位で指定します。

OUT転送時は書き込んだバイト数を返します。IN転送時は読み込んだデータをarray.arrayオブジェクトとして返します。

clear_halt(self, dev_handle, ep)¶: エンドポイントの停止/失速(halt/stall)状態をクリアします。

reset_device(self, dev_handle)¶: デバイスをリセットする。

is_kernel_driver_active(self, dev_handle, intf)¶

カーネル・ドライバーがインターフェイスでアクティブかどうかを確認します。

カーネル・ドライバがアクティブな場合、あなたはインターフェイスを要求(claim)できず、バックエンドは入出力を実行できません。

detach_kernel_driver(self, dev_handle, intf)¶

インターフェイスからカーネル・ドライバを取り外します。

成功ならば、あなたはインターフェイスを要求(claim)して入出力を実行可能です。

attach_kernel_driver(self, dev_handle, intf)¶: 以前 detach_kernel_driver() を使用して切り離されていたインターフェイスのカーネル・ドライバーを再接続します。

サブモジュール¶

`usb._debug`¶

Module Contents¶

Functions¶

usb._debug.methodtrace
usb._debug.functiontrace

usb._debug.methodtrace(logger)¶

usb._debug.functiontrace(logger)¶

`usb._interop`¶

Module Contents¶

Functions¶

usb._interop._next

Attributes¶

usb._interop._reduce
usb._interop._set
usb._interop._update_wrapper

usb._interop._reduce¶

usb._interop._set¶

usb._interop._next(iter)¶

usb._interop._update_wrapper¶

`usb._lookup`¶

usb._lookups - Lookup tables for USB

Module Contents¶

usb._lookup.descriptors¶

usb._lookup.device_classes¶

usb._lookup.interface_classes¶

usb._lookup.ep_attributes¶

usb._lookup.MAX_POWER_UNITS_USB2p0 = 2¶

usb._lookup.MAX_POWER_UNITS_USB_SUPERSPEED = 8¶

`usb._objfinalizer`¶

`usb.control`¶

usb.control - USB 標準制御要求(standard control requests)

本モジュールからは以下がエスクポートされます:

get_status - get recipeint status
clear_feature - clear a recipient feature
set_feature - set a recipient feature
get_descriptor - get a device descriptor
set_descriptor - set a device descriptor
get_configuration - get a device configuration
set_configuration - set a device configuration
get_interface - get a device interface
set_interface - set a device interface

Module Contents¶

Functions¶

usb.control.get_status
usb.control.clear_feature
usb.control.set_feature
usb.control.get_descriptor
usb.control.set_descriptor
usb.control.get_configuration
usb.control.set_configuration
usb.control.get_interface
usb.control.set_interface

Attributes¶

usb.control.ENDPOINT_HALT
usb.control.FUNCTION_SUSPEND
usb.control.DEVICE_REMOTE_WAKEUP
usb.control.U1_ENABLE
usb.control.U2_ENABLE
usb.control.LTM_ENABLE

usb.control.ENDPOINT_HALT = 0¶

usb.control.FUNCTION_SUSPEND = 0¶

usb.control.DEVICE_REMOTE_WAKEUP = 1¶

usb.control.U1_ENABLE = 48¶

usb.control.U2_ENABLE = 49¶

usb.control.LTM_ENABLE = 50¶

usb.control.get_status(dev, recipient=None)¶

指定の受信者(recipient)のステータスを返す。