From ff09f2d0c9f13a868c8f71d71d9348ade438e4b6 Mon Sep 17 00:00:00 2001 From: Genteure Date: Mon, 8 Jun 2026 00:45:31 +0800 Subject: [PATCH] docs: reorganise supported hardware page (#3363) * docs: supported hardware structure changes Added a few links to hardware intergration pages to provide clearly signal to reader "you can make your own". Removed "Contributing" section since it's not really relavent anymore. * docs: move unsupported boards section out of metadata * address review comments * fix broken link * board variants, interconnect, fix link, move unsupported section * Apply suggested change Co-authored-by: Nicolas Munnich <98408764+nmunnich@users.noreply.github.com> --------- Co-authored-by: Nicolas Munnich <98408764+nmunnich@users.noreply.github.com> --- .../arduino_uno/arduino_uno.zmk.yml | 4 -- .../interconnects/pro_micro/pro_micro.zmk.yml | 8 +--- docs/docs/hardware.mdx | 38 ++++++++-------- docs/src/components/hardware-list.tsx | 45 +++++++++++++------ 4 files changed, 54 insertions(+), 41 deletions(-) diff --git a/app/boards/interconnects/arduino_uno/arduino_uno.zmk.yml b/app/boards/interconnects/arduino_uno/arduino_uno.zmk.yml index d6eb89a3..b06e8d54 100644 --- a/app/boards/interconnects/arduino_uno/arduino_uno.zmk.yml +++ b/app/boards/interconnects/arduino_uno/arduino_uno.zmk.yml @@ -9,10 +9,6 @@ description: | natural extension, once there were many shields designed for it, many other *boards* began to be developed that were compatible to leverage the extensive available shields. Today, many dev kits come with Uno headers to make it easy to work with them. - - 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 diff --git a/app/boards/interconnects/pro_micro/pro_micro.zmk.yml b/app/boards/interconnects/pro_micro/pro_micro.zmk.yml index 83aa31c7..041375ae 100644 --- a/app/boards/interconnects/pro_micro/pro_micro.zmk.yml +++ b/app/boards/interconnects/pro_micro/pro_micro.zmk.yml @@ -6,12 +6,8 @@ url: https://www.sparkfun.com/products/12640 manufacturer: SparkFun description: | The SparkFun Pro Micro grew popular as a low cost ATmega32U4 board with sufficient GPIO and peripherals - to work for many keyboard needs. Since the original Pro Micro, many pin compatible boards have appeared, - with various changes or improvements, such as the Elite-C w/ USB-C, nice!nano with nRF52840 wireless. - - 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. + to work for many keyboard needs. Since the original Pro Micro, many pin compatible boards have appeared + with various changes or improvements. node_labels: gpio: pro_micro i2c: pro_micro_i2c diff --git a/docs/docs/hardware.mdx b/docs/docs/hardware.mdx index b580daab..770ef2eb 100644 --- a/docs/docs/hardware.mdx +++ b/docs/docs/hardware.mdx @@ -11,11 +11,6 @@ import Heading from "@theme/Heading"; import { groupedMetadata } from "@site/src/components/hardware-utils"; export const toc = [ - { - value: "Onboard Controller Keyboards", - id: "onboard", - level: 2, - }, { value: "Composite Keyboards", id: "composite", @@ -28,25 +23,33 @@ export const toc = [ id: interconnect.id, level: 3, })), + { + value: "Onboard Controller Keyboards", + id: "onboard", + level: 2, + }, { value: "Other Hardware", id: "other-hardware", level: 2, }, - { - value: "Contributing", - id: "contributing", - level: 2, - }, ]; -With the solid technical foundation of Zephyr™ RTOS, ZMK can support a wide diversity of hardware targets, +With the solid technical foundation of Zephyr™ RTOS, ZMK can support a wide variety of hardware targets, including but not limited to Nordic nRF52, Raspberry Pi RP2040/RP2350, most ST STM32 MCUs, and Microchip SAMD21. -That being said, there are specific [boards / shields](hardware-integration/index.mdx#boards--shields) that have been implemented and tested by the ZMK contributors, listed below. +ZMK has the potential to run on any hardware supported by Zephyr™, such as those on +the [Zephyr™ supported boards](https://docs.zephyrproject.org/4.1.0/boards/index.html) page, though you may need to do some additional work to configure them for ZMK. +That being said, there are specific boards that have been tested and pre-configured by the ZMK contributors, denoted by the `zmk` board variants below. -:::note +Designing a new keyboard? Check out the [Hardware Integration](hardware-integration/index.mdx) section +for more information on how to configure ZMK to run on your custom hardware. -With the [upgrade to Zephyr 4.1](/blog/2025/12/09/zephyr-4-1#zmk-board-variant), the ZMK project has moved all in-tree boards to use a `zmk` [board variant](https://docs.zephyrproject.org/4.1.0/glossary.html#term-variant), for consistency when distinguishing from stock boards that are actually in upstream Zephyr. +:::info[Boards, Board Variants, and Shields] + +ZMK uses the Zephyr concepts of "boards" and "shields" to refer to different parts of a keyboard build that are then combined during a firmware build. +Please see the [explainer on boards & shields](hardware-integration/index.mdx#boards--shields) for more details. + +Zephyr boards come with minimal configuration. ZMK board variants add the necessary configuration to make the board usable out of the box with ZMK. ::: @@ -58,7 +61,6 @@ With the [upgrade to Zephyr 4.1](/blog/2025/12/09/zephyr-4-1#zmk-board-variant), In addition to the basic keyboard functionality, there is also support for additional keyboard hardware such as encoders, RGB underglow, backlight and displays. Please see pages under the "Features" header in the sidebar for details. -{/* prettier-ignore */} -Contributing - -If you'd like to add support for a new keyboard shield, head over to the [New Keyboard Shield](hardware-integration/new-shield.mdx) documentation and note the [clean room design requirements](development/contributing/clean-room.md). +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, Elite-C, +and Arduino Uno Rev3 are **NOT** supported by ZMK. diff --git a/docs/src/components/hardware-list.tsx b/docs/src/components/hardware-list.tsx index 92cca32b..e027df3b 100644 --- a/docs/src/components/hardware-list.tsx +++ b/docs/src/components/hardware-list.tsx @@ -84,6 +84,34 @@ function HardwareList({ items }: HardwareListProps) { return ( <> +
+ + Composite Keyboards + +

+ 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. The + board and shield share the same interconnect{" "} + standard, which defines the physical and electrical specifications for + the PCB-to-PCB connection. +

+

+ Boards and shields that share the same interconnect are usually + compatible with each other but not always. Check hardware + compatibility before connecting them. +

+

+ Designing a custom composite keyboard with an off-the-shelf controller + board? Check out the{" "} + + New Keyboard Shield + {" "} + guide. +

+ + {Object.values(grouped.interconnects).map(mapInterconnect)} +
Onboard Controller Keyboards @@ -93,6 +121,10 @@ function HardwareList({ items }: HardwareListProps) { the components of a keyboard, including the controller chip, switch footprints, etc.

+

+ Designing a custom keyboard with an onboard controller? Check out the{" "} + New Board guide. +

    {grouped["onboard"] .sort((a, b) => a.name.localeCompare(b.name)) @@ -101,19 +133,6 @@ function HardwareList({ items }: HardwareListProps) { ))}
-
- - Composite Keyboards - -

- 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 a location where the controller is - added. This location is called an interconnect. Multiple interconnects - can be found below. -

- {Object.values(grouped.interconnects).map(mapInterconnect)} -
); }