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 <caksoylar@users.noreply.github.com>
This commit is contained in:
parent
d993b03433
commit
c23443a086
app/boards/interconnects
arduino_uno
blackpill
pro_micro
seeed_xiao
docs
docs
assets
interconnects
pro-micro
development
src
components
data/interconnects
hardware-metadata-collection-plugin
schema
@ -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.
|
||||
|
@ -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.
|
||||
|
@ -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.
|
||||
|
@ -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.
|
||||
|
BIN
docs/docs/assets/interconnects/arduino_uno/pinout.png
Normal file
BIN
docs/docs/assets/interconnects/arduino_uno/pinout.png
Normal file
Binary file not shown.
After (image error) Size: 116 KiB |
Before (image error) Size: 902 KiB After (image error) Size: 902 KiB |
BIN
docs/docs/assets/interconnects/pro_micro/pinout.png
Normal file
BIN
docs/docs/assets/interconnects/pro_micro/pinout.png
Normal file
Binary file not shown.
After (image error) Size: 481 KiB |
BIN
docs/docs/assets/interconnects/seeed_xiao/pinout.png
Normal file
BIN
docs/docs/assets/interconnects/seeed_xiao/pinout.png
Normal file
Binary file not shown.
After (image error) Size: 484 KiB |
Binary file not shown.
Before (image error) Size: 479 KiB |
@ -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
|
||||
|
@ -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"
|
||||
|
74
docs/src/components/interconnect-tabs.tsx
Normal file
74
docs/src/components/interconnect-tabs.tsx
Normal file
@ -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;
|
1
docs/src/data/interconnects/.gitignore
vendored
Normal file
1
docs/src/data/interconnects/.gitignore
vendored
Normal file
@ -0,0 +1 @@
|
||||
*/
|
@ -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)
|
||||
|
@ -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"
|
||||
},
|
||||
|
Loading…
Reference in New Issue
Block a user