diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..0ca44bd --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,45 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + + + +## [3.0.0] - 2024-06-18 +### Added +- Facedancer documentation has been updated and can be found at: [https://facedancer.readthedocs.io](https://facedancer.readthedocs.io) +- A new backend has been added for the Great Scott Gadgets Cynthion. +- Emulations can now set USB device speed on supported boards. + +### Changed +- The Facedancer core API has been rewritten. See the Facedancer documentation for details. +- Some legacy applets have been replaced with new examples based on the modern Facedancer core: + - `facedancer-ftdi.py` => `ftdi-echo.py` + - `facedancer-keyboard.py` => `rubber-ducky.py` + - `facedancer-umass.py` => `mass-storage.py` + +### Fixed +- 64bit LBA support has been added to the `mass-storage.py` example. (Tx @shutingrz!) + +### Removed +- The legacy Facedancer core has been removed. If you're using scripts or training materials that depend on features or APIs removed in `v3.0.x` please use `v2.9.x`. +- All legacy applets not ported to the modern Facedancer core have been removed. + + +## [2.9.0] - 2024-02-09 + +This release is intended as a reference point for anyone who has scripts, training materials etc. that are based on Facedancer `v2.x` features or API's that have been deprecated from `v3` onwards. + +Any future bug-fixes or backports to Facedancer `2.9.x` should use the [`v2.9.x branch`](https://github.com/greatscottgadgets/facedancer/tree/v2.9.x) as the starting point for forks or PR's. + +### Deprecated +- The current Facedancer core will be supersed by the implementation in `future/` with the `v3.0` release. + + +[Unreleased]: https://github.com/greatscottgadgets/facedancer/compare/3.0.0...HEAD +[3.0.0]: https://github.com/greatscottgadgets/facedancer/compare/2.9.0...3.0.0 +[2.9.0]: https://github.com/greatscottgadgets/facedancer/releases/tag/2.9.0 diff --git a/README.md b/README.md index 2aad0b9..a7d2270 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ and some pretty significant new features. Install this package with the following command: - pip install . + pip install facedancer After that you can import the facedancer package as usual: diff --git a/docs/Makefile b/docs/Makefile index f3f9d37..e90f1d6 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,10 +2,10 @@ # # You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SOURCEDIR = source -BUILDDIR = build +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +BUILDDIR = build # Put it first so that "make" without argument is like "make help". help: @@ -13,13 +13,7 @@ help: .PHONY: help Makefile -# api docs -apidocs: - rm -rf source/api_docs/ - sphinx-apidoc -o source/api_docs/ ../facedancer - # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - diff --git a/docs/requirements.txt b/docs/requirements.txt index ae3df67..0357674 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,10 +1,9 @@ +setuptools sphinx==7.2.6 sphinx_rtd_theme==2.0.0 +sphinxcontrib-apidoc readthedocs-sphinx-search==0.3.2 jinja2==3.1.4 # needed to build api docs -prompt_toolkit -pyusb -pyserial -libusb1 +facedancer @ git+https://github.com/greatscottgadgets/facedancer diff --git a/docs/source/api_docs/facedancer.backends.rst b/docs/source/api_docs/facedancer.backends.rst deleted file mode 100644 index 5f41dff..0000000 --- a/docs/source/api_docs/facedancer.backends.rst +++ /dev/null @@ -1,77 +0,0 @@ -facedancer.backends package -=========================== - -Submodules ----------- - -facedancer.backends.MAXUSBApp module ------------------------------------- - -.. automodule:: facedancer.backends.MAXUSBApp - :members: - :undoc-members: - :show-inheritance: - -facedancer.backends.base module -------------------------------- - -.. automodule:: facedancer.backends.base - :members: - :undoc-members: - :show-inheritance: - -facedancer.backends.goodfet module ----------------------------------- - -.. automodule:: facedancer.backends.goodfet - :members: - :undoc-members: - :show-inheritance: - -facedancer.backends.greatdancer module --------------------------------------- - -.. automodule:: facedancer.backends.greatdancer - :members: - :undoc-members: - :show-inheritance: - -facedancer.backends.greathost module ------------------------------------- - -.. automodule:: facedancer.backends.greathost - :members: - :undoc-members: - :show-inheritance: - -facedancer.backends.libusbhost module -------------------------------------- - -.. automodule:: facedancer.backends.libusbhost - :members: - :undoc-members: - :show-inheritance: - -facedancer.backends.moondancer module -------------------------------------- - -.. automodule:: facedancer.backends.moondancer - :members: - :undoc-members: - :show-inheritance: - -facedancer.backends.raspdancer module -------------------------------------- - -.. automodule:: facedancer.backends.raspdancer - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: facedancer.backends - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api_docs/facedancer.classes.hid.rst b/docs/source/api_docs/facedancer.classes.hid.rst deleted file mode 100644 index bb466ca..0000000 --- a/docs/source/api_docs/facedancer.classes.hid.rst +++ /dev/null @@ -1,37 +0,0 @@ -facedancer.classes.hid package -============================== - -Submodules ----------- - -facedancer.classes.hid.descriptor module ----------------------------------------- - -.. automodule:: facedancer.classes.hid.descriptor - :members: - :undoc-members: - :show-inheritance: - -facedancer.classes.hid.keyboard module --------------------------------------- - -.. automodule:: facedancer.classes.hid.keyboard - :members: - :undoc-members: - :show-inheritance: - -facedancer.classes.hid.usage module ------------------------------------ - -.. automodule:: facedancer.classes.hid.usage - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: facedancer.classes.hid - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api_docs/facedancer.classes.rst b/docs/source/api_docs/facedancer.classes.rst deleted file mode 100644 index 318a79c..0000000 --- a/docs/source/api_docs/facedancer.classes.rst +++ /dev/null @@ -1,18 +0,0 @@ -facedancer.classes package -========================== - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - facedancer.classes.hid - -Module contents ---------------- - -.. automodule:: facedancer.classes - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api_docs/facedancer.devices.rst b/docs/source/api_docs/facedancer.devices.rst deleted file mode 100644 index 234af6f..0000000 --- a/docs/source/api_docs/facedancer.devices.rst +++ /dev/null @@ -1,37 +0,0 @@ -facedancer.devices package -========================== - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - facedancer.devices.umass - -Submodules ----------- - -facedancer.devices.ftdi module ------------------------------- - -.. automodule:: facedancer.devices.ftdi - :members: - :undoc-members: - :show-inheritance: - -facedancer.devices.keyboard module ----------------------------------- - -.. automodule:: facedancer.devices.keyboard - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: facedancer.devices - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api_docs/facedancer.devices.umass.rst b/docs/source/api_docs/facedancer.devices.umass.rst deleted file mode 100644 index 9b54d73..0000000 --- a/docs/source/api_docs/facedancer.devices.umass.rst +++ /dev/null @@ -1,29 +0,0 @@ -facedancer.devices.umass package -================================ - -Submodules ----------- - -facedancer.devices.umass.disk\_image module -------------------------------------------- - -.. automodule:: facedancer.devices.umass.disk_image - :members: - :undoc-members: - :show-inheritance: - -facedancer.devices.umass.umass module -------------------------------------- - -.. automodule:: facedancer.devices.umass.umass - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: facedancer.devices.umass - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api_docs/facedancer.filters.rst b/docs/source/api_docs/facedancer.filters.rst deleted file mode 100644 index 6ea2266..0000000 --- a/docs/source/api_docs/facedancer.filters.rst +++ /dev/null @@ -1,37 +0,0 @@ -facedancer.filters package -========================== - -Submodules ----------- - -facedancer.filters.base module ------------------------------- - -.. automodule:: facedancer.filters.base - :members: - :undoc-members: - :show-inheritance: - -facedancer.filters.logging module ---------------------------------- - -.. automodule:: facedancer.filters.logging - :members: - :undoc-members: - :show-inheritance: - -facedancer.filters.standard module ----------------------------------- - -.. automodule:: facedancer.filters.standard - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: facedancer.filters - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api_docs/facedancer.rst b/docs/source/api_docs/facedancer.rst deleted file mode 100644 index 034bc1b..0000000 --- a/docs/source/api_docs/facedancer.rst +++ /dev/null @@ -1,120 +0,0 @@ -facedancer package -================== - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - facedancer.backends - facedancer.classes - facedancer.devices - facedancer.filters - -Submodules ----------- - -facedancer.configuration module -------------------------------- - -.. automodule:: facedancer.configuration - :members: - :undoc-members: - :show-inheritance: - -facedancer.core module ----------------------- - -.. automodule:: facedancer.core - :members: - :undoc-members: - :show-inheritance: - -facedancer.descriptor module ----------------------------- - -.. automodule:: facedancer.descriptor - :members: - :undoc-members: - :show-inheritance: - -facedancer.device module ------------------------- - -.. automodule:: facedancer.device - :members: - :undoc-members: - :show-inheritance: - -facedancer.endpoint module --------------------------- - -.. automodule:: facedancer.endpoint - :members: - :undoc-members: - :show-inheritance: - -facedancer.errors module ------------------------- - -.. automodule:: facedancer.errors - :members: - :undoc-members: - :show-inheritance: - -facedancer.interface module ---------------------------- - -.. automodule:: facedancer.interface - :members: - :undoc-members: - :show-inheritance: - -facedancer.logging module -------------------------- - -.. automodule:: facedancer.logging - :members: - :undoc-members: - :show-inheritance: - -facedancer.magic module ------------------------ - -.. automodule:: facedancer.magic - :members: - :undoc-members: - :show-inheritance: - -facedancer.proxy module ------------------------ - -.. automodule:: facedancer.proxy - :members: - :undoc-members: - :show-inheritance: - -facedancer.request module -------------------------- - -.. automodule:: facedancer.request - :members: - :undoc-members: - :show-inheritance: - -facedancer.types module ------------------------ - -.. automodule:: facedancer.types - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: facedancer - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api_docs/modules.rst b/docs/source/api_docs/modules.rst deleted file mode 100644 index dbbf5d6..0000000 --- a/docs/source/api_docs/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -facedancer -========== - -.. toctree:: - :maxdepth: 4 - - facedancer diff --git a/docs/source/conf.py b/docs/source/conf.py index 7ff48d7..40a9498 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,5 +1,6 @@ -import os, sys, time +import os, pkg_resources, sys, time sys.path.insert(0, os.path.abspath("../../")) +sys.path.insert(0, os.path.abspath('../../facedancer')) import sphinx_rtd_theme @@ -13,7 +14,7 @@ copyright = time.strftime('2018-%Y, Great Scott Gadgets') author = 'Great Scott Gadget' -version = '' +version = pkg_resources.get_distribution('facedancer').version release = '' @@ -32,8 +33,15 @@ 'sphinx.ext.extlinks', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode', + 'sphinxcontrib.apidoc', ] +# configure extension: sphinxcontrib.apidoc +apidoc_module_dir = '../../facedancer' +apidoc_output_dir = 'api_docs' +apidoc_excluded_paths = ['test'] +apidoc_separate_modules = True + # configure extension: extlinks extlinks = { 'repo': ('https://github.com/greatscottgadgets/facedancer/blob/main/%s', '%s'), diff --git a/docs/source/index.rst b/docs/source/index.rst index ed34e0f..28c9f71 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,14 +12,16 @@ Facedancer Documentation using_usb_proxy facedancer_examples +.. toctree:: + :maxdepth: 2 + :caption: Developer Documentation + + howto_facedancer_backend + .. toctree:: :maxdepth: 1 :caption: API Documentation api_docs/modules -.. toctree:: - :maxdepth: 2 - :caption: Developer Documentation - - howto_facedancer_backend +:ref:`genindex` | :ref:`modindex` diff --git a/examples/ftdi-echo.py b/examples/ftdi-echo.py index b50b5ce..eac9eb6 100755 --- a/examples/ftdi-echo.py +++ b/examples/ftdi-echo.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 # -# This file is part of FaceDancer. +# This file is part of Facedancer. # diff --git a/examples/hackrf-info.py b/examples/hackrf-info.py index 88618c7..04f1eb0 100755 --- a/examples/hackrf-info.py +++ b/examples/hackrf-info.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # pylint: disable=unused-wildcard-import, wildcard-import # -# This file is part of FaceDancer. +# This file is part of Facedancer. # from facedancer import * @@ -23,7 +23,7 @@ class HackRF(USBDevice): product_id : int = 0x6089 # Most hosts won't accept a device unless it has a configuration - # and an interface. We'll add some default/empty ones. FaceDancer + # and an interface. We'll add some default/empty ones. Facedancer # provides sane defaults, so we don't need to do anything else! class DefaultConfiguration(USBConfiguration): class DefaultInterface(USBInterface): @@ -65,7 +65,7 @@ def handle_get_version_request(self, request): # failing with "hackrf_version_string_read() failed: Pipe error (-1000)." # # That's a pretty good hint of what it expects. - request.reply(b"Sekret FaceDancer Version") + request.reply(b"Sekret Facedancer Version") @vendor_request_handler(number=18, direction=USBDirection.IN) diff --git a/examples/imperative.py b/examples/imperative.py index b7af76d..c3364f0 100755 --- a/examples/imperative.py +++ b/examples/imperative.py @@ -1,12 +1,12 @@ #!/usr/bin/env python3 # pylint: disable=unused-wildcard-import, wildcard-import # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ Example for using the imperative API. """ # -# The other FaceDancer examples tend to use the declarative API, +# The other Facedancer examples tend to use the declarative API, # as it's more succinct, and typically can be created faster. # # However, the new API still supports an imperative syntax, diff --git a/examples/mass-storage.py b/examples/mass-storage.py old mode 100644 new mode 100755 index 62a5fe7..14607a3 --- a/examples/mass-storage.py +++ b/examples/mass-storage.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 # -# This file is part of FaceDancer. +# This file is part of Facedancer. # import sys diff --git a/examples/minimal.py b/examples/minimal.py old mode 100644 new mode 100755 index 437b5da..0a1a70d --- a/examples/minimal.py +++ b/examples/minimal.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # pylint: disable=unused-wildcard-import, wildcard-import # -# This file is part of FaceDancer. +# This file is part of Facedancer. # import logging diff --git a/examples/rubber-ducky.py b/examples/rubber-ducky.py index 628904b..ba56391 100755 --- a/examples/rubber-ducky.py +++ b/examples/rubber-ducky.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ USB 'Rubber Ducky' example; enters some text via the keyboard module. """ @@ -16,20 +16,8 @@ async def type_letters(): logging.info("Beginning message typing demo...") - # Type ls. - await asyncio.sleep(5) - await device.type_letters('l', 's', '\n') - - # Echo hi. await asyncio.sleep(2) - await device.type_string("echo hi, user\n") - - # Finally, try to pop calc, just for fun. - logging.info("Bonus: trying to pop calc.") - await device.type_string('r', modifiers=KeyboardModifiers.MOD_LEFT_META) - await asyncio.sleep(0.5) - await device.type_string('calc\n') - + await device.type_string("echo Hello, Facedancer!\n") logging.info("Typing complete. Idly handling USB requests.") diff --git a/examples/template.py b/examples/template.py index 7a0e79a..62771ba 100755 --- a/examples/template.py +++ b/examples/template.py @@ -1,9 +1,9 @@ #!/usr/bin/env python3 # pylint: disable=unused-wildcard-import, wildcard-import # -# This file is part of FaceDancer. +# This file is part of Facedancer. # -""" Example template for creating new FaceDancer devices. """ +""" Example template for creating new Facedancer devices. """ import logging @@ -13,11 +13,11 @@ @use_inner_classes_automatically class TemplateDevice(USBDevice): - """ This class is meant to act as a template to help you get acquainted with FaceDancer.""" + """ This class is meant to act as a template to help you get acquainted with Facedancer.""" # # Core 'dataclass' definitions. - # These define the basic way that a FaceDancer device advertises itself to the host. + # These define the basic way that a Facedancer device advertises itself to the host. # # Every one of these is optional. The defaults are relatively sane, so you can mostly # ignore these unless you want to change them! See the other examples for more minimal @@ -45,7 +45,7 @@ class TemplateDevice(USBDevice): # The string descriptors we'll provide for our device. # Note that these should be Python strings, and _not_ bytes. - manufacturer_string : str = "FaceDancer" + manufacturer_string : str = "Facedancer" product_string : str = "Generic USB Device" serial_number_string : str = "S/N 3420E" @@ -264,7 +264,7 @@ def handle_another_request(self, request): # -# FaceDancer ships with a default main() function that you can use to set up and run +# Facedancer ships with a default main() function that you can use to set up and run # your device. It ships with some nice features -- including a ``--suggest`` function # that can suggest pieces of boilerplate code that might be useful in device emulation. # diff --git a/examples/test_minimal.py b/examples/test_minimal.py old mode 100644 new mode 100755 diff --git a/examples/usbproxy.py b/examples/usbproxy.py old mode 100644 new mode 100755 index ecf4214..1bd5e39 --- a/examples/usbproxy.py +++ b/examples/usbproxy.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ USB Proxy example; forwards all USB transactions and logs them to the console. """ diff --git a/facedancer/backends/greatdancer.py b/facedancer/backends/greatdancer.py index 0c47f38..7ffe677 100644 --- a/facedancer/backends/greatdancer.py +++ b/facedancer/backends/greatdancer.py @@ -13,7 +13,7 @@ class GreatDancerApp(FacedancerApp): """ - Backend for using GreatFET devices as FaceDancers. + Backend for using GreatFET devices as Facedancers. """ app_name = "GreatDancer" diff --git a/facedancer/backends/greathost.py b/facedancer/backends/greathost.py index 4836bcc..08bd95d 100644 --- a/facedancer/backends/greathost.py +++ b/facedancer/backends/greathost.py @@ -202,13 +202,13 @@ def device_is_connected(self): def port_is_enabled(self): - """ Returns true iff the FaceDancer host port's enabled. """ + """ Returns true iff the Facedancer host port's enabled. """ status = self._port_status() return bool(status & self.PORT_STATUS_REGISTER_ENABLED_MASK) def port_is_powered(self): - """ Returns true iff the FaceDancer host port's enabled. """ + """ Returns true iff the Facedancer host port's enabled. """ status = self._port_status() return bool(status & self.PORT_STATUS_REGISTER_POWERED_MASK) @@ -226,7 +226,7 @@ def current_device_speed(self, as_string=False): (self._port_status() >> self.PORT_STATUS_REGISTER_SPEED_SHIFT) & \ self.PORT_STATUS_REGISTER_SPEED_MASK - # Translate from a GreatFET format device speed to a FaceDancer one. + # Translate from a GreatFET format device speed to a Facedancer one. port_speed = self.STATUS_REG_SPEED_VALUES[port_speed_raw] if as_string: diff --git a/facedancer/backends/moondancer.py b/facedancer/backends/moondancer.py index 51d87d4..247aa69 100644 --- a/facedancer/backends/moondancer.py +++ b/facedancer/backends/moondancer.py @@ -75,7 +75,7 @@ def __repr__(self): # class MoondancerApp(FacedancerApp, FacedancerBackend): """ - Backend for using Cynthion devices as FaceDancers. + Backend for using Cynthion devices as Facedancers. """ app_name = "Moondancer" diff --git a/facedancer/classes/__init__.py b/facedancer/classes/__init__.py index 81749cc..86bc316 100644 --- a/facedancer/classes/__init__.py +++ b/facedancer/classes/__init__.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ Support code for USB classes. """ diff --git a/facedancer/classes/hid/__init__.py b/facedancer/classes/hid/__init__.py index 4364159..e734f16 100644 --- a/facedancer/classes/hid/__init__.py +++ b/facedancer/classes/hid/__init__.py @@ -1,4 +1,4 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ Code for implementing HID classes. """ diff --git a/facedancer/classes/hid/descriptor.py b/facedancer/classes/hid/descriptor.py index 3239c23..e24b595 100644 --- a/facedancer/classes/hid/descriptor.py +++ b/facedancer/classes/hid/descriptor.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ Code for implementing HID classes. """ diff --git a/facedancer/classes/hid/keyboard.py b/facedancer/classes/hid/keyboard.py index 2a35acf..c2af5f0 100644 --- a/facedancer/classes/hid/keyboard.py +++ b/facedancer/classes/hid/keyboard.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ Helpers for HID keyboards. """ diff --git a/facedancer/classes/hid/usage.py b/facedancer/classes/hid/usage.py index c989333..3282093 100644 --- a/facedancer/classes/hid/usage.py +++ b/facedancer/classes/hid/usage.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ Code for working with HID usages. """ diff --git a/facedancer/configuration.py b/facedancer/configuration.py index c00ca87..31580bf 100644 --- a/facedancer/configuration.py +++ b/facedancer/configuration.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ Functionality for describing USB device configurations. """ diff --git a/facedancer/core.py b/facedancer/core.py index 4fa8002..4262e38 100644 --- a/facedancer/core.py +++ b/facedancer/core.py @@ -122,7 +122,7 @@ def FacedancerUSBHostApp(verbose=0, quirks=None): class FacedancerUSBHost: """ - Base class for FaceDancer host connections-- extended to provide actual + Base class for Facedancer host connections-- extended to provide actual connections to each host. """ diff --git a/facedancer/descriptor.py b/facedancer/descriptor.py index c9642cb..f21cc17 100644 --- a/facedancer/descriptor.py +++ b/facedancer/descriptor.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ Functionality for working with objects with associated USB descriptors. """ diff --git a/facedancer/device.py b/facedancer/device.py index d77eaf8..1774f1f 100644 --- a/facedancer/device.py +++ b/facedancer/device.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ Functionality for defining USB devices. """ @@ -33,7 +33,7 @@ @dataclass class USBBaseDevice(USBDescribable, USBRequestHandler): """ - Base-most class for FaceDancer USB devices. This version is very similar to the USBDevice type, + Base-most class for Facedancer USB devices. This version is very similar to the USBDevice type, except that it does not define _any_ standard handlers. This allows you the freedom to declare whatever standard requests you'd like. @@ -68,7 +68,7 @@ class USBBaseDevice(USBDescribable, USBRequestHandler): vendor_id : int = 0x610b product_id : int = 0x4653 - manufacturer_string : str = "FaceDancer" + manufacturer_string : str = "Facedancer" product_string : str = "Generic USB Device" serial_number_string : str = "S/N 3420E" diff --git a/facedancer/devices/__init__.py b/facedancer/devices/__init__.py index d22c558..db097e9 100644 --- a/facedancer/devices/__init__.py +++ b/facedancer/devices/__init__.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # import sys @@ -11,7 +11,7 @@ from ..logging import configure_default_logging def default_main(device_or_type, *coroutines): - """ Simple, default main for FaceDancer emulation. + """ Simple, default main for Facedancer emulation. Parameters: device_type -- The USBDevice type to emulate. diff --git a/facedancer/devices/ftdi.py b/facedancer/devices/ftdi.py index 6f8f2e9..94555c0 100644 --- a/facedancer/devices/ftdi.py +++ b/facedancer/devices/ftdi.py @@ -1,6 +1,6 @@ # pylint: disable=unused-wildcard-import, wildcard-import # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ Emulation of an FTDI USB-to-serial converter. """ diff --git a/facedancer/devices/keyboard.py b/facedancer/devices/keyboard.py index 8b4e830..e9e3563 100644 --- a/facedancer/devices/keyboard.py +++ b/facedancer/devices/keyboard.py @@ -1,6 +1,6 @@ # pylint: disable=unused-wildcard-import, wildcard-import # -# This file is part of FaceDancer. +# This file is part of Facedancer. # import asyncio diff --git a/facedancer/endpoint.py b/facedancer/endpoint.py index 9cdf451..ed8c83b 100644 --- a/facedancer/endpoint.py +++ b/facedancer/endpoint.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer +# This file is part of Facedancer # """ Functionality for describing USB endpoints. """ diff --git a/facedancer/errors.py b/facedancer/errors.py index 19883e8..967ff42 100644 --- a/facedancer/errors.py +++ b/facedancer/errors.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # class DeviceNotFoundError(IOError): diff --git a/facedancer/filters/base.py b/facedancer/filters/base.py index 08d8bcb..557d19a 100644 --- a/facedancer/filters/base.py +++ b/facedancer/filters/base.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # diff --git a/facedancer/filters/standard.py b/facedancer/filters/standard.py index 65dceb8..079ba33 100644 --- a/facedancer/filters/standard.py +++ b/facedancer/filters/standard.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ Standard filters for USBProxy that should (almost) always be used. """ diff --git a/facedancer/magic.py b/facedancer/magic.py index 12a706f..1a9fe09 100644 --- a/facedancer/magic.py +++ b/facedancer/magic.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ Functionally for automatic instantiations / tracking via decorators. """ @@ -27,7 +27,7 @@ def matches_identifier(self, other: int) -> bool: class AutoInstantiator: """ Simple wrapper class annotated on objects that can be instantiated automatically. - Used for the @use_automatically decorator; which removes a lot of the FaceDancer boilerplate + Used for the @use_automatically decorator; which removes a lot of the Facedancer boilerplate at the cost of being somewhat cryptic. """ @@ -49,7 +49,7 @@ def __call__(self, parent): def use_automatically(cls): - """ Class decorator used to annotate FaceDancer inner classes. Implies @dataclass. + """ Class decorator used to annotate Facedancer inner classes. Implies @dataclass. This decorator can be placed on inner classes that describe "subordinate" objects on USB devices. For example, a USBDevice can have several subordinate @@ -59,7 +59,7 @@ def use_automatically(cls): instantiate the relevant given class during its creation; automatically populating the subordinate properties of the relevant device. - For example, assume we have a FaceDancer class representing a custom USB device:: + For example, assume we have a Facedancer class representing a custom USB device:: @dataclass class ExampleDevice(USBDevice): diff --git a/facedancer/proxy.py b/facedancer/proxy.py index 983d938..0ebef57 100644 --- a/facedancer/proxy.py +++ b/facedancer/proxy.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ USB Proxy implementation. """ diff --git a/facedancer/request.py b/facedancer/request.py index 479e923..21d2196 100644 --- a/facedancer/request.py +++ b/facedancer/request.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ Functionality for declaring and working with USB control requests. """ diff --git a/facedancer/types.py b/facedancer/types.py index 4f85fcf..0ac93b0 100644 --- a/facedancer/types.py +++ b/facedancer/types.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # """ USB types -- defines enumerations that describe standard USB types """ diff --git a/pyproject.toml b/pyproject.toml index b453f0c..44746b0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,35 +4,47 @@ build-backend = "setuptools.build_meta" [project] name = "facedancer" -dynamic = ["version"] +description = "Implement your own USB device in Python, supported by a hardware peripheral such as Cynthion or GreatFET." +license = { text = "BSD" } +readme = "README.md" requires-python = ">=3.8" authors = [ {name = "Great Scott Gadgets", email = "dev@greatscottgadgets.com"}, ] -license = { text = "BSD" } -description = "Implement your own USB device in Python, supported by a hardware peripheral such as Cynthion or GreatFET." -urls = { Source = "https://github.com/greatscottgadgets/facedancer" } -readme = "README.md" + classifiers = [ "Development Status :: 5 - Production/Stable", + "Programming Language :: Python", + "Programming Language :: Python :: 3", + "License :: OSI Approved :: BSD License", + "Operating System :: OS Independent", "Natural Language :: English", "Environment :: Console", "Environment :: Plugins", "Intended Audience :: Developers", "Intended Audience :: Science/Research", - "License :: OSI Approved :: BSD License", - "Operating System :: OS Independent", "Topic :: Scientific/Engineering", "Topic :: Security", - "Programming Language :: Python", - "Programming Language :: Python :: 3", + "Topic :: System :: Hardware :: Universal Serial Bus (USB)", ] + dependencies = [ - "pyusb", "pyserial", "prompt-toolkit", "libusb1", + "pyusb", + "pyserial", + "prompt-toolkit", + "libusb1", ] -[tool.setuptools-git-versioning] -enabled = true +dynamic = ["version"] + +[project.urls] +Documentation = "https://facedancer.readthedocs.io" +Repository = "https://github.com/greatscottgadgets/facedancer" +Issues = "https://github.com/greatscottgadgets/facedancer/issues" [tool.setuptools.package-dir] -facedancer = "facedancer" \ No newline at end of file +facedancer = "facedancer" + +[tool.setuptools-git-versioning] +enabled = true +starting_version = "3.0.0" diff --git a/test/base.py b/test/base.py index fc8843e..54c4578 100644 --- a/test/base.py +++ b/test/base.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # import logging diff --git a/test/device.py b/test/device.py index 35e038a..dd8d076 100644 --- a/test/device.py +++ b/test/device.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # pylint: disable=unused-wildcard-import, wildcard-import # -# This file is part of FaceDancer. +# This file is part of Facedancer. # import logging, random, sys diff --git a/test/test_stress.py b/test/test_stress.py index 80a29c4..ddd96b0 100644 --- a/test/test_stress.py +++ b/test/test_stress.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # import asyncio, logging, random, sys, time diff --git a/test/test_transfers.py b/test/test_transfers.py index ce583f0..3c01c8f 100644 --- a/test/test_transfers.py +++ b/test/test_transfers.py @@ -1,5 +1,5 @@ # -# This file is part of FaceDancer. +# This file is part of Facedancer. # import asyncio, logging, random, sys, time