├── .gitignore ├── CODE_OF_CONDUCT.md ├── LICENSE ├── README.rst ├── adafruit_usb_descriptor ├── audio.py ├── audio10.py ├── cdc.py ├── cdc.rst ├── hid.py ├── midi.py ├── msc.py ├── standard.py ├── standard.rst ├── util.py └── util.rst ├── api.rst ├── conf.py ├── readthedocs.yml └── requirements.txt /.gitignore: -------------------------------------------------------------------------------- 1 | __pycache__ 2 | _build 3 | *.pyc 4 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to making participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, gender identity and expression, level of experience, 9 | nationality, personal appearance, race, religion, or sexual identity and 10 | orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting the project team at support@adafruit.com. All 59 | complaints will be reviewed and investigated and will result in a response that 60 | is deemed necessary and appropriate to the circumstances. The project team is 61 | obligated to maintain confidentiality with regard to the reporter of an incident. 62 | Further details of specific enforcement policies may be posted separately. 63 | 64 | Project maintainers who do not follow or enforce the Code of Conduct in good 65 | faith may face temporary or permanent repercussions as determined by other 66 | members of the project's leadership. 67 | 68 | ## Attribution 69 | 70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 71 | available at [http://contributor-covenant.org/version/1/4][version] 72 | 73 | [homepage]: http://contributor-covenant.org 74 | [version]: http://contributor-covenant.org/version/1/4/ 75 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2017 Scott Shawcroft for Adafruit Industries 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | *This repo is archived because it is no longer used by CircuitPython. We recommend https://github.com/usb-tools/python-usb-protocol instead.* 2 | 3 | 4 | Introduction 5 | ============ 6 | 7 | .. image:: https://readthedocs.org/projects/adafruit-usb-descriptor/badge/?version=latest 8 | :target: http://adafruit-usb-descriptor.readthedocs.io/en/latest/?badge=latest 9 | :alt: Documentation Status 10 | 11 | .. image :: https://img.shields.io/discord/327254708534116352.svg 12 | :target: https://adafru.it/discord 13 | :alt: Discord 14 | 15 | The `adafruit_usb_descriptor` library provides Python classes that make it 16 | easier to generate a binary USB descriptor. It can be used in place of a series 17 | of C macros. 18 | 19 | Dependencies 20 | ============= 21 | This library has no external dependencies. It only uses Python `struct`. 22 | 23 | Usage Example 24 | ============= 25 | 26 | A current usage example that generates descriptors for use with [TinyUSB](https://github.com/hathach/tinyusb) can be found `here `_ in CircuitPython. 27 | 28 | Contributing 29 | ============ 30 | 31 | Contributions are welcome! Please read our `Code of Conduct 32 | `_ 33 | before contributing to help this project stay welcoming. 34 | 35 | API Reference 36 | ============= 37 | 38 | .. toctree:: 39 | :maxdepth: 2 40 | 41 | api 42 | -------------------------------------------------------------------------------- /adafruit_usb_descriptor/audio.py: -------------------------------------------------------------------------------- 1 | # The MIT License (MIT) 2 | # 3 | # Copyright (c) 2018 Scott Shawcroft for Adafruit Industries 4 | # 5 | # Permission is hereby granted, free of charge, to any person obtaining a copy 6 | # of this software and associated documentation files (the "Software"), to deal 7 | # in the Software without restriction, including without limitation the rights 8 | # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | # copies of the Software, and to permit persons to whom the Software is 10 | # furnished to do so, subject to the following conditions: 11 | # 12 | # The above copyright notice and this permission notice shall be included in 13 | # all copies or substantial portions of the Software. 14 | # 15 | # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 21 | # THE SOFTWARE. 22 | 23 | import struct 24 | 25 | """ 26 | Audio specific descriptors 27 | ================================ 28 | 29 | * Author(s): Scott Shawcroft 30 | """ 31 | 32 | AUDIO_CLASS_DEVICE = 0x01 33 | 34 | AUDIO_SUBCLASS_UNKNOWN = 0x00 35 | AUDIO_SUBCLASS_CONTROL = 0x01 36 | AUDIO_SUBCLASS_AUDIO_STREAMING = 0x02 37 | AUDIO_SUBCLASS_MIDI_STREAMING = 0x03 38 | 39 | AUDIO_PROTOCOL_V1 = 0x0 40 | AUDIO_PROTOCOL_V2 = 0x20 41 | AUDIO_PROTOCOL_V3 = 0x30 42 | -------------------------------------------------------------------------------- /adafruit_usb_descriptor/audio10.py: -------------------------------------------------------------------------------- 1 | # The MIT License (MIT) 2 | # 3 | # Copyright (c) 2018 Scott Shawcroft for Adafruit Industries 4 | # 5 | # Permission is hereby granted, free of charge, to any person obtaining a copy 6 | # of this software and associated documentation files (the "Software"), to deal 7 | # in the Software without restriction, including without limitation the rights 8 | # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | # copies of the Software, and to permit persons to whom the Software is 10 | # furnished to do so, subject to the following conditions: 11 | # 12 | # The above copyright notice and this permission notice shall be included in 13 | # all copies or substantial portions of the Software. 14 | # 15 | # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 21 | # THE SOFTWARE. 22 | 23 | import struct 24 | 25 | from . import standard 26 | 27 | """ 28 | Audio specific descriptors 29 | ================================ 30 | 31 | * Author(s): Scott Shawcroft 32 | """ 33 | 34 | class AudioControlInterface: 35 | """Single interface that includes ``subdescriptors`` such as endpoints. 36 | 37 | ``subdescriptors`` can also include other class and vendor specific 38 | descriptors. They are serialized in order after the `InterfaceDescriptor`. 39 | They have their own bLength, and are not included in this descriptor's bLength. 40 | """ 41 | bDescriptorType = standard.DESCRIPTOR_TYPE_CLASS_SPECIFIC_INTERFACE 42 | bDescriptorSubtype = 0x01 43 | fixed_fmt = " 1: 276 | self._bLength = value[0] 277 | if value[1] != 3: 278 | raise ValueError("Sequence not a StringDescriptor") 279 | self._bString = value[2:2+self.bLength] 280 | 281 | def notes(self): 282 | return [str(self)] 283 | 284 | def __bytes__(self): 285 | return struct.pack("BB{}s".format(len(self._bString)), self.bLength, 286 | self.bDescriptorType, self._bString) 287 | 288 | @property 289 | def bString(self): 290 | return self._bString.decode("utf-16-le") 291 | 292 | @bString.setter 293 | def bString(self, value): 294 | self._bString = value.encode("utf-16-le") 295 | self._bLength = len(self.encoded) + 2 296 | 297 | @property 298 | def bLength(self): 299 | return self._bLength 300 | -------------------------------------------------------------------------------- /adafruit_usb_descriptor/standard.rst: -------------------------------------------------------------------------------- 1 | `adafruit_usb_descriptor.standard` - Standard descriptors 2 | ============================================================= 3 | 4 | This is a good reference: http://www.beyondlogic.org/usbnutshell/usb5.shtml 5 | 6 | * Author(s): Scott Shawcroft 7 | 8 | .. automodule:: adafruit_usb_descriptor.standard 9 | :members: 10 | -------------------------------------------------------------------------------- /adafruit_usb_descriptor/util.py: -------------------------------------------------------------------------------- 1 | # The MIT License (MIT) 2 | # 3 | # Copyright (c) 2017 Scott Shawcroft for Adafruit Industries 4 | # 5 | # Permission is hereby granted, free of charge, to any person obtaining a copy 6 | # of this software and associated documentation files (the "Software"), to deal 7 | # in the Software without restriction, including without limitation the rights 8 | # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | # copies of the Software, and to permit persons to whom the Software is 10 | # furnished to do so, subject to the following conditions: 11 | # 12 | # The above copyright notice and this permission notice shall be included in 13 | # all copies or substantial portions of the Software. 14 | # 15 | # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 21 | # THE SOFTWARE. 22 | 23 | from . import standard 24 | 25 | def join_interfaces(args, *, renumber_endpoints=True): 26 | """Renumbers interfaces and endpoints so they are compatible. 27 | 28 | ``args`` is any number of interface sequences (usually lists with 29 | `InterfaceDescriptor` s inside them). Interfaces within a sequence 30 | should be numbered beginning at 0x0. Endpoints should be numbered per 31 | interface.""" 32 | interfaces = [] 33 | base_endpoint_number = 1 34 | for interface_set in args: 35 | base_interface_number = len(interfaces) 36 | for i, interface in enumerate(interface_set): 37 | interfaces.append(interface) 38 | interface.bInterfaceNumber = interfaces.index(interface) 39 | max_endpoint_address = base_endpoint_number 40 | for subdescriptor in interface.subdescriptors: 41 | endpoint_used = False 42 | if (subdescriptor.bDescriptorType == 43 | standard.EndpointDescriptor.bDescriptorType): 44 | if renumber_endpoints: 45 | endpoint_used = True 46 | subdescriptor.bEndpointAddress += base_endpoint_number 47 | endpoint_address = subdescriptor.bEndpointAddress & 0xf 48 | max_endpoint_address = max(max_endpoint_address, 49 | endpoint_address) 50 | elif subdescriptor.bEndpointAddress == 0: 51 | raise ValueError('Endpoint address must not be 0') 52 | if endpoint_used: 53 | base_endpoint_number = max_endpoint_address + 1 54 | return interfaces 55 | -------------------------------------------------------------------------------- /adafruit_usb_descriptor/util.rst: -------------------------------------------------------------------------------- 1 | `adafruit_usb_descriptor.util` - Utility functions 2 | ============================================================== 3 | 4 | Utility functions 5 | 6 | * Author(s): Scott Shawcroft 7 | 8 | .. automodule:: adafruit_usb_descriptor.util 9 | :members: 10 | -------------------------------------------------------------------------------- /api.rst: -------------------------------------------------------------------------------- 1 | 2 | .. If you created a package, create one automodule per module in the package. 3 | 4 | `adafruit_usb_descriptor` - USB descriptor generation 5 | ======================================================== 6 | 7 | .. module:: adafruit_usb_descriptor 8 | 9 | .. toctree:: 10 | 11 | adafruit_usb_descriptor/core 12 | adafruit_usb_descriptor/standard 13 | adafruit_usb_descriptor/cdc 14 | -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | 3 | import os 4 | import sys 5 | sys.path.insert(0, os.path.abspath('.')) 6 | 7 | # -- General configuration ------------------------------------------------ 8 | 9 | # Add any Sphinx extension module names here, as strings. They can be 10 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 11 | # ones. 12 | extensions = [ 13 | 'sphinx.ext.autodoc', 14 | 'sphinx.ext.intersphinx', 15 | 'sphinx.ext.viewcode', 16 | ] 17 | 18 | intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None),'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)} 19 | 20 | # Add any paths that contain templates here, relative to this directory. 21 | templates_path = ['_templates'] 22 | 23 | source_suffix = '.rst' 24 | 25 | # The master toctree document. 26 | master_doc = 'README' 27 | 28 | # General information about the project. 29 | project = u'Adafruit USB Descriptor Library' 30 | copyright = u'2017 Scott Shawcroft' 31 | author = u'Scott Shawcroft' 32 | 33 | # The version info for the project you're documenting, acts as replacement for 34 | # |version| and |release|, also used in various other places throughout the 35 | # built documents. 36 | # 37 | # The short X.Y version. 38 | version = u'1.0' 39 | # The full version, including alpha/beta/rc tags. 40 | release = u'1.0' 41 | 42 | # The language for content autogenerated by Sphinx. Refer to documentation 43 | # for a list of supported languages. 44 | # 45 | # This is also used if you do content translation via gettext catalogs. 46 | # Usually you set "language" from the command line for these cases. 47 | language = None 48 | 49 | # List of patterns, relative to source directory, that match files and 50 | # directories to ignore when looking for source files. 51 | # This patterns also effect to html_static_path and html_extra_path 52 | exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 53 | 54 | # The reST default role (used for this markup: `text`) to use for all 55 | # documents. 56 | # 57 | default_role = "any" 58 | 59 | # If true, '()' will be appended to :func: etc. cross-reference text. 60 | # 61 | add_function_parentheses = True 62 | 63 | # The name of the Pygments (syntax highlighting) style to use. 64 | pygments_style = 'sphinx' 65 | 66 | # If true, `todo` and `todoList` produce output, else they produce nothing. 67 | todo_include_todos = False 68 | 69 | 70 | # -- Options for HTML output ---------------------------------------------- 71 | 72 | # The theme to use for HTML and HTML Help pages. See the documentation for 73 | # a list of builtin themes. 74 | # 75 | on_rtd = os.environ.get('READTHEDOCS', None) == 'True' 76 | 77 | if not on_rtd: # only import and set the theme if we're building docs locally 78 | try: 79 | import sphinx_rtd_theme 80 | html_theme = 'sphinx_rtd_theme' 81 | html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.'] 82 | except: 83 | html_theme = 'default' 84 | html_theme_path = ['.'] 85 | else: 86 | html_theme_path = ['.'] 87 | 88 | # Add any paths that contain custom static files (such as style sheets) here, 89 | # relative to this directory. They are copied after the builtin static files, 90 | # so a file named "default.css" will overwrite the builtin "default.css". 91 | html_static_path = ['_static'] 92 | 93 | # Output file base name for HTML help builder. 94 | htmlhelp_basename = 'AdafruitUSBDescriptorLibrarydoc' 95 | 96 | # -- Options for LaTeX output --------------------------------------------- 97 | 98 | latex_elements = { 99 | # The paper size ('letterpaper' or 'a4paper'). 100 | # 101 | # 'papersize': 'letterpaper', 102 | 103 | # The font size ('10pt', '11pt' or '12pt'). 104 | # 105 | # 'pointsize': '10pt', 106 | 107 | # Additional stuff for the LaTeX preamble. 108 | # 109 | # 'preamble': '', 110 | 111 | # Latex figure (float) alignment 112 | # 113 | # 'figure_align': 'htbp', 114 | } 115 | 116 | # Grouping the document tree into LaTeX files. List of tuples 117 | # (source start file, target name, title, 118 | # author, documentclass [howto, manual, or own class]). 119 | latex_documents = [ 120 | (master_doc, 'AdafruitUSBDescriptorLibrary.tex', u'Adafruit USB Descriptor Library Documentation', 121 | author, 'manual'), 122 | ] 123 | 124 | # -- Options for manual page output --------------------------------------- 125 | 126 | # One entry per manual page. List of tuples 127 | # (source start file, name, description, authors, manual section). 128 | man_pages = [ 129 | (master_doc, 'adafruitUSBDescriptorlibrary', u'Adafruit USB Descriptor Library Documentation', 130 | [author], 1) 131 | ] 132 | 133 | # -- Options for Texinfo output ------------------------------------------- 134 | 135 | # Grouping the document tree into Texinfo files. List of tuples 136 | # (source start file, target name, title, author, 137 | # dir menu entry, description, category) 138 | texinfo_documents = [ 139 | (master_doc, 'AdafruitUSBDescriptorLibrary', u'Adafruit USB Descriptor Library Documentation', 140 | author, 'AdafruitUSBDescriptorLibrary', 'One line description of project.', 141 | 'Miscellaneous'), 142 | ] 143 | -------------------------------------------------------------------------------- /readthedocs.yml: -------------------------------------------------------------------------------- 1 | requirements_file: requirements.txt 2 | 3 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | 2 | --------------------------------------------------------------------------------