facedancer.core module

class facedancer.core.FacedancerApp(device, verbose=0)[source]

Bases: object

app_name = 'override this'

app_num = 0

classmethod appropriate_for_environment(backend_name=None)[source]

Returns true if the current class is likely to be the appropriate class to connect to a facedancer given the board_name and other environmental factors.

Parameters:: backend_name – The name of the backend, as typically retrieved from the BACKEND environment variable, or None to try figuring things out based on other environmental factors.

classmethod autodetect(verbose=0, quirks=None)[source]

Convenience function that automatically creates the appropriate subclass based on the BOARD environment variable and some crude internal automagic.

Parameters:: verbose – Sets the verbosity level of the relevant app. Increasing this from zero yields progressively more output.

enable()[source]

init_commands()[source]

class facedancer.core.FacedancerBasicScheduler[source]

Bases: object

Most basic scheduler for Facedancer devices– and the schedule which is created implicitly if no other scheduler is provided. Executes each of its tasks in order, over and over.

add_task(callback)[source]

Adds a facedancer task to the scheduler, which will be called repeatedly according to the internal scheduling algorithm

callback: The callback to be scheduled.

do_exit = False

run()[source]: Run the main scheduler stack.

stop()[source]: Stop the scheduler on next loop.

facedancer.core.FacedancerUSBApp(verbose=0, quirks=None)[source]

Convenience function that automatically creates a FacedancerApp based on the BOARD environment variable and some crude internal automagic.

Parameters:: verbose – Sets the verbosity level of the relevant app. Increasing this from zero yields progressively more output.

class facedancer.core.FacedancerUSBHost[source]

Bases: object

Base class for Facedancer host connections– extended to provide actual connections to each host.

ENDPOINT_DIRECTION_IN = 128

ENDPOINT_DIRECTION_OUT = 0

ENDPOINT_TYPE_CONTROL = 0

PID_IN = 1

PID_OUT = 0

PID_SETUP = 2

REQUEST_RECIPIENT_DEVICE = 0

REQUEST_RECIPIENT_ENDPOINT = 2

REQUEST_RECIPIENT_INTERFACE = 1

REQUEST_RECIPIENT_OTHER = 3

REQUEST_TYPE_CLASS = 1

REQUEST_TYPE_RESERVED = 3

REQUEST_TYPE_STANDARD = 0

REQUEST_TYPE_VENDOR = 2

STANDARD_REQUEST_GET_DESCRIPTOR = 6

STANDARD_REQUEST_GET_STATUS = 0

STANDARD_REQUEST_SET_ADDRESS = 5

STANDARD_REQUEST_SET_CONFIGURATION = 9

apply_configuration(index, set_configuration=True)[source]

Applies a device’s configuration. Necessary to use endpoints other: than the control endpoint.

Parameters:

index – The configuration index to apply.
set_configuration – If true, also informs the device of the change. Setting this to false can allow the host to update its view of all endpoints without communicating with the device – e.g. to update the device’s address.

classmethod appropriate_for_environment(backend_name=None)[source]

Returns true if the current class is likely to be the appropriate class to connect to a facedancer given the board_name and other environmental factors.

Parameters:: backend_name – The name of the backend, as typically retrieved from the BACKEND environment variable, or None to try figuring things out based on other environmental factors.

classmethod autodetect(verbose=0, quirks=None)[source]

Convenience function that automatically creates the appropriate subclass based on the BOARD environment variable and some crude internal automagic.

Parameters:: verbose – Sets the verbosity level of the relevant app. Increasing this from zero yields progressively more output.

control_request_in(request_type, recipient, request, value=0, index=0, length=0)[source]

Performs an IN control request.

Parameters:

request_type – Determines if this is a standard, class, or vendor request. Accepts a REQUEST_TYPE_* constant.
recipient – Determines the context in which this command is interpreted. Accepts a REQUEST_RECIPIENT_* constant.
request – The request number to be performed.
value, index – The standard USB request arguments, to be included in the setup packet. Their meaning varies depending on the request.
length – The maximum length of data expected in response, or 0 if we don’t expect any data back.

control_request_out(request_type, recipient, request, value=0, index=0, data=[])[source]

Performs an OUT control request.

Parameters:

request_type – Determines if this is a standard, class, or vendor request. Accepts a REQUEST_TYPE_* constant.
recipient – Determines the context in which this command is interpreted. Accepts a REQUEST_RECIPIENT_* constant.
request – The request number to be performed.
value, index – The standard USB request arguments, to be included in the setup packet. Their meaning varies depending on the request.
data – The data to be transmitted with this control request.

get_configuration_descriptor(index=0, include_subordinates=True)[source]

Returns the device’s configuration descriptor.

Parameters:: include_subordinate – if true, subordinate descriptors will also be returned

get_descriptor(descriptor_type, descriptor_index, language_id, max_length)[source]: Reads up to max_length bytes of a device’s descriptors.

get_device_descriptor(max_length=18)[source]: Returns the device’s device descriptor.

handle_events()[source]

initialize_device(apply_configuration=0, assign_address=0)[source]

Sets up a connection to a directly-attached USB device.

Parameters:

apply_configuration – If non-zero, the configuration with the given index will be applied to the relevant device.
assign_address – If non-zero, the device will be assigned the given address as part of the enumeration/initialization process.

read_ep0_max_packet_size()[source]: Returns the device’s reported maximum packet size on EP0, in a way appropriate for an barely-configured endpoint.

set_address(device_address)[source]

Sets the device’s address.

Note that all endpoints must be set up again after issuing the new address; the easiest way to do this is to call apply_configuration().

Parameters:: device_address – the address to apply to the given device

set_configuration(index)[source]

Sets the device’s active configuration.

Note that this does not configure the host for the given configuration. Most of the time, you probably want apply_configuration, which does.

Parameters:: index – the index of the configuration to apply

facedancer.core.FacedancerUSBHostApp(verbose=0, quirks=None)[source]

Convenience function that automatically creates a FacedancerApp based on the BOARD environment variable and some crude internal automagic.

verbose: Sets the verbosity level of the relevant app. Increasing: this from zero yields progressively more output.