facedancer.configuration module

Functionality for describing USB device configurations.

class facedancer.configuration.USBConfiguration(*, number: int = 1, configuration_string: ~facedancer.descriptor.StringRef = None, max_power: int = 500, self_powered: bool = True, supports_remote_wakeup: bool = True, parent: ~facedancer.descriptor.USBDescribable = None, interfaces: ~facedancer.interface.USBInterface = <factory>)

Bases: USBDescribable, AutoInstantiable, USBRequestHandler

Class representing a USBDevice’s configuration.

Fields:

number:

The configuration’s number; one-indexed.

configuration_string

A string describing the configuration; or None if not provided.

max_power:

The maximum power expected to be drawn by the device when using this interface, in mA. Typically 500mA, for maximum possible.

supports_remote_wakeup:

True iff this device should be able to wake the host from suspend.

DESCRIPTOR_SIZE_BYTES = 9

DESCRIPTOR_TYPE_NUMBER = 2

add_interface(interface: USBInterface)

Adds an interface to the configuration.

property attributes

Retrives the “attributes” composite word.

configuration_string: StringRef = None

classmethod from_binary_descriptor(data, strings={})

Generates a new USBConfiguration object from a configuration descriptor, handling any attached subordinate descriptors.

Parameters:

data – The raw bytes for the descriptor to be parsed.

generate_code(name=None, indent=0)

get_descriptor() → bytes

Returns this configuration’s configuration descriptor, including subordinates.

get_device()

Returns a reference to the associated device.

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

Attempts to find an endpoint with the given number + direction.

Parameters:

• number – The endpoint number to look for.

• direction – Whether to look for an IN or OUT endpoint.

get_identifier() → int

Returns a unique integer identifier for this object.

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

get_interfaces() → Iterable[USBInterface]

Returns an iterable over all interfaces on the provided device.

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 – The endpoint 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 – The endpoint on which the host requested data.

interfaces: USBInterface

max_power: int = 500

number: int = 1

parent: USBDescribable = None

self_powered: bool = True

supports_remote_wakeup: bool = True