facedancer package

Subpackages

Submodules

Module contents

class facedancer.DeviceSpeed(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

FULL = 2

HIGH = 3

LOW = 1

SUPER = 4

SUPER_PLUS = 5

UNKNOWN = 0

class facedancer.LanguageIDs(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

AFRIKAANS = 1078

ALBANIAN = 1052

ARABIC_ALGERIA = 5121

ARABIC_BAHRAIN = 15361

ARABIC_EGYPT = 3073

ARABIC_IRAQ = 2049

ARABIC_JORDAN = 11265

ARABIC_KUWAIT = 13313

ARABIC_LEBANON = 12289

ARABIC_LIBYA = 4097

ARABIC_MOROCCO = 6145

ARABIC_OMAN = 8193

ARABIC_QATAR = 16385

ARABIC_SAUDI_ARABIA = 1025

ARABIC_SYRIA = 10241

ARABIC_TUNISIA = 7169

ARABIC_UAE = 14337

ARABIC_YEMEN = 9217

ARMENIAN = 1067

ASSAMESE = 1101

AZERI_CYRILLIC = 2092

AZERI_LATIN = 1068

BASQUE = 1069

BELARUSSIAN = 1059

BENGALI = 1093

BULGARIAN = 1026

BURMESE = 1109

CATALAN = 1027

CHINESE_HONG_KONG = 3076

CHINESE_MACAU_SAR = 5124

CHINESE_PRC = 2052

CHINESE_SINGAPORE = 4100

CHINESE_TAIWAN = 1028

CROATIAN = 1050

CZECH = 1029

DANISH = 1030

DUTCH_BELGIUM = 2067

DUTCH_NETHERLANDS = 1043

ENGLISH_AUSTRALIAN = 3081

ENGLISH_BELIZE = 10249

ENGLISH_CANADIAN = 4105

ENGLISH_CARIBBEAN = 9225

ENGLISH_IRELAND = 6153

ENGLISH_JAMAICA = 8201

ENGLISH_NEW_ZEALAND = 5129

ENGLISH_PHILIPPINES = 13321

ENGLISH_SOUTH_AFRICA = 7177

ENGLISH_TRINIDAD = 11273

ENGLISH_UNITED_KINGDOM = 2057

ENGLISH_US = 1033

ENGLISH_ZIMBABWE = 12297

ESTONIAN = 1061

FAEROESE = 1080

FARSI = 1065

FINNISH = 1035

FRENCH_BELGIAN = 2060

FRENCH_CANADIAN = 3084

FRENCH_LUXEMBOURG = 5132

FRENCH_MONACO = 6156

FRENCH_STANDARD = 1036

FRENCH_SWITZERLAND = 4108

GEORGIAN = 1079

GERMAN_AUSTRIA = 3079

GERMAN_LIECHTENSTEIN = 5127

GERMAN_LUXEMBOURG = 4103

GERMAN_STANDARD = 1031

GERMAN_SWITZERLAND = 2055

GREEK = 1032

GUJARATI = 1095

HEBREW = 1037

HID_USAGE_DATA_DESCRIPTOR = 1279

HID_VENDOR_DEFINED_1 = 61695

HID_VENDOR_DEFINED_2 = 62719

HID_VENDOR_DEFINED_3 = 63743

HID_VENDOR_DEFINED_4 = 64767

HINDI = 1081

HUNGARIAN = 1038

ICELANDIC = 1039

INDONESIAN = 1057

ITALIAN_STANDARD = 1040

ITALIAN_SWITZERLAND = 2064

JAPANESE = 1041

KANNADA = 1099

KASHMIRI_INDIA = 2144

KAZAKH = 1087

KONKANI = 1111

KOREAN = 1042

KOREAN_JOHAB = 2066

LATVIAN = 1062

LITHUANIAN = 1063

LITHUANIAN_CLASSIC = 2087

MACEDONIAN = 1071

MALAYALAM = 1100

MALAY_BRUNEI_DARUSSALAM = 2110

MALAY_MALAYSIAN = 1086

MANIPURI = 1112

MARATHI = 1102

NEPALI_INDIA = 2145

NORWEGIAN_BOKMAL = 1044

NORWEGIAN_NYNORSK = 2068

ORIYA = 1096

POLISH = 1045

PORTUGUESE_BRAZIL = 1046

PORTUGUESE_STANDARD = 2070

PUNJABI = 1094

ROMANIAN = 1048

RUSSIAN = 1049

SANSKRIT = 1103

SERBIAN_CYRILLIC = 3098

SERBIAN_LATIN = 2074

SINDHI = 1113

SLOVAK = 1051

SLOVENIAN = 1060

SPANISH_ARGENTINA = 11274

SPANISH_BOLIVIA = 16394

SPANISH_CHILE = 13322

SPANISH_COLOMBIA = 9226

SPANISH_COSTA_RICA = 5130

SPANISH_DOMINICAN_REPUBLIC = 7178

SPANISH_ECUADOR = 12298

SPANISH_EL_SALVADOR = 17418

SPANISH_GUATEMALA = 4106

SPANISH_HONDURAS = 18442

SPANISH_MEXICAN = 2058

SPANISH_MODERN_SORT = 3082

SPANISH_NICARAGUA = 19466

SPANISH_PANAMA = 6154

SPANISH_PARAGUAY = 15370

SPANISH_PERU = 10250

SPANISH_PUERTO_RICO = 20490

SPANISH_TRADITIONAL_SORT = 1034

SPANISH_URUGUAY = 14346

SPANISH_VENEZUELA = 8202

SUTU = 1072

SWAHILI_KENYA = 1089

SWEDISH = 1053

SWEDISH_FINLAND = 2077

TAMIL = 1097

TATAR_TATARSTAN = 1092

TELUGU = 1098

THAI = 1054

TURKISH = 1055

UKRAINIAN = 1058

URDU_INDIA = 2080

URDU_PAKISTAN = 1056

UZBEK_CYRILLIC = 2115

UZBEK_LATIN = 1091

VIETNAMESE = 1066

class facedancer.StringRef(index: int = None, string: str = None)[source]

Bases: object

Class representing a reference to a USB string descriptor.

classmethod ensure(value)[source]: Turn a value into a StringRef it is not one already.

classmethod field(**kwargs)[source]: Used to create StringRef fields in dataclasses.

generate_code()[source]: Generate input that will produce this StringRef when passed to ensure()

classmethod lookup(strings: Dict[int, str], index: int)[source]: Try to construct a StringRef given an index and a mapping

class facedancer.USBClassDescriptor(*, raw: bytes, type_number: int = None, number: int = None, parent: USBDescribable = None, include_in_config: bool = True)[source]

Bases: USBDescriptor

Class for arbitrary USB Class descriptors.

include_in_config: bool = True

class facedancer.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>)[source]

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)[source]: Adds an interface to the configuration.

