Support hardware model v2

[joelspadin]

This updates ZMK CLI to understand Zephyr's hardware model v2 board revisions. zmk keyboard new now also generates board files correctly for hardware model v2.

Board qualifiers are not yet handled, since those need to go after the board revision, but I want to see what we decide on zmkfirmware/zmk#3145 before figuring out if/how ZMK CLI needs to handle those.

[caksoylar]

LGTM, a few comments.

Maybe it'd make sense to rename Keyboard class to KeyboardComponent, given it also encapsulates boards that are not keyboards by itself?

[joelspadin]

LGTM, a few comments.

Maybe it'd make sense to rename Keyboard class to KeyboardComponent, given it also encapsulates boards that are not keyboards by itself?

I don't think I designed this very well, and I think I want to fix it in a separate PR rather than trying to do it here.

Currently, both boards and shields can be a "keyboard" if they have the keys feature. MaybeKeyboard would be a more appropriate name for this class. My current solution for modeling the hardware is to have both Board and Shield derive from a class that has the interface for everything we want to know about a keyboard, then to use an is_keyboard() function to check if something is actually a keyboard.

The problem with this is that the component that has keys is usually not a complete keyboard on its own. I'm thinking of restructuring it something more like this, where Keyboard describes the combination of components that result in a complete keyboard. This would also give a more convenient place to store the board revision (and maybe any board qualifiers) that are chosen for the build, and it would make it easier to implement a UI where zmk keyboard add offers to add other shields to the build (displays, etc.).

classDiagram
    Hardware <|-- Interconnect
    Hardware <|-- KeyboardComponent
    KeyboardComponent <|-- Board
    KeyboardComponent <|-- Shield

    Keyboard *-- Board
    Keyboard *-- Shield

    class Hardware {
        +str type
        +str id
        +str name
        +str file_format
        +str url
        +str description
        +str manufacturer
        +str version
        $from_dict(data)
    }

    class KeyboardComponent {
        +list[str] siblings
        +list[str] exposes
        +list[Feature] features
        +list[Variant] variants
    }

    class Board {
        +str arch
        +list[Output] outputs
        +list[str] revisions
        +str default_revision
    }

    class Shield {
        +list[str] requires
    }

    class Interconnect {
        +dict[str, str] node_labels
        +str design_guideline
    }



    note for Keyboard "get_build_items() returns
    one item per combination 
    of board/shield siblings,
    with revision+qualifiers, e.g. 
    - board=foo
    - shield=bar,baz
    - board_revision=2
    - board_qualifiers=a,b
    with bar having siblings
    returns:
    - 'foo@2/a/b', 'bar_left baz'
    - 'foo@2/a/b', 'bar_right baz'"

    note for Keyboard "is_complete is true when 
    board is set and at least 
    one item in boards/shields 
    has the 'keys' feature."

    class Keyboard {
        +Board board
        +list[Shield] shields
        +str board_revision
        +list[str] board_qualifiers
        +bool is_complete 
        +bool has_revision(revision)

        +list[BuildItem] get_build_items()
    }

    class BuildItem {
        +str board
        +str shield
        +str snippet
        +str cmake_args
        +str artifact_name
    }

    Keyboard -- BuildItem

Loading

[caksoylar]

I see, your plan+diagram makes sense to me (and certainly, not for this PR). I like the is_complete flag too, and supporting multiple shields would be pretty nice.