Merge pull request #870 from zapta/main

Renamed apio device usb/serial to scan-usb/serial.

Author: zapta

.github/workflows/monitor-apio-latest.yaml

@@ -74,8 +74,8 @@ jobs:
                 apio sim --no-gtkwave
                 apio graph -n
                 apio format
-                apio devices usb
-                apio devices serial
+                apio devices scan-usb
+                apio devices scan-serial
 
                 find .
 
@@ -104,8 +104,8 @@ jobs:
                 apio sim --no-gtkwave
                 apio graph -n
                 apio format
-                apio devices usb
-                apio devices serial
+                apio devices scan-usb
+                apio devices scan-serial
 
                 find .
 
@@ -134,8 +134,8 @@ jobs:
                 apio sim --no-gtkwave
                 apio graph -n
                 apio format
-                apio devices usb
-                apio devices serial
+                apio devices scan-usb
+                apio devices scan-serial
 
                 find .
 

COMMANDS.txt

@@ -56,7 +56,7 @@ Setup commands:
   apio preferences  Manage the apio user preferences.
   apio packages     Manage the apio packages.
   apio drivers      Manage the operating system drivers.
-  apio devices      List attached devices.
+  apio devices      Scan attached devices.
 
 Utility commands:
   apio boards       List available board definitions.
@@ -439,31 +439,30 @@ apio devices
 Usage: apio devices [OPTIONS] COMMAND [ARGS]...
 
   The command group 'apio devices' includes subcommands that lists
-  devices
-  that are attached to the computer. It's main usage is diagnostics or
-  devices connectivity and drivers.
+  devices that are attached to the computer. It's main usage is
+  diagnostics or devices connectivity and drivers.
 
 Options:
   -h, --help  Show this message and exit.
 
 Subcommands:
-  apio devices usb     List USB devices.
-  apio devices serial  List serial devices.
+  apio devices scan-usb     Scan for USB devices.
+  apio devices scan-serial  Scan for serial devices.
 
 
 
 --------------------------------------------
 
-apio devices serial
+apio devices scan-serial
 
-Usage: apio devices serial [OPTIONS]
+Usage: apio devices scan-serial [OPTIONS]
 
-  The command 'apio devices serial' displays the serial devices
-  currently connected to your computer. It is useful for diagnosing FPGA
-  board connectivity issues.
+  The command 'apio devices scan-serial' scans and displays the serial
+  devicescurrently connected to your computer. It is useful for
+  diagnosing FPGA board connectivity issues.
 
   Examples:
-    apio devices serial    # List the serial devices.
+    apio devices scan-serial    # List the serial devices.
 
   Note that devices such as FTDI FTDI2232 that have more than one
   channel are listed as multiple rows, one for each of their serial
@@ -480,16 +479,16 @@ Options:
 
 --------------------------------------------
 
-apio devices usb
+apio devices scan-usb
 
-Usage: apio devices usb [OPTIONS]
+Usage: apio devices scan-usb [OPTIONS]
 
-  The command 'apio devices usb' displays the USB devices currently
-  connected to your computer. It is useful for diagnosing FPGA board
-  connectivity issues.
+  The command 'apio devices scan-usb' scans and display the USB devices
+  currently connected to your computer. It is useful for diagnosing FPGA
+  board connectivity issues.
 
   Examples:
-    apio devices usb    # List the usb devices.
+    apio devices scan-usb    # List the usb devices.
 
 Options:
   -h, --help  Show this message and exit.

apio/commands/apio_devices.py

@@ -23,11 +23,11 @@
 from apio.utils import serial_util, usb_util, util
 
 
-# --- apio devices usb
+# --- apio devices scan-usb
 
 
 def _list_usb_devices(apio_ctx: ApioContext) -> None:
-    """Lists the connected USB devices in table format."""
+    """Scans and display the connected USB devices in table format."""
 
     devices = usb_util.scan_usb_devices(apio_ctx=apio_ctx)
 
@@ -74,25 +74,25 @@ def _list_usb_devices(apio_ctx: ApioContext) -> None:
 
 
 # -- Text in the rich-text format of the python rich library.
-APIO_DEVICES_USB_HELP = """
-The command 'apio devices usb' displays the USB devices currently \
-connected to your computer. It is useful for diagnosing FPGA board \
+APIO_DEVICES_SCAN_USB_HELP = """
+The command 'apio devices scan-usb' scans and display the USB devices \
+currently connected to your computer. It is useful for diagnosing FPGA board \
 connectivity issues.
 
 Examples:[code]
