`usb.core`¶

usb.core - コアUSB機能

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

Device - USBデバイスを表すクラス。
Configuration - 構成(configuration)デスクリプターを表すクラス。
Interface - インタフェース(interface)デスクリプターを表すクラス。
Endpoint - エンドポイント(endpoint)デスクリプターを表すクラス。
find() - USBデバイス達を探す関数
show_devices() - 存在するデバイスを表示する関数。

モジュール内容¶

Classes¶

usb.core.Endpoint
usb.core.Interface
usb.core.Configuration
usb.core.Device

Functions¶

usb.core.find
usb.core.show_devices

exception usb.core.USBError(strerror, error_code=None, errno=None)¶

Bases: OSError

USBエラーの例外クラス。

USB関連のエラーが発生した場合、バックエンドはこの例外を発生させる必要があります。バックエンド固有のエラーコードは、 'backend_error_code' メンバー変数を介して利用できます。

exception usb.core.USBTimeoutError(strerror, error_code=None, errno=None)¶

Bases: USBError

接続タイムアウトエラーの例外クラス。

USB接続での呼び出しがタイムアウトエラーコードを返す場合、バックエンドはこの例外を発生させる必要があります。

exception usb.core.NoBackendError¶

Bases: ValueError

有効なバックエンドが見つからない場合の例外クラス。

class usb.core.Endpoint(device, endpoint, interface=0, alternate_setting=0, configuration=0)¶

Bases: object

エンドポイントオブジェクトを表します。

このクラスには、USB仕様に従ったエンドポイントデスクリプターのすべてのフィールドが含まれています。クラスプロパティとしてアクセスできます。たとえば、エンドポイントデスクリプターのフィールドbEndpointAddressにアクセスするには、以下のようにします:

>>> import usb.core
>>> dev = usb.core.find()
>>> for cfg in dev:
>>>     for i in cfg:
>>>         for e in i:
>>>             print e.bEndpointAddress

__repr__(self)¶

戻り値: repr(self)

__str__(self)¶

戻り値: str(self)

write(self, data, timeout=None)¶

エンドポイントにデータを書き込みます。

パラメータデータにはエンドポイントに送信されるデータが含まれ、タイムアウトは操作の制限時間です。転送タイプとエンドポイントアドレスは自動的に推測されます。

このメソッドは、書き込まれたバイト数を返します。

詳細については、Device.write()メソッドを参照してください。

read(self, size_or_buffer, timeout=None)¶

エンドポイントからデータを読み取ります。

パラメータsize_or_bufferは、読み取るバイト数、またはデータが挿入される配列オブジェクトのいずれかであり、timeoutは操作の時間制限です。転送タイプとエンドポイントアドレスは自動的に推測されます。

このメソッドは、配列オブジェクトまたは実際に読み取られたバイト数のいずれかを返します。

詳細については、Device.read()メソッドを参照してください。

clear_halt(self)¶: エンドポイントのhalt/status条件をクリアします。

_str(self)¶

class usb.core.Interface(device, interface=0, alternate_setting=0, configuration=0)¶

Bases: object

インターフェイスオブジェクトを表します。

このクラスには、USB仕様に従ったインターフェースデスクリプターのすべてのフィールドが含まれています。クラスプロパティとしてアクセスできます。たとえば、インターフェイスデスクリプターのフィールドbInterfaceNumberにアクセスするには、以下のようにします:

>>> import usb.core
>>> dev = usb.core.find()
>>> for cfg in dev:
>>>     for i in cfg:
>>>         print i.bInterfaceNumber

__repr__(self)¶

戻り値: repr(self)

__str__(self)¶: インターフェイスのすべての情報を表示します。

endpoints(self)¶

戻り値: そのデバイスの構成群をタプルで返します。

set_altsetting(self)¶: インターフェイスの代替設定を設定します。

__iter__(self)¶: インターフェイスのすべてのエンドポイントを繰り返し処理します。

__getitem__(self, index)¶

戻り値: 指定された位置にあるエンドポイントオブジェクト。

_str(self)¶

_get_full_descriptor_str(self)¶

class usb.core.Configuration(device, configuration=0)¶

Bases: object

構成(configuration)オブジェクトを表します。

