diff --git a/app/boards/interconnects/arduino_uno/arduino_uno.zmk.yml b/app/boards/interconnects/arduino_uno/arduino_uno.zmk.yml index 8ec164eb23a..d6eb89a3df2 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 d3fcdc88fbb..0d91e96c730 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 78aa14a10bf..83aa31c75d4 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 cb9f6b56c89..48080c7f2f9 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 00000000000..b7960700632 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 00000000000..7e548da5154 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 00000000000..74a1005335a 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 88161e39fb2..00000000000 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 4444537e3ae..4644ee793f2 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 -![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 index 2e468fe0b57..62d71f0328e 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 - - - - -### 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`. - - - - - -### 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`. - - - + + + + + + {interconnect.node_labels && ( + <> + The following node labels are available: +
    +
  • + GPIO: &{interconnect.node_labels.gpio} +
    • + {interconnect.node_labels.i2c && ( +
  • + I2C bus: &{interconnect.node_labels.i2c} +
    • + )} + {interconnect.node_labels.spi && ( +
  • + SPI bus: &{interconnect.node_labels.spi} +
    • + )} + {interconnect.node_labels.uart && ( +
  • + UART: &{interconnect.node_labels.uart} +
    • + )} + {interconnect.node_labels.adc && ( +
  • + ADC: &{interconnect.node_labels.adc} +
    • + )} +
+ + )} + + ); +} + +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 ( + + {grouped.map(mapInterconnect)} + + ); +} + +export default InterconnectTabs; diff --git a/docs/src/data/interconnects/.gitignore b/docs/src/data/interconnects/.gitignore new file mode 100644 index 00000000000..0a00d70141f --- /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 89f057a83a7..f118c0baf5c 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 49755749282..8ca382c552e 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" },