property attributes: Retrives the “attributes” composite word.

configuration_string: StringRef = None

classmethod from_binary_descriptor(data, strings={})[source]

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)[source]

get_descriptor() → bytes[source]: Returns this configuration’s configuration descriptor, including subordinates.

get_device()[source]: Returns a reference to the associated device.

get_endpoint(number: int, direction: USBDirection) → USBEndpoint[source]

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[source]

Returns a unique integer identifier for this object.

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

get_interfaces() → Iterable[USBInterface][source]: Returns an iterable over all interfaces on the provided device.

handle_buffer_empty(endpoint: USBEndpoint)[source]

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)[source]

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)[source]

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

class facedancer.USBControlRequest(direction: USBDirection, type: USBRequestType, recipient: USBRequestRecipient, number: int, value: int, index: int, length: int, data: bytes = b'', device: USBDescribable = None)[source]

Bases: object

Class encapsulating a USB control request.

TODO: document parameters

ack(*, blocking: bool = False)[source]

Acknowledge the given request without replying.

Convenience alias for .acknowledge().

Parameters:: blocking – If true, the relevant control request will complete before returning.

acknowledge(*, blocking: bool = False)[source]

Acknowledge the given request without replying.

Parameters:: blocking – If true, the relevant control request will complete before returning.

data: bytes = b''

device: USBDescribable = None

direction: USBDirection

classmethod from_raw_bytes(raw_bytes: bytes, *, device=None)[source]

Creates a request object from a sequence of raw bytes.

Parameters:

raw_bytes – The raw bytes to create the object from.
device – The USBDevice to associate with the given request. Optional, but necessary to use the .reply() / .acknowledge() methods.

get_direction() → USBDirection[source]

get_recipient() → USBRequestRecipient[source]

get_type() → USBRequestType[source]

index: int

property index_high: int

property index_low: int

length: int