-  apio devices usb    # List the usb devices.[/code]
+  apio devices scan-usb    # List the usb devices.[/code]
 
 """
 
 
 @click.command(
-    name="usb",
+    name="scan-usb",
     cls=ApioCommand,
-    short_help="List USB devices.",
-    help=APIO_DEVICES_USB_HELP,
+    short_help="Scan for USB devices.",
+    help=APIO_DEVICES_SCAN_USB_HELP,
 )
-def _usb_cli():
-    """Implements the 'apio devices usb' command."""
+def _scan_usb_cli():
+    """Implements the 'apio devices scan-usb' command."""
 
     # Create the apio context.
     apio_ctx = ApioContext(
@@ -106,11 +106,11 @@ def _usb_cli():
     sys.exit(0)
 
 
-# -- apio devices serial
+# -- apio devices scan-serial
 
 
 def _list_serial_devices() -> None:
-    """Lists the connected serial devices in table format."""
+    """Scans and displays the connected serial devices in table format."""
 
     devices = serial_util.scan_serial_devices()
 
@@ -157,13 +157,13 @@ def _list_serial_devices() -> None:
 
 
 # -- Text in the rich-text format of the python rich library.
-APIO_DEVICES_SERIAL_HELP = """
-The command 'apio devices serial' displays the serial devices currently \
-connected to your computer. It is useful for diagnosing FPGA board \
+APIO_DEVICES_SCAN_SERIAL_HELP = """
+The command 'apio devices scan-serial' scans and displays the serial devices\
+currently connected to your computer. It is useful for diagnosing FPGA board \
 connectivity issues.
 
 Examples:[code]
-  apio devices serial    # List the serial devices.[/code]
+  apio devices scan-serial    # List the serial devices.[/code]
 
 Note that devices such as FTDI FTDI2232 that have more than one channel \
 are listed as multiple rows, one for each of their serial ports.
@@ -175,13 +175,13 @@ def _list_serial_devices() -> None:
 
 
 @click.command(
-    name="serial",
+    name="scan-serial",
     cls=ApioCommand,
-    short_help="List serial devices.",
-    help=APIO_DEVICES_SERIAL_HELP,
+    short_help="Scan for serial devices.",
+    help=APIO_DEVICES_SCAN_SERIAL_HELP,
 )
-def _serial_cli():
-    """Implements the 'apio devices serial' command."""
+def _scan_serial_cli():
+    """Implements the 'apio devices scan-serial' command."""
 
     # -- Create the apio context. We create it for consistency though
     # -- we don't use .t
@@ -200,8 +200,8 @@ def _serial_cli():
 
 # -- Text in the rich-text format of the python rich library.
 APIO_DEVICES_HELP = """
-The command group 'apio devices' includes subcommands that lists devices
-that are attached to the computer. It's main usage is diagnostics or
+The command group 'apio devices' includes subcommands that lists devices \
+that are attached to the computer. It's main usage is diagnostics or \
 devices connectivity and drivers.
 """
 
@@ -210,8 +210,8 @@ def _serial_cli():
     ApioSubgroup(
         "Subcommands",
         [
-            _usb_cli,
-            _serial_cli,
+            _scan_usb_cli,
+            _scan_serial_cli,
         ],
     )
 ]
@@ -221,7 +221,7 @@ def _serial_cli():
     name="devices",
     cls=ApioGroup,
     subgroups=SUBGROUPS,
-    short_help="List attached devices.",
+    short_help="Scan attached devices.",
     help=APIO_DEVICES_HELP,
 )
 def cli():

apio/managers/drivers.py

@@ -52,7 +52,7 @@
   8. {E1}Disconnect and reconnect[/] your FPGA board for the new driver
      to take affect.
 
-  9. {E1}Run the command 'apio devices usb'[/] and verify that
+  9. {E1}Run the command 'apio devices scan-usb'[/] and verify that
      your board is listed.
 """
 
@@ -100,7 +100,7 @@
   3. Find the Serial installer window and {E1}follow the instructions.[/]
 
   4. To verify, {E1}disconnect and reconnect the board[/] and run the command
