add examples

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}")

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()}")

usb_protocol/emitters/descriptors/__init__.py

@@ -0,0 +1,2 @@
+
+from .standard import *

usb_protocol/types/descriptors/__init__.py

@@ -0,0 +1,2 @@
+
+from .standard import *