Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add a few well known interconnects to the Hardware Metadata File page #2563

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

amacleod
Copy link
Contributor

Fixes #2562

Added two sentences to list the same set of interconnects that have pinouts shown in the New Keyboard Shield guide and point readers at the interconnects directory in source for more.

@amacleod amacleod requested a review from a team as a code owner October 17, 2024 02:47
@@ -75,7 +75,7 @@ url: https://github.com/foostan/crkbd/

### Interconnect Requires/Exposes

For boards and shields, one of the key pieces of high level information is compatibility between the two items. In particular, a board usually exposes one ore more "interconnects", the physical location/type of connections available, and their assigned possible uses (e.g. GPIO, power, ground, i2c, etc). Similarly, a shield is usually designed around one (or sometimes more) "interconnects" that allow it to connect to one of those boards.
For boards and shields, one of the key pieces of high level information is compatibility between the two items. In particular, a board usually exposes one ore more "interconnects", the physical location/type of connections available, and their assigned possible uses (e.g. GPIO, power, ground, i2c, etc). Similarly, a shield is usually designed around one (or sometimes more) "interconnects" that allow it to connect to one of those boards. Common "interconnects" available in ZMK include (but are not limited to) `arduino_uno`, `blackpill`, `pro_micro`, and `seeed_xiao`. The names of "interconnects" may be found in the `app/boards/interconnects/` directory of ZMK source.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some changes I considered but was not sure of:

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not 100% sure that the Hardware Metadata File page is the proper place for this information, but it felt a little more right than the New Keyboard Shields page when I was writing it. Then again, the itch that led to this PR in the first place occurred when I was reading the new shields guide 🤷

@Nick-Munnich
Copy link
Contributor

Thanks for the PR! The interconnects can be found in multiple locations, having hardware metadata be another one seems like a good addition to me. I don't think plaintext is the way to go, though; I'd say we want something along the lines of hardware list where it uses some typescript to pull the information from the metadata directly.

@caksoylar caksoylar added the documentation Improvements or additions to documentation label Oct 17, 2024
@caksoylar
Copy link
Contributor

For a more limited dynamic use of metadata, you can also check out the shield overlays section which gets the interconnect metadata: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/hardware-integration/new-shield.mdx?plain=1#L269

This is essentially reading from these files https://github.com/zmkfirmware/zmk/tree/main/app/boards/interconnects and you'd only need to get the id and name for enumerating them in this page.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Docs: New-shield guide Metadata section should list some well-known interconnects
3 participants