このクラスには、USB仕様に従ったconfigurationデスクリプターのすべてのフィールドが含まれています。クラスプロパティとしてアクセスできます。たとえば、configurationデスクリプターのフィールドbConfigurationValueにアクセスするには、以下のようにします:

>>> import usb.core
>>> dev = usb.core.find()
>>> for cfg in dev:
>>>     print cfg.bConfigurationValue

__repr__(self)¶

戻り値: repr(self)

__str__(self)¶

戻り値: str(self)

interfaces(self)¶

戻り値: そのデバイスの構成インターフェース達をタプルで返します。

set(self)¶: この構成をアクティブな構成として設定します。

__iter__(self)¶: 構成(configuration)のすべてのインターフェースを反復処理します。

__getitem__(self, index)¶

戻り値: 指定された位置にあるInterfaceオブジェクト。

indexは、それぞれインターフェイスインデックスと代替設定インデックスを持つ2つの値のタプルです。例:

>>> interface = config[(0, 0)]

_str(self)¶

_get_full_descriptor_str(self)¶

class usb.core.Device(dev, backend)¶

Bases: usb._objfinalizer.AutoFinalizedObject

Deviceオブジェクトです。

このクラスには、USB仕様に基づくデバイス・デスクリプタのすべてのフィールドが含まれています。あなたはそれらにクラスのプロパティとしてアクセスできます。たとえば、デバイス・デスクリプタのフィールドbDescriptorTypeにアクセスするには、次のようにします:

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

さらに、クラスはハードウェアと通信するメソッドを提供します。通常、アプリケーションは最初にset_configuration()メソッドを呼び出してデバイスを既知の構成済み状態(a known conifgured state)にし、代替設定が複数ある場合、オプションでset_interface_altsetting()を呼び出して、使用するインターフェイスの代替設定を選択し、 write() や read() メソッドでデータを送受信します。

新しいハードウェアで作業する場合、最初の試行は次のようになります:

>>> import usb.core
>>> dev = usb.core.find(idVendor=myVendorId, idProduct=myProductId)
>>> dev.set_configuration()
>>> dev.write(1, 'test')

このサンプルでは、対象のデバイスを見つけ（myVendorIdおよびmyProductIdをデバイスの対応する値で置き換える必要があります）、デバイスを構成し（デフォルトでは、構成値(configuration value)は1であり、ほとんどのデバイスの一般的な値です）、エンドポイント0x01へデータを幾つか書き込みます。

書き込み、読み取り、およびctrl_transferメソッドのタイムアウト値はミリ秒単位で指定します。このパラメーターを省略した場合、代わりにDevice.default_timeout値が使用されます。Device.default_timeoutプロパティは、ユーザがいつでも設定できます。

default_timeout¶

__repr__(self)¶

__str__(self)¶

configurations(self)¶

戻り値: そのデバイスの構成群をタプルで返します。

property langids(self)¶

USBデバイスでサポートされている言語IDコードを返します。

これらは、Windows開発者に馴染みのある16ビットコードです。たとえば、en-USの代わりに0x0409と言います。詳細については、usb.org開発者サイトのUSB_LANGIDS.pdfを参照してください。この配列にないLANGIDを使用する文字列要求は、デバイスに送信しないでください。

このプロパティは、最初にアクセスされたときに一部のUSBトラフィックを引き起こし、将来の使用のために結果の値をキャッシュします。

property serial_number(self)¶

USBデバイスのシリアル番号文字列デスクリプター(serial number string descriptor)を返します。

このプロパティは、最初にアクセスされたときに一部のUSBトラフィックを引き起こし、将来の使用のために結果の値をキャッシュします。

property product(self)¶

USBデバイスの製品文字列記述子(product string descriptor)を返します。

このプロパティは、最初にアクセスされたときに一部のUSBトラフィックを引き起こし、将来の使用のために結果の値をキャッシュします。

property parent(self)¶

戻り値: 親デバイス。

property manufacturer(self)¶

USBデバイスの製造元の文字列記述子(manufacturer string descriptor)を返します。

このプロパティは、最初にアクセスされたときに一部のUSBトラフィックを引き起こし、将来の使用のために結果の値をキャッシュします。

property backend(self)¶: そのデバイスが使っているバックエンドを返します。