number: int

raw() → bytes[source]: Returns the raw bytes that compose the request.

recipient: USBRequestRecipient

reply(data: bytes)[source]: Replies to the given request with a given set of bytes.

property request: int

property request_type: int: Fetches the whole request_type byte.

stall()[source]

Stalls the associated device’s control request.

Used to indicate that a given request isn’t supported; or isn’t supported with the provided arguments.

type: USBRequestType

value: int

property value_high: int

property value_low: int

class facedancer.USBDescriptor(*, raw: bytes, type_number: int = None, number: int = None, parent: USBDescribable = None, include_in_config: bool = False)[source]

Bases: USBDescribable, AutoInstantiable

Class for arbitrary USB descriptors; minimal concrete implementation of USBDescribable.

__call__(index=0)[source]: Converts the descriptor object into raw bytes.

classmethod from_binary_descriptor(data, strings={})[source]: Attempts to create a USBDescriptor subclass from the given raw descriptor data.

generate_code(name=None, indent=0)[source]

get_identifier()[source]

Returns a unique integer identifier for this object.

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

include_in_config: bool = False

number: int = None: Parent object which this descriptor is associated with.

parent: USBDescribable = None: Whether this descriptor should be included in a GET_CONFIGURATION response.

raw: bytes: The bDescriptorType of the descriptor.

type_number: int = None: Number to request this descriptor with a GET_DESCRIPTOR request.

