facedancer.interface module

Functionality for defining USB interfaces.

class facedancer.interface.USBInterface(*, name: ~facedancer.descriptor.StringRef = <factory>, number: int = 0, alternate: int = 0, class_number: int = 0, subclass_number: int = 0, protocol_number: int = 0, interface_string: str = None, attached_descriptors: ~typing.List[~facedancer.descriptor.USBDescriptor] = <factory>, requestable_descriptors: ~typing.Dict[tuple[int, int], ~facedancer.descriptor.USBDescriptor] = <factory>, endpoints: ~typing.Dict[int, ~facedancer.endpoint.USBEndpoint] = <factory>, parent: ~facedancer.descriptor.USBDescribable = None)

Bases: USBDescribable, AutoInstantiable, USBRequestHandler

Class representing a USBDevice interface.

Fields:

number :

The interface’s index. Zero indexed.

class_number, subclass_number, protocol_number :

The USB class adhered to on this interface; usually a USBDeviceClass constant.

interface_string :

A short, descriptive string used to identify the endpoint; or None if not provided.

DESCRIPTOR_TYPE_NUMBER = 4

add_descriptor(descriptor: USBDescriptor)

Adds the provided descriptor to the interface.

add_endpoint(endpoint: USBEndpoint)

Adds the provided endpoint to the interface.

alternate: int = 0

attached_descriptors: List[USBDescriptor]

class_number: int = 0

endpoints: Dict[int, USBEndpoint]

classmethod from_binary_descriptor(data, strings={})

Generates an interface object from a descriptor.

generate_code(name=None, indent=0)

get_descriptor() → bytes

Retrieves the given interface’s interface descriptor, with subordinates.

get_device()

Returns the device associated with the given descriptor.

get_endpoint(endpoint_number: int, direction: USBDirection) → USBEndpoint

Attempts to find a subordinate endpoint matching the given number/direction.

Parameters:

• endpoint_number – The endpoint number to search for.

• direction – The endpoint direction to be matched.

Returns:

The matching endpoint; or None if no matching endpoint existed.

get_endpoints()

Returns an iterable over all endpoints in this interface.

get_identifier()

Returns a unique integer identifier for this object.

This is usually the index or address of the relevant USB object.

handle_buffer_empty(endpoint: USBEndpoint)

Handler called when a given endpoint first has an empty buffer.

Often, an empty buffer indicates an opportunity to queue data for sending (‘prime an endpoint’), but doesn’t necessarily mean that the host is planning on reading the data.

This function is called only once per buffer.

handle_data_received(endpoint: USBEndpoint, data: bytes)

Handler for receipt of non-control request data.

Typically, this method will delegate any data received to the appropriate configuration/interface/endpoint. If overridden, the overriding function will receive all data; and can delegate it by calling the .handle_data_received method on self.configuration.

Parameters:

• endpoint_number – The endpoint number on which the data was received.

• data – The raw bytes received on the relevant endpoint.

handle_data_requested(endpoint: USBEndpoint)

Handler called when the host requests data on a non-control endpoint.

Typically, this method will delegate the request to the appropriate interface+endpoint. If overridden, the overriding function will receive all data.

Parameters:

endpoint_number – The endpoint number on which the host requested data.

handle_get_descriptor_request = <ControlRequestHandler wrapping USBInterface.handle_get_descriptor_request at 0x7f80aa9ac3b0

handle_get_interface_request = <ControlRequestHandler wrapping USBInterface.handle_get_interface_request at 0x7f80aa9acce0

handle_set_interface_request = <ControlRequestHandler wrapping USBInterface.handle_set_interface_request at 0x7f80aa9aca70

has_endpoint(endpoint_number: int, direction: USBDirection) → USBEndpoint

Returns true iff we have matching subordinate endpoint.

Parameters:

• endpoint_number – The endpoint number to search for.

• direction – The endpoint direction to be matched.

interface_string: str = None

matches_identifier(other: int) → bool

name: StringRef

number: int = 0

parent: USBDescribable = None

protocol_number: int = 0

requestable_descriptors: Dict[tuple[int, int], USBDescriptor]

subclass_number: int = 0