feat(docs): Generate new shield interconnect docs.

* Add to metadata schema for interconnects. * New conventional location for pinout diagrams/pics. * New component to generate the tabs for the new shield doc section on interconnects. * Add XIAO and arduino uno pinout diagram. Co-authored-by: Cem Aksoylar <[email protected]>
3dJan · Dec 23, 2022 · c23443a · c23443a
1 parent d993b03
commit c23443a
Show file tree

Hide file tree

Showing 15 changed files with 149 additions and 28 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
diff --git a/...ets/blackpill/blackpill-pins-labelled.png → ...assets/interconnects/blackpill/pinout.png b/...ets/blackpill/blackpill-pins-labelled.png → ...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
diff --git a/docs/docs/assets/interconnects/seeed_xiao/pinout.png b/docs/docs/assets/interconnects/seeed_xiao/pinout.png
diff --git a/docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg b/docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg
diff --git 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
 
-![Labelled Pro Micro pins](../assets/pro-micro/pro-micro-pins-labelled.jpg)
+![Labelled Pro Micro pins](../assets/interconnects/pro_micro/pinout.png)
 
 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
@@ -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
-
-![Labelled Pro Micro pins](../assets/pro-micro/pro-micro-pins-labelled.jpg)
-
-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
-
-![Labelled BlackPill pins](../assets/blackpill/blackpill-pins-labelled.png)
-
-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
@@ -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
@@ -0,0 +1 @@
+*/
diff --git 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
@@ -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"
         },