set_configuration(self, configuration=None)¶

アクティブなconfigurationをセットします。

configurationパラメーターは、アクティブとして設定するconfigurationのbConfigurationValueフィールドです。このメソッドをパラメーターなしで呼び出すと、最初に見つかったconfigurationが使用されます。デバイスに複数のconfigurationがあることはほとんどないため、引数なしでメソッドを呼び出すだけでデバイスを準備できます。

get_active_configuration(self)¶

戻り値: 現在の構成セットを表す構成オブジェクト。

set_interface_altsetting(self, interface=None, alternate_setting=None)¶

インターフェイスの代替設定を設定します。

あなたが、インターフェイスを使用する必要があり、そのインターフェイスに複数の代替設定がある場合は、あなたはこのメソッドを呼び出して適切な代替設定を選択する必要があります。 1つまたは2つのパラメーターを指定せずにメソッドを呼び出すと、set_configurationメソッドと同じ方法で、デバイスで最初に見つかったメソッドが選択されます。

通常、インターフェイスには代替設定が1つしかないため、この呼び出しは必要ありません。ほとんどのデバイスでは、代替設定が複数あるかどうかに関係なく、引数なしでこのメソッドを呼び出すことは有害ではありません。USB仕様では許可されていますが、代替設定が1つしかない場合、デバイスは要求をサイレントに無視するためです。追加の代替設定がないデバイスは、SET_INTERFACE要求に応答してホストにエラーを返します。

疑わしい場合は、try/except句でラップされた引数なしで呼び出すことをお勧めします:

>>> try:
>>>     dev.set_interface_altsetting()
>>> except usb.core.USBError:
>>>     pass

clear_halt(self, ep)¶: epに指定したエンドポイントの halt/stall 状態をクリアします。

reset(self)¶: デバイスをリセットします。

write(self, endpoint, data, timeout=None)¶

エンドポイントにデータを書き込みます。

このメソッドは、デバイスにデータを送信するために使用されます。エンドポイントパラメータは、エンドポイントと通信するbEndpointAddressメンバーに対応します。

データパラメータは、配列型に変換可能な型のようなシーケンスである必要があります（配列モジュールを参照）。

タイムアウトはミリ秒単位で指定されます。

このメソッドは、書き込まれたバイト数を返します。

read(self, endpoint, size_or_buffer, timeout=None)¶

エンドポイントからデータを読み取ります。

このメソッドは、デバイスからデータを受信するために使用されます。エンドポイントパラメータは、エンドポイントと通信するbEndpointAddressメンバーに対応します。 size_or_bufferパラメーターは、読み取るバイト数を指定するか、データを受信するためのバッファーを提供します（配列型のオブジェクトである必要があります）。

タイムアウトはミリ秒単位で指定されます。

size_or_bufferパラメーターが読み取るバイト数である場合、メソッドは読み取られたデータを含む配列オブジェクトを返します。 size_or_bufferパラメーターが配列オブジェクトの場合、実際に読み取られたバイト数を返します。

ctrl_transfer(self, bmRequestType, bRequest, wValue=0, wIndex=0, data_or_wLength=None, timeout=None)¶

エンドポイント0で制御転送(control transfer)を行います。

このメソッドは、エンドポイント0を介して制御転送を発行するために使用します（エンドポイント0は常に制御エンドポイントである必要があります）。

パラメータbmRequestType、bRequest、wValue、wIndexは、USB標準制御要求(Standard Control Request)フォーマットと同じです。

制御要求には、書き込み/読み取り用のデータペイロードがある場合とない場合があります。ある場合は、bmRequestTypeフィールドの方向ビットを使用して、目的の要求方向を推測します。ホストからデバイスへの要求（OUT）の場合、data_or_wLengthパラメーターは送信するデータペイロードであり、配列オブジェクトに変換可能なシーケンスタイプである必要があります。この場合、戻り値はデータペイロードに書き込まれたバイト数です。デバイスからホストへの要求（IN）の場合、data_or_wLengthは、データペイロードで読み取るバイト数を指定する制御要求のwLengthパラメーターであり、その戻り値はデータが読み取られる配列オブジェクトです。またはdata_or_wLengthはデータが読み取られる配列オブジェクトであり、戻り値は読み取られたバイト数です。

