diff --git a/examples/descriptor_builder.py b/examples/descriptor_builder.py new file mode 100755 index 0000000..e9fd5da --- /dev/null +++ b/examples/descriptor_builder.py @@ -0,0 +1,45 @@ +#!/usr/bin/env python3 +# +# This file is part of usb-protocol. +# +""" Example that builds a device-worth of descriptors using a collection object. """ + +from usb_protocol.emitters.descriptors import DeviceDescriptorCollection + +collection = DeviceDescriptorCollection() + +# Create our device descriptor, and populate it with some fields. +# Many fields have sane/common defaults; and thus can be omitted. +with collection.DeviceDescriptor() as d: + d.idVendor = 0xc001 + d.idProduct = 0xc0de + d.bNumConfigurations = 1 + + d.iManufacturer = "usb-tools" + d.iProduct = "Illegitimate USB Device" + d.iSerialNumber = "123456" + + +# Create our configuration descriptor, and its subordinates. +with collection.ConfigurationDescriptor() as c: + # Here, this is our first configuration, and is automatically assigned number '1'. + + # We'll create a simple interface with a couple of endpoints. + with c.InterfaceDescriptor() as i: + i.bInterfaceNumber = 0 + + # Our endpoints default to bulk; with mostly-sane defaults. + with i.EndpointDescriptor() as e: + e.bEndpointAddress = 0x01 + e.wMaxPacketSize = 512 + + with i.EndpointDescriptor() as e: + e.bEndpointAddress = 0x81 + e.wMaxPacketSize = 512 + + +print("This device's descriptors would look like:") + +# Iterate over all of our descriptors. +for value, index, raw in collection: + print(f" type {value} (index {index}) = {raw}") diff --git a/examples/simple_descriptors.py b/examples/simple_descriptors.py new file mode 100755 index 0000000..e465370 --- /dev/null +++ b/examples/simple_descriptors.py @@ -0,0 +1,45 @@ +#!/usr/bin/env python3 +# +# This file is part of usb-protocol. +# +""" Examples for using the simple descriptor data structures. """ + +from usb_protocol.types.descriptors import StringDescriptor +from usb_protocol.emitters.descriptors import DeviceDescriptorEmitter + +string_descriptor = bytes([ + 40, # Length + 3, # Type + ord('G'), 0x00, + ord('r'), 0x00, + ord('e'), 0x00, + ord('a'), 0x00, + ord('t'), 0x00, + ord(' '), 0x00, + ord('S'), 0x00, + ord('c'), 0x00, + ord('o'), 0x00, + ord('t'), 0x00, + ord('t'), 0x00, + ord(' '), 0x00, + ord('G'), 0x00, + ord('a'), 0x00, + ord('d'), 0x00, + ord('g'), 0x00, + ord('e'), 0x00, + ord('t'), 0x00, + ord('s'), 0x00, + ]) + +# Use our simple StringDescriptor object to parse a binary blob string descriptor. +print(f"Parsing: {string_descriptor}") +parsed = StringDescriptor.parse(string_descriptor) +print(parsed) + +# Create a simple Device Descriptor via an emitter object. +# Our object has sane defaults, so we can skip some fields if we want. +builder = DeviceDescriptorEmitter() +builder.idVendor = 0x1234 +builder.idProduct = 0xabcd +builder.bNumConfigurations = 3 +print(f"Generated device descriptor: {builder.emit()}") diff --git a/usb_protocol/emitters/descriptors/__init__.py b/usb_protocol/emitters/descriptors/__init__.py index e69de29..03d6f27 100644 --- a/usb_protocol/emitters/descriptors/__init__.py +++ b/usb_protocol/emitters/descriptors/__init__.py @@ -0,0 +1,2 @@ + +from .standard import * diff --git a/usb_protocol/types/descriptors/__init__.py b/usb_protocol/types/descriptors/__init__.py index e69de29..03d6f27 100644 --- a/usb_protocol/types/descriptors/__init__.py +++ b/usb_protocol/types/descriptors/__init__.py @@ -0,0 +1,2 @@ + +from .standard import *