tessl/pypi-pyusb

Easy USB access for Python with backend-neutral, cross-platform support

—

Pending

Overview

Eval results

Files

Control Requests

Name: tessl/pypi-pyusb
Author: tessl

Standard USB control transfer operations for device configuration and status management. The control module provides functions for USB standard requests as defined in the USB specification.

Capabilities

Status Operations

Retrieve and monitor device, interface, or endpoint status.

def get_status(dev, recipient, index=0):
    """
    Get recipient status.
    
    Parameters:
    - dev: Device object
    - recipient: int, recipient type (RECIP_DEVICE, RECIP_INTERFACE, RECIP_ENDPOINT)
    - index: int, interface or endpoint index
    
    Returns:
    int: status value
    
    Raises:
    - USBError: Status request failed
    """

Feature Management

Set and clear device features for power management and functionality control.

def clear_feature(dev, feature, recipient, index=0):
    """
    Clear a recipient feature.
    
    Parameters:
    - dev: Device object
    - feature: int, feature selector (ENDPOINT_HALT, DEVICE_REMOTE_WAKEUP, etc.)
    - recipient: int, recipient type
    - index: int, interface or endpoint index
    
    Raises:
    - USBError: Clear feature request failed
    """

def set_feature(dev, feature, recipient, index=0):
    """
    Set a recipient feature.
    
    Parameters:
    - dev: Device object
    - feature: int, feature selector
    - recipient: int, recipient type
    - index: int, interface or endpoint index
    
    Raises:
    - USBError: Set feature request failed
    """

Descriptor Operations

Retrieve and set device descriptors for configuration and information access.

def get_descriptor(dev, desc_size, desc_type, desc_index, wIndex=0):
    """
    Get a device descriptor.
    
    Parameters:
    - dev: Device object
    - desc_size: int, descriptor size to read
    - desc_type: int, descriptor type (DT_DEVICE, DT_CONFIG, DT_STRING, etc.)
    - desc_index: int, descriptor index
    - wIndex: int, wIndex value for control transfer
    
    Returns:
    array.array: descriptor data
    
    Raises:
    - USBError: Get descriptor request failed
    """

def set_descriptor(dev, desc, desc_type, desc_index, wIndex=None):
    """
    Set a device descriptor.
    
    Parameters:
    - dev: Device object
    - desc: array-like, descriptor data to set
    - desc_type: int, descriptor type
    - desc_index: int, descriptor index
    - wIndex: int, wIndex value for control transfer
    
    Raises:
    - USBError: Set descriptor request failed
    """

Configuration Management

Get and set device configurations for operational state control.

def get_configuration(dev):
    """
    Get device configuration.
    
    Parameters:
    - dev: Device object
    
    Returns:
    int: active configuration value
    
    Raises:
    - USBError: Get configuration request failed
    """

def set_configuration(dev, config):
    """
    Set device configuration.
    
    Parameters:
    - dev: Device object
    - config: int, configuration value to set
    
    Raises:
    - USBError: Set configuration request failed
    """

Interface Management

Get and set interface alternate settings for interface configuration.

def get_interface(dev, bInterfaceNumber):
    """
    Get device interface alternate setting.
    
    Parameters:
    - dev: Device object
    - bInterfaceNumber: int, interface number
    
    Returns:
    int: alternate setting value
    
    Raises:
    - USBError: Get interface request failed
    """

def set_interface(dev, bInterfaceNumber, bAlternateSetting):
    """
    Set device interface alternate setting.
    
    Parameters:
    - dev: Device object
    - bInterfaceNumber: int, interface number
    - bAlternateSetting: int, alternate setting value
    
    Raises:
    - USBError: Set interface request failed
    """

Feature Constants

Standard USB feature selectors for use with set_feature and clear_feature functions.

ENDPOINT_HALT = 0           # Endpoint halt feature
FUNCTION_SUSPEND = 0        # Function suspend feature
DEVICE_REMOTE_WAKEUP = 1    # Device remote wakeup feature
LTM_ENABLE = 50             # Link power management feature

Usage Examples

Basic Status Check

import usb.core
import usb.control

device = usb.core.find(idVendor=0x1234, idProduct=0x5678)