is_kernel_driver_active(self, interface)¶

インターフェイスに関連付けられているカーネルドライバがあるかどうかを確認します。

カーネルドライバがアクティブな場合、オブジェクトは入出力を実行できません。

interfaceパラメータは、チェックするデバイスインターフェイス番号です。

detach_kernel_driver(self, interface)¶

カーネルドライバーを取り外します(detach)。

成功すると、あなたは入出力を実行できるようになります。

interfaceパラメータは、ドライバを取り外す(detach)デバイスインターフェイス番号です。

attach_kernel_driver(self, interface)¶

以前にdetach_kernel_driver()を使って切り離し(detach)した、指定のインターフェイスのカーネル・ドライバを再接続(re-attach)します。

interface パラメータは、ドライバを接続したい、デバイスのインターフェイス番号を指定します。

__iter__(self)¶: デバイスのすべての構成(configuration)を繰り返します。

__getitem__(self, index)¶

戻り値: 指定された位置にある構成オブジェクト。

_finalize_object(self)¶

__get_timeout(self, timeout)¶

__set_def_tmo(self, tmo)¶

__get_def_tmo(self)¶

_str(self)¶

_get_full_descriptor_str(self)¶

usb.core.find(find_all=False, backend=None, custom_match=None, **args)¶

USBデバイスを見つけてそれを返します。

find（）は、USBデバイスを検出するために使用される関数です。デバイスに一致するように、USBデバイスデスクリプターフィールドの任意の組み合わせを引数として渡すことができます。例えば:

find(idVendor=0x3f4, idProduct=0x2009)

idVendorフィールドが0x3f4に等しく、idProductが0x2009に等しいデバイスのDeviceオブジェクトを返します。

基準に一致するデバイスが複数ある場合は、最初に見つかったデバイスが返されます。一致するデバイスが見つからない場合、関数はNoneを返します。すべてのデバイスを取得する場合は、パラメーターfind_allをTrueに設定すると、findは一致するすべてのデバイスのイテレーターを返します。一致するデバイスが見つからない場合は、空のイテレータが返されます。例:

for printer in find(find_all=True, bDeviceClass=7):
    print (printer)

この呼び出しにより、すべてのUSBプリンターがシステムに接続されます。(一部のデバイスはクラス情報をインターフェイスデスクリプターに配置するため、実際にはそうではない場合があります)。

あなたはカスタマイズされた一致基準を使用することもできます:

dev = find(custom_match = lambda d: d.idProduct=0x3f4 and d.idvendor=0x2009)

カスタマイズされた一致を使用したより正確なプリンター探索器は、以下のようになります:

def is_printer(dev):
    import usb.util
    if dev.bDeviceClass == 7:
        return True
    for cfg in dev:
        if usb.util.find_descriptor(cfg, bInterfaceClass=7) is not None:
            return True

for printer in find(find_all=True, custom_match = is_printer):
    print (printer)

これで、デバイスクラスコードがインターフェイスデスクリプターにある場合でも、プリンタが見つかります。

カスタマイズされた一致をデバイスデスクリプターフィールドと組み合わせることができます。この場合、フィールドは一致する必要があり、custom_matchはTrueを返す必要があります。前の例では、製造元0x3f4に属するすべてのプリンターを取得する場合、コードは以下のようになります:

printers = list(find(find_all=True, idVendor=0x3f4, custom_match=is_printer))

「すべてのデバイスを一覧表示する」関数としてfindを使用する場合は、find_all = Trueで呼び出します:

devices = list(find(find_all=True))

最後に、カスタムバックエンドをfind関数に渡すことができます:

find(backend = MyBackend())

PyUSBには、libusb 0.1、libusb 1.0、およびOpenUSB用のバックエンドが組み込まれています。バックエンドを明示的に指定しない場合、find()関数は、システムの可用性に応じて、事前定義されたバックエンドの1つを選択します。

バックエンドについては、usb.backendモジュールで説明されています。

usb.core.show_devices(verbose=False, **kwargs)¶

接続されているデバイスに関する情報を表示します。

verbose フラグは、verbose or not に設定されます。 * kwargsはfind()関数に直接渡されます。

usb.core¶

モジュール内容¶

Classes¶

Functions¶

`usb.core`¶