Merge pull request #173 from antoinevg/antoinevg/doc-update

Update docs & cli to help prevent folk from trying to run Facedancer on Windows.

cynthion/python/src/commands/cynthion_flash.py

@@ -7,7 +7,7 @@
 
 """ Cynthion 'flash' command. """
 
-import logging
+import logging, platform, sys
 
 from .util import find_cynthion_asset, find_cynthion_bitstream
 from .util import flash_bitstream, flash_mcu_firmware, flash_soc_firmware
@@ -23,6 +23,14 @@ def cynthion_flash(device, args):
     elif args.target == "analyzer":
         flash_bitstream(device, find_cynthion_bitstream(device, "analyzer.bit"))
     elif args.target == "facedancer":
+        if platform.system() == "Windows":
+            logging.error("\nFacedancer and USBProxy are not currently supported on Windows.")
+            logging.error("Attempting to use Facedancer or USBProxy on Windows may cause")
+            logging.error("USB analysis to stop working.\n")
+            logging.error("For more information please see the tracking issue:\n")
+            logging.error("  https://github.com/greatscottgadgets/cynthion/issues/170\n")
+            logging.error("Command aborted.")
+            sys.exit(1)
         flash_soc_firmware(device, find_cynthion_asset("moondancer.bin"))
         flash_bitstream(device, find_cynthion_bitstream(device, "facedancer.bit"))
     elif args.target == "selftest":

cynthion/python/src/commands/cynthion_run.py

@@ -7,7 +7,7 @@
 
 """ Cynthion 'run' command. """
 
-import logging, os, subprocess, sys, tempfile
+import logging, os, platform, subprocess, sys, tempfile
 
 from .util  import find_cynthion_asset, find_cynthion_bitstream
 from .util  import flash_soc_firmware, run_bitstream
@@ -21,6 +21,14 @@ def cynthion_run(device, args):
         run_bitstream(device, find_cynthion_bitstream(device, f"analyzer.bit"))
 
     elif args.target == "facedancer":
+        if platform.system() == "Windows":
+            logging.error("\nFacedancer and USBProxy are not currently supported on Windows.")
+            logging.error("Attempting to use Facedancer or USBProxy on Windows may cause")
+            logging.error("USB analysis to stop working.\n")
+            logging.error("For more information please see the tracking issue:\n")
+            logging.error("  https://github.com/greatscottgadgets/cynthion/issues/170\n")
+            logging.error("Command aborted.")
+            sys.exit(1)
         flash_soc_firmware(device, find_cynthion_asset("moondancer.bin"))
         run_bitstream(device, find_cynthion_bitstream(device, f"facedancer.bit"))
 

docs/source/getting_started_facedancer.rst

@@ -2,6 +2,12 @@
 Using Cynthion with Facedancer
 ==============================
 
+.. warning::
+
+   Facedancer is not currently supported on Windows. Attempting to use Facedancer on Windows may cause USB analysis to stop working.
+
+   For more information please see the tracking issue: `#170 <https://github.com/greatscottgadgets/cynthion/issues/170>`__
+
 Before proceeding, please ensure you have completed all steps in the :doc:`getting_started` section.
 
 

docs/source/getting_started_usbproxy.rst

@@ -2,6 +2,12 @@
 Using Cynthion with USB Proxy
 =============================
 
+.. warning::
+
+   USBProxy is not currently supported on Windows. Attempting to use USB Proxy on Windows may cause USB analysis to stop working.
+
+   For more information please see the tracking issue: `#170 <https://github.com/greatscottgadgets/cynthion/issues/170>`__
+
 Before proceeding, please ensure you have completed all steps in the :doc:`getting_started` and :doc:`getting_started_facedancer` sections.