class facedancer.USBDescriptorTypeNumber(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

CONFIGURATION = 2

DEVICE = 1

DEVICE_QUALIFIER = 6

ENDPOINT = 5

HID = 33

INTERFACE = 4

INTERFACE_POWER = 8

OTHER_SPEED_CONFIGURATION = 7

REPORT = 34

STRING = 3

class facedancer.USBDevice(*, name: str = 'generic device', device_class: int = 0, device_subclass: int = 0, protocol_revision_number: int = 0, max_packet_size_ep0: int = 64, vendor_id: int = 24843, product_id: int = 18003, manufacturer_string: ~facedancer.descriptor.StringRef = <factory>, product_string: ~facedancer.descriptor.StringRef = <factory>, serial_number_string: ~facedancer.descriptor.StringRef = <factory>, supported_languages: tuple = (LanguageIDs.ENGLISH_US,), device_revision: int = 0, usb_spec_version: int = 512, device_speed: ~facedancer.types.DeviceSpeed = None, requestable_descriptors: ~typing.Dict[tuple[int, int], bytes | callable] = <factory>, configurations: ~typing.Dict[int, ~facedancer.configuration.USBConfiguration] = <factory>, backend: ~facedancer.core.FacedancerUSBApp = None)[source]

Bases: USBBaseDevice

Class representing the behavior of a USB device.

This default implementation provides standard request handlers in order to facilitate creating a host-compatible USB device.

These functions can be overloaded to change their behavior. If you want to dramatically change the behavior of these requests, you can opt to use USBBaseDevice, which lacks standard request handling.

Fields:

device_class/device_subclass/protocol_revision_number –: The USB descriptor fields that select the class, subclass, and protcol.
vendor_id, product_id –: The USB vendor and product ID for this device.
manufacturer_string, product_string, serial_number_string –: Python strings identifying the device to the USB host.
supported_languages –: A tuple containing all of the language IDs supported by the device.
device_revision –: Number indicating the hardware revision of this device. Typically BCD.
usb_spec_revision –: Number indicating the version of the USB specification we adhere to. Typically 0x0200.

generate_code(name='Device')[source]

handle_clear_feature_request = <ControlRequestHandler wrapping USBDevice.handle_clear_feature_request at 0x7f80aa9ad640

handle_get_configuration_request = <ControlRequestHandler wrapping USBDevice.handle_get_configuration_request at 0x7f80aa9ae630

handle_get_descriptor_request = <ControlRequestHandler wrapping USBDevice.handle_get_descriptor_request at 0x7f80aa9ae0c0

handle_get_status_request = <ControlRequestHandler wrapping USBDevice.handle_get_status_request at 0x7f80aa9acfe0

handle_set_address_request = <ControlRequestHandler wrapping USBDevice.handle_set_address_request at 0x7f80aa9adcd0

handle_set_configuration_request = <ControlRequestHandler wrapping USBDevice.handle_set_configuration_request at 0x7f80aa9ae900

handle_set_descriptor_request = <ControlRequestHandler wrapping USBDevice.handle_set_descriptor_request at 0x7f80aa9ae390

handle_set_feature_request = <ControlRequestHandler wrapping USBDevice.handle_set_feature_request at 0x7f80aa9ad850

handle_synch_frame_request = <ControlRequestHandler wrapping USBDevice.handle_synch_frame_request at 0x7f80aa9aeb70

class facedancer.USBDirection(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Class representing USB directions.

IN = 1

OUT = 0

classmethod from_endpoint_address(address)[source]: Helper method that extracts the direction from an endpoint address.

classmethod from_request_type(request_type_int)[source]: Helper method that extracts the direction from a request_type integer.

is_in()[source]

is_out()[source]

classmethod parse(value)[source]: Helper that converts a numeric field into a direction.

reverse()[source]: Returns the reverse of the given direction.

to_endpoint_address(endpoint_number)[source]: Helper method that converts and endpoint_number to an address, given direction.

token()[source]: Generates the token corresponding to the given direction.

class facedancer.USBEndpoint(*, number: int, direction: ~facedancer.types.USBDirection, transfer_type: ~facedancer.types.USBTransferType = USBTransferType.BULK, synchronization_type: ~facedancer.types.USBSynchronizationType = USBSynchronizationType.NONE, usage_type: ~facedancer.types.USBUsageType = USBUsageType.DATA, max_packet_size: int = 64, interval: int = 0, extra_bytes: bytes = b'', attached_descriptors: ~typing.List[~facedancer.descriptor.USBDescriptor] = <factory>, requestable_descriptors: ~typing.Dict[tuple[int, int], ~facedancer.descriptor.USBDescriptor] = <factory>, parent: ~facedancer.descriptor.USBDescribable = None)[source]

Bases: USBDescribable, AutoInstantiable, USBRequestHandler

Class representing a USBEndpoint object.

Field:

number:: The endpoint number (without the direction bit) for this endpoint.
direction:: A USBDirection constant indicating this endpoint’s direction.
transfer_type:: A USBTransferType constant indicating the type of communications used.
max_packet_size:: The maximum packet size for this endpoint.
interval:: The polling interval, for an INTERRUPT endpoint.

DESCRIPTOR_TYPE_NUMBER = 5

add_descriptor(descriptor: USBDescriptor)[source]: Adds the provided descriptor to the endpoint.

property address: Fetches the address for the given endpoint.

static address_for_number(endpoint_number: int, direction: USBDirection) → int[source]: Computes the endpoint address for a given number + direction.

attached_descriptors: List[USBDescriptor]

property attributes: Fetches the attributes for the given endpoint, as a single byte.

direction: USBDirection

extra_bytes: bytes = b''

classmethod from_binary_descriptor(data, strings={})[source]: Creates an endpoint object from a description of that endpoint.

generate_code(name=None, indent=0)[source]

get_address()[source]: Method alias for the address property. For backend support.

get_descriptor() → bytes[source]: Get a descriptor string for this endpoint.

get_device()[source]: Returns the device associated with the given descriptor.

get_identifier() → int[source]

Returns a unique integer identifier for this object.

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

handle_buffer_empty()[source]: Handler called when this endpoint first has an empty buffer.

handle_clear_feature_request = <ControlRequestHandler wrapping USBEndpoint.handle_clear_feature_request at 0x7f80aa9ac560

handle_data_received(data: bytes)[source]

Handler for receipt of non-control request data.

Parameters:: data – The raw bytes received.

handle_data_requested()[source]: Handler called when the host requests data on this endpoint.

interval: int = 0

matches_identifier(other: int) → bool[source]

max_packet_size: int = 64

number: int

parent: USBDescribable = None

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

send(data: bytes, *, blocking: bool = False)[source]

Sends data on this endpoint. Valid only for IN endpoints.

Parameters:

data – The data to be sent.
blocking – True if we should block until the backend reports the transmission to be complete.

synchronization_type: USBSynchronizationType = 0

transfer_type: USBTransferType = 2

usage_type: USBUsageType = 0

class facedancer.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)[source]

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)[source]: Adds the provided descriptor to the interface.

add_endpoint(endpoint: USBEndpoint)[source]: 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={})[source]: Generates an interface object from a descriptor.

generate_code(name=None, indent=0)[source]

get_descriptor() → bytes[source]: Retrieves the given interface’s interface descriptor, with subordinates.

