usb.backend パッケージ

サブモジュール

usb.backend.libusb0 モジュール

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

usb.backend.libusb1 モジュール

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

usb.backend.openusb モジュール

モジュール内容

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()関数のドキュメントを参照してください。

class usb.backend.IBackend

ベースクラス: usb._objfinalizer.AutoFinalizedObject

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

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

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

attach_kernel_driver(dev_handle, intf)

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

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

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

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

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

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

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

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

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

claim_interface(dev_handle, intf)

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

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

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

clear_halt(dev_handle, ep)

エンドポイントの停止/失速(halt/stall)状態をクリアします。

close_device(dev_handle)

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

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

ctrl_transfer(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オブジェクトとして返します。

detach_kernel_driver(dev_handle, intf)

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

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

enumerate_devices()

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

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

get_configuration(dev_handle)

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

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

get_configuration_descriptor(dev, config)

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

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

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

get_device_descriptor(dev)

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

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

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

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

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

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

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

get_interface_descriptor(dev, intf, alt, config)

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

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

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

get_parent(dev)

与えたデバイスの親デバイスを返します。

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

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

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

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

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

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

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

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

is_kernel_driver_active(dev_handle, intf)

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

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

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

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

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

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

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

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

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

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

open_device(dev)

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

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

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

release_interface(dev_handle, intf)

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

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

reset_device(dev_handle)

デバイスをリセットする。

set_configuration(dev_handle, config_value)

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

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

set_interface_altsetting(dev_handle, intf, altsetting)

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

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