usb_protocol.emitters.descriptors.standard module

Convenience emitters for simple, standard descriptors.

class usb_protocol.emitters.descriptors.standard.BinaryObjectStoreDescriptorEmitter(collection=None)

Bases: ComplexDescriptorEmitter

Emitter that creates a BinaryObjectStore descriptor.

DESCRIPTOR_FORMAT: DescriptorFormat = <DescriptorFormat +nonbuild>

SuperSpeedUSBDeviceCapability()

Context manager that allows addition of a SS Device Capability to this Binary Object Store.

It can be used with a with statement; and yields an SuperSpeedUSBDeviceCapabilityDescriptorEmitter that can be populated:

with bos.SuperSpeedUSBDeviceCapability() as e:
    e.wSpeedSupported       = 0b1110
    e.bFunctionalitySupport = 1

This adds the relevant descriptor, automatically.

USB2Extension()

Context manager that allows addition of a USB 2.0 Extension to this Binary Object Store.

It can be used with a with statement; and yields an USB2ExtensionDescriptorEmitter that can be populated:

with bos.USB2Extension() as e:
    e.bmAttributes = 1

This adds the relevant descriptor, automatically.

class usb_protocol.emitters.descriptors.standard.ConfigurationDescriptorEmitter(collection=None)

Bases: ComplexDescriptorEmitter

Emitter that creates a configuration descriptor.

DESCRIPTOR_FORMAT: DescriptorFormat = <DescriptorFormat>

InterfaceDescriptor()

Context manager that allows addition of a subordinate interface descriptor.

It can be used with a with statement; and yields an InterfaceDescriptorEmitter that can be populated:

with interface.InterfaceDescriptor() as d:
    d.bInterfaceNumber = 0x01
    [snip]

This adds the relevant descriptor, automatically. Note that populating derived fields such as bNumEndpoints aren’t necessary; they’ll be populated automatically.

class usb_protocol.emitters.descriptors.standard.DeviceDescriptorCollection(automatic_language_descriptor=True)

Bases: object

Object that builds a full collection of descriptors related to a given USB device.

ConfigurationDescriptor()

Context manager that allows addition of a configuration descriptor.

It can be used with a with statement; and yields an ConfigurationDescriptorEmitter that can be populated:

with collection.ConfigurationDescriptor() as d:
    d.bConfigurationValue = 1
    [snip]

This adds the relevant descriptor, automatically. Note that populating derived fields such as bNumInterfaces aren’t necessary; they’ll be populated automatically.

DEFAULT_SUPPORTED_LANGUAGES = [LanguageIDs.ENGLISH_US]

DeviceDescriptor()

Context manager that allows addition of a device descriptor.

It can be used with a with statement; and yields an DeviceDescriptorEmitter that can be populated:

with collection.DeviceDescriptor() as d:
    d.idVendor  = 0xabcd
    d.idProduct = 0x1234
    [snip]

This adds the relevant descriptor, automatically.

add_descriptor(descriptor, index=0, descriptor_type=None)

Adds a descriptor to our collection.

Parameters:

• descriptor – The descriptor to be added.

• index – The index of the relevant descriptor. Defaults to 0.

• descriptor_type – The type of the descriptor to be added. If None, this is automatically derived from the descriptor contents.

add_language_descriptor(supported_languages=None)

Adds a language descriptor to the list of device descriptors.

Parameters:

supported_languages – A list of languages supported by the device.

ensure_string_field_is_index(field_value)

Processes the given field value; if it’s not an string index, converts it to one.

Non-index-fields are converted to indices using get_index_for_string, which automatically adds the relevant fields to our string descriptor collection.

get_descriptor_bytes(type_number: int, index: int = 0)

Returns the raw, binary descriptor for a given descriptor type/index.

Parameters:

• type_number – The descriptor type number.

• index – The index of the relevant descriptor, if relevant.

get_index_for_string(string)

Returns an string descriptor index for the given string.

If a string descriptor already exists for the given string, its index is returned. Otherwise, a string descriptor is created.

class usb_protocol.emitters.descriptors.standard.EndpointDescriptorEmitter(collection=None)

Bases: ComplexDescriptorEmitter

Emitter that creates an InterfaceDescriptor.

DESCRIPTOR_FORMAT: DescriptorFormat = <DescriptorFormat>

SuperSpeedCompanion()

Context manager that allows addition of a SuperSpeed Companion to this endpoint descriptor.

It can be used with a with statement; and yields an SuperSpeedEndpointCompanionDescriptorEmitter that can be populated:

with endpoint.SuperSpeedEndpointCompanion() as d:
    d.bMaxBurst = 1

This adds the relevant descriptor, automatically.

class usb_protocol.emitters.descriptors.standard.InterfaceDescriptorEmitter(collection=None)

Bases: ComplexDescriptorEmitter

Emitter that creates an InterfaceDescriptor.

DESCRIPTOR_FORMAT: DescriptorFormat = <DescriptorFormat>

EndpointDescriptor(*, add_default_superspeed=False)

Context manager that allows addition of a subordinate endpoint descriptor.

It can be used with a with statement; and yields an EndpointDesriptorEmitter that can be populated:

with interface.EndpointDescriptor() as d:
    d.bEndpointAddress = 0x01
    d.bmAttributes     = 0x80
    d.wMaxPacketSize   = 64
    d.bInterval        = 0

This adds the relevant descriptor, automatically.

class usb_protocol.emitters.descriptors.standard.SuperSpeedDeviceDescriptorCollection(automatic_descriptors=True)

Bases: DeviceDescriptorCollection

Object that builds a full collection of descriptors related to a given USB3 device.

BOSDescriptor()

Context manager that allows addition of a Binary Object Store descriptor.

It can be used with a with statement; and yields an BinaryObjectStoreDescriptorEmitter that can be populated:

with collection.BOSDescriptor() as d:
    [snip]

This adds the relevant descriptor, automatically. Note that populating derived fields such as bNumDeviceCaps aren’t necessary; they’ll be populated automatically.

add_default_bos_descriptor()

Adds a default, empty BOS descriptor.

usb_protocol.emitters.descriptors.standard.get_string_descriptor(string)

Generates a string descriptor for the relevant string.