-      {E1}'apio devices serial'.[/]
+      {E1}'apio devices scan-serial'.[/]
 """
 
 # -- Text in the rich-text format of the python rich library.

apio/managers/programmers.py

@@ -298,7 +298,7 @@ def _match_serial_device(
     if not matching:
         cerror("No matching serial device.")
         cout(
-            "Type 'apio devices serial' for available serial devices.",
+            "Type 'apio devices scan-serial' for available serial devices.",
             style=INFO,
         )
         sys.exit(1)
@@ -307,7 +307,7 @@ def _match_serial_device(
     if len(matching) > 1:
         cerror("Found multiple matching serial devices.")
         cout(
-            "Type 'apio devices serial' for available serial devices.",
+            "Type 'apio devices scan-serial' for available serial devices.",
             style=INFO,
         )
         sys.exit(1)
@@ -364,7 +364,7 @@ def _match_usb_device(
     if not matching:
         cerror("No matching USB device.")
         cout(
-            "Type 'apio devices usb' for available usb devices.",
+            "Type 'apio devices scan-usb' for available usb devices.",
             style=INFO,
         )
         sys.exit(1)
@@ -373,7 +373,7 @@ def _match_usb_device(
     if len(matching) > 1:
         cerror("Found multiple matching usb devices.")
         cout(
-            "Type 'apio devices usb' for available usb device.",
+            "Type 'apio devices scan-usb' for available usb device.",
             style=INFO,
         )
         sys.exit(1)
@@ -424,7 +424,7 @@ def _check_device_presence(apio_ctx: ApioContext, scanner: _DeviceScanner):
     if not matching_devices:
         cerror("No matching device.")
         cout(
-            "Type 'apio devices usb' for available usb devices.",
+            "Type 'apio devices scan-usb' for available usb devices.",
             style=INFO,
         )
         sys.exit(1)

docs/assets/apio-devices-serial.png docs/assets/apio-devices-scanserial.pngdocs/assets/apio-devices-serial.png renamed to docs/assets/apio-devices-scanserial.png

@@ -13,4 +13,4 @@ Apio provides two types of driver: `ftdi` and `serial`. The table below compares
 | Platforms        | Linux, Windows                | Linux, Windows                  |
 | Driver install   | `apio drivers install ftdi`   | `apio drivers install serial`   |
 | Driver uninstall | `apio drivers uninstall ftdi` | `apio drivers uninstall serial` |
-| List devices     | `apio devices usb`            | `apio devices serial`           |
+| List devices     | `apio devices scan-usb`       | `apio devices scan-serial`      |

docs/assets/apio-devices-usb.png docs/assets/apio-devices-scanusb.pngdocs/assets/apio-devices-usb.png renamed to docs/assets/apio-devices-scanusb.png

@@ -4,8 +4,8 @@
 
 ## apio devices
 
-The `apio devices` command group lists devices connected to your computer.
-It is mainly used for diagnosing connectivity or driver issues.
+The `apio devices` command group scans and displays devices connected to your
+computer. It is mainly used for diagnosing connectivity or driver issues.
 
 <h3>Options</h3>
 
@@ -16,22 +16,22 @@ It is mainly used for diagnosing connectivity or driver issues.
 <h3>Subcommands</h3>
 
 ```
-apio devices usb
-apio devices serial
+apio devices scan-usb
+apio devices scan-serial
 ```
 
 ---
 
-## apio devices usb
+## apio devices scan-usb
 
-The command `apio devices usb` displays the USB devices currently
-connected to your computer. It is useful for diagnosing FPGA board
+The command `apio devices scan-usb` scans and displays the USB devices 
+currently connected to your computer. It is useful for diagnosing FPGA board
 connectivity issues.
 
 <h3>Examples</h3>
 
 ```
-apio devices usb    # List USB devices.
+apio devices scan-usb    # Lists USB devices.
 ```
 
 <h3>Options</h3>
@@ -42,20 +42,20 @@ apio devices usb    # List USB devices.
 
 Example output
 
-![](assets/apio-devices-usb.png)
+![](assets/apio-devices-scanusb.png)
 
 ---
 
-## apio devices serial
+## apio devices scan-serial
 
-The command `apio devices serial` displays the serial devices
+The command `apio devices scan-serial` scans and displays the serial devices
 currently connected to your computer. It is useful for diagnosing FPGA
 board connectivity issues.
 
 <h3>Examples</h3>
 
 ```
-apio devices serial    # List serial devices.
+apio devices scan-serial    # List serial devices.
 ```
 
 <h3>Options</h3>
@@ -70,8 +70,9 @@ apio devices serial    # List serial devices.
   multiple entries—one per serial port.
 
 - On Windows, manufacturer and product strings of FTDI based devices may
-  show their FTDI generic values rather than the custom values such as 'Alhambra II' set by the device manufacturer.
+  show their FTDI generic values rather than the custom values such as
+  'Alhambra II' set by the device manufacturer.
 
 Example output
 
-![](assets/apio-devices-serial.png)
+![](assets/apio-devices-scanserial.png)