From 47abbe7925dece8a50b1001b0b9f32c64268f61b Mon Sep 17 00:00:00 2001 From: Peter Johanson Date: Mon, 29 Mar 2021 01:20:57 +0000 Subject: [PATCH] feat(docs): Add dynamic hardware list component. --- docs/docs/hardware.md | 56 ------ docs/docs/hardware.mdx | 26 +++ docs/docusaurus.config.js | 2 +- docs/src/components/hardware-list.tsx | 176 ++++++++++++++++++ .../index.js | 12 +- .../index.js | 4 +- docs/tsconfig.json | 2 +- 7 files changed, 214 insertions(+), 64 deletions(-) delete mode 100644 docs/docs/hardware.md create mode 100644 docs/docs/hardware.mdx create mode 100644 docs/src/components/hardware-list.tsx diff --git a/docs/docs/hardware.md b/docs/docs/hardware.md deleted file mode 100644 index 4aacf95d..00000000 --- a/docs/docs/hardware.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Supported Hardware -sidebar_label: Supported Hardware ---- - -:::warning - -ZMK Firmware is still an early stage project. Many features are still waiting to be implemented, and only a select few keyboards -have had their hardware details codified in boards/shields for ZMK. - -::: - -With the solid technical foundation of Zephyr™ RTOS, ZMK can support a wide diversity of hardware targets. -That being said, there are currently only a few specific [boards](faq.md#what-is-a-board)/[shields](faq.md#what-is-a-shield) that have been written and tested by the ZMK contributors. - -## Boards - -- [nice!nano](https://nicekeyboards.com/nice-nano) (`nice_nano`, `nice_nano_v2`) -- [nrfMicro](https://github.com/joric/nrfmicro) (`nrfmicro_13`, `nrfmicro_11`, `nrfmicro_11_flipped`) -- [BlueMicro840](https://store.jpconstantineau.com/#/group/bluemicro) (`bluemicro840_v1`) -- [QMK Proton-C](https://qmk.fm/proton-c/) (`proton_c`) -- [BDN9 Rev2](https://keeb.io/products/bdn9-rev-2-3x3-9-key-macropad-rotary-encoder-and-rgb) (`bdn9_rev2`) - -## Keyboard Shields - -- [Kyria](https://splitkb.com/products/kyria-pcb-kit) (`kyria_left` and `kyria_right`) -- [Corne](https://github.com/foostan/crkbd) (`corne_left` and `corne_right`) -- [Helix](https://github.com/mcmadhatter/helix) (`helix_left` and `helix_right`) -- [Lily58](https://github.com/kata0510/Lily58) (`lily58_left` and `lily58_right`) -- [Sofle](https://github.com/josefadamcik/SofleKeyboard) (`sofle_left` and `sofle_right`) -- [Splitreus62](https://github.com/Na-Cly/splitreus62) (`splitreus62_left` and `splitreus62_right`) -- [Jorne](https://github.com/joric/jorne) (`jorne_left` and `jorne_right`) -- [Jian](https://github.com/KGOH/Jian-Info) (`jian_left` and `jian_right`) -- [Reviung41](https://github.com/gtips/reviung/tree/master/reviung41) (`reviung41`) -- [RoMac+ v4](https://www.littlekeyboards.com/products/romac) (`romac_plus`) -- [RoMac v2](https://mechboards.co.uk/shop/kits/romac-macro-pad/) (`romac`) -- [Boardsource 3x4 Macro](https://boardsource.xyz/store/5ecc2008eee64242946c98c1) (`boardsource3x4`) -- [QAZ](https://www.cbkbd.com/product/qaz-keyboard-kit) (`qaz`) -- [CRBN](https://keygem.store/collections/group-buys/products/group-buy-featherlight-40-kit) (`crbn`) -- [tidbit](https://nullbits.co/tidbit/) (`tidbit`) -- [Eek!](https://www.cbkbd.com/product/eek-keyboard) (`eek`) -- [BFO-9000](https://keeb.io/products/bfo-9000-keyboard-customizable-full-size-split-ortholinear) (`bfo9000_left` and `bfo9000_right`) - -## Other Hardware - -In addition to the basic keyboard functionality, there is some initial support for additional keyboard hardware: - -- Encoders -- OLEDs -- RGB Underglow - -Until detailed documentation is available, feel free to ask questions about how these are supported in the [Discord server](https://zmk.dev/community/discord/invite). - -## Contributing - -If you'd like to add support for a new keyboard shield, head over to the [New Keyboard Shield](development/new-shield.md) documentation. diff --git a/docs/docs/hardware.mdx b/docs/docs/hardware.mdx new file mode 100644 index 00000000..ccdd063e --- /dev/null +++ b/docs/docs/hardware.mdx @@ -0,0 +1,26 @@ +--- +title: Supported Hardware +sidebar_label: Supported Hardware +--- + +import HardwareList from "@site/src/components/hardware-list"; +import Metadata from "@site/src/data/hardware-metadata.json"; + +With the solid technical foundation of Zephyr™ RTOS, ZMK can support a wide diversity of hardware targets. +That being said, there are currently only a few specific [boards](/docs/faq#what-is-a-board)/[shields](faq.md#what-is-a-shield) that have been implemented and tested by the ZMK contributors. + + + +## Other Hardware + +In addition to the basic keyboard functionality, there is some initial support for additional keyboard hardware: + +- Encoders +- Displays +- RGB Underglow + +Until detailed documentation is available, feel free to ask questions about how these are supported in the [Discord server](https://zmk.dev/community/discord/invite). + +## Contributing + +If you'd like to add support for a new keyboard shield, head over to the [New Keyboard Shield](development/new-shield.md) documentation. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 6eba9fc9..fc5677c2 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -11,7 +11,7 @@ module.exports = { plugins: [ path.resolve(__dirname, "src/docusaurus-tree-sitter-plugin"), path.resolve(__dirname, "src/hardware-metadata-collection-plugin"), - path.resolve(__dirname, "src/hardware-schema-typescript-plugin") + path.resolve(__dirname, "src/hardware-schema-typescript-plugin"), ], themeConfig: { colorMode: { diff --git a/docs/src/components/hardware-list.tsx b/docs/src/components/hardware-list.tsx new file mode 100644 index 00000000..ec7e8a10 --- /dev/null +++ b/docs/src/components/hardware-list.tsx @@ -0,0 +1,176 @@ +import React from "react"; + +import { + Board, + HardwareMetadata, + Interconnect, + Shield, +} from "../hardware-metadata"; + +interface HardwareListProps { + items: HardwareMetadata[]; +} + +type ElementOrString = JSX.Element | string; + +function itemHasMultiple(item: HardwareMetadata) { + return ( + (item.type == "board" || item.type == "shield") && + (item.siblings?.length ?? 1) > 1 + ); +} + +function itemIds(item: HardwareMetadata) { + if (item.type == "board" || item.type == "shield") { + let nodes = (item.siblings ?? [item.id]) + .map((id) => {id}) + .reduce( + (prev, curr, index) => [...prev, index > 0 ? ", " : "", curr], + [] as ElementOrString[] + ); + return {nodes}; + } else { + return {item.id}; + } +} + +const TYPE_LABELS: Record< + HardwareMetadata["type"], + Record<"singular" | "plural", string> +> = { + board: { plural: "Boards: ", singular: "Board: " }, + shield: { singular: "Shield: ", plural: "Shields: " }, + interconnect: { singular: "Interconnect: ", plural: "Interconnects: " }, +}; + +function HardwareLineItem({ item }: { item: HardwareMetadata }) { + return ( +
  • + {item.name} ( + {TYPE_LABELS[item.type][itemHasMultiple(item) ? "plural" : "singular"]}{" "} + {itemIds(item)}) +
    • + ); +} + +interface InterconnectDetails { + interconnect?: Interconnect; + boards: Board[]; + shields: Shield[]; +} + +function mapInterconnect({ + interconnect, + boards, + shields, +}: InterconnectDetails) { + if (!interconnect) { + return null; + } + + return ( +
    +

    {interconnect.name} Keyboards

    + {interconnect.description &&

    {interconnect.description}

    } +
    Boards
    +
      + {boards.map((s) => ( + + ))} +
    +
    Shields
    +
      + {shields.map((s) => ( + + ))} +
    +
    + ); +} + +interface GroupedMetadata { + onboard: Board[]; + interconnects: Record; +} + +function groupedBoard(agg: GroupedMetadata, board: Board) { + if (board.features?.includes("keys")) { + agg.onboard.push(board); + } else if (board.exposes) { + board.exposes.forEach((element) => { + let ic = agg.interconnects[element] ?? { + boards: [], + shields: [], + }; + ic.boards.push(board); + agg.interconnects[element] = ic; + }); + } else { + console.error("Board without keys or interconnect"); + } + + return agg; +} + +function groupedShield(agg: GroupedMetadata, shield: Shield) { + shield.requires.forEach((id) => { + let ic = agg.interconnects[id] ?? { boards: [], shields: [] }; + ic.shields.push(shield); + agg.interconnects[id] = ic; + }); + + return agg; +} + +function groupedInterconnect(agg: GroupedMetadata, item: Interconnect) { + let ic = agg.interconnects[item.id] ?? { boards: [], shields: [] }; + ic.interconnect = item; + agg.interconnects[item.id] = ic; + + return agg; +} + +function HardwareList({ items }: HardwareListProps) { + let grouped = items.reduce( + (agg, hm) => { + switch (hm.type) { + case "board": + return groupedBoard(agg, hm); + case "shield": + return groupedShield(agg, hm); + case "interconnect": + return groupedInterconnect(agg, hm); + } + }, + { onboard: [] as Board[], interconnects: {} } + ); + + return ( + <> +

    Keyboards

    +

    Onboard Controller Boards

    +

    + Keyboards with onboard controllers are single PCBs that contain all the + components of a keyboard, including the controller chip, switch + footprints, etc. +

    +
      + {grouped["onboard"] + .sort((a, b) => a.name.localeCompare(b.name)) + .map((s) => ( + + ))} +
    +

    Composite Boards

    +

    + Composite keyboards are composed of two main PCBs: a small controller + board with exposed pads, and a larger keyboard PCB (a shield, in ZMK + lingo) with switch footprints and location a where the controller is + added. +

    + {Object.values(grouped.interconnects).map(mapInterconnect)} + + ); +} + +export default HardwareList; diff --git a/docs/src/hardware-metadata-collection-plugin/index.js b/docs/src/hardware-metadata-collection-plugin/index.js index cbea805f..5f5660bb 100644 --- a/docs/src/hardware-metadata-collection-plugin/index.js +++ b/docs/src/hardware-metadata-collection-plugin/index.js @@ -8,12 +8,16 @@ var PrebuildPlugin = require("prebuild-webpack-plugin"); const fs = require("fs"); const yaml = require("js-yaml"); const glob = require("glob"); -const { compile, compileFromFile } = require('json-schema-to-typescript'); function generateHardwareMetadataAggregate() { glob("../app/boards/**/*.zmk.yml", (error, files) => { - const aggregated = files.flatMap(f => yaml.safeLoadAll(fs.readFileSync(f, "utf8"))); - fs.writeFileSync("src/data/hardware-metadata.json", JSON.stringify(aggregated)); + const aggregated = files.flatMap((f) => + yaml.safeLoadAll(fs.readFileSync(f, "utf8")) + ); + fs.writeFileSync( + "src/data/hardware-metadata.json", + JSON.stringify(aggregated) + ); }); } @@ -30,4 +34,4 @@ module.exports = function () { }; }, }; -}; \ No newline at end of file +}; diff --git a/docs/src/hardware-schema-typescript-plugin/index.js b/docs/src/hardware-schema-typescript-plugin/index.js index 2ccbf19c..728d501d 100644 --- a/docs/src/hardware-schema-typescript-plugin/index.js +++ b/docs/src/hardware-schema-typescript-plugin/index.js @@ -6,7 +6,7 @@ var PrebuildPlugin = require("prebuild-webpack-plugin"); const fs = require("fs"); -const { compileFromFile } = require('json-schema-to-typescript'); +const { compileFromFile } = require("json-schema-to-typescript"); async function generateHardwareMetadataTypescript() { const ts = await compileFromFile("../schema/hardware-metadata.schema.json"); @@ -26,4 +26,4 @@ module.exports = function () { }; }, }; -}; \ No newline at end of file +}; diff --git a/docs/tsconfig.json b/docs/tsconfig.json index 77c5f752..4360f0da 100644 --- a/docs/tsconfig.json +++ b/docs/tsconfig.json @@ -1,4 +1,4 @@ { "extends": "@tsconfig/docusaurus/tsconfig.json", "include": ["src/"] -} \ No newline at end of file +}