Library Overview

The Facedancer library may be somewhat overwhelming at first but the modules can be broken down into a number of clearly delineated categories:

Core USB Device Model

These packages contain the functionality used to define devices and their organisation closely mirrors the hierarchical USB device model:

+--------------------------------+
| USB Device                     |
|   - Device Descriptor          |
|   - Configuration Descriptor   |
|      - Interface Descriptor    |     +----------------------------------+
|         - Endpoint Descriptor  |     | Host                             |
|           - Request Handler    | --> |   - Function                     |
|         - Endpoint Descriptor  |     |                                  |
|           - Request Handler    | <-- |   - Function                     |
|   - Control Interface          |     |                                  |
|      - Request Handlers        | <-> |   - Enumeration, Status, Command |
+--------------------------------+     +----------------------------------+

(simplified diagram for didactic purposes, not drawn to scale)

• facedancer.device

  – USBDevice is the device root. It is responsible for managing the device’s descriptors and marshalling host requests.

• facedancer.configuration

  – USBConfiguration is responsible for managing the device’s configuration descriptor(s).

• facedancer.interface

  – USBInterface is responsible for managing the device’s interface descriptor(s).

• facedancer.endpoint

  – USBEndpoint is responsible for managing the device’s endpoints.

• facedancer.request

  – USBControlRequest is responsible for managing USB control transfers.

In addition to the core device model there are also two modules containing support functionality:

• facedancer.descriptor

  – contains functionality for working with USB descriptors.

• facedancer.magic

  – contains functionality for Facedancer’s declarative device definition syntax.

Device Emulation Support

These modules contain a small selection of example USB device classes and device emulations.

• facedancer.classes

• facedancer.devices

USB Proxy

These modules contain the USB Proxy implementation.

• facedancer.proxy

  – contains the USBProxyDevice implementation.

• facedancer.filters

  – contains a selection of filters to intercept, view or modify proxied USB transfers.

Facedancer Board Backends

Contains backend implementations for the various supported Facedancer boards.

• facedancer.backends

Supporting Functionality

• facedancer.core

  – the Facedancer scheduler and execution core.

• facedancer.errors

  – an error type, there should probably be more.

• facedancer.types

  – various type definitions and constants.

• facedancer.logging

  – logging boilerplate.