API Reference

relic_usb_host_descriptor_parser

Helper to parse USB descriptors

  • Author(s): Cooper Dalrymple

Implementation Notes

Hardware:

Software and Dependencies:

class relic_usb_host_descriptor_parser.ConfigurationDescriptor(device: usb.core.Device, configuration: int = 0)

Fetch and parse the specified configuration descriptor and its interface and endpoint descriptors from a device.

Parameters:

  • device (usb.core.Device) – The USB device to fetch descriptors from.

  • configuration (int, optional) – The zero-based index of the device configuration to fetch. Defaults to 0.

get_class_identifier(interface: int = 0)

A tuple containing the class and subclass of an interface within this configuration.

Parameters:

interface (int, optional) – The index of the desired interface. Defaults to 0.

property interfaces: tuple

A tuple of the descriptors for the interfaces utilized by this configuration.

property max_power: int

The maximimum power in milliamps that the device can draw from the host.

property value: int

The configuration value which indicates the number for the configuration defined in the firmware of the device.

class relic_usb_host_descriptor_parser.Descriptor(descriptor: bytearray, length: int = None, descriptor_type: int = None)

The base class of a descriptor parser. Validates descriptor data length and type. The constructor will throw a ValueError exception if the data is invalid.

Parameters:

  • descriptor (bytearray) – The descriptor data to validate.

  • length (int, optional) – The length of the descriptor data.

  • descriptor_type (int, optional) – The type of the descriptor data.

class relic_usb_host_descriptor_parser.DeviceDescriptor(device: usb.core.Device)

Fetch and parse all device, configuration, interface, and endpoint descriptors.

Parameters:

device (usb.core.Device) – The USB device to fetch descriptors from.

property configurations: tuple

A tuple of the descriptors for the configurations as ConfigurationDescriptor objects offered by this device.

property device_class: int

The class specification of the device.

property device_subclass: int

The subclass specification of the device.

get_class_identifier(configuration: int = 0, interface: int = 0) → tuple

A tuple of 4 int elements containing the class and subclass of this device as well as the class and subclass of the designated configuration and interface.

Parameters:

  • configuration (int, optional) – The index of the desired device configuration. Defaults to 0.

  • interface (int, optional) – The index of the desired interface within the configuration. Defaults to 0.

property max_packet_size: int

The maximum expected packet size of a report from the default endpoint in bytes.

property protocol: int

The device protocol.

class relic_usb_host_descriptor_parser.EndpointDescriptor(descriptor: bytearray)

Parse the provided endpoint descriptor. This class should only be instantiated by ConfigurationDescriptor.

Parameters:

descriptor (bytearray) – The endpoint descriptor data to parse.

property address: int

The endpoint address.

property attributes: int

The attributes of the endpoint.

property input: bool

Whether or not this endpoint is used for input data.

property interval: int

The expected polling interval of an endpoint. If the device is low-speed or full-speed, the interval is in increments of 1ms. If the device is high-speed, the interval can be calculated using the formula: “2^(interval-1) * 125 µs”.

property max_packet_size: int

The maximum expected packet size of a report from the endpoint in bytes.

property output: bool

Whether or not this endpoint is used for output data.

class relic_usb_host_descriptor_parser.HIDDescriptor(descriptor: bytearray, device: usb.core.Device, interface: int = 0)

Parse the provided HID descriptor. This class should only be instantiated by ConfigurationDescriptor.

Parameters:

descriptor (bytearray) – The HID descriptor data to parse.

property count: int

The count of the HID descriptor.

property country: int

The country of the HID descriptor.

property report_length: int

The length of the HID report derscriptor.

property report_type: int

The type of the HID report descriptor.

property usage_id: int

The ID of the first HID usage.

property usage_page_id: int

The ID of the first HID usage page.

class relic_usb_host_descriptor_parser.InterfaceDescriptor(descriptor: bytearray)

Parse the provided interface descriptor. This class should only be instantiated by ConfigurationDescriptor.

Parameters:

descriptor (bytearray) – The interface descriptor data to parse.

property endpoints: tuple

A tuple of the descriptors for the endpoints utilized by this interface.

get_class_identifier() → tuple

A tuple containing the class and subclass of the interface.

property hid_descriptor: HIDDescriptor

The HID descriptor of the interface if it is an HID-compliant interface. Otherwise, this property will be None.

property in_endpoint: EndpointDescriptor

The first endpoint designated as an input within the interface.

property index: int

The number of the interface in the usb device configuration.

property interface_class: int

The class specification of the interface.

property interface_subclass: int

The subclass specification of the interface.

property out_endpoint: EndpointDescriptor

The first endpoint designated as an output within the interface.

property protocol: int

The interface protocol.