# Get device status
try:
    status = usb.control.get_status(device, usb.control.RECIP_DEVICE)
    print(f"Device status: 0x{status:04x}")
    
    # Check if device is self-powered
    if status & 0x01:
        print("Device is self-powered")
    else:
        print("Device is bus-powered")
        
    # Check remote wakeup capability
    if status & 0x02:
        print("Remote wakeup enabled")
        
except usb.core.USBError as e:
    print(f"Failed to get device status: {e}")

Clear Endpoint Halt

import usb.core
import usb.control
import usb.util

device = usb.core.find(idVendor=0x1234, idProduct=0x5678)
endpoint_addr = 0x81  # IN endpoint 1

try:
    # Clear endpoint halt condition
    usb.control.clear_feature(
        device, 
        usb.control.ENDPOINT_HALT,
        usb.control.RECIP_ENDPOINT,
        endpoint_addr
    )
    print("Endpoint halt cleared")
    
except usb.core.USBError as e:
    print(f"Failed to clear endpoint halt: {e}")

Device Remote Wakeup Management

import usb.core
import usb.control

device = usb.core.find(idVendor=0x1234, idProduct=0x5678)

try:
    # Enable remote wakeup
    usb.control.set_feature(
        device,
        usb.control.DEVICE_REMOTE_WAKEUP,
        usb.control.RECIP_DEVICE
    )
    print("Remote wakeup enabled")
    
    # Later, disable remote wakeup
    usb.control.clear_feature(
        device,
        usb.control.DEVICE_REMOTE_WAKEUP,
        usb.control.RECIP_DEVICE
    )
    print("Remote wakeup disabled")
    
except usb.core.USBError as e:
    print(f"Remote wakeup operation failed: {e}")

Configuration Management

import usb.core
import usb.control

device = usb.core.find(idVendor=0x1234, idProduct=0x5678)

try:
    # Get current configuration
    current_config = usb.control.get_configuration(device)
    print(f"Current configuration: {current_config}")
    
    # Set configuration (usually 1 for single-configuration devices)
    usb.control.set_configuration(device, 1)
    print("Configuration set to 1")
    
except usb.core.USBError as e:
    print(f"Configuration operation failed: {e}")

Interface Alternate Setting

import usb.core
import usb.control

device = usb.core.find(idVendor=0x1234, idProduct=0x5678)
interface_num = 0

try:
    # Get current alternate setting
    alt_setting = usb.control.get_interface(device, interface_num)
    print(f"Interface {interface_num} alternate setting: {alt_setting}")
    
    # Set alternate setting
    usb.control.set_interface(device, interface_num, 1)
    print(f"Interface {interface_num} alternate setting changed to 1")
    
except usb.core.USBError as e:
    print(f"Interface operation failed: {e}")

Descriptor Retrieval

import usb.core
import usb.control

device = usb.core.find(idVendor=0x1234, idProduct=0x5678)

try:
    # Get device descriptor
    device_desc = usb.control.get_descriptor(
        device,
        18,  # Device descriptor size
        usb.control.DT_DEVICE
    )
    print(f"Device descriptor: {device_desc}")
    
    # Get configuration descriptor
    config_desc = usb.control.get_descriptor(
        device,
        9,   # Configuration descriptor size  
        usb.control.DT_CONFIG,
        0    # First configuration
    )
    print(f"Configuration descriptor: {config_desc}")
    
except usb.core.USBError as e:
    print(f"Descriptor retrieval failed: {e}")

String Descriptor Access

import usb.core
import usb.control
import usb.util

device = usb.core.find(idVendor=0x1234, idProduct=0x5678)

try:
    # Get supported language IDs
    langids = usb.util.get_langids(device)
    print(f"Supported language IDs: {langids}")
    
    if langids:
        langid = langids[0]  # Use first supported language
        
        # Get manufacturer string
        if device.iManufacturer:
            manufacturer = usb.util.get_string(device, device.iManufacturer, langid)
            print(f"Manufacturer: {manufacturer}")
            
        # Get product string
        if device.iProduct:
            product = usb.util.get_string(device, device.iProduct, langid)
            print(f"Product: {product}")
            
except usb.core.USBError as e:
    print(f"String descriptor access failed: {e}")

Install with Tessl CLI