tessl/pypi-pyusb
Easy USB access for Python with backend-neutral, cross-platform support
—
Pending
device-communication.mddocs/
Device Communication
Core device operations for USB communication including configuration, data transfer, and endpoint operations. The Device class provides the primary interface for all USB device interactions in PyUSB's modern API.
Capabilities
Device Configuration
Configure USB devices by setting active configurations and managing device state.
class Device:
def set_configuration(self, configuration=None):
"""
Set device configuration.
Parameters:
- configuration: int or Configuration object, configuration to set (default: first configuration)
Raises:
- USBError: Configuration failed
"""
def get_active_configuration(self):
"""
Get active configuration.
Returns:
Configuration object representing active configuration
Raises:
- USBError: Unable to get configuration
"""
def set_interface_altsetting(self, interface=None, alternate_setting=None):
"""
Set alternate setting for an interface.
Parameters:
- interface: int or Interface object, interface to modify
- alternate_setting: int, alternate setting to select
Raises:
- USBError: Interface setting failed
"""
def configurations(self):
"""
Get tuple of all device configurations.
Returns:
tuple: Configuration objects for device
"""Data Transfer Operations
Read and write data to USB endpoints with configurable timeouts and error handling.
class Device:
def read(self, endpoint, size_or_buffer, timeout=None):
"""
Read data from endpoint.
Parameters:
- endpoint: int, endpoint address to read from
- size_or_buffer: int or array-like, size to read or buffer to fill
- timeout: int, timeout in milliseconds (None for no timeout)
Returns:
array.array of bytes read
Raises:
- USBTimeoutError: Read operation timed out
- USBError: Read operation failed
"""
def write(self, endpoint, data, timeout=None):
"""
Write data to endpoint.
Parameters:
- endpoint: int, endpoint address to write to
- data: bytes or array-like, data to write
- timeout: int, timeout in milliseconds (None for no timeout)
Returns:
int: number of bytes written
Raises:
- USBTimeoutError: Write operation timed out
- USBError: Write operation failed
"""Control Transfers
Perform USB control transfers for device-specific operations and standard requests.
class Device:
def ctrl_transfer(self, bmRequestType, bRequest, wValue=0, wIndex=0, data_or_wLength=None, timeout=None):
"""
Perform control transfer.
Parameters:
- bmRequestType: int, request type and direction
- bRequest: int, specific request
- wValue: int, request-specific value
- wIndex: int, request-specific index
- data_or_wLength: bytes/int, data to send or length to read
- timeout: int, timeout in milliseconds
Returns:
array.array for IN transfers, int (bytes transferred) for OUT transfers
Raises:
- USBTimeoutError: Control transfer timed out
- USBError: Control transfer failed
"""Device Reset and Recovery
Reset devices and manage device state for error recovery.
class Device:
def reset(self):
"""
Reset the device.
Raises:
- USBError: Reset operation failed
"""
def clear_halt(self, endpoint):
"""
Clear halt/stall condition for endpoint.
Parameters:
- endpoint: int or Endpoint object, endpoint to clear
Raises:
- USBError: Clear operation failed
"""Kernel Driver Management
Manage kernel driver attachment for proper device access on Linux systems.
class Device:
def detach_kernel_driver(self, interface):
"""
Detach kernel driver from interface.
Parameters:
- interface: int, interface number
Raises:
- USBError: Detach operation failed
"""
def attach_kernel_driver(self, interface):
"""
Attach kernel driver to interface.
Parameters:
- interface: int, interface number
Raises:
- USBError: Attach operation failed
"""
def is_kernel_driver_active(self, interface):
"""
Check if kernel driver is active on interface.
Parameters:
- interface: int, interface number
Returns:
bool: True if kernel driver is active
Raises:
- USBError: Check operation failed
"""Device Properties
Access device descriptor information and attributes.
class Device:
# Device descriptor fields
idVendor: int # Vendor ID
idProduct: int # Product ID
bcdDevice: int # Device release number
iManufacturer: int # Manufacturer string index
iProduct: int # Product string index
iSerialNumber: int # Serial number string index
bNumConfigurations: int # Number of configurations
# USB specification fields
bcdUSB: int # USB specification version
bDeviceClass: int # Device class code
bDeviceSubClass: int # Device sub-class code
bDeviceProtocol: int # Device protocol code
bMaxPacketSize0: int # Maximum packet size for endpoint 0
# Property accessors for string descriptors
@property
def langids(self):
"""Get list of supported language ID codes."""
@property
def serial_number(self):
"""Get device serial number string descriptor."""
@property
def product(self):
"""Get device product string descriptor."""
@property
def manufacturer(self):
"""Get device manufacturer string descriptor."""
@property
def parent(self):
"""Get parent device (for composite devices)."""
@property
def backend(self):
"""Get backend object being used by this device."""Usage Examples
Basic Device Communication
import usb.core
import usb.util
# Find and configure device
device = usb.core.find(idVendor=0x1234, idProduct=0x5678)
device.set_configuration()
# Get endpoint for communication
config = device.get_active_configuration()
interface = config.interfaces()[0]
endpoint = interface.endpoints()[0]
# Read data
try:
data = device.read(endpoint.bEndpointAddress, 64, timeout=1000)
print(f"Received: {data}")
except usb.core.USBTimeoutError:
print("Read timeout")
# Write data (if endpoint supports output)
if usb.util.endpoint_direction(endpoint.bEndpointAddress) == usb.util.ENDPOINT_OUT:
written = device.write(endpoint.bEndpointAddress, b'Hello Device!', timeout=1000)
print(f"Sent {written} bytes")Control Transfer Example
import usb.core
import usb.util
device = usb.core.find(idVendor=0x1234, idProduct=0x5678)
# Device-specific control request
result = device.ctrl_transfer(
bmRequestType=usb.util.build_request_type(
usb.util.CTRL_IN,
usb.util.CTRL_TYPE_VENDOR,
usb.util.CTRL_RECIPIENT_DEVICE
),
bRequest=0x01, # Custom request
wValue=0x0000,
wIndex=0x0000,
data_or_wLength=64
)
print(f"Control transfer result: {result}")Kernel Driver Management
import usb.core
device = usb.core.find(idVendor=0x1234, idProduct=0x5678)
interface_num = 0
# Check and detach kernel driver if active
if device.is_kernel_driver_active(interface_num):
print("Detaching kernel driver")
device.detach_kernel_driver(interface_num)
try:
# Perform device operations
device.set_configuration()
# ... device communication ...
finally:
# Reattach kernel driver
device.attach_kernel_driver(interface_num)Install with Tessl CLI
npx tessl i tessl/pypi-pyusb