get_device()[source]: Returns the device associated with the given descriptor.

get_endpoint(endpoint_number: int, direction: USBDirection) → USBEndpoint[source]

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()[source]: Returns an iterable over all endpoints in this interface.

get_identifier()[source]

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)[source]

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)[source]

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)[source]

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[source]

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[source]

name: StringRef

number: int = 0

parent: USBDescribable = None

protocol_number: int = 0

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

subclass_number: int = 0

class facedancer.USBRequestRecipient(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Enumeration that describes each ‘recipient’ of a USB request field.

DEVICE = 0

ENDPOINT = 2

INTERFACE = 1

OTHER = 3

RESERVED = 4

classmethod from_integer(value)[source]: Special factory that correctly handles reserved values.

classmethod from_request_type(request_type_int)[source]: Helper method that extracts the type from a request_type integer.

class facedancer.USBRequestType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Enumeration that describes each possible Type field for a USB request.

CLASS = 1

RESERVED = 3

STANDARD = 0

VENDOR = 2

classmethod from_request_type(request_type_int)[source]: Helper method that extracts the type from a request_type integer.

class facedancer.USBStandardRequests(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

CLEAR_FEATURE = 1

GET_CONFIGURATION = 8

GET_DESCRIPTOR = 6

GET_INTERFACE = 10

GET_STATUS = 0

SET_ADDRESS = 5

SET_CONFIGURATION = 9

SET_DESCRIPTOR = 7

SET_FEATURE = 3

SET_INTERFACE = 11

SYNCH_FRAME = 12

class facedancer.USBSynchronizationType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

ADAPTIVE = 2

ASYNC = 1

NONE = 0

SYNCHRONOUS = 3

class facedancer.USBTransferType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

BULK = 2

CONTROL = 0

INTERRUPT = 3

ISOCHRONOUS = 1

class facedancer.USBUsageType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

DATA = 0

FEEDBACK = 1

IMPLICIT_FEEDBACK = 2

facedancer.class_request_handler(**kwargs)[source]: Decorator; declares a class request handler. See control_request_handler() for usage.

facedancer.include_in_config(cls)[source]: Decorator that marks a descriptor to be included in configuration data.

facedancer.requestable(type_number, number)[source]: Decorator that marks a descriptor as requestable.

facedancer.standard_request_handler(**kwargs)[source]: Decorator; declares a standard request handler. See control_request_handler() for usage.

facedancer.to_any_endpoint(func)[source]: Decorator; refines a handler so it’s only called on requests with an endpoint recipient.

facedancer.to_any_interface(func)[source]: Decorator; refines a handler so it’s only called on requests with an interface recipient.

facedancer.to_device(func)[source]: Decorator; refines a handler so it’s only called on requests with a device recipient.

facedancer.to_other(func)[source]: Decorator; refines a handler so it’s only called on requests with an Other (TM) recipient.

facedancer.to_this_endpoint(func)[source]: Decorator; refines a handler so it’s only called on requests targeting this endpoint.

facedancer.to_this_interface(func)[source]: Decorator; refines a handler so it’s only called on requests targeting this interface.

facedancer.use_automatically(cls)[source]

Class decorator used to annotate Facedancer inner classes. Implies @dataclass.

This decorator can be placed on inner classes that describe “subordinate” objects on USB devices. For example, a USBDevice can have several subordinate USBConfigurations; which select the various configurations for that class.

When placed on a subordinate class, this allows the parent class to automatically instantiate the relevant given class during its creation; automatically populating the subordinate properties of the relevant device.

For example, assume we have a Facedancer class representing a custom USB device:

class ExampleDevice(USBDevice):
    product_string : str = "My Example Device"

    @use_automatically
    class DefaultConfiguration(USBConfiguration):
        number : int = 1

In this case, when an ExampleDevice is instantiated, the USBDevice code knows how to instantiate DefaultConfiguration, and will do so automatically.

Note that this decorator should _only_ be used for subordinate types; and expects that the decorated class has no explicitly-declared __init__ method. The __post_init__ mechanism of python dataclasses can be overridden to perform any needed initialization.

facedancer.use_inner_classes_automatically(cls)[source]: Decorator that acts as if all inner classes were defined with use_automatically.

facedancer.vendor_request_handler(**kwargs)[source]: Decorator; declares a vendor request handler. See control_request_handler() for usage.