diff --git a/app/boards/interconnects/arduino_uno/arduino_uno.zmk.yml b/app/boards/interconnects/arduino_uno/arduino_uno.zmk.yml
index 8ec164eb..d6eb89a3 100644
--- a/app/boards/interconnects/arduino_uno/arduino_uno.zmk.yml
+++ b/app/boards/interconnects/arduino_uno/arduino_uno.zmk.yml
@@ -13,3 +13,13 @@ description: |
Note: ZMK doesn't support boards with AVR 8-bit processors, such as the ATmega32U4, because Zephyr™ only
supports 32-bit and 64-bit platforms. As a result, boards like the original Arduino Uno Rev3 itself are
*not* supported by ZMK.
+node_labels:
+ gpio: arduino_header
+ i2c: arduino_i2c
+ spi: arduino_spi
+ uart: arduino_serial
+ adc: arduino_adc
+design_guideline: |
+ The GPIO pin references for the Uno format are a bit odd. The `&arduino_header` label is used, but the numbering
+ starts at the `A0` pin and increments as you go counter clockwise around the board. That means the `D6` pin
+ can be referenced by `&arduino_header 12` in your overlay files.
diff --git a/app/boards/interconnects/blackpill/blackpill.zmk.yml b/app/boards/interconnects/blackpill/blackpill.zmk.yml
index d3fcdc88..0d91e96c 100644
--- a/app/boards/interconnects/blackpill/blackpill.zmk.yml
+++ b/app/boards/interconnects/blackpill/blackpill.zmk.yml
@@ -6,3 +6,10 @@ url: https://github.com/WeActStudio/WeActStudio.MiniSTM32F4x1
manufacturer: WeAct Studio
description: |
The WeAct Studio BlackPill has grown in popularity due to its low price, availability, and utilization of the powerful STM32F4x1CEU6 microcontroller. The BlackPill features more GPIO than most other boards, but also has a comparatively larger footprint as a result. Many clones and variations of the original BlackPill are available on the market as an affordable and more powerful alternative to many popular boards. The official WeAct variations of the WeAct Studio BlackPill are powered by the STM32F411CEU6 and STM32F401CEU6 microcontrollers.
+node_labels:
+ gpio: blackpill
+ i2c: blackpill_i2c
+ spi: blackpill_spi
+ uart: blackpill_serial
+design_guideline: |
+ ZMK uses the blue color coded pin names to generate devicetree node references. For example, to refer to the pin labeled `17` in the diagram, use `&blackpill 17` in the devicetree files.
diff --git a/app/boards/interconnects/pro_micro/pro_micro.zmk.yml b/app/boards/interconnects/pro_micro/pro_micro.zmk.yml
index 78aa14a1..83aa31c7 100644
--- a/app/boards/interconnects/pro_micro/pro_micro.zmk.yml
+++ b/app/boards/interconnects/pro_micro/pro_micro.zmk.yml
@@ -12,3 +12,10 @@ description: |
Note: ZMK doesn't support boards with AVR 8-bit processors, such as the ATmega32U4, because Zephyr™ only
supports 32-bit and 64-bit platforms. As a result, controllers like the SparkFun Pro Micro and the Elite-C
are *not* supported by ZMK.
+node_labels:
+ gpio: pro_micro
+ i2c: pro_micro_i2c
+ spi: pro_micro_spi
+ uart: pro_micro_serial
+design_guideline: |
+ ZMK uses the blue color coded "Arduino" pin names to generate devicetree node references. For example, to refer to the pin labeled `0` in the diagram, use `&pro_micro 0` in the devicetree files.
diff --git a/app/boards/interconnects/seeed_xiao/seeed_xiao.zmk.yml b/app/boards/interconnects/seeed_xiao/seeed_xiao.zmk.yml
index cb9f6b56..48080c7f 100644
--- a/app/boards/interconnects/seeed_xiao/seeed_xiao.zmk.yml
+++ b/app/boards/interconnects/seeed_xiao/seeed_xiao.zmk.yml
@@ -8,3 +8,10 @@ description: |
The Seeed(uino) XIAO is a popular smaller format micro-controller, that has gained popularity as an alterative
to the SparkFun Pro Micro. Since its creation, several pin compatible controllers, such
as the Seeeduino XIAO BLE, Adafruit QT Py and Adafruit QT Py RP2040, have become available.
+node_labels:
+ gpio: xiao_d
+ i2c: xiao_i2c
+ spi: xiao_spi
+ uart: xiao_serial
+design_guideline: |
+ ZMK uses the "D"-prefixed, green color coded pin names, e.g. `D2`, to generate devicetree node references. For example, to refer to the pin labeled `D0` in the diagram, use `&xiao_d 0` in the devicetree files.
diff --git a/docs/docs/assets/interconnects/arduino_uno/pinout.png b/docs/docs/assets/interconnects/arduino_uno/pinout.png
new file mode 100644
index 00000000..b7960700
Binary files /dev/null and b/docs/docs/assets/interconnects/arduino_uno/pinout.png differ
diff --git a/docs/docs/assets/blackpill/blackpill-pins-labelled.png b/docs/docs/assets/interconnects/blackpill/pinout.png
similarity index 100%
rename from docs/docs/assets/blackpill/blackpill-pins-labelled.png
rename to docs/docs/assets/interconnects/blackpill/pinout.png
diff --git a/docs/docs/assets/interconnects/pro_micro/pinout.png b/docs/docs/assets/interconnects/pro_micro/pinout.png
new file mode 100644
index 00000000..7e548da5
Binary files /dev/null and b/docs/docs/assets/interconnects/pro_micro/pinout.png differ
diff --git a/docs/docs/assets/interconnects/seeed_xiao/pinout.png b/docs/docs/assets/interconnects/seeed_xiao/pinout.png
new file mode 100644
index 00000000..74a10053
Binary files /dev/null and b/docs/docs/assets/interconnects/seeed_xiao/pinout.png differ
diff --git a/docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg b/docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg
deleted file mode 100644
index 88161e39..00000000
Binary files a/docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg and /dev/null differ
diff --git a/docs/docs/development/boards-shields-keymaps.md b/docs/docs/development/boards-shields-keymaps.md
index 4444537e..4644ee79 100644
--- a/docs/docs/development/boards-shields-keymaps.md
+++ b/docs/docs/development/boards-shields-keymaps.md
@@ -34,7 +34,7 @@ in the `app/boards/${arch}/${board_name}` directory, e.g. `app/boards/arm/planck
## Pro Micro Compatible Keyboard
-
+
For keyboards that require a (usually Pro Micro compatible) add-on board to operate, the ZMK integration pieces are places
in the _shield_ definition for that keyboard, allowing users to
diff --git a/docs/docs/development/new-shield.md b/docs/docs/development/new-shield.md
index 2e468fe0..62d71f03 100644
--- a/docs/docs/development/new-shield.md
+++ b/docs/docs/development/new-shield.md
@@ -6,6 +6,9 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import KeymapExampleFile from '../keymap-example-file.md';
+import InterconnectTabs from "@site/src/components/interconnect-tabs";
+import Metadata from "@site/src/data/hardware-metadata.json";
+
## Overview
This guide will walk through the steps necessary to add ZMK support for a keyboard the uses a (Pro Micro compatible) addon MCU board to provide the microprocessor.
@@ -115,33 +118,7 @@ endif
## Shield Overlays
-<Tabs
-defaultValue="pro_micro"
-values={[
-{label: 'Pro Micro Shields', value: 'pro_micro'},
-{label: 'BlackPill Shields', value: 'blackpill'},
-]}>
-
-<TabItem value="pro_micro">
-
-### Pro Micro Shields
-
-
-
-ZMK uses the blue color coded pin names to generate devicetree node references. For example, to refer to the node `0` in the devicetree files, use `&pro_micro 0`.
-
-</TabItem>
-
-<TabItem value="blackpill">
-
-### BlackPill Shields
-
-
-
-ZMK uses the blue color coded pin names to generate devicetree node references. For example, to refer to the node `17` in the devicetree files, use `&blackpill 17`.
-
-</TabItem>
-</Tabs>
+<InterconnectTabs items={Metadata}/>
<Tabs
defaultValue="unibody"
diff --git a/docs/src/components/interconnect-tabs.tsx b/docs/src/components/interconnect-tabs.tsx
new file mode 100644
index 00000000..c7912793
--- /dev/null
+++ b/docs/src/components/interconnect-tabs.tsx
@@ -0,0 +1,74 @@
+import React from "react";
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+import { HardwareMetadata, Interconnect } from "../hardware-metadata";
+import { groupedMetadata, InterconnectDetails } from "./hardware-utils";
+
+interface InterconnectTabsProps {
+ items: HardwareMetadata[];
+}
+
+function mapInterconnect(interconnect: Interconnect) {
+ let content = require(`@site/src/data/interconnects/${interconnect.id}/design_guideline.md`);
+ let imageUrl = require(`@site/docs/assets/interconnects/${interconnect.id}/pinout.png`);
+
+ return (
+ <TabItem value={interconnect.id}>
+ <img src={imageUrl.default} />
+
+ <content.default />
+
+ {interconnect.node_labels && (
+ <>
+ The following node labels are available:
+ <ul>
+ <li>
+ GPIO: <code>&{interconnect.node_labels.gpio}</code>
+ </li>
+ {interconnect.node_labels.i2c && (
+ <li>
+ I2C bus: <code>&{interconnect.node_labels.i2c}</code>
+ </li>
+ )}
+ {interconnect.node_labels.spi && (
+ <li>
+ SPI bus: <code>&{interconnect.node_labels.spi}</code>
+ </li>
+ )}
+ {interconnect.node_labels.uart && (
+ <li>
+ UART: <code>&{interconnect.node_labels.uart}</code>
+ </li>
+ )}
+ {interconnect.node_labels.adc && (
+ <li>
+ ADC: <code>&{interconnect.node_labels.adc}</code>
+ </li>
+ )}
+ </ul>
+ </>
+ )}
+ </TabItem>
+ );
+}
+
+function mapInterconnectValue(interconnect: Interconnect) {
+ return { label: `${interconnect.name} Shields`, value: interconnect.id };
+}
+
+function InterconnectTabs({ items }: InterconnectTabsProps) {
+ let grouped = Object.values(groupedMetadata(items).interconnects)
+ .map((i) => i?.interconnect as Interconnect)
+ .filter((i) => i?.design_guideline)
+ .sort((a, b) => a.id.localeCompare(b.id));
+
+ return (
+ <Tabs defaultValue={"pro_micro"} values={grouped.map(mapInterconnectValue)}>
+ {grouped.map(mapInterconnect)}
+ </Tabs>
+ );
+}
+
+export default InterconnectTabs;
diff --git a/docs/src/data/interconnects/.gitignore b/docs/src/data/interconnects/.gitignore
new file mode 100644
index 00000000..0a00d701
--- /dev/null
+++ b/docs/src/data/interconnects/.gitignore
@@ -0,0 +1 @@
+*/
\ No newline at end of file
diff --git a/docs/src/hardware-metadata-collection-plugin/index.js b/docs/src/hardware-metadata-collection-plugin/index.js
index 89f057a8..f118c0ba 100644
--- a/docs/src/hardware-metadata-collection-plugin/index.js
+++ b/docs/src/hardware-metadata-collection-plugin/index.js
@@ -14,6 +14,22 @@ function generateHardwareMetadataAggregate() {
const aggregated = files.flatMap((f) =>
yaml.loadAll(fs.readFileSync(f, "utf8"))
);
+
+ aggregated
+ .filter((agg) => agg.type === "interconnect")
+ .forEach((agg) => {
+ let baseDir = `src/data/interconnects/${agg.id}`;
+ if (!fs.existsSync(baseDir)) {
+ fs.mkdirSync(baseDir);
+ }
+
+ if (agg.design_guideline) {
+ fs.writeFileSync(
+ `${baseDir}/design_guideline.md`,
+ agg.design_guideline
+ );
+ }
+ });
fs.writeFileSync(
"src/data/hardware-metadata.json",
JSON.stringify(aggregated)
diff --git a/schema/hardware-metadata.schema.json b/schema/hardware-metadata.schema.json
index 49755749..8ca382c5 100644
--- a/schema/hardware-metadata.schema.json
+++ b/schema/hardware-metadata.schema.json
@@ -85,6 +85,21 @@
}
}
},
+ "interconnect_node_labels": {
+ "title": "InterconnectNodeLabels",
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "gpio"
+ ],
+ "properties": {
+ "gpio": { "type": "string" },
+ "i2c": { "type": "string" },
+ "spi": { "type": "string" },
+ "uart": { "type": "string" },
+ "adc": { "type": "string" }
+ }
+ },
"interconnect": {
"title": "Interconnect",
"type": "object",
@@ -93,6 +108,7 @@
"file_format",
"id",
"name",
+ "description",
"url",
"type"
],
@@ -117,6 +133,12 @@
"description": {
"type": "string"
},
+ "node_labels": {
+ "$ref": "#/$defs/interconnect_node_labels"
+ },
+ "design_guideline": {
+ "type": "string"
+ },
"manufacturer": {
"type": "string"
},