feat: Support board revisions in keyboard add/list commands

"zmk keyboard add" nows understand board revisions.

If you attempt to add a board which has multiple revisions (and you
don't provide a revision with a parameter like "-c nice_nano@2"), it
will now prompt you to select a revision.

When copying .keymap and .conf files to your config repo, if the
keyboard is a board with a revision, it will now check for versioned
files before checking for a common file with no revision.

"zmk keyboard list" now supports a --revisions flag which prints each
board revision as a separate item.

Author: joelspadin

zmk/commands/config.py

@@ -10,9 +10,7 @@
 from .. import styles
 from ..config import Config, get_config
 
-console = Console(
-    highlighter=styles.KeyValueHighlighter(), theme=styles.KEY_VALUE_THEME
-)
+console = Console(highlighter=styles.KeyValueHighlighter(), theme=styles.THEME)
 
 
 def _path_callback(ctx: typer.Context, value: bool):

zmk/commands/keyboard/add.py

@@ -15,11 +15,16 @@
 from ...exceptions import FatalError
 from ...hardware import (
     Board,
+    Hardware,
     Keyboard,
     Shield,
+    append_revision,
     get_hardware,
     is_compatible,
+    normalize_revision,
     show_hardware_menu,
+    show_revision_menu,
+    split_revision,
 )
 from ...repo import Repo
 from ...util import spinner
@@ -59,12 +64,21 @@ def keyboard_add(
 
     keyboard = None
     controller = None
+    revision = None
 
     if keyboard_id:
+        keyboard_id, keyboard_revision = split_revision(keyboard_id)
+
         keyboard = hardware.find_keyboard(keyboard_id)
         if keyboard is None:
             raise KeyboardNotFound(keyboard_id)
 
+        # If the keyboard ID contained a revision, use that.
+        # Make sure it is valid before continuing to any other prompts.
+        if keyboard_revision:
+            revision = keyboard_revision
+            _check_revision(keyboard, revision)
+
         if controller_id:
             if not isinstance(keyboard, Shield):
                 raise FatalError(
@@ -77,12 +91,20 @@ def keyboard_add(
                 raise ControllerNotFound(controller_id)
 
     elif controller_id:
+        controller_id, controller_revision = split_revision(controller_id)
+
         # User specified a controller but not a keyboard. Filter the keyboard
         # list to just those compatible with the controller.
         controller = hardware.find_controller(controller_id)
         if controller is None:
             raise ControllerNotFound(controller_id)
 
+        # If the controller ID contained a revision, use that.
+        # Make sure it is valid before continuing to any other prompts.
+        if controller_revision:
+            revision = controller_revision
+            _check_revision(controller, revision)
+
         hardware.keyboards = [
             kb
             for kb in hardware.keyboards
@@ -108,16 +130,28 @@ def keyboard_add(
                 f'Keyboard "{keyboard.id}" is not compatible with controller "{controller.id}"'
             )
 
+        # Check if the controller needs a revision.
+        revision = _get_revision(controller, revision)
+    else:
+        # If the keyboard isn't a shield, it may need a revision.
+        revision = _get_revision(keyboard, revision)
+
     name = keyboard.id
     if controller:
         name += ", " + controller.id
 
-    if _add_keyboard(repo, keyboard, controller):
+    if revision:
+        revision = normalize_revision(revision)
+        name = append_revision(name, revision)
+
+    if _add_keyboard(repo, keyboard, controller, revision):
         console.print(f'Added "{name}".')
     else:
         console.print(f'"{name}" is already in the build matrix.')
 
-    console.print(f'Run "zmk code {keyboard.id}" to edit the keymap.')
+    keymap_name = keyboard.get_keymap_path(revision).with_suffix("").name
+
+    console.print(f'Run "zmk code {keymap_name}" to edit the keymap.')
 
 
 class KeyboardNotFound(FatalError):
@@ -140,23 +174,26 @@ def _copy_keyboard_file(repo: Repo, path: Path):
         shutil.copy2(path, dest_path)
 
 
-def _get_build_items(keyboard: Keyboard, controller: Board | None):
+def _get_build_items(
+    keyboard: Keyboard, controller: Board | None, revision: str | None
+):
     boards = []
     shields = []
 
     match keyboard:
         case Shield(id=shield_id, siblings=siblings):
             if controller is None:
-                raise ValueError("controller may not be None if keyboard is a shield")
+                raise FatalError("controller may not be None if keyboard is a shield")
 
             shields = siblings or [shield_id]
-            boards = [controller.id]
+            boards = [append_revision(controller.id, revision)]
 
         case Board(id=board_id, siblings=siblings):
             boards = siblings or [board_id]
+            boards = [append_revision(board, revision) for board in boards]
 
         case _:
-            raise ValueError("Unexpected keyboard/controller combination")
+            raise FatalError("Unexpected keyboard/controller combination")
 
     if shields:
         return [
@@ -166,11 +203,35 @@ def _get_build_items(keyboard: Keyboard, controller: Board | None):
     return [BuildItem(board=b) for b in boards]
 
 
-def _add_keyboard(repo: Repo, keyboard: Keyboard, controller: Board | None):
-    _copy_keyboard_file(repo, keyboard.keymap_path)
-    _copy_keyboard_file(repo, keyboard.config_path)
+def _get_revision(board: Hardware, revision: str | None):
+    # If no revision was specified and the board uses revisions, prompt to
+    # select a revision.
+    return revision if revision else show_revision_menu(board)
+
+
+def _check_revision(board: Hardware, revision: str):
+    if board.has_revision(revision):
+        # Revision is OK
+        return
+
+    supported_revisions = board.get_revisions()
+
+    if not supported_revisions:
+        raise FatalError(f"{board.id} does not have any revisions.")
+
+    raise FatalError(
+        f'{board.id} does not support revision "@{revision}". Use one of:\n'
+        + "\n".join(f"  @{normalize_revision(rev)}" for rev in supported_revisions)
+    )
+
+
+def _add_keyboard(
+    repo: Repo, keyboard: Keyboard, controller: Board | None, revision: str | None
+):
+    _copy_keyboard_file(repo, keyboard.get_keymap_path(revision))
+    _copy_keyboard_file(repo, keyboard.get_config_path(revision))
 
-    items = _get_build_items(keyboard, controller)
+    items = _get_build_items(keyboard, controller, revision)
 
     matrix = BuildMatrix.from_repo(repo)
     added = matrix.append(items)

zmk/commands/keyboard/list.py

@@ -5,17 +5,27 @@
 from collections.abc import Iterable
 from typing import Annotated
 
-import rich
 import typer
 from rich import box
 from rich.columns import Columns
+from rich.console import Console
 from rich.table import Table
 
+from zmk import styles
+
 from ...backports import StrEnum
 from ...build import BuildItem, BuildMatrix
 from ...config import get_config
 from ...exceptions import FatalError
-from ...hardware import Board, Hardware, Shield, get_hardware, is_compatible
+from ...hardware import (
+    Board,
+    Hardware,
+    Shield,
+    append_revision,
+    get_hardware,
+    is_compatible,
+    normalize_revision,
+)
 from ...util import spinner
 
 # TODO: allow output as unformatted list
@@ -36,7 +46,12 @@ def _list_build_matrix(ctx: typer.Context, value: bool):
     if not value:
         return
 
-    console = rich.get_console()
+    console = Console(
+        highlighter=styles.chain_highlighters(
+            [styles.BoardIdHighlighter(), styles.CommandLineHighlighter()]
+        ),
+        theme=styles.THEME,
+    )
 
     cfg = get_config(ctx)
     repo = cfg.get_repo()
@@ -48,7 +63,12 @@ def _list_build_matrix(ctx: typer.Context, value: bool):
     has_cmake_args = any(item.cmake_args for item in include)
     has_artifact_name = any(item.artifact_name for item in include)
 
-    table = Table(box=box.SQUARE, border_style="dim blue", header_style="bright_cyan")
+    table = Table(
+        box=box.SQUARE,
+        border_style="dim blue",
+        header_style="bright_cyan",
+        highlight=True,
+    )
     table.add_column("Board")
     table.add_column("Shield")
     if has_snippet:
@@ -129,10 +149,16 @@ def keyboard_list(
             "--standalone", help="List only keyboards with onboard controllers."
         ),
     ] = False,
+    revisions: Annotated[
+        bool,
+        typer.Option(
+            "--revisions", "--rev", "-r", help="Display revisions for each board."
+        ),
+    ] = False,
 ) -> None:
     """List supported keyboards or keyboards in the build matrix."""
 
-    console = rich.get_console()
+    console = Console(highlighter=styles.BoardIdHighlighter(), theme=styles.THEME)
 
     cfg = get_config(ctx)
     repo = cfg.get_repo()
@@ -187,7 +213,15 @@ def keyboard_list(
         list_type = ListType.KEYBOARD
 
     def print_items(header: str, items: Iterable[Hardware]):
-        names = [item.id for item in items]
+        if revisions:
+            names = [
+                append_revision(item.id, normalize_revision(rev))
+                for item in items
+                for rev in (item.get_revisions() or [None])
+            ]
+        else:
+            names = [item.id for item in items]
+
         if not names:
             return