From ed56d81db79cf3a6e5dc02697277c0fad880ad34 Mon Sep 17 00:00:00 2001 From: Nicolas Munnich <98408764+nmunnich@users.noreply.github.com> Date: Tue, 26 May 2026 22:33:57 +0200 Subject: [PATCH 01/12] docs: Move the hardware integration section out of development (#3360) --- app/keymap-module/modules/modules.cmake | 4 +- app/src/physical_layouts.c | 2 +- app/src/split/wired/central.c | 2 +- app/src/split/wired/peripheral.c | 2 +- docs/blog/2020-08-12-zmk-sotf-1.md | 2 +- docs/blog/2022-04-10-zmk-sotf-5.md | 2 +- docs/blog/2023-10-05-zmk-sotf-6.md | 2 +- docs/blog/2024-01-05-zmk-tools.md | 2 +- docs/blog/2024-11-11-zmk-studio-mvp-ga.mdx | 2 +- docs/blog/2025-12-09-zephyr-4-1.md | 2 +- docs/docs/config/bootloader.md | 2 +- docs/docs/config/index.md | 2 +- docs/docs/config/layout.md | 6 +- docs/docs/config/lighting.md | 8 +- docs/docs/config/pointing.md | 2 +- docs/docs/config/settings.md | 2 +- docs/docs/config/split.md | 2 +- .../local-toolchain/build-flash.mdx | 2 +- docs/docs/faq.md | 4 +- docs/docs/features/battery.md | 2 +- docs/docs/features/encoders.md | 2 +- docs/docs/features/led-indicators.md | 4 +- docs/docs/features/lighting.md | 4 +- docs/docs/features/low-power-states.md | 2 +- docs/docs/features/pointing.md | 2 +- docs/docs/features/split-keyboards.md | 6 +- docs/docs/features/studio.md | 6 +- .../hardware-integration/battery.md | 4 +- .../bootloader/_base-config.md | 0 .../bootloader/adafruit-nrf52.mdx | 0 .../hardware-integration/bootloader/index.mdx | 0 .../hardware-integration/bootloader/rp2.mdx | 2 +- .../bootloader/samd21-uf2.mdx | 0 .../hardware-integration/bootloader/stm32.mdx | 2 +- .../bootloader/tinyuf2.mdx | 0 .../hardware-integration/dongle.mdx | 16 ++-- .../hardware-integration/encoders.md | 8 +- .../hardware-metadata-files.md | 2 +- .../includes/_gpio-key-direct.md | 0 .../includes/_gpio-key-matrix.md | 0 .../includes/_gpio-key-wakeup.md | 0 .../includes/_sideband-direct.md | 6 +- .../includes/_sideband-matrix.md | 4 +- .../includes/_sideband-wakeup-direct.md | 4 +- .../includes/_soft-off-behavior.md | 2 +- .../includes/_soft-off-waker.md | 2 +- .../hardware-integration/index.mdx | 32 +++---- .../lighting/backlight.mdx | 2 +- .../hardware-integration/lighting/index.mdx | 0 .../lighting/led-indicators.md | 2 +- .../lighting/underglow.md | 2 +- .../hardware-integration/new-board.md | 10 +-- .../hardware-integration/new-shield.mdx | 42 ++++----- .../hardware-integration/physical-layouts.md | 16 ++-- .../hardware-integration/pinctrl.mdx | 0 .../hardware-integration/pointing.mdx | 12 +-- .../hardware-integration/shift-registers.md | 4 +- .../hardware-integration/soft-off-setup.mdx | 6 +- docs/docs/hardware.mdx | 4 +- docs/docs/troubleshooting/hardware-issues.mdx | 2 +- docs/docs/user-setup.mdx | 2 +- docs/docs/zmk-cli.mdx | 2 +- docs/sidebars.js | 88 +++++++++---------- docs/static/_redirects | 9 +- 64 files changed, 184 insertions(+), 183 deletions(-) rename docs/docs/{development => }/hardware-integration/battery.md (82%) rename docs/docs/{development => }/hardware-integration/bootloader/_base-config.md (100%) rename docs/docs/{development => }/hardware-integration/bootloader/adafruit-nrf52.mdx (100%) rename docs/docs/{development => }/hardware-integration/bootloader/index.mdx (100%) rename docs/docs/{development => }/hardware-integration/bootloader/rp2.mdx (92%) rename docs/docs/{development => }/hardware-integration/bootloader/samd21-uf2.mdx (100%) rename docs/docs/{development => }/hardware-integration/bootloader/stm32.mdx (92%) rename docs/docs/{development => }/hardware-integration/bootloader/tinyuf2.mdx (100%) rename docs/docs/{development => }/hardware-integration/dongle.mdx (91%) rename docs/docs/{development => }/hardware-integration/encoders.md (89%) rename docs/docs/{development => }/hardware-integration/hardware-metadata-files.md (99%) rename docs/docs/{development => }/hardware-integration/includes/_gpio-key-direct.md (100%) rename docs/docs/{development => }/hardware-integration/includes/_gpio-key-matrix.md (100%) rename docs/docs/{development => }/hardware-integration/includes/_gpio-key-wakeup.md (100%) rename docs/docs/{development => }/hardware-integration/includes/_sideband-direct.md (64%) rename docs/docs/{development => }/hardware-integration/includes/_sideband-matrix.md (89%) rename docs/docs/{development => }/hardware-integration/includes/_sideband-wakeup-direct.md (67%) rename docs/docs/{development => }/hardware-integration/includes/_soft-off-behavior.md (69%) rename docs/docs/{development => }/hardware-integration/includes/_soft-off-waker.md (88%) rename docs/docs/{development => }/hardware-integration/index.mdx (82%) rename docs/docs/{development => }/hardware-integration/lighting/backlight.mdx (98%) rename docs/docs/{development => }/hardware-integration/lighting/index.mdx (100%) rename docs/docs/{development => }/hardware-integration/lighting/led-indicators.md (95%) rename docs/docs/{development => }/hardware-integration/lighting/underglow.md (97%) rename docs/docs/{development => }/hardware-integration/new-board.md (89%) rename docs/docs/{development => }/hardware-integration/new-shield.mdx (88%) rename docs/docs/{development => }/hardware-integration/physical-layouts.md (93%) rename docs/docs/{development => }/hardware-integration/pinctrl.mdx (100%) rename docs/docs/{development => }/hardware-integration/pointing.mdx (94%) rename docs/docs/{development => }/hardware-integration/shift-registers.md (93%) rename docs/docs/{development => }/hardware-integration/soft-off-setup.mdx (91%) diff --git a/app/keymap-module/modules/modules.cmake b/app/keymap-module/modules/modules.cmake index eed28907..e19230c8 100644 --- a/app/keymap-module/modules/modules.cmake +++ b/app/keymap-module/modules/modules.cmake @@ -50,12 +50,12 @@ if (ZMK_CONFIG) set(ENV{ZMK_CONFIG} "${ZMK_CONFIG}") if(EXISTS ${ZMK_CONFIG}/boards) message(STATUS "Adding ZMK config directory as board root: ${ZMK_CONFIG}") - message(DEPRECATION "The `config/boards` folder is deprecated. Please use a module instead. See https://zmk.dev/docs/development/hardware-integration/new-shield and https://zmk.dev/docs/development/module-creation for more information.") + message(DEPRECATION "The `config/boards` folder is deprecated. Please use a module instead. See https://zmk.dev/docs/hardware-integration/new-shield and https://zmk.dev/docs/development/module-creation for more information.") list(APPEND BOARD_ROOT ${ZMK_CONFIG}) endif() if(EXISTS ${ZMK_CONFIG}/dts) message(STATUS "Adding ZMK config directory as DTS root: ${ZMK_CONFIG}") - message(DEPRECATION "The `config/dts` folder is deprecated. Please use a module instead. See https://zmk.dev/docs/development/hardware-integration/new-shield and https://zmk.dev/docs/development/module-creation for more information.") + message(DEPRECATION "The `config/dts` folder is deprecated. Please use a module instead. See https://zmk.dev/docs/hardware-integration/new-shield and https://zmk.dev/docs/development/module-creation for more information.") list(APPEND DTS_ROOT ${ZMK_CONFIG}) endif() endif() diff --git a/app/src/physical_layouts.c b/app/src/physical_layouts.c index 31a8ac05..ba21ae31 100644 --- a/app/src/physical_layouts.c +++ b/app/src/physical_layouts.c @@ -71,7 +71,7 @@ BUILD_ASSERT( #define ZMK_LAYOUT_INST(n) \ BUILD_ASSERT(!IS_ENABLED(CONFIG_ZMK_STUDIO) || DT_INST_NODE_HAS_PROP(n, keys), \ "ZMK Studio requires physical layouts with key positions. See " \ - "https://zmk.dev/docs/development/hardware-integration/studio-setup"); \ + "https://zmk.dev/docs/hardware-integration/studio-setup"); \ static const struct zmk_key_physical_attrs _CONCAT(_zmk_physical_layout_keys_, \ n)[DT_INST_PROP_LEN_OR(n, keys, 0)] = { \ LISTIFY(DT_INST_PROP_LEN_OR(n, keys, 0), ZKPA_INIT, (, ), n)}; \ diff --git a/app/src/split/wired/central.c b/app/src/split/wired/central.c index 7ba66142..0354e52d 100644 --- a/app/src/split/wired/central.c +++ b/app/src/split/wired/central.c @@ -77,7 +77,7 @@ static const struct gpio_dt_spec detect_gpio = GPIO_DT_SPEC_INST_GET(0, detect_g #else #error \ - "Need to create a node with compatible of 'zmk,wired-split` with a `device` property set to an enabled UART. See http://zmk.dev/docs/development/hardware-integration/new-shield#wired-split" + "Need to create a node with compatible of 'zmk,wired-split` with a `device` property set to an enabled UART. See http://zmk.dev/docs/hardware-integration/new-shield#wired-split" #endif diff --git a/app/src/split/wired/peripheral.c b/app/src/split/wired/peripheral.c index b5b91cd9..71d3da83 100644 --- a/app/src/split/wired/peripheral.c +++ b/app/src/split/wired/peripheral.c @@ -76,7 +76,7 @@ static const struct gpio_dt_spec detect_gpio = GPIO_DT_SPEC_INST_GET(0, detect_g #else #error \ - "Need to create a node with compatible of 'zmk,wired-split` with a `device` property set to an enabled UART. See http://zmk.dev/docs/development/hardware-integration/new-shield#wired-split" + "Need to create a node with compatible of 'zmk,wired-split` with a `device` property set to an enabled UART. See http://zmk.dev/docs/hardware-integration/new-shield#wired-split" #endif diff --git a/docs/blog/2020-08-12-zmk-sotf-1.md b/docs/blog/2020-08-12-zmk-sotf-1.md index 31c6ffc6..9ea4038b 100644 --- a/docs/blog/2020-08-12-zmk-sotf-1.md +++ b/docs/blog/2020-08-12-zmk-sotf-1.md @@ -18,7 +18,7 @@ There's been lots of various activity in ZMK land! - Tons of [documentation](/docs) work. - Refactoring ([#73](https://github.com/zmkfirmware/zmk/pull/73), [#74](https://github.com/zmkfirmware/zmk/pull/74)) of [keymaps](/docs/keymaps) to make them simpler for users. - Mod-Tap Behavior (docs coming!) is much improved ([#69](https://github.com/zmkfirmware/zmk/pull/69)) and usable now. -- An initial [`setup.sh`](/docs/user-setup#user-config-setup-script) script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you. +- An initial `setup.sh` script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you. - Corne shield ([#80](https://github.com/zmkfirmware/zmk/pull/80)) shield definition was added. - Initial [encoder](/docs/features/encoders) support ([#61](https://github.com/zmkfirmware/zmk/pull/61)) was added. diff --git a/docs/blog/2022-04-10-zmk-sotf-5.md b/docs/blog/2022-04-10-zmk-sotf-5.md index 7abc2205..e771f2e2 100644 --- a/docs/blog/2022-04-10-zmk-sotf-5.md +++ b/docs/blog/2022-04-10-zmk-sotf-5.md @@ -219,7 +219,7 @@ This can be useful to be sure that lowering brightness doesn't set the brightnes ## Board/Shield Metadata -[nicell] and [petejohanson] worked together in [#883](https://github.com/zmkfirmware/zmk/pull/883) to settle on a [metadata format](/docs/development/hardware-integration/hardware-metadata-files) that is used to document every board and shield. This now drives automatic generation of our [supported hardware](/docs/hardware) page and our +[nicell] and [petejohanson] worked together in [#883](https://github.com/zmkfirmware/zmk/pull/883) to settle on a [metadata format](/docs/hardware-integration/hardware-metadata-files) that is used to document every board and shield. This now drives automatic generation of our [supported hardware](/docs/hardware) page and our more nuanced GH Actions automation for testing changes to ZMK. ## Coming Soon! diff --git a/docs/blog/2023-10-05-zmk-sotf-6.md b/docs/blog/2023-10-05-zmk-sotf-6.md index 45c2af49..ba1bf63b 100644 --- a/docs/blog/2023-10-05-zmk-sotf-6.md +++ b/docs/blog/2023-10-05-zmk-sotf-6.md @@ -173,7 +173,7 @@ For users or future contributors that might want to dive into writing their own #### Shield interconnects -[petejohanson] updated the [new shield guide](/docs/development/hardware-integration/new-shield) for non-Pro Micro interconnects including Xiao, Arduino Uno and Blackpill in [#1607](https://github.com/zmkfirmware/zmk/pull/1607). +[petejohanson] updated the [new shield guide](/docs/hardware-integration/new-shield) for non-Pro Micro interconnects including Xiao, Arduino Uno and Blackpill in [#1607](https://github.com/zmkfirmware/zmk/pull/1607). #### Bluetooth feature page diff --git a/docs/blog/2024-01-05-zmk-tools.md b/docs/blog/2024-01-05-zmk-tools.md index 1104396d..f18ad30d 100644 --- a/docs/blog/2024-01-05-zmk-tools.md +++ b/docs/blog/2024-01-05-zmk-tools.md @@ -19,7 +19,7 @@ Stay tuned for future installments in the series! ## ZMK Tools -[ZMK Tools](https://github.com/joelspadin/zmk-tools) is an extension for [Visual Studio Code](https://code.visualstudio.com) that helps with editing a ZMK user config repo or a fork of ZMK. I originally created it to add some code completion in `.keymap` files, but then I realized that with the web version of VS Code, I could also let you set up a user config repo and build firmware, much like the [user setup script](/docs/user-setup#user-config-setup-script), except without downloading a single thing. +[ZMK Tools](https://github.com/joelspadin/zmk-tools) is an extension for [Visual Studio Code](https://code.visualstudio.com) that helps with editing a ZMK user config repo or a fork of ZMK. I originally created it to add some code completion in `.keymap` files, but then I realized that with the web version of VS Code, I could also let you set up a user config repo and build firmware, much like the user setup script, except without downloading a single thing. ### User Config Setup in Browser diff --git a/docs/blog/2024-11-11-zmk-studio-mvp-ga.mdx b/docs/blog/2024-11-11-zmk-studio-mvp-ga.mdx index 8c4cac43..d1bb7218 100644 --- a/docs/blog/2024-11-11-zmk-studio-mvp-ga.mdx +++ b/docs/blog/2024-11-11-zmk-studio-mvp-ga.mdx @@ -225,7 +225,7 @@ return ( :::note -For keyboard maintainers, additional changes are needed to add metadata about the keyboard's physical layouts in order to use ZMK Studio. See the documentation on [physical layouts](/docs/development/hardware-integration/physical-layouts#optional-keys-property) for more information. +For keyboard maintainers, additional changes are needed to add metadata about the keyboard's physical layouts in order to use ZMK Studio. See the documentation on [physical layouts](/docs/hardware-integration/physical-layouts#optional-keys-property) for more information. ::: To use ZMK Studio, you need to have a firmware for your keyboard with the feature enabled, as well as a small keymap change to add an unlock key. See [Building with ZMK Studio](/docs/features/studio#building) and [ZMK Studio keymap changes](/docs/features/studio#keymap-changes) for more details. diff --git a/docs/blog/2025-12-09-zephyr-4-1.md b/docs/blog/2025-12-09-zephyr-4-1.md index c1cfefb2..0d3eb07f 100644 --- a/docs/blog/2025-12-09-zephyr-4-1.md +++ b/docs/blog/2025-12-09-zephyr-4-1.md @@ -257,7 +257,7 @@ A few other changes, unrelated to the HWMv2 move, may impact out-of-tree boards/ ### Bootloader Setup -With the version bump, the previous method to enable `&bootloader` has been disabled. Instead, ZMK is introducing _boot retention_, which as a side effect also enables `&bootloader` for SoCs which previously didn't work with said behavior, such as the STM32F072. To set up boot retention for your board, please read through [the dedicated page](/docs/development/hardware-integration/bootloader). +With the version bump, the previous method to enable `&bootloader` has been disabled. Instead, ZMK is introducing _boot retention_, which as a side effect also enables `&bootloader` for SoCs which previously didn't work with said behavior, such as the STM32F072. To set up boot retention for your board, please read through [the dedicated page](/docs/hardware-integration/bootloader). ### nRF52840 NFC Pins as GPIO diff --git a/docs/docs/config/bootloader.md b/docs/docs/config/bootloader.md index 7b4d2252..1387bc4c 100644 --- a/docs/docs/config/bootloader.md +++ b/docs/docs/config/bootloader.md @@ -32,7 +32,7 @@ To ensure the BOOT button on keyboard and controllers using these SoCs works as ### Bootmode Magic Value Mapper -Some target SoCs may use the bootmode magic value mapper for [bootloader integration](docs/development/hardware-integration/bootloader/index.mdx). When doing so, the following configurations are used: +Some target SoCs may use the bootmode magic value mapper for [bootloader integration](docs/hardware-integration/bootloader/index.mdx). When doing so, the following configurations are used: | Config | Type | Description | Default | | ---------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------- | ------- | diff --git a/docs/docs/config/index.md b/docs/docs/config/index.md index 2a6f183b..e81f65c3 100644 --- a/docs/docs/config/index.md +++ b/docs/docs/config/index.md @@ -64,7 +64,7 @@ ZMK will search the shield folder for the following config files _in addition_ t Shared config files (excluding any `_left` or `_right` suffix) are not currently supported in shield folders. -For more documentation on creating and configuring a new shield, see [Zephyr's shield documentation](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html) and [ZMK's new keyboard shield](../development/hardware-integration/new-shield.mdx) guide. +For more documentation on creating and configuring a new shield, see [Zephyr's shield documentation](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html) and [ZMK's new keyboard shield](../hardware-integration/new-shield.mdx) guide. ## Kconfig Files diff --git a/docs/docs/config/layout.md b/docs/docs/config/layout.md index 04fdf73b..dafcb9cf 100644 --- a/docs/docs/config/layout.md +++ b/docs/docs/config/layout.md @@ -11,7 +11,7 @@ Defines a mapping from keymap logical positions to physical [kscan](./kscan.md) You can define multiple matrix transform nodes, one for each layout, and users can select which one they want from the `/chosen` node in their keymaps. -See the [new shield guide](../development/hardware-integration/new-shield.mdx#matrix-transform) for more documentation on how to define a matrix transform. +See the [new shield guide](../hardware-integration/new-shield.mdx#matrix-transform) for more documentation on how to define a matrix transform. ### Devicetree @@ -174,7 +174,7 @@ Note that the entire addressable space does not need to be mapped. Defines a keyboard layout by joining together a [matrix transform](#matrix-transform), a [keyboard scan](./kscan.md), and a list of physical key properties. Multiple physical layouts can be defined for keyboards with multiple physical key layouts. -Read through the [page on physical layouts](../development/hardware-integration/physical-layouts.md) for more information. +Read through the [page on physical layouts](../hardware-integration/physical-layouts.md) for more information. ### Devicetree @@ -211,7 +211,7 @@ The `key_physical_attrs` node is defined in [`dts/physical_layouts.dtsi`](https: ## Physical Layout Position Map -Defines a mapping between [physical layouts](#physical-layout), allowing key mappings to be preserved in the same locations as previously when using [ZMK Studio](../features/studio.md). Read through the [page on physical layouts](../development/hardware-integration/physical-layouts.md) for more information. +Defines a mapping between [physical layouts](#physical-layout), allowing key mappings to be preserved in the same locations as previously when using [ZMK Studio](../features/studio.md). Read through the [page on physical layouts](../hardware-integration/physical-layouts.md) for more information. ### Devicetree diff --git a/docs/docs/config/lighting.md b/docs/docs/config/lighting.md index ceb49db8..07388b07 100644 --- a/docs/docs/config/lighting.md +++ b/docs/docs/config/lighting.md @@ -7,7 +7,7 @@ See the [Lighting feature page](../features/lighting.md) for an overview of the ## RGB Underglow -See the [RGB underglow section](../features/lighting.md#rgb-underglow) in the Lighting feature page for more details, and [hardware integration page](../development/hardware-integration/lighting/underglow.md) for adding underglow support to a board. +See the [RGB underglow section](../features/lighting.md#rgb-underglow) in the Lighting feature page for more details, and [hardware integration page](../hardware-integration/lighting/underglow.md) for adding underglow support to a board. See [Configuration Overview](index.md) for instructions on how to change these settings. @@ -52,11 +52,11 @@ The `*_START` settings only determine the initial underglow state. Any changes y ZMK does not have any Devicetree properties of its own. See the Devicetree bindings for [Zephyr's LED strip drivers](https://github.com/zephyrproject-rtos/zephyr/tree/main/dts/bindings/led_strip). -See the [RGB underglow hardware integration page](../development/hardware-integration/lighting/underglow.md) for examples of the properties that must be set to enable underglow. +See the [RGB underglow hardware integration page](../hardware-integration/lighting/underglow.md) for examples of the properties that must be set to enable underglow. ## Backlight -See the [backlight section](../features/lighting.md#backlight) in Lighting feature page for more details, and [hardware integration page](../development/hardware-integration/lighting/backlight.mdx) for adding backlight support to a board. +See the [backlight section](../features/lighting.md#backlight) in Lighting feature page for more details, and [hardware integration page](../hardware-integration/lighting/backlight.mdx) for adding backlight support to a board. See [Configuration Overview](index.md) for instructions on how to change these settings. @@ -90,4 +90,4 @@ See the Zephyr devicetree bindings for LED drivers: - [gpio-leds](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings/led/gpio-leds.html) - [pwm-leds](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings/led/pwm-leds.html) -See the [backlight hardware integration page](../development/hardware-integration/lighting/backlight.mdx) for examples of the properties that must be set to enable backlighting. +See the [backlight hardware integration page](../hardware-integration/lighting/backlight.mdx) for examples of the properties that must be set to enable backlighting. diff --git a/docs/docs/config/pointing.md b/docs/docs/config/pointing.md index a0e175d8..63565e4a 100644 --- a/docs/docs/config/pointing.md +++ b/docs/docs/config/pointing.md @@ -53,7 +53,7 @@ Additional properties can be set on child nodes, which allows changing the setti ## Input Split -Input splits are used for [pointing devices on split peripherals](../development/hardware-integration/pointing.mdx#listener-and-input-split-device). +Input splits are used for [pointing devices on split peripherals](../hardware-integration/pointing.mdx#listener-and-input-split-device). ### Devicetree diff --git a/docs/docs/config/settings.md b/docs/docs/config/settings.md index b6245475..f7b4c7b3 100644 --- a/docs/docs/config/settings.md +++ b/docs/docs/config/settings.md @@ -36,7 +36,7 @@ Definition file: [zmk/app/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/ While regular ZMK builds will not cause any settings to be cleared upon flashing, flashing a build with `CONFIG_ZMK_SETTINGS_RESET_ON_START` enabled as documented above will cause the firmware to run a special procedure when the controller starts that clears the settings partition. -For end users, it is recommended to use a special [shield](../development/hardware-integration/index.mdx#boards--shields) named `settings_reset` to build a new firmware file, then flash that firmware. +For end users, it is recommended to use a special [shield](../hardware-integration/index.mdx#boards--shields) named `settings_reset` to build a new firmware file, then flash that firmware. See example for building firmware using this shield in the [troubleshooting docs](../troubleshooting/connection-issues.mdx#building-a-reset-firmware). In both cases, regular, non-reset firmware will need to be flashed afterwards for normal operation. diff --git a/docs/docs/config/split.md b/docs/docs/config/split.md index d855e8ae..9aab0b02 100644 --- a/docs/docs/config/split.md +++ b/docs/docs/config/split.md @@ -76,7 +76,7 @@ The following settings only apply when using wired split in polling mode: ### Wired Split -Wired splits require a properly configured UART to function. If writing a shield, you may be able to use the standard UART already provided by the board, e.g. `&pro_micro_serial`. See [predefined nodes](../development/hardware-integration/pinctrl.mdx#predefined-nodes) for details on the UART node labels provided by various interconnects. If you are creating your own board, or using custom pins for the UART, see the documentation on [pin control](../development/hardware-integration/pinctrl.mdx#additional-examples) to configure the pins for your UART. +Wired splits require a properly configured UART to function. If writing a shield, you may be able to use the standard UART already provided by the board, e.g. `&pro_micro_serial`. See [predefined nodes](../hardware-integration/pinctrl.mdx#predefined-nodes) for details on the UART node labels provided by various interconnects. If you are creating your own board, or using custom pins for the UART, see the documentation on [pin control](../hardware-integration/pinctrl.mdx#additional-examples) to configure the pins for your UART. Once you have a properly configured UART device, it needs to be assigned in a new node with a compatible value of `"zmk,wired-split"`. For example: diff --git a/docs/docs/development/local-toolchain/build-flash.mdx b/docs/docs/development/local-toolchain/build-flash.mdx index 561c59ae..a9572feb 100644 --- a/docs/docs/development/local-toolchain/build-flash.mdx +++ b/docs/docs/development/local-toolchain/build-flash.mdx @@ -160,7 +160,7 @@ west build -b nice_nano -- -DSHIELD=vendor_shield -DZMK_EXTRA_MODULES="C:/Users/ ### Building from `zmk-config` Folder Instead of building .uf2 files using the default keymap and config files, you -can build using files from your [`zmk-config` folder](../../user-setup.mdx#github-repo) +can build using files from your [`zmk-config` folder](../../user-setup.mdx#config-repo-setup) by adding `-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build` command. **Notice that this path should point to the folder labeled `config` within your `zmk-config` folder.** diff --git a/docs/docs/faq.md b/docs/docs/faq.md index 5abcc30f..fa9fcea5 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -51,7 +51,7 @@ ZMK is still in its infancy, so there’s a learning curve involved. But if you ZMK uses the Zephyr concepts of "boards" and "shields" to refer to different parts of a keyboard build, that in turn get combined during a firmware build. This provides the modularity to be able to use composite keyboards with different compatible controllers. -Please see the [explainer on boards & shields](development/hardware-integration/index.mdx#boards--shields) for more details. +Please see the [explainer on boards & shields](hardware-integration/index.mdx#boards--shields) for more details. ### Does ZMK support wired split? @@ -63,7 +63,7 @@ The latency of ZMK is comparable to other firmware offerings. ZMK is equipped wi ### Any chance for 2.4GHz dongle implementation? -At this time, there are no current plans to implement 2.4GHz dongle mode. This is because utilizing Nordic's proprietary 2.4GHz low level protocols requires use of the Nordic Connect SDK, which is licensed with a more restrictive license than ZMK's MIT license. However, it is possible to [create a dongle](development/hardware-integration/dongle.mdx) for your keyboard that runs ZMK and communicates between parts using BLE (with encryption). This results in a 3.75ms average theoretical latency from the protocol itself. +At this time, there are no current plans to implement 2.4GHz dongle mode. This is because utilizing Nordic's proprietary 2.4GHz low level protocols requires use of the Nordic Connect SDK, which is licensed with a more restrictive license than ZMK's MIT license. However, it is possible to [create a dongle](hardware-integration/dongle.mdx) for your keyboard that runs ZMK and communicates between parts using BLE (with encryption). This results in a 3.75ms average theoretical latency from the protocol itself. ### What bootloader does ZMK use? diff --git a/docs/docs/features/battery.md b/docs/docs/features/battery.md index 4d77d805..1a34c02f 100644 --- a/docs/docs/features/battery.md +++ b/docs/docs/features/battery.md @@ -16,4 +16,4 @@ Windows may not properly ask the keyboard to notify it of changes in battery lev ## Adding a Battery Sensor to a Board If your keyboard is using one of the [boards supported in ZMK](../hardware.mdx) it will already be configured to sense and report battery levels. -If you are using a custom board, see [battery sensing hardware integration page](../development/hardware-integration/battery.md) to add support. +If you are using a custom board, see [battery sensing hardware integration page](../hardware-integration/battery.md) to add support. diff --git a/docs/docs/features/encoders.md b/docs/docs/features/encoders.md index 267f2e3d..5b128556 100644 --- a/docs/docs/features/encoders.md +++ b/docs/docs/features/encoders.md @@ -41,4 +41,4 @@ Here, the left encoder is configured to control volume up and down while the rig ## Adding Encoder Support -See the [Hardware Integration page for encoders](../development/hardware-integration/encoders.md) for instructions on adding them to your keyboard. +See the [Hardware Integration page for encoders](../hardware-integration/encoders.md) for instructions on adding them to your keyboard. diff --git a/docs/docs/features/led-indicators.md b/docs/docs/features/led-indicators.md index c8229d78..b4a6ddab 100644 --- a/docs/docs/features/led-indicators.md +++ b/docs/docs/features/led-indicators.md @@ -58,10 +58,10 @@ For example, if you want the LED to be off when the indicator is active, 100% br If the LED is not configured to support brightness control, any value greater than 0 will result in maximum brightness. -For most LEDs, you can enable PWM brightness control, though this will increase power usage slightly. See the [LED indicators hardware integration page](../development/hardware-integration/lighting/led-indicators.md) for details on configuring the LEDs. +For most LEDs, you can enable PWM brightness control, though this will increase power usage slightly. See the [LED indicators hardware integration page](../hardware-integration/lighting/led-indicators.md) for details on configuring the LEDs. ::: ## Adding LED Indicator Support to a Keyboard -See the [LED indicators hardware integration page](../development/hardware-integration/lighting/led-indicators.md) for instructions to enable this feature on a keyboard. +See the [LED indicators hardware integration page](../hardware-integration/lighting/led-indicators.md) for instructions to enable this feature on a keyboard. diff --git a/docs/docs/features/lighting.md b/docs/docs/features/lighting.md index b0535503..c2a6699b 100644 --- a/docs/docs/features/lighting.md +++ b/docs/docs/features/lighting.md @@ -73,7 +73,7 @@ See [RGB underglow configuration](../config/lighting.md#rgb-underglow). ### Adding RGB Underglow Support to a Keyboard -See [RGB underglow hardware integration page](../development/hardware-integration/lighting/underglow.md) on adding underglow support to a ZMK keyboard. +See [RGB underglow hardware integration page](../hardware-integration/lighting/underglow.md) on adding underglow support to a ZMK keyboard. ## Backlight @@ -100,4 +100,4 @@ See [backlight configuration](../config/lighting.md#backlight) for details. ### Adding Backlight to a Board or a Shield -See [backlight hardware integration page](../development/hardware-integration/lighting/backlight.mdx) for information on adding backlight support to a ZMK keyboard. +See [backlight hardware integration page](../hardware-integration/lighting/backlight.mdx) for information on adding backlight support to a ZMK keyboard. diff --git a/docs/docs/features/low-power-states.md b/docs/docs/features/low-power-states.md index 4818ecd3..5e0a384b 100644 --- a/docs/docs/features/low-power-states.md +++ b/docs/docs/features/low-power-states.md @@ -78,4 +78,4 @@ You can then wake up the keyboard by pressing the reset button once, and repeati ### Adding Soft Off to a Keyboard -Please refer to the [corresponding page under hardware integration](../development/hardware-integration/soft-off-setup.mdx) for details. +Please refer to the [corresponding page under hardware integration](../hardware-integration/soft-off-setup.mdx) for details. diff --git a/docs/docs/features/pointing.md b/docs/docs/features/pointing.md index b22485ab..92772722 100644 --- a/docs/docs/features/pointing.md +++ b/docs/docs/features/pointing.md @@ -24,7 +24,7 @@ See the [mouse emulation behaviors](../keymaps/behaviors/mouse-emulation.md) for There are a few drivers available for supporting physical pointing devices integrated into a ZMK powered device. When doing so, you can use your device as both a keyboard and a pointing device with any connected hosts. The functionality can be extended further, e.g. slow mode, scroll mode, temporary mouse layers, etc. by configuring [input processors](#input-processors) linked to the physical pointing device. -For more information, refer to the [pointer hardware integration](../development/hardware-integration/pointing.mdx) documentation. +For more information, refer to the [pointer hardware integration](../hardware-integration/pointing.mdx) documentation. ## Input Processors diff --git a/docs/docs/features/split-keyboards.md b/docs/docs/features/split-keyboards.md index 36cf9043..1f3e6675 100644 --- a/docs/docs/features/split-keyboards.md +++ b/docs/docs/features/split-keyboards.md @@ -8,7 +8,7 @@ ZMK supports setups where a keyboard is split into two or more physical parts (a ## Central and Peripheral Roles In split keyboards running ZMK, one part is assigned the "central" role which receives key position and sensor events from the other parts that are called "peripherals." -The central runs the necessary keymap logic to convert received events into HID events such as keycodes and then communicates with the connected host devices, e.g. over USB or bluetooth. If the keyboard makes use of a [dongle](../development/hardware-integration/dongle.mdx), then the dongle takes on the role of central. +The central runs the necessary keymap logic to convert received events into HID events such as keycodes and then communicates with the connected host devices, e.g. over USB or bluetooth. If the keyboard makes use of a [dongle](../hardware-integration/dongle.mdx), then the dongle takes on the role of central. The internal keyboard state (like active layers) is handled exclusively by the central. Peripherals _cannot_ communicate with host devices on their own, since they can only communicate with the central. @@ -23,7 +23,7 @@ You can refer to the [power profiler](/power-profiler) to see battery life estim ### Configuration -The [new shield guide](../development/hardware-integration/new-shield.mdx) details how to define a split keyboard shield with two parts, enabling the split feature and setting up the necessary roles for each part. +The [new shield guide](../hardware-integration/new-shield.mdx) details how to define a split keyboard shield with two parts, enabling the split feature and setting up the necessary roles for each part. Also see the reference section on [split keyboards configuration](../config/split.md) where the relevant symbols include `CONFIG_ZMK_SPLIT` that enables the feature, `CONFIG_ZMK_SPLIT_ROLE_CENTRAL` which sets the central role and `CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS` that sets the number of peripherals. @@ -44,7 +44,7 @@ Many popular cables, in particular, TRRS/TRS cables, can cause irreparable damag ### Bluetooth -[Bluetooth](./bluetooth.md) is the most well tested and flexible transport available in ZMK. Using Bluetooth, a central can connect to multiple peripherals, enabling the use of a [dongle](../development/hardware-integration/dongle.mdx) to improve battery life, or allowing for multi-part split keyboards. +[Bluetooth](./bluetooth.md) is the most well tested and flexible transport available in ZMK. Using Bluetooth, a central can connect to multiple peripherals, enabling the use of a [dongle](../hardware-integration/dongle.mdx) to improve battery life, or allowing for multi-part split keyboards. This transport will be enabled for designs that set `CONFIG_ZMK_SPLIT=y` and have `CONFIG_ZMK_BLE=y` set by a supported MCU/controller. diff --git a/docs/docs/features/studio.md b/docs/docs/features/studio.md index 8cca1fb8..82e256e2 100644 --- a/docs/docs/features/studio.md +++ b/docs/docs/features/studio.md @@ -172,12 +172,12 @@ The reserved layers will be ignored during regular ZMK builds but will become av To allow ZMK Studio to be used with a keyboard, the keyboard will need to have a physical layout with the `keys` property defined. The keyboard should also **not** have a `chosen` `zmk,matrix-transform`. Relevant information can be found in: -- The [dedicated page on physical layouts](../development/hardware-integration/physical-layouts.md), informing you how to define one -- The [new shield guide](../development/hardware-integration/new-shield.mdx), informing you how to select a physical layout once defined +- The [dedicated page on physical layouts](../hardware-integration/physical-layouts.md), informing you how to define one +- The [new shield guide](../hardware-integration/new-shield.mdx), informing you how to select a physical layout once defined - The corresponding [configuration page](../config/layout.md#physical-layout), for reference To use the `studio-rpc-usb-uart` snippet, the keyboard also needs to be configured to allow CDC-ACM console snippets (this is also used for [USB logging](../development/usb-logging.mdx)). If your keyboard is a composite keyboard, consisting of an in-tree board and a shield, then you can skip this step as the board will already be configured properly. Relevant information on that can be found [in the Zephyr documentation](https://docs.zephyrproject.org/4.1.0/snippets/cdc-acm-console/README.html). Firmware with ZMK Studio enabled require significantly more RAM. Some MCUs, such as the STM32F072 series, will require fine tuning of various settings in order to reduce the RAM consumption enough for a Studio enabled build to fit. -Finally, once you have successfully built and tested firmware with ZMK Studio enabled, add the `studio` flag to your keyboard's [metadata](../development/hardware-integration/hardware-metadata-files#features). +Finally, once you have successfully built and tested firmware with ZMK Studio enabled, add the `studio` flag to your keyboard's [metadata](../hardware-integration/hardware-metadata-files#features). diff --git a/docs/docs/development/hardware-integration/battery.md b/docs/docs/hardware-integration/battery.md similarity index 82% rename from docs/docs/development/hardware-integration/battery.md rename to docs/docs/hardware-integration/battery.md index d3276069..9b717baf 100644 --- a/docs/docs/development/hardware-integration/battery.md +++ b/docs/docs/hardware-integration/battery.md @@ -3,7 +3,7 @@ title: Battery Sensing sidebar_label: Battery Sensing --- -If your keyboard is using one of the [boards supported in ZMK](../../hardware.mdx) it will already be configured to [sense and report battery levels](../../features/battery.md). +If your keyboard is using one of the [boards supported in ZMK](../hardware.mdx) it will already be configured to [sense and report battery levels](../features/battery.md). Below instructions are only intended for users defining and using a custom board. To enable a battery sensor on a new board, add the driver for the sensor to your board's `.dts` file. ZMK provides two drivers for estimating the battery level using its voltage: @@ -11,7 +11,7 @@ To enable a battery sensor on a new board, add the driver for the sensor to your - `zmk,battery-voltage-divider`: Reads the voltage on an analog input pin. - `zmk,battery-nrf-vddh`: Reads the power supply voltage on a Nordic nRF52's VDDH pin. -See the [battery level configuration page](../../config/battery.md) for the configuration supported by each driver provided by ZMK. +See the [battery level configuration page](../config/battery.md) for the configuration supported by each driver provided by ZMK. Zephyr also provides some drivers for fuel gauge ICs such as the TI bq274xx series and Maxim MAX17xxx series. If you use a battery sensor that does not have an existing driver, you will need to write a new driver that supports the `SENSOR_CHAN_GAUGE_STATE_OF_CHARGE` sensor channel and contribute it to Zephyr or ZMK. diff --git a/docs/docs/development/hardware-integration/bootloader/_base-config.md b/docs/docs/hardware-integration/bootloader/_base-config.md similarity index 100% rename from docs/docs/development/hardware-integration/bootloader/_base-config.md rename to docs/docs/hardware-integration/bootloader/_base-config.md diff --git a/docs/docs/development/hardware-integration/bootloader/adafruit-nrf52.mdx b/docs/docs/hardware-integration/bootloader/adafruit-nrf52.mdx similarity index 100% rename from docs/docs/development/hardware-integration/bootloader/adafruit-nrf52.mdx rename to docs/docs/hardware-integration/bootloader/adafruit-nrf52.mdx diff --git a/docs/docs/development/hardware-integration/bootloader/index.mdx b/docs/docs/hardware-integration/bootloader/index.mdx similarity index 100% rename from docs/docs/development/hardware-integration/bootloader/index.mdx rename to docs/docs/hardware-integration/bootloader/index.mdx diff --git a/docs/docs/development/hardware-integration/bootloader/rp2.mdx b/docs/docs/hardware-integration/bootloader/rp2.mdx similarity index 92% rename from docs/docs/development/hardware-integration/bootloader/rp2.mdx rename to docs/docs/hardware-integration/bootloader/rp2.mdx index fce59b03..fcbc65e9 100644 --- a/docs/docs/development/hardware-integration/bootloader/rp2.mdx +++ b/docs/docs/hardware-integration/bootloader/rp2.mdx @@ -7,7 +7,7 @@ import BaseConfig from "./_base-config.md"; The RP2040/RP2350 Bootloader is a [jump-to type bootloader](./index.mdx#jump-to-bootloaders), with some extra setup used to integrate with it. -By default, when integrating this bootloader, a ["double tap reset to enter the bootloader"](../../../config/system.md#double-tap-to-bootloader) feature will be enabled, to help with designs that do not easily expose a BOOTSEL pin. +By default, when integrating this bootloader, a ["double tap reset to enter the bootloader"](../../config/bootloader.md#double-tap-to-bootloader) feature will be enabled, to help with designs that do not easily expose a BOOTSEL pin. diff --git a/docs/docs/development/hardware-integration/bootloader/samd21-uf2.mdx b/docs/docs/hardware-integration/bootloader/samd21-uf2.mdx similarity index 100% rename from docs/docs/development/hardware-integration/bootloader/samd21-uf2.mdx rename to docs/docs/hardware-integration/bootloader/samd21-uf2.mdx diff --git a/docs/docs/development/hardware-integration/bootloader/stm32.mdx b/docs/docs/hardware-integration/bootloader/stm32.mdx similarity index 92% rename from docs/docs/development/hardware-integration/bootloader/stm32.mdx rename to docs/docs/hardware-integration/bootloader/stm32.mdx index 6d7a45dd..5fcca6dd 100644 --- a/docs/docs/development/hardware-integration/bootloader/stm32.mdx +++ b/docs/docs/hardware-integration/bootloader/stm32.mdx @@ -8,7 +8,7 @@ import BaseConfig from "./_base-config.md"; The [STM32 ROM Bootloader](https://www.st.com/resource/en/application_note/an2606-stm32-microcontroller-system-memory-boot-mode-stmicroelectronics.pdf) is a [jump-to type bootloader](./index.mdx#jump-to-bootloaders), with some extra setup used to integrate with it. -By default, when integrating this bootloader, a ["double tap reset to enter the bootloader"](../../../config/system.md#double-tap-to-bootloader) feature will be enabled, to help with designs that do not easily expose a BOOT pin. +By default, when integrating this bootloader, a ["double tap reset to enter the bootloader"](../../config/bootloader.md#double-tap-to-bootloader) feature will be enabled, to help with designs that do not easily expose a BOOT pin. diff --git a/docs/docs/development/hardware-integration/bootloader/tinyuf2.mdx b/docs/docs/hardware-integration/bootloader/tinyuf2.mdx similarity index 100% rename from docs/docs/development/hardware-integration/bootloader/tinyuf2.mdx rename to docs/docs/hardware-integration/bootloader/tinyuf2.mdx diff --git a/docs/docs/development/hardware-integration/dongle.mdx b/docs/docs/hardware-integration/dongle.mdx similarity index 91% rename from docs/docs/development/hardware-integration/dongle.mdx rename to docs/docs/hardware-integration/dongle.mdx index c9fe5222..822b6248 100644 --- a/docs/docs/development/hardware-integration/dongle.mdx +++ b/docs/docs/hardware-integration/dongle.mdx @@ -6,7 +6,7 @@ sidebar_label: Keyboard Dongle import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; -A bluetooth dongle can be added to any wireless keyboard running ZMK. The result is a [split keyboard](../../features/split-keyboards.md) with the dongle as ["central"](../../features/split-keyboards.md#central-and-peripheral-roles). There are a number of advantages to adding a dongle, but also some disadvantages: +A bluetooth dongle can be added to any wireless keyboard running ZMK. The result is a [split keyboard](../features/split-keyboards.md) with the dongle as ["central"](../features/split-keyboards.md#central-and-peripheral-roles). There are a number of advantages to adding a dongle, but also some disadvantages: Benefits: @@ -18,7 +18,7 @@ Disadvantages: - An extra [board](index.mdx#what-is-a-board) is needed (any BLE-capable board that ZMK supports will work). - The keyboard becomes unusable without the dongle. -Depending on how the dongle is used, there are some additional [latency considerations](../../features/split-keyboards.md#latency-considerations) to keep in mind. +Depending on how the dongle is used, there are some additional [latency considerations](../features/split-keyboards.md#latency-considerations) to keep in mind. The addition of the dongle adds an extra "hop" for the former central, increasing its latency to that of a peripheral. The other parts are unchanged latency-wise. There is also a commonly occurring case where the peripherals benefit. Assuming the dongle is connected to USB and the former central would have been connected via bluetooth to the host if the dongle wasn't present: @@ -119,7 +119,7 @@ You will now need to find and copy your keyboard's matrix transform into the `my #### Matrix transform -Navigate to the directory defining your keyboard (in-tree keyboards found [here](https://github.com/zmkfirmware/zmk/tree/main/app/boards), if your keyboard is a shield look under the `shields` subdirectory) and look through the [devicetree files](../../config/index.md) for nodes with `compatible = "zmk,matrix-transform";`. +Navigate to the directory defining your keyboard (in-tree keyboards found [here](https://github.com/zmkfirmware/zmk/tree/main/app/boards), if your keyboard is a shield look under the `shields` subdirectory) and look through the [devicetree files](../config/index.md) for nodes with `compatible = "zmk,matrix-transform";`. This should look something like this: ```dts @@ -141,7 +141,7 @@ Make a note of the label that the transform has, it will be used later. In the e #### Physical layout -A full physical layout is necessary to allow your dongle to be used with [ZMK Studio](../../features/studio.md). +A full physical layout is necessary to allow your dongle to be used with [ZMK Studio](../features/studio.md). If your keyboard is not Studio-ready or you have no interest in using ZMK Studio with your dongle, then this section is simplified significantly. ; ``` -Add additional bindings as necessary to match the default number of encoders on your board. See the [Encoders](../../features/encoders.md) and [Keymaps](../../keymaps/index.mdx) documentation pages for more details. +Add additional bindings as necessary to match the default number of encoders on your board. See the [Encoders](../features/encoders.md) and [Keymaps](../keymaps/index.mdx) documentation pages for more details. diff --git a/docs/docs/development/hardware-integration/hardware-metadata-files.md b/docs/docs/hardware-integration/hardware-metadata-files.md similarity index 99% rename from docs/docs/development/hardware-integration/hardware-metadata-files.md rename to docs/docs/hardware-integration/hardware-metadata-files.md index 6a3c5a33..62fdb348 100644 --- a/docs/docs/development/hardware-integration/hardware-metadata-files.md +++ b/docs/docs/hardware-integration/hardware-metadata-files.md @@ -95,7 +95,7 @@ Boards and shields should document the sets of hardware features found on them u - `encoder` - Indicates the hardware contains one or more rotary encoders. - `underglow` - Indicates the hardware includes underglow LEDs. - `backlight` - Indicates the hardware includes backlight LEDs. -- `studio` - Indicates the keyboard is ready to use with [ZMK Studio](../../features/studio.md). +- `studio` - Indicates the keyboard is ready to use with [ZMK Studio](../features/studio.md). - `pointer` (future) - Used to indicate the hardware includes one or more pointer inputs, e.g. joystick, touchpad, or trackpoint. ### Siblings diff --git a/docs/docs/development/hardware-integration/includes/_gpio-key-direct.md b/docs/docs/hardware-integration/includes/_gpio-key-direct.md similarity index 100% rename from docs/docs/development/hardware-integration/includes/_gpio-key-direct.md rename to docs/docs/hardware-integration/includes/_gpio-key-direct.md diff --git a/docs/docs/development/hardware-integration/includes/_gpio-key-matrix.md b/docs/docs/hardware-integration/includes/_gpio-key-matrix.md similarity index 100% rename from docs/docs/development/hardware-integration/includes/_gpio-key-matrix.md rename to docs/docs/hardware-integration/includes/_gpio-key-matrix.md diff --git a/docs/docs/development/hardware-integration/includes/_gpio-key-wakeup.md b/docs/docs/hardware-integration/includes/_gpio-key-wakeup.md similarity index 100% rename from docs/docs/development/hardware-integration/includes/_gpio-key-wakeup.md rename to docs/docs/hardware-integration/includes/_gpio-key-wakeup.md diff --git a/docs/docs/development/hardware-integration/includes/_sideband-direct.md b/docs/docs/hardware-integration/includes/_sideband-direct.md similarity index 64% rename from docs/docs/development/hardware-integration/includes/_sideband-direct.md rename to docs/docs/hardware-integration/includes/_sideband-direct.md index f59673fd..e224a584 100644 --- a/docs/docs/development/hardware-integration/includes/_sideband-direct.md +++ b/docs/docs/hardware-integration/includes/_sideband-direct.md @@ -1,8 +1,8 @@ ### KScan sideband behavior -The kscan sideband behavior driver will be used to trigger the [soft off behavior](../../../keymaps/behaviors/soft-off.md) "out of band" from the normal keymap processing. To do so, it will decorate/wrap an underlying kscan driver. +The kscan sideband behavior driver will be used to trigger the [soft off behavior](../../keymaps/behaviors/soft-off.md) "out of band" from the normal keymap processing. To do so, it will decorate/wrap an underlying kscan driver. -With a simple direct pin setup, the [direct kscan](../../../config/kscan.md) driver can be used with a [GPIO key](#gpio-key), to make a small "side matrix": +With a simple direct pin setup, the [direct kscan](../../config/kscan.md) driver can be used with a [GPIO key](#gpio-key), to make a small "side matrix": ```dts / { @@ -34,4 +34,4 @@ With that in place, the kscan sideband behavior will wrap the new driver: }; ``` -As the kscan used only has a single key, both column and row are set to 0. The properties of the `kscan-sideband-behaviors` node can be found in the [appropriate configuration section](../../../config/kscan.md#kscan-sideband-behavior-driver). +As the kscan used only has a single key, both column and row are set to 0. The properties of the `kscan-sideband-behaviors` node can be found in the [appropriate configuration section](../../config/kscan.md#kscan-sideband-behavior-driver). diff --git a/docs/docs/development/hardware-integration/includes/_sideband-matrix.md b/docs/docs/hardware-integration/includes/_sideband-matrix.md similarity index 89% rename from docs/docs/development/hardware-integration/includes/_sideband-matrix.md rename to docs/docs/hardware-integration/includes/_sideband-matrix.md index 2d727801..c6de0f41 100644 --- a/docs/docs/development/hardware-integration/includes/_sideband-matrix.md +++ b/docs/docs/hardware-integration/includes/_sideband-matrix.md @@ -1,6 +1,6 @@ ### KScan sideband behavior -The kscan sideband behavior driver will be used to trigger the [soft off behavior](../../../keymaps/behaviors/soft-off.md) "out of band" from the normal keymap processing. To do so, it will decorate/wrap an underlying kscan driver. +The kscan sideband behavior driver will be used to trigger the [soft off behavior](../../keymaps/behaviors/soft-off.md) "out of band" from the normal keymap processing. To do so, it will decorate/wrap an underlying kscan driver. For the matrix-integrated approach you will supplement the existing kscan matrix by adding the additional pin as another entry in the `row-gpios`/`col-gpios` for whichever pins are used to read the matrix state. This approach requires a matrix transform to be present. As an example, consider the following existing kscan matrix: @@ -63,4 +63,4 @@ With that in place, you would decorate the kscan driver: }; ``` -Critically, the `column` and `row` values would correspond to the location of the added entry. The properties of the `kscan-sideband-behaviors` node can be found in the [appropriate configuration section](../../../config/kscan.md#kscan-sideband-behavior-driver). +Critically, the `column` and `row` values would correspond to the location of the added entry. The properties of the `kscan-sideband-behaviors` node can be found in the [appropriate configuration section](../../config/kscan.md#kscan-sideband-behavior-driver). diff --git a/docs/docs/development/hardware-integration/includes/_sideband-wakeup-direct.md b/docs/docs/hardware-integration/includes/_sideband-wakeup-direct.md similarity index 67% rename from docs/docs/development/hardware-integration/includes/_sideband-wakeup-direct.md rename to docs/docs/hardware-integration/includes/_sideband-wakeup-direct.md index a3b8d565..dc389726 100644 --- a/docs/docs/development/hardware-integration/includes/_sideband-wakeup-direct.md +++ b/docs/docs/hardware-integration/includes/_sideband-wakeup-direct.md @@ -1,6 +1,6 @@ ### KScan sideband behavior -With a simple direct pin setup, the [direct kscan](../../../config/kscan.md) driver can be used with a [GPIO key](#gpio-key), to make a small "side matrix": +With a simple direct pin setup, the [direct kscan](../../config/kscan.md) driver can be used with a [GPIO key](#gpio-key), to make a small "side matrix": ```dts / { @@ -25,4 +25,4 @@ The kscan sideband behavior needs to wrap the new driver to enable it: }; ``` -The properties of the `kscan-sideband-behaviors` node can be found in the [appropriate configuration section](../../../config/kscan.md#kscan-sideband-behavior-driver). +The properties of the `kscan-sideband-behaviors` node can be found in the [appropriate configuration section](../../config/kscan.md#kscan-sideband-behavior-driver). diff --git a/docs/docs/development/hardware-integration/includes/_soft-off-behavior.md b/docs/docs/hardware-integration/includes/_soft-off-behavior.md similarity index 69% rename from docs/docs/development/hardware-integration/includes/_soft-off-behavior.md rename to docs/docs/hardware-integration/includes/_soft-off-behavior.md index 9967f398..9f9ac021 100644 --- a/docs/docs/development/hardware-integration/includes/_soft-off-behavior.md +++ b/docs/docs/hardware-integration/includes/_soft-off-behavior.md @@ -1,6 +1,6 @@ ### Soft off behavior instance -Behind the scenes, a hardware dedicated GPIO pin utilizes the [soft off behavior](../../../keymaps/behaviors/soft-off.md) to trigger entering the soft-off state. To use said behavior outside of a keymap, add an instance of the behavior to your `.overlay`/`.dts` file: +Behind the scenes, a hardware dedicated GPIO pin utilizes the [soft off behavior](../../keymaps/behaviors/soft-off.md) to trigger entering the soft-off state. To use said behavior outside of a keymap, add an instance of the behavior to your `.overlay`/`.dts` file: ```dts / { diff --git a/docs/docs/development/hardware-integration/includes/_soft-off-waker.md b/docs/docs/hardware-integration/includes/_soft-off-waker.md similarity index 88% rename from docs/docs/development/hardware-integration/includes/_soft-off-waker.md rename to docs/docs/hardware-integration/includes/_soft-off-waker.md index 88b830e3..d6349b46 100644 --- a/docs/docs/development/hardware-integration/includes/_soft-off-waker.md +++ b/docs/docs/hardware-integration/includes/_soft-off-waker.md @@ -13,5 +13,5 @@ We need to add another device which will be enabled only when the keyboard is go }; ``` -The properties for the `gpio-key-wakeup-trigger` node can be found in the [appropriate configuration section](../../../config/power.md#gpio-key-wakeup-trigger). +The properties for the `gpio-key-wakeup-trigger` node can be found in the [appropriate configuration section](../../config/power.md#gpio-key-wakeup-trigger). In particular, note the `extra-gpios` property containing the MCU output pins of any keys used to wake the keyboard (for a `col2row` matrix, these are your columns). diff --git a/docs/docs/development/hardware-integration/index.mdx b/docs/docs/hardware-integration/index.mdx similarity index 82% rename from docs/docs/development/hardware-integration/index.mdx rename to docs/docs/hardware-integration/index.mdx index a9da0109..5c7ed01b 100644 --- a/docs/docs/development/hardware-integration/index.mdx +++ b/docs/docs/hardware-integration/index.mdx @@ -12,10 +12,10 @@ Please see pages in the sidebar for guides and reference that describe different The foundational elements needed to get a specific keyboard working with ZMK can be broken down into: - A [physical layout](physical-layouts.md) that describes the electrical and physical structure of the keyboard, referring to: - - A [kscan driver](../../config/kscan.md), which most frequently uses `compatible = "zmk,kscan-gpio-matrix"` for GPIO matrix based keyboards, or `compatible = "zmk,kscan-gpio-direct"` for direct wires. - - A [matrix transform](../../config/layout.md), which defines how the kscan row/column events are translated into logical "key positions". - - An [optional description](physical-layouts.md#optional-keys-property) of physical key positions and sizes, in order to visualize the keyboard accurately in [ZMK Studio](../../features/studio.md). -- A [keymap](../../keymaps/index.mdx), which binds each key position to a behavior, e.g. key press, mod-tap, momentary layer, in a set of layers. + - A [kscan driver](../config/kscan.md), which most frequently uses `compatible = "zmk,kscan-gpio-matrix"` for GPIO matrix based keyboards, or `compatible = "zmk,kscan-gpio-direct"` for direct wires. + - A [matrix transform](../config/layout.md), which defines how the kscan row/column events are translated into logical "key positions". + - An [optional description](physical-layouts.md#optional-keys-property) of physical key positions and sizes, in order to visualize the keyboard accurately in [ZMK Studio](../features/studio.md). +- A [keymap](../keymaps/index.mdx), which binds each key position to a behavior, e.g. key press, mod-tap, momentary layer, in a set of layers. - Other, optional configuration items to support features such as encoders or lighting systems. These core architectural elements are defined per-keyboard, and _where_ they are defined depends on the specifics of how that keyboard is structured. @@ -41,7 +41,7 @@ The shield is usually the big PCB containing all the keys. ### Why not just "keyboard"? -["Composite" keyboards](../../hardware.mdx#composite) are keyboards which use a separate small PCB MCU module for its "brains". +["Composite" keyboards](../hardware.mdx#composite) are keyboards which use a separate small PCB MCU module for its "brains". In such keyboards, the [shield](#what-is-a-shield) is a brainless shell containing all the keys, RGB LEDs, encoders etc. It typically maps all of these features to a standard pin footprint, such as the Pro Micro pinout. @@ -52,7 +52,7 @@ But each board comes with its own features (MCU, flash, BLE, etc.) which must al Therefore in ZMK, board and shield are considered two different (but related) entities so that it is easier to mix and match them, and they are combined during a ZMK build. This provides the modularity to be able to use composite keyboards with different compatible controllers. -Note that ["self-contained" keyboards](../../hardware.mdx#onboard) only have a single PCB which includes the "brains" (MCU) onboard. +Note that ["self-contained" keyboards](../hardware.mdx#onboard) only have a single PCB which includes the "brains" (MCU) onboard. In ZMK, these have no shield, only a board. ## Organization Overview @@ -67,11 +67,11 @@ values={[ -For a [self-contained keyboard](../../hardware.mdx#onboard) that includes the microprocessor, all of the above architecture components are included in the Zephyr _board_ definition and no shield is defined. +For a [self-contained keyboard](../hardware.mdx#onboard) that includes the microprocessor, all of the above architecture components are included in the Zephyr _board_ definition and no shield is defined. You can see an example for the [Planck V6](https://github.com/zmkfirmware/zmk/tree/main/app/boards/olkb/planck) board directory. -With this type of keyboard, the full ZMK definition for the keyboard exists in the `/boards//` directory where `` is `zmk/app` or a [module](../../features/modules.mdx) root, e.g. `zmk/app/boards/olkb/planck/`. -In that directory you'll have the following files, where there can be multiples of files with ``s, corresponding to each keyboard part for [split keyboards](../../features/split-keyboards.md): +With this type of keyboard, the full ZMK definition for the keyboard exists in the `/boards//` directory where `` is `zmk/app` or a [module](../features/modules.mdx) root, e.g. `zmk/app/boards/olkb/planck/`. +In that directory you'll have the following files, where there can be multiples of files with ``s, corresponding to each keyboard part for [split keyboards](../features/split-keyboards.md): ``` @@ -89,14 +89,14 @@ These files include [base Kconfig files](https://docs.zephyrproject.org/4.1.0/bu - A `Kconfig.` file that defines the toplevel [Kconfig](https://docs.zephyrproject.org/4.1.0/build/kconfig/index.html) items for the board, including selecting the corresponding SoC Kconfig setting. - A `Kconfig.defconfig` file that sets some initial defaults when building this keyboard. This usually includes: - - Setting [`ZMK_KEYBOARD_NAME`](../../config/system.md#general) to a value, for the product name to be used for USB/BLE info + - Setting [`ZMK_KEYBOARD_NAME`](../config/system.md#general) to a value, for the product name to be used for USB/BLE info -[Configuration files](../../config/index.md#kconfig-files) that set the visible Kconfig symbols: +[Configuration files](../config/index.md#kconfig-files) that set the visible Kconfig symbols: - A `_defconfig` file that forces specific Kconfig settings that are specific to this hardware configuration. These tend to be settings enabling various drivers or features, e.g. GPIO, USB support, or memory settings for ZMK Studio. -[Devicetree files](../../config/index.md#devicetree-files): +[Devicetree files](../config/index.md#devicetree-files): - `.dts` which contains all the devicetree definitions[^1], including but not limited to: - An `#include` line that pulls in the specific microprocessor that is used, e.g. `#include `, @@ -120,11 +120,11 @@ See also our [new board guide](new-board.md) for information on creating a ZMK-c -Keyboards that require an add-on board to operate are [composite keyboards](../../hardware.mdx#composite), where the ZMK integration pieces are placed in the _shield_ definition for that keyboard. +Keyboards that require an add-on board to operate are [composite keyboards](../hardware.mdx#composite), where the ZMK integration pieces are placed in the _shield_ definition for that keyboard. This allows users to swap in different boards that use the same interconnect (e.g. Pro Micro RP2040, or nice!nano) and build a firmware the matches their actual combination of physical components. -With this type of keyboard, the partial definition for the keyboard exists in the `/boards/shields/` directory where `` is `zmk/app` or a [module](../../features/modules.mdx) root, e.g. `zmk/app/boards/shields/clueboard_california/`. -In that directory, you'll have the following files, where there can be multiple ``s, corresponding to each keyboard part for [split keyboards](../../features/split-keyboards.md): +With this type of keyboard, the partial definition for the keyboard exists in the `/boards/shields/` directory where `` is `zmk/app` or a [module](../features/modules.mdx) root, e.g. `zmk/app/boards/shields/clueboard_california/`. +In that directory, you'll have the following files, where there can be multiple ``s, corresponding to each keyboard part for [split keyboards](../features/split-keyboards.md): ``` @@ -140,7 +140,7 @@ These files include [base Kconfig files](new-shield.mdx#base-kconfig-files): - A `Kconfig.shield` that defines the toplevel Kconfig value for the shield, which uses a supplied utility to function to default the value based on the shield list, e.g. `def_bool $(shields_list_contains,clueboard_california)`. - A `Kconfig.defconfig` file to set default values for settings like `ZMK_KEYBOARD_NAME` -[Devicetree files](../../config/index.md#devicetree-files): +[Devicetree files](../config/index.md#devicetree-files): - A `.overlay` file which is a devicetree overlay file[^1], containing definitions including but not limited to: - Kscan, matrix transform and physical layout devicetree nodes as described above, where the kscan node uses the interconnect [nexus node](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html#gpio-nexus-nodes) aliases such as `&pro_micro` for GPIO pins. diff --git a/docs/docs/development/hardware-integration/lighting/backlight.mdx b/docs/docs/hardware-integration/lighting/backlight.mdx similarity index 98% rename from docs/docs/development/hardware-integration/lighting/backlight.mdx rename to docs/docs/hardware-integration/lighting/backlight.mdx index f7b221da..8b484d08 100644 --- a/docs/docs/development/hardware-integration/lighting/backlight.mdx +++ b/docs/docs/hardware-integration/lighting/backlight.mdx @@ -7,7 +7,7 @@ description: Lighting system that controls an array of single-color LEDs. import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; -Please see [lighting feature page](../../../features/lighting.md#backlight) for an introduction on the feature. +Please see [lighting feature page](../../features/lighting.md#backlight) for an introduction on the feature. @@ -182,6 +182,6 @@ See [here](./bootloader/index.mdx) for bootloader instructions for other SoCs. D ## Next Steps -If your board is a keyboard, continue from [the `Kconfig.defconfig` step](https://zmk.dev/docs/development/hardware-integration/new-shield?keyboard-type=unibody#kconfigdefconfig) of the new shield guide. Use your ZMK variant's devicetree instead of the overlay file which would be used for a shield. +If your board is a keyboard, continue from [the `Kconfig.defconfig` step](https://zmk.dev/docs/hardware-integration/new-shield?keyboard-type=unibody#kconfigdefconfig) of the new shield guide. Use your ZMK variant's devicetree instead of the overlay file which would be used for a shield. -If your board is a board with an interconnect, your next step should be to write a [tester shield](../../troubleshooting/hardware-issues.mdx#identifying-issues). Such a shield should be the bare minimum shield to verify that your board works with ZMK. +If your board is a board with an interconnect, your next step should be to write a [tester shield](../troubleshooting/hardware-issues.mdx#identifying-issues). Such a shield should be the bare minimum shield to verify that your board works with ZMK. diff --git a/docs/docs/development/hardware-integration/new-shield.mdx b/docs/docs/hardware-integration/new-shield.mdx similarity index 88% rename from docs/docs/development/hardware-integration/new-shield.mdx rename to docs/docs/hardware-integration/new-shield.mdx index 73c80fe4..de9eca55 100644 --- a/docs/docs/development/hardware-integration/new-shield.mdx +++ b/docs/docs/hardware-integration/new-shield.mdx @@ -44,7 +44,7 @@ This guide will walk through the steps necessary to add ZMK support for a keyboa The high level steps are: -- Create a new [ZMK module](../module-creation.md) to contain your shield. +- Create a new [ZMK module](../development/module-creation.md) to contain your shield. - Create a new shield directory. - Add the base Kconfig files. - Add the shield overlay file defining: @@ -54,7 +54,7 @@ The high level steps are: - Add a default keymap, which users can override in their own configs as needed. - Add a `.zmk.yml` metadata file to document the high level details of your shield, and the features it supports. -Many of the above files will differ depending on whether your keyboard is a unibody or is [split into multiple parts](../../features/split-keyboards.md). +Many of the above files will differ depending on whether your keyboard is a unibody or is [split into multiple parts](../features/split-keyboards.md). After adding ZMK support for a basic shield using this guide, check the sidebar for guides on adding any additional features (such as encoders) that your keyboard has. It may be helpful to review the upstream [shields documentation](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html#shields) to get a proper understanding of the underlying system before continuing. @@ -63,7 +63,7 @@ It may be helpful to review the upstream [shields documentation](https://docs.ze When writing your shield, please be aware of [licensing](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository): - If you reference code or other items that are under a copyleft license (e.g. GNU GPLv2, used by QMK) as a reference, you must license your shield under a compatible copyleft license. -- If you license anything under a copyleft license, it cannot be referenced by anyone working on ZMK (see our [clean room policy](../contributing/clean-room.md)). +- If you license anything under a copyleft license, it cannot be referenced by anyone working on ZMK (see our [clean room policy](../development/contributing/clean-room.md)). We generally recommend licensing your shield under MIT, if you don't have a particular incentive to do otherwise. ::: @@ -89,9 +89,9 @@ Follow these steps to create your new repository: The repository is a combination of the directories and files required of a ZMK config, and those required of a shield module. This enables the use of GitHub Actions to test that the shield is defined correctly. -See also the page on [module creation](../module-creation.md) for a reference on exactly which file structure and files are required for a ZMK keyboard module. +See also the page on [module creation](../development/module-creation.md) for a reference on exactly which file structure and files are required for a ZMK keyboard module. -We recommend that you take this moment to name your module according to our [convention](../module-creation.md), i.e. your `zephyr/module.yml` file should begin with +We recommend that you take this moment to name your module according to our [convention](../development/module-creation.md), i.e. your `zephyr/module.yml` file should begin with ```yaml title="zephyr/module.yml" name: zmk-keyboard- @@ -108,7 +108,7 @@ mkdir boards/shields/ ## Base Kconfig Files :::tip[Example shields] -You can check out the [`shields` folder](https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields) in the ZMK repo that houses [the in-tree supported shields](../../hardware.mdx) in order to copy and modify as a starting point. +You can check out the [`shields` folder](https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields) in the ZMK repo that houses [the in-tree supported shields](../hardware.mdx) in order to copy and modify as a starting point. ::: There are two required [Kconfig](https://docs.zephyrproject.org/4.1.0/build/kconfig/index.html) files that need to be created for your new keyboard shield to get it picked up for ZMK, `Kconfig.shield` and `Kconfig.defconfig`. @@ -208,7 +208,7 @@ endif ### User Configuration Files In addition to the `Kconfig.shield` and `Kconfig.defconfig` files, many shields will also define a user configuration file called `my_keyboard.conf`. -This file exists to provide "suggestions" of [configuration settings](../../config/index.md) for a user to select, such as enabling deep sleep. +This file exists to provide "suggestions" of [configuration settings](../config/index.md) for a user to select, such as enabling deep sleep. Note that the name should match the shield/part name defined in the [Kconfig.shield file](#kconfigshield). :::warning @@ -231,7 +231,7 @@ Split keyboards can have multiple `.conf` files, one for each part. For example: In most case you'll only need to use the .conf file that affects both halves of a split board. :::note -The shared configuration in `my_keyboard.conf` is only applied when you are building with a [`zmk-config` folder](../local-toolchain/build-flash.mdx#building-from-zmk-config-folder) and it is present at `config/my_keyboard.conf`. +The shared configuration in `my_keyboard.conf` is only applied when you are building with a [`zmk-config` folder](../development/local-toolchain/build-flash.mdx#building-from-zmk-config-folder) and it is present at `config/my_keyboard.conf`. ::: @@ -246,7 +246,7 @@ There are three main things that need to be defined in this file: - Your keyboard scan (kscan) driver, which determines which GPIO pins to scan for key press events - Your matrix transform, which acts as a "bridge" between the kscan and the keymap -- Your physical layout, which aggregates the above and (optionally) defines physical key positions so that the keyboard can be used with [ZMK Studio](../../features/studio.md). +- Your physical layout, which aggregates the above and (optionally) defines physical key positions so that the keyboard can be used with [ZMK Studio](../features/studio.md). @@ -280,7 +280,7 @@ To use GPIO pins that are not part of the interconnects as described above, you For instance, pins numbered `PX.Y` in nRF52840-based boards can be referred to via `&gpioX Y` labels. An example is `&gpio1 7` for the `P1.07` pin that the nice!nano exposes in the middle of the board. -The [Keyboard Scan configuration documentation](../../config/kscan.md) has the full details on configuring the kscan driver. +The [Keyboard Scan configuration documentation](../config/kscan.md) has the full details on configuring the kscan driver. @@ -450,7 +450,7 @@ The matrix transform is also used to "correct" pin orderings into something that See the [in-tree keyboards](https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields) that ZMK defines for examples of more complex matrix transformations. -Also see the [matrix transform section](../../config/layout.md#matrix-transform) in the Keyboard Scan configuration documentation for further details and examples of matrix transforms. +Also see the [matrix transform section](../config/layout.md#matrix-transform) in the Keyboard Scan configuration documentation for further details and examples of matrix transforms. ### Physical Layout @@ -460,7 +460,7 @@ Physical layouts organize the matrix transform, kscan and optionally the physica -If you are not planning to add support for [ZMK Studio](../../features/studio.md), you can add a `zmk,physical-layout`-compatible node for each physical layout your keyboard supports: +If you are not planning to add support for [ZMK Studio](../features/studio.md), you can add a `zmk,physical-layout`-compatible node for each physical layout your keyboard supports: ```dts / { @@ -478,7 +478,7 @@ These nodes should be placed in `my_keyboard.overlay` for unibody keyboards and -If you are planning to add support for [ZMK Studio](../../features/studio.md), you should follow the [physical layouts documentation](physical-layouts.md) to create a new file `my_keyboard-layouts.dtsi` which includes the physical layout definitions. +If you are planning to add support for [ZMK Studio](../features/studio.md), you should follow the [physical layouts documentation](physical-layouts.md) to create a new file `my_keyboard-layouts.dtsi` which includes the physical layout definitions. Once you have finished defining your physical layouts, import the `my_keyboard-layouts.dtsi` file at the top of your `my_keyboard.overlay` file (unibody) or `my_keyboard.dtsi` file (split). ```dts @@ -501,7 +501,7 @@ Set the `chosen` node to a defined "default" physical layout. This should also b }; ``` -If you define multiple physical layouts, users can select a different layout by overriding the `zmk,physical-layout` chosen node in their keymap file or by using [ZMK Studio](../../features/studio.md) if your board is compatible with it. +If you define multiple physical layouts, users can select a different layout by overriding the `zmk,physical-layout` chosen node in their keymap file or by using [ZMK Studio](../features/studio.md) if your board is compatible with it. :::note If all of your physical layouts use the same `kscan` node under the hood, you can skip setting the `kscan` property on each layout and instead assign the `zmk,kscan` chosen node to your single kscan instance: @@ -524,7 +524,7 @@ If all of your physical layouts use the same `kscan` node under the hood, you ca This is only required for wired split keyboards. -If testing the experimental [wired split](../../features/split-keyboards.md) support, you should assign a [predefined](./pinctrl.mdx#predefined-nodes) or [pinctrl configured](./pinctrl.mdx) UART to the `device` property of a new node with `compatible` value of `"zmk,wired-split"`: +If testing the experimental [wired split](../features/split-keyboards.md) support, you should assign a [predefined](./pinctrl.mdx#predefined-nodes) or [pinctrl configured](./pinctrl.mdx) UART to the `device` property of a new node with `compatible` value of `"zmk,wired-split"`: ```dts / { @@ -535,7 +535,7 @@ If testing the experimental [wired split](../../features/split-keyboards.md) sup }; ``` -See the [wired split](../../config/split.md#wired-split) configuration for more details. +See the [wired split](../config/split.md#wired-split) configuration for more details. For wireless split keyboards, this step should be skipped, especially since the UART pins on your controller might already be in use for other functionality. @@ -573,8 +573,8 @@ Here is an example simple keymap for a 3x3 macropad, with only one layer: ``` The keymap should match the order of the keys in the [matrix transform](#matrix-transform) exactly, left to right, top to bottom (they are both 1 dimensional arrays rearranged with newline characters for better legibility). -See [Keymaps](../../keymaps/index.mdx) for information on defining keymaps in ZMK. -If you wish to use [ZMK Studio](../../features/studio.md) with your keyboard, make sure to assign the [ZMK Studio unlocking behavior](../../keymaps/behaviors/studio-unlock.md) to a key in your keymap. +See [Keymaps](../keymaps/index.mdx) for information on defining keymaps in ZMK. +If you wish to use [ZMK Studio](../features/studio.md) with your keyboard, make sure to assign the [ZMK Studio unlocking behavior](../keymaps/behaviors/studio-unlock.md) to a key in your keymap. ## Metadata @@ -604,12 +604,12 @@ See [Hardware Metadata Files](hardware-metadata-files.md) for the full details. ## Testing Once you've defined everything as described above, you can build your firmware to make sure everything is working. -If you wish to test that your keyboard works with [ZMK Studio](../../features/studio.md), you'll also need to follow the [instructions for enabling Studio](../../features/studio.md#building). +If you wish to test that your keyboard works with [ZMK Studio](../features/studio.md), you'll also need to follow the [instructions for enabling Studio](../features/studio.md#building). ### GitHub Actions To use GitHub Actions to test, push the files defining the keyboard to GitHub. -Next, [update the `build.yaml`](../../customization.md#building-additional-keyboards) of your `zmk-config` to build your keyboard. +Next, [update the `build.yaml`](../customization.md#building-additional-keyboards) of your `zmk-config` to build your keyboard. - If your shield is defined in your `zmk-config`, then the shield should start building. - If the shield is defined in a separate module, you will need to [adjust your `west.yml` to reference the module](https://zmk.dev/docs/features/modules#building-with-modules). @@ -617,5 +617,5 @@ Next, [update the `build.yaml`](../../customization.md#building-additional-keybo ### Local Toolchain You can also use a local toolchain setup to test your keyboard. -Follow [our guide for getting set up](../local-toolchain/setup/index.md), then follow the [instructions for building and flashing locally](../local-toolchain/build-flash.mdx). +Follow [our guide for getting set up](../development/local-toolchain/setup/index.md), then follow the [instructions for building and flashing locally](../development/local-toolchain/build-flash.mdx). You will need to specify the module of your keyboard when building. diff --git a/docs/docs/development/hardware-integration/physical-layouts.md b/docs/docs/hardware-integration/physical-layouts.md similarity index 93% rename from docs/docs/development/hardware-integration/physical-layouts.md rename to docs/docs/hardware-integration/physical-layouts.md index 281b1c97..4678e0f7 100644 --- a/docs/docs/development/hardware-integration/physical-layouts.md +++ b/docs/docs/hardware-integration/physical-layouts.md @@ -6,8 +6,8 @@ toc_max_heading_level: 4 A physical layout is a devicetree entity that aggregates all details about a certain possible keyboard layout. It contains: -- A [keyboard scan (kscan) driver](../../config/kscan.md) -- A [matrix transform](../../config/layout.md#matrix-transform) +- A [keyboard scan (kscan) driver](../config/kscan.md) +- A [matrix transform](../config/layout.md#matrix-transform) - (Optional) [Physical key positions](#optional-keys-property) By convention, physical layouts and any [position maps](#position-map) are defined in a separate file called `-layouts.dtsi`. @@ -35,11 +35,11 @@ Every physical layout needs a matrix transform, and optionally can also have a k }; ``` -The `kscan` property only needs to be assigned if some of your physical layouts use different kscans. Otherwise, it can be omitted and the `kscan` can be assigned in the [`chosen` node](./new-shield.mdx#chosen-node) instead. See the [configuration section on physical layouts](../../config/layout.md#physical-layout) for reference. +The `kscan` property only needs to be assigned if some of your physical layouts use different kscans. Otherwise, it can be omitted and the `kscan` can be assigned in the [`chosen` node](./new-shield.mdx#chosen-node) instead. See the [configuration section on physical layouts](../config/layout.md#physical-layout) for reference. ## (Optional) Keys Property -The `keys` property is required for [ZMK Studio](../../features/studio.md) support. It is used to describe the physical attributes of each key position present in that layout. +The `keys` property is required for [ZMK Studio](../features/studio.md) support. It is used to describe the physical attributes of each key position present in that layout. To pull in the necessary definition for creating physical layouts with the `keys` property, a new include should be added to the top of the devicetree file: @@ -171,7 +171,7 @@ If necessary, you can also define multiple kscan instances. ### Position Map -When switching between layouts using [ZMK Studio](../../features/studio.md), an attempt is made to automatically infer bindings for the keys in the new layout from the old layout. Keys with the same physical key properties are given the same binding. This approach has some limitations, so for more accurate transference of bindings a position map is used. +When switching between layouts using [ZMK Studio](../features/studio.md), an attempt is made to automatically infer bindings for the keys in the new layout from the old layout. Keys with the same physical key properties are given the same binding. This approach has some limitations, so for more accurate transference of bindings a position map is used. :::warning @@ -203,9 +203,9 @@ A child node is defined for every layout the keyboard can have. The `positions` When switching from one layout to another, say from layout 1 to layout 2, the _orderings_ found in the `positions` arrays are used. The first key in the `positions` array of layout 2 is given the binding assigned to the first key in the `positions` array of layout 1, the second key in the `positions` array of layout 2 is given the binding assigned to the second key in the `positions` array of layout 1, and so on. -The position map should be marked as `complete` if all desired binding transfers are defined within it. Otherwise, [ZMK Studio](../../features/studio.md) will continue to automatically determine assignments for keys not listed in the position map. See [this example non-complete position map](#example-non-complete-position-map) for why this could be useful. +The position map should be marked as `complete` if all desired binding transfers are defined within it. Otherwise, [ZMK Studio](../features/studio.md) will continue to automatically determine assignments for keys not listed in the position map. See [this example non-complete position map](#example-non-complete-position-map) for why this could be useful. -See also the [configuration section on position maps](../../config/layout.md#physical-layout-position-map). +See also the [configuration section on position maps](../config/layout.md#physical-layout-position-map). :::tip @@ -257,7 +257,7 @@ Next write the child nodes for every other layout with respect to the reference. Consider the following macropad/numpad with two physical layouts: -![A 4x5 numpad/macropad](../../assets/hardware-integration/numpad.svg) +![A 4x5 numpad/macropad](../assets/hardware-integration/numpad.svg) Let us first consider each side individually. The "reference" position map of the left side would look like this: diff --git a/docs/docs/development/hardware-integration/pinctrl.mdx b/docs/docs/hardware-integration/pinctrl.mdx similarity index 100% rename from docs/docs/development/hardware-integration/pinctrl.mdx rename to docs/docs/hardware-integration/pinctrl.mdx diff --git a/docs/docs/development/hardware-integration/pointing.mdx b/docs/docs/hardware-integration/pointing.mdx similarity index 94% rename from docs/docs/development/hardware-integration/pointing.mdx rename to docs/docs/hardware-integration/pointing.mdx index af50e5fd..cad34272 100644 --- a/docs/docs/development/hardware-integration/pointing.mdx +++ b/docs/docs/hardware-integration/pointing.mdx @@ -7,10 +7,10 @@ import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; ZMK's pointing device support builds upon the Zephyr [input API](https://docs.zephyrproject.org/4.1.0/services/input/index.html) to offer pointing/mouse functionality with various hardware. -A limited number of input drivers are available in the Zephyr version currently used by ZMK, but additional drivers can be found in [external modules](../../features/modules.mdx) for a variety of hardware. +A limited number of input drivers are available in the Zephyr version currently used by ZMK, but additional drivers can be found in [external modules](../features/modules.mdx) for a variety of hardware. -Pointing devices are also supported on split peripherals, with some additional configuration using the [input split device](../../config/pointing.md#input-split). -The configuration details will thus vary depending on if you are adding a pointing device to a [split peripheral](../../features/split-keyboards.md#central-and-peripheral-roles) as opposed to a unibody keyboard or split central part. +Pointing devices are also supported on split peripherals, with some additional configuration using the [input split device](../config/pointing.md#input-split). +The configuration details will thus vary depending on if you are adding a pointing device to a [split peripheral](../features/split-keyboards.md#central-and-peripheral-roles) as opposed to a unibody keyboard or split central part. export const SplitTabs = (props) => ( diff --git a/docs/docs/development/hardware-integration/shift-registers.md b/docs/docs/hardware-integration/shift-registers.md similarity index 93% rename from docs/docs/development/hardware-integration/shift-registers.md rename to docs/docs/hardware-integration/shift-registers.md index f2bd9977..01bc35e6 100644 --- a/docs/docs/development/hardware-integration/shift-registers.md +++ b/docs/docs/hardware-integration/shift-registers.md @@ -15,7 +15,7 @@ To understand how shift registers work, we recommend reading through ["How does ## Design Guidelines -The shift register output pins should act as MCU outputs in your design. All MCU inputs should remain connected directly to MCU/board pins. This is to allow the inputs to trigger "interrupts" on the MCU/board, upon which it will begin scanning the keys. Using a shift register for MCU inputs is also possible, but requires you to use a PISO shift register and will harm your battery life. Note that a [direct kscan](../../config/kscan.md#direct-gpio-driver) keyboard does not have any MCU output pins, but a diodeless keyboard is still possible by making use of a single row pin and using the [matrix kscan](../../config/kscan.md#matrix-driver) driver. +The shift register output pins should act as MCU outputs in your design. All MCU inputs should remain connected directly to MCU/board pins. This is to allow the inputs to trigger "interrupts" on the MCU/board, upon which it will begin scanning the keys. Using a shift register for MCU inputs is also possible, but requires you to use a PISO shift register and will harm your battery life. Note that a [direct kscan](../config/kscan.md#direct-gpio-driver) keyboard does not have any MCU output pins, but a diodeless keyboard is still possible by making use of a single row pin and using the [matrix kscan](../config/kscan.md#matrix-driver) driver. :::info In a diode matrix, MCU output pins are those connected to the [anodes of your diodes](https://learn.sparkfun.com/tutorials/diodes/all#ideal-diodes). You most likely will need to rearrange your matrix to maximize the use of shift register output pins, in order to reduce the total number of GPIO pins connected to your MCU. For example, a 9 column 5 row `col2row` matrix could be rearranged to use 16 columns and 3 rows. @@ -25,7 +25,7 @@ You will want to make sure that the data and clock pins of the shift register ar ZMK allows you to daisy-chain up to four shift registers. Below is a fragment of a schematic showing two shift registers that are daisy-chained. -![A fragment of a schematic featuring two shift registers daisy chained together.](../../assets/hardware-integration/shift-register-daisy.png) +![A fragment of a schematic featuring two shift registers daisy chained together.](../assets/hardware-integration/shift-register-daisy.png) ## Configuration diff --git a/docs/docs/development/hardware-integration/soft-off-setup.mdx b/docs/docs/hardware-integration/soft-off-setup.mdx similarity index 91% rename from docs/docs/development/hardware-integration/soft-off-setup.mdx rename to docs/docs/hardware-integration/soft-off-setup.mdx index 0f326b56..8ca1cbd6 100644 --- a/docs/docs/development/hardware-integration/soft-off-setup.mdx +++ b/docs/docs/hardware-integration/soft-off-setup.mdx @@ -16,7 +16,7 @@ import SidebandDirect from "./includes/_sideband-direct.md"; import SidebandMatrix from "./includes/_sideband-matrix.md"; import SidebandWakeupDirect from "./includes/_sideband-wakeup-direct.md"; -Advanced methods of adding [soft off](../../features/low-power-states.md#soft-off) to a keyboard are detailed below. The first two tabs describe methods involving hardware changes, while the last describes the firmware changes necessary to define a single specific key switch for waking up. +Advanced methods of adding [soft off](../features/low-power-states.md#soft-off) to a keyboard are detailed below. The first two tabs describe methods involving hardware changes, while the last describes the firmware changes necessary to define a single specific key switch for waking up. @@ -68,7 +68,7 @@ Several items work together to make both triggering soft off properly, and setti ### Soft off behavior -For this approach, you will need to make sure that the [soft off behavior](../../keymaps/behaviors/soft-off.md) is present in your keymap, to trigger soft off. +For this approach, you will need to make sure that the [soft off behavior](../keymaps/behaviors/soft-off.md) is present in your keymap, to trigger soft off. @@ -166,7 +166,7 @@ Finally, we will list the `wakeup_scan` device in an additional configuration se Here are the properties for the node: - The `compatible` property for the node must be `zmk,soft-off-wakeup-sources`. -- The `wakeup-sources` property is a [phandle array](../devicetree.md#property-types) pointing to all the devices that should be enabled during the shutdown process to be sure they can later wake the keyboard. +- The `wakeup-sources` property is a [phandle array](../development/devicetree.md#property-types) pointing to all the devices that should be enabled during the shutdown process to be sure they can later wake the keyboard. :::tip If you add your kscan to the `wakeup-sources` array, then your keyboard will wake upon pressing any key in your kscan. Essentially, this causes `&soft_off` to behave like a behavior that puts the keyboard in deep sleep. If you choose to do so, then you can omit everything aside from the `soft_off_wakers` node. diff --git a/docs/docs/hardware.mdx b/docs/docs/hardware.mdx index 8611f94b..b580daab 100644 --- a/docs/docs/hardware.mdx +++ b/docs/docs/hardware.mdx @@ -42,7 +42,7 @@ export const toc = [ With the solid technical foundation of Zephyr™ RTOS, ZMK can support a wide diversity 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](development/hardware-integration/index.mdx#boards--shields) that have been implemented and tested by the ZMK contributors, listed below. +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. :::note @@ -61,4 +61,4 @@ 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](development/hardware-integration/new-shield.mdx) documentation and note the [clean room design requirements](development/contributing/clean-room.md). +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). diff --git a/docs/docs/troubleshooting/hardware-issues.mdx b/docs/docs/troubleshooting/hardware-issues.mdx index 7cf49d7f..fc234e7c 100644 --- a/docs/docs/troubleshooting/hardware-issues.mdx +++ b/docs/docs/troubleshooting/hardware-issues.mdx @@ -175,7 +175,7 @@ Once you have done so, you will need to adjust the `kscan` of your keyboard slig }; ``` -could have the pin `&pro_micro 6` (D6 in the [Pro Micro pinout](../development/hardware-integration/new-shield.mdx#shield-overlays)) replaced with `&gpio0 8` (P0.08 for nRF MCUs). +could have the pin `&pro_micro 6` (D6 in the [Pro Micro pinout](../hardware-integration/new-shield.mdx#shield-overlays)) replaced with `&gpio0 8` (P0.08 for nRF MCUs). ```dts title=".keymap" &kscan0 { diff --git a/docs/docs/user-setup.mdx b/docs/docs/user-setup.mdx index 9482cb0b..ba96b489 100644 --- a/docs/docs/user-setup.mdx +++ b/docs/docs/user-setup.mdx @@ -280,7 +280,7 @@ Run `zmk keyboard add` again, and the new keyboards should appear in the list. **Create It Yourself** -If nobody has created a module for your keyboard yet, or if it is your own custom design, you will need to set it up yourself. Your config repo is already set up as a module, so you can define new keyboards there. See ZMK's [new keyboard shield guide](development/hardware-integration/new-shield.mdx) for more information. +If nobody has created a module for your keyboard yet, or if it is your own custom design, you will need to set it up yourself. Your config repo is already set up as a module, so you can define new keyboards there. See ZMK's [new keyboard shield guide](hardware-integration/new-shield.mdx) for more information. ZMK CLI can also help generate some of the boilerplate for defining a new keyboard: diff --git a/docs/docs/zmk-cli.mdx b/docs/docs/zmk-cli.mdx index 8def4542..1e278d39 100644 --- a/docs/docs/zmk-cli.mdx +++ b/docs/docs/zmk-cli.mdx @@ -51,7 +51,7 @@ Run `zmk keyboard list` to print a list of supported keyboard hardware. If ZMK doesn't support your keyboard yet, you can run `zmk keyboard new` to create a new keyboard from a template. -This won't walk you through all of the details of adding support for a new keyboard, but it will generate most of the boilerplate for you. See the [New Keyboard Shield](development/hardware-integration/new-shield.mdx) guide for how to finish writing the keyboard files. +This won't walk you through all of the details of adding support for a new keyboard, but it will generate most of the boilerplate for you. See the [New Keyboard Shield](hardware-integration/new-shield.mdx) guide for how to finish writing the keyboard files. ### Module Management diff --git a/docs/sidebars.js b/docs/sidebars.js index 88c3a426..51c140b6 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -141,59 +141,59 @@ module.exports = { ], }, { - Development: [ + type: "category", + label: "Hardware Integration", + link: { + type: "doc", + id: "hardware-integration/index", + }, + collapsed: true, + items: [ + "hardware-integration/new-board", + "hardware-integration/new-shield", + "hardware-integration/physical-layouts", + "hardware-integration/hardware-metadata-files", + "hardware-integration/pinctrl", + "hardware-integration/dongle", + "hardware-integration/shift-registers", + "hardware-integration/encoders", + "hardware-integration/soft-off-setup", + "hardware-integration/pointing", + "hardware-integration/battery", { type: "category", - label: "Hardware Integration", + label: "Bootloader", link: { type: "doc", - id: "development/hardware-integration/index", + id: "hardware-integration/bootloader/index", }, collapsed: true, items: [ - "development/hardware-integration/new-shield", - "development/hardware-integration/physical-layouts", - "development/hardware-integration/hardware-metadata-files", - "development/hardware-integration/pinctrl", - "development/hardware-integration/dongle", - "development/hardware-integration/shift-registers", - "development/hardware-integration/encoders", - "development/hardware-integration/soft-off-setup", - "development/hardware-integration/pointing", - "development/hardware-integration/new-board", - "development/hardware-integration/battery", - { - type: "category", - label: "Bootloader", - link: { - type: "doc", - id: "development/hardware-integration/bootloader/index", - }, - collapsed: true, - items: [ - "development/hardware-integration/bootloader/adafruit-nrf52", - "development/hardware-integration/bootloader/tinyuf2", - "development/hardware-integration/bootloader/samd21-uf2", - "development/hardware-integration/bootloader/rp2", - "development/hardware-integration/bootloader/stm32", - ], - }, - { - type: "category", - label: "Lighting", - link: { - type: "doc", - id: "development/hardware-integration/lighting/index", - }, - collapsed: true, - items: [ - "development/hardware-integration/lighting/underglow", - "development/hardware-integration/lighting/backlight", - "development/hardware-integration/lighting/led-indicators", - ], - }, + "hardware-integration/bootloader/adafruit-nrf52", + "hardware-integration/bootloader/tinyuf2", + "hardware-integration/bootloader/samd21-uf2", + "hardware-integration/bootloader/rp2", + "hardware-integration/bootloader/stm32", ], }, + { + type: "category", + label: "Lighting", + link: { + type: "doc", + id: "hardware-integration/lighting/index", + }, + collapsed: true, + items: [ + "hardware-integration/lighting/underglow", + "hardware-integration/lighting/backlight", + "hardware-integration/lighting/led-indicators", + ], + }, + ], + }, + { + Development: [ { type: "category", label: "Contributing", diff --git a/docs/static/_redirects b/docs/static/_redirects index c2e58dec..1de2aba9 100644 --- a/docs/static/_redirects +++ b/docs/static/_redirects @@ -10,17 +10,18 @@ /docs/config/underglow /docs/config/lighting#rgb-underglow 301 /docs/features/beta-testing /docs/features/modules#beta-testing 301 /docs/development/setup /docs/development/local-toolchain/setup 301 -/docs/development/boards-shields-keymaps /docs/development/hardware-integration/boards-shields-keymaps 301 -/docs/development/hardware-metadata-files /docs/development/hardware-integration/hardware-metadata-files 301 +/docs/development/boards-shields-keymaps /docs/hardware-integration 301 +/docs/development/hardware-metadata-files /docs/hardware-integration/hardware-metadata-files 301 /docs/development/clean-room /docs/development/contributing/clean-room 301 /docs/development/documentation /docs/development/contributing/documentation 301 -/docs/development/new-shield /docs/development/hardware-integration/new-shield 301 +/docs/development/new-shield /docs/hardware-integration/new-shield 301 /docs/development/build-flash /docs/development/local-toolchain/build-flash 301 /docs/development/ide-integration /docs/development/local-toolchain/ide-integration 301 /docs/development/posix-board /docs/development/local-toolchain/posix-board 301 /docs/development/pre-commit /docs/development/local-toolchain/pre-commit 301 /docs/development/tests /docs/development/local-toolchain/tests 301 /docs/development/guides/new-behavior /docs/development/new-behavior 301 -/docs/development/hardware-integration/studio-setup /docs/development/hardware-integration/physical-layouts 301 +/docs/development/hardware-integration/studio-setup /docs/hardware-integration/physical-layouts 301 /docs/keymaps/behaviors/mod-tap /docs/keymaps/behaviors/hold-tap#mod-tap /docs/user-setup-cli /docs/user-setup 301 +/docs/development/hardware-integration/* /docs/hardware-integration/:splat 301 From 26246da1b69733b224a33d82b33750541cd5933a Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 30 May 2026 19:58:53 +0200 Subject: [PATCH 02/12] chore(deps): bump actions/stale from 10.2.0 to 10.3.0 (#3358) Bumps [actions/stale](https://github.com/actions/stale) from 10.2.0 to 10.3.0. - [Release notes](https://github.com/actions/stale/releases) - [Changelog](https://github.com/actions/stale/blob/main/CHANGELOG.md) - [Commits](https://github.com/actions/stale/compare/v10.2.0...v10.3.0) --- updated-dependencies: - dependency-name: actions/stale dependency-version: 10.3.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/stale.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index c45c9dfd..475a37db 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -7,7 +7,7 @@ jobs: stale: runs-on: ubuntu-24.04 steps: - - uses: actions/stale@v10.2.0 + - uses: actions/stale@v10.3.0 with: days-before-pr-stale: 300 # ~10 months stale-pr-label: "stale" From 773dec58eaacaef4703b3e4595e50bd71f6cad3d Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Wed, 3 Jun 2026 14:26:39 -0700 Subject: [PATCH 03/12] docs: Add missing input processor to sidebar (#3372) --- docs/sidebars.js | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/sidebars.js b/docs/sidebars.js index 51c140b6..167527f5 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -107,6 +107,7 @@ module.exports = { "keymaps/input-processors/transformer", "keymaps/input-processors/code-mapper", "keymaps/input-processors/temp-layer", + "keymaps/input-processors/behaviors", ], }, ], From ff09f2d0c9f13a868c8f71d71d9348ade438e4b6 Mon Sep 17 00:00:00 2001 From: Genteure Date: Mon, 8 Jun 2026 00:45:31 +0800 Subject: [PATCH 04/12] 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)} -
); } From 0a6c6a185680d08abdb463cca6d001b0142a49bf Mon Sep 17 00:00:00 2001 From: yekingyan <529616@gmail.com> Date: Sat, 20 Jun 2026 12:25:02 +0800 Subject: [PATCH 05/12] feat(boards): add physical layout for reviung34 (#3351) * feat(boards): add physical layout for reviung34 Add physical layout support for the REVIUNG34 keyboard: - Dual 1U (34-key) layout - Single 2U (33-key) layout - Position map for layout switching Coordinates extracted from the original KiCad PCB (gtips/reviung). Closes #2536 * Update app/boards/shields/reviung34/reviung34-layouts.dtsi Co-authored-by: Nicolas Munnich <98408764+nmunnich@users.noreply.github.com> * Update app/boards/shields/reviung34/reviung34-layouts.dtsi Co-authored-by: Nicolas Munnich <98408764+nmunnich@users.noreply.github.com> * Update app/boards/shields/reviung34/reviung34-layouts.dtsi Co-authored-by: Nicolas Munnich <98408764+nmunnich@users.noreply.github.com> * Update app/boards/shields/reviung34/reviung34-layouts.dtsi Co-authored-by: Nicolas Munnich <98408764+nmunnich@users.noreply.github.com> * Update app/boards/shields/reviung34/reviung34-layouts.dtsi Co-authored-by: Nicolas Munnich <98408764+nmunnich@users.noreply.github.com> * fix: wrap negative numbers in parentheses for DTS syntax --------- Co-authored-by: Nicolas Munnich <98408764+nmunnich@users.noreply.github.com> --- .../shields/reviung34/reviung34-layouts.dtsi | 114 ++++++++++++++++++ .../shields/reviung34/reviung34.overlay | 12 +- 2 files changed, 125 insertions(+), 1 deletion(-) create mode 100644 app/boards/shields/reviung34/reviung34-layouts.dtsi diff --git a/app/boards/shields/reviung34/reviung34-layouts.dtsi b/app/boards/shields/reviung34/reviung34-layouts.dtsi new file mode 100644 index 00000000..cc331fee --- /dev/null +++ b/app/boards/shields/reviung34/reviung34-layouts.dtsi @@ -0,0 +1,114 @@ +/* + * Copyright (c) 2026 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + +#include + +/ { + reviung34_dual_1u_layout: reviung34_dual_1u_layout { + compatible = "zmk,physical-layout"; + display-name = "Dual 1U (34 keys)"; + + keys // w h x y rot rx ry + = <&key_physical_attrs 100 100 35 2 1000 85 52> + , <&key_physical_attrs 100 100 136 1 1000 186 51> + , <&key_physical_attrs 100 100 238 0 1000 288 50> + , <&key_physical_attrs 100 100 333 35 1000 383 85> + , <&key_physical_attrs 100 100 429 71 1000 479 121> + , <&key_physical_attrs 100 100 555 71 (-1000) 605 121> + , <&key_physical_attrs 100 100 650 35 (-1000) 700 85> + , <&key_physical_attrs 100 100 746 0 (-1000) 796 50> + , <&key_physical_attrs 100 100 847 1 (-1000) 897 51> + , <&key_physical_attrs 100 100 949 1 (-1000) 999 51> + , <&key_physical_attrs 100 100 17 100 1000 67 150> + , <&key_physical_attrs 100 100 119 99 1000 169 149> + , <&key_physical_attrs 100 100 221 98 1000 271 148> + , <&key_physical_attrs 100 100 316 134 1000 366 184> + , <&key_physical_attrs 100 100 411 169 1000 461 219> + , <&key_physical_attrs 100 100 572 169 (-1000) 622 219> + , <&key_physical_attrs 100 100 668 134 (-1000) 718 184> + , <&key_physical_attrs 100 100 763 98 (-1000) 813 148> + , <&key_physical_attrs 100 100 865 99 (-1000) 915 149> + , <&key_physical_attrs 100 100 966 100 (-1000) 1016 150> + , <&key_physical_attrs 100 100 0 198 1000 50 248> + , <&key_physical_attrs 100 100 102 198 1000 152 248> + , <&key_physical_attrs 100 100 203 197 1000 253 247> + , <&key_physical_attrs 100 100 298 232 1000 348 282> + , <&key_physical_attrs 100 100 394 268 1000 444 318> + , <&key_physical_attrs 100 100 590 268 (-1000) 640 318> + , <&key_physical_attrs 100 100 685 232 (-1000) 735 282> + , <&key_physical_attrs 100 100 780 197 (-1000) 830 247> + , <&key_physical_attrs 100 100 882 198 (-1000) 932 248> + , <&key_physical_attrs 100 100 984 198 (-1000) 1034 248> + , <&key_physical_attrs 100 100 328 370 1500 378 420> + , <&key_physical_attrs 100 100 442 385 0 0 0> + , <&key_physical_attrs 100 100 542 385 0 0 0> + , <&key_physical_attrs 100 100 655 370 (-1500) 705 420> + ; + }; + + reviung34_single_2u_layout: reviung34_single_2u_layout { + compatible = "zmk,physical-layout"; + display-name = "Single 2U (33 keys)"; + + keys // w h x y rot rx ry + = <&key_physical_attrs 100 100 35 2 1000 85 52> + , <&key_physical_attrs 100 100 136 1 1000 186 51> + , <&key_physical_attrs 100 100 238 0 1000 288 50> + , <&key_physical_attrs 100 100 333 35 1000 383 85> + , <&key_physical_attrs 100 100 429 71 1000 479 121> + , <&key_physical_attrs 100 100 555 71 (-1000) 605 121> + , <&key_physical_attrs 100 100 650 35 (-1000) 700 85> + , <&key_physical_attrs 100 100 746 0 (-1000) 796 50> + , <&key_physical_attrs 100 100 847 1 (-1000) 897 51> + , <&key_physical_attrs 100 100 949 1 (-1000) 999 51> + , <&key_physical_attrs 100 100 17 100 1000 67 150> + , <&key_physical_attrs 100 100 119 99 1000 169 149> + , <&key_physical_attrs 100 100 221 98 1000 271 148> + , <&key_physical_attrs 100 100 316 134 1000 366 184> + , <&key_physical_attrs 100 100 411 169 1000 461 219> + , <&key_physical_attrs 100 100 572 169 (-1000) 622 219> + , <&key_physical_attrs 100 100 668 134 (-1000) 718 184> + , <&key_physical_attrs 100 100 763 98 (-1000) 813 148> + , <&key_physical_attrs 100 100 865 99 (-1000) 915 149> + , <&key_physical_attrs 100 100 966 100 (-1000) 1016 150> + , <&key_physical_attrs 100 100 0 198 1000 50 248> + , <&key_physical_attrs 100 100 102 198 1000 152 248> + , <&key_physical_attrs 100 100 203 197 1000 253 247> + , <&key_physical_attrs 100 100 298 232 1000 348 282> + , <&key_physical_attrs 100 100 394 268 1000 444 318> + , <&key_physical_attrs 100 100 590 268 (-1000) 640 318> + , <&key_physical_attrs 100 100 685 232 (-1000) 735 282> + , <&key_physical_attrs 100 100 780 197 (-1000) 830 247> + , <&key_physical_attrs 100 100 882 198 (-1000) 932 248> + , <&key_physical_attrs 100 100 984 198 (-1000) 1034 248> + , <&key_physical_attrs 100 100 328 370 1500 378 420> + , <&key_physical_attrs 200 100 442 385 0 0 0> + , <&key_physical_attrs 100 100 655 370 (-1500) 705 420> + ; + }; + + reviung34_position_map { + compatible = "zmk,physical-layout-position-map"; + + reviung34_dual_1u_posmap { + physical-layout = <&reviung34_dual_1u_layout>; + positions + = < 0 1 2 3 4 5 6 7 8 9> + , <10 11 12 13 14 15 16 17 18 19> + , <20 21 22 23 24 25 26 27 28 29> + , <30 31 33 32>; + }; + + reviung34_single_2u_posmap { + physical-layout = <&reviung34_single_2u_layout>; + positions + = < 0 1 2 3 4 5 6 7 8 9> + , <10 11 12 13 14 15 16 17 18 19> + , <20 21 22 23 24 25 26 27 28 29> + , <30 31 32>; + }; + }; +}; diff --git a/app/boards/shields/reviung34/reviung34.overlay b/app/boards/shields/reviung34/reviung34.overlay index 0f58b99d..0e800a7d 100644 --- a/app/boards/shields/reviung34/reviung34.overlay +++ b/app/boards/shields/reviung34/reviung34.overlay @@ -6,10 +6,20 @@ #include +#include "reviung34-layouts.dtsi" + +&reviung34_dual_1u_layout { + transform = <&dual_1u_transform>; +}; + +&reviung34_single_2u_layout { + transform = <&single_2u_transform>; +}; + / { chosen { zmk,kscan = &kscan0; - zmk,matrix-transform = &dual_1u_transform; + zmk,physical-layout = &reviung34_dual_1u_layout; }; dual_1u_transform: keymap_transform_0 { From 68212cfb1d5e174ee27f4e258087897d89370a43 Mon Sep 17 00:00:00 2001 From: Genteure Date: Sat, 20 Jun 2026 12:28:27 +0800 Subject: [PATCH 06/12] docs: reduce the use of admonitions (#3371) * docs: reduce use of admonitions - Removed some admonitions - Some are merged with surrounding paragraphs - Also slipped in a bit of other formatting changes * address review comments * address review comments --- docs/docs/config/encoders.md | 4 ---- .../development/contributing/documentation.md | 18 +++--------------- docs/docs/development/module-creation.md | 16 +++++++--------- docs/docs/features/led-indicators.md | 4 ---- docs/docs/features/lighting.md | 2 +- docs/docs/features/low-power-states.md | 6 +----- docs/docs/features/studio.md | 4 ++-- .../hardware-integration/lighting/underglow.md | 10 ++-------- docs/docs/hardware-integration/new-board.md | 2 +- .../hardware-integration/physical-layouts.md | 12 ++---------- docs/docs/hardware-integration/pinctrl.mdx | 6 ------ .../hardware-integration/shift-registers.md | 2 -- docs/docs/keymaps/behaviors/hold-tap.mdx | 6 ++---- docs/docs/keymaps/behaviors/macros.md | 4 ---- docs/docs/keymaps/behaviors/power.md | 2 +- .../docs/keymaps/input-processors/behaviors.md | 4 ---- docs/docs/keymaps/list-of-keycodes.mdx | 5 ----- docs/docs/troubleshooting/building-issues.md | 4 +--- 18 files changed, 23 insertions(+), 88 deletions(-) diff --git a/docs/docs/config/encoders.md b/docs/docs/config/encoders.md index 2052fc9d..7f68a0e9 100644 --- a/docs/docs/config/encoders.md +++ b/docs/docs/config/encoders.md @@ -55,12 +55,8 @@ Per sensor overrides can be added with ordered nested nodes with the correct ove }; ``` -:::note - The names of the child nodes are not important, and are applied in order to the sensors listed in the `sensors` property of the sensors node. -::: - Applies to the node and child nodes of: `compatible = "zmk,keymap-sensors"` Definition file: [zmk/app/drivers/zephyr/dts/bindings/zmk,keymap-sensors.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/drivers/zephyr/dts/bindings/zmk%2Ckeymap-sensors.yaml) diff --git a/docs/docs/development/contributing/documentation.md b/docs/docs/development/contributing/documentation.md index 5bca6303..26ba14fe 100644 --- a/docs/docs/development/contributing/documentation.md +++ b/docs/docs/development/contributing/documentation.md @@ -11,6 +11,8 @@ This document outlines how to test your documentation changes locally and prepar The documentation is written with [Docusaurus](https://docusaurus.io/). The ZMK source code has all of the necessary Docusaurus dependencies included, but referencing their documentation can be helpful at times. +The website is built using the latest LTS version of node, which is available at . + The general process for updating the ZMK documentation is: 1. Update the documentation @@ -18,14 +20,6 @@ The general process for updating the ZMK documentation is: 3. Ensure the sources are formatted properly and linted 4. Create a Pull Request for review and inclusion into the ZMK sources -:::note -If you are working with the documentation from within VS Code+Docker please be aware the documentation will not be auto-generated when making changes while the server is running. You'll need to restart the server when saving changes to the documentation. -::: - -:::note -You will need `Node.js` and `npm` installed to update the documentation. If you're using the ZMK dev container (Docker) the necessary dependencies are already installed. Otherwise, you must install these dependencies yourself. Since `Node.js` packages in Linux distributions tend to be outdated, it's recommended to install the current version from a repository like [NodeSource](https://github.com/nodesource/distributions) to avoid build errors. -::: - ## Testing Documentation Updates Locally To verify documentation updates locally, follow the following procedure. The `npm` commands and first step will need to be run from a terminal. @@ -52,15 +46,9 @@ The check commands can be run with the following procedure in a terminal that's 3. Run `npm run lint` 4. Run `npm run build` -:::danger If any of the above steps throw an error, they need to be addressed and all of the checks re-run prior to submitting a pull request. -::: -:::note -The documentation uses American English spelling and grammar conventions. Title case is used for the first three heading levels, with sentence case used beyond that. - -Please make sure your changes conform to these conventions - prettier and lint are unfortunately unable to do this automatically. -::: +The documentation uses American English spelling and grammar conventions. Title case is used for the first three heading levels, with sentence case used beyond that. Please make sure your changes conform to these conventions. ## Submitting a Pull Request diff --git a/docs/docs/development/module-creation.md b/docs/docs/development/module-creation.md index f12a1944..f3d351d7 100644 --- a/docs/docs/development/module-creation.md +++ b/docs/docs/development/module-creation.md @@ -12,9 +12,7 @@ sidebar_label: ZMK Module Creation See also Zephyr's [page on modules](https://docs.zephyrproject.org/4.1.0/develop/modules.html). -:::tip -For open source hardware designs, it can be convenient to use [Git submodules](https://github.blog/open-source/git/working-with-submodules/) to have the ZMK module also be a Git submodule of the repository hosting the hardware design. -::: +For open source hardware designs, it's recommended to **not** include the hardware design files in the ZMK module itself, since the module will be fetched by users during build and having design files in the module would likely make the module unnecessarily large and slow to fetch. ## Module Setup @@ -133,15 +131,15 @@ Note that the `include` and `src` folders are not mandated by the module system, Modules should expose all provided header files with an include path name beginning with the module-name, for example at `include/zmk__/
.h`. :::info -If your module requires adding drivers to existing subsystems in modules, you will need to use the `zephyr_library_amend()` CMake command, which requires you to have a specific directory structure. See [here](https://github.com/zephyrproject-rtos/zephyr/blob/main/cmake/modules/extensions.cmake#L454) for the definition and some documentation in the comments, with an example [here](https://github.com/petejohanson/ec-support-zmk-module/tree/main/drivers/kscan). +If your module requires adding drivers to existing subsystems in modules, you will need to use the `zephyr_library_amend()` CMake command, which requires you to have a specific directory structure. See [`zephyr/cmake/modules/extensions.cmake`](https://github.com/zephyrproject-rtos/zephyr/blob/main@%7B2025-Feb-15%7D/cmake/modules/extensions.cmake#L492) for the definition and some documentation in the comments, with an example in [`petejohanson/ec-support-zmk-module`](https://github.com/petejohanson/ec-support-zmk-module/tree/main/drivers/kscan). ::: ## Examples Below are some examples of modules for different types. Unless under the `zmkfirmware` project, these are not endorsed officially and may not follow our conventions perfectly. For such reason, the modules chosen to be presented here may change with time. -- Keyboard: https://github.com/petejohanson/zmk-keyboards-katori -- Behavior: https://github.com/urob/zmk-leader-key -- Driver: https://github.com/petejohanson/cirque-input-module -- Feature: https://github.com/joelspadin/zmk-locales -- VFX: https://github.com/caksoylar/zmk-rgbled-widget +- Keyboard: +- Behavior: +- Driver: +- Feature: +- VFX: diff --git a/docs/docs/features/led-indicators.md b/docs/docs/features/led-indicators.md index b4a6ddab..f017d5cd 100644 --- a/docs/docs/features/led-indicators.md +++ b/docs/docs/features/led-indicators.md @@ -54,14 +54,10 @@ For example, if you want the LED to be off when the indicator is active, 100% br }; ``` -:::note - If the LED is not configured to support brightness control, any value greater than 0 will result in maximum brightness. For most LEDs, you can enable PWM brightness control, though this will increase power usage slightly. See the [LED indicators hardware integration page](../hardware-integration/lighting/led-indicators.md) for details on configuring the LEDs. -::: - ## Adding LED Indicator Support to a Keyboard See the [LED indicators hardware integration page](../hardware-integration/lighting/led-indicators.md) for instructions to enable this feature on a keyboard. diff --git a/docs/docs/features/lighting.md b/docs/docs/features/lighting.md index c2a6699b..2276488e 100644 --- a/docs/docs/features/lighting.md +++ b/docs/docs/features/lighting.md @@ -11,7 +11,7 @@ Your keyboard likely uses only one type, depending on the type of LED hardware i - [Backlight](#backlight) system controls parallel-connected, non-addressable, single color LEDs. These are found on keyboards that have a single color backlight that only allows for brightness control. -:::warning +:::info Although the naming of the systems might imply it, which system you use typically does _not_ depend on the physical location of the LEDs. Instead, you should use the one that supports the LED hardware type that your keyboard has, as described above. diff --git a/docs/docs/features/low-power-states.md b/docs/docs/features/low-power-states.md index 5e0a384b..d428d0eb 100644 --- a/docs/docs/features/low-power-states.md +++ b/docs/docs/features/low-power-states.md @@ -44,13 +44,9 @@ It is recommended to add the `wakeup-source` property to `kscan` devices even if The soft off feature is used to turn the keyboard on and off explicitly, rather than through a timeout like the deep sleep feature. Depending on the keyboard, this may be through a dedicated on/off push button defined in hardware, or merely through an additional binding in the keymap to turn the device off and an existing reset button to turn the device back on. -The feature is intended as an alternative to using a hardware switch to physically cut power from the battery to the keyboard. This can be useful for existing PCBs not designed for wireless that don't have a power switch, or for new designs that favor a push button on/off like found on other devices. It yields power savings comparable to the deep sleep state. - -:::note - The device enters the same software power-off state as in deep sleep, but is significantly more restrictive in the sources which can wake it. Power is _not_ technically removed from the entire system, unlike a hardware switch. -::: +The feature is intended as an alternative to using a hardware switch to physically cut power from the battery to the keyboard. This can be useful for existing PCBs not designed for wireless that don't have a power switch, or for new designs that favor a push button on/off like found on other devices. It yields power savings comparable to the deep sleep state. A device can be put in the soft off state by: diff --git a/docs/docs/features/studio.md b/docs/docs/features/studio.md index 82e256e2..19760245 100644 --- a/docs/docs/features/studio.md +++ b/docs/docs/features/studio.md @@ -6,7 +6,7 @@ ZMK Studio provides runtime update functionality to ZMK powered devices, allowin :::info -To use ZMK Studio, a keyboard needs to be [configured appropriately](#adding-zmk-studio-support-to-a-keyboard). ZMK has updated some, but not all, of its in-tree keyboards for use with ZMK Studio, the list of which can be found [here](/blog/2024/11/11/zmk-studio-mvp-ga). If your keyboard is supported by an external module/config, check with the maintainer to see if support has been added. +To use ZMK Studio, a keyboard needs to be [configured appropriately](#adding-zmk-studio-support-to-a-keyboard). ZMK has updated some, but not all, of its in-tree keyboards for use with ZMK Studio, the list of which can be found in the [ZMK Studio blog post](/blog/2024/11/11/zmk-studio-mvp-ga). If your keyboard is supported by an external module/config, check with the maintainer to see if support has been added. ::: @@ -54,7 +54,7 @@ Generally, if you intend to use ZMK Studio, then you should not make any further ## Accessing ZMK Studio -You can use ZMK Studio with Chrome/Edge at https://zmk.studio/. +You can use ZMK Studio with Chrome/Edge at . To use the native app for Linux, macOS, or Windows, visit the [download page](https://zmk.studio/download). diff --git a/docs/docs/hardware-integration/lighting/underglow.md b/docs/docs/hardware-integration/lighting/underglow.md index f891c56e..61ecacf6 100644 --- a/docs/docs/hardware-integration/lighting/underglow.md +++ b/docs/docs/hardware-integration/lighting/underglow.md @@ -15,12 +15,10 @@ For example: the `kyria` shield has a [`boards/nice_nano_nrf52840_zmk.overlay`]( ### nRF52-Based Boards -Using an SPI-based LED strip driver on the `&spi3` interface is the simplest option for nRF52-based boards. If possible, avoid using pins which are limited to low-frequency I/O for this purpose. The resulting interference may result in poor wireless performance. +Using an SPI-based LED strip driver on the `&spi3` interface is the simplest option for nRF52-based boards. :::info - -The list of low frequency I/O pins for the nRF52840 can be found [here](https://docs.nordicsemi.com/bundle/ps_nrf52840/page/pin.html). - +If possible, avoid using pins which are limited to low-frequency I/O for this purpose. The resulting interference may result in poor wireless performance. The list of low frequency I/O pins for the nRF52840 can be found at . ::: The following example uses `P0.06` as the "Data In" pin of a WS2812-compatible LED strip: @@ -69,13 +67,9 @@ The following example uses `P0.06` as the "Data In" pin of a WS2812-compatible L }; ``` -:::note - Standard WS2812 LEDs use a wire protocol where the bits for the colors green, red, and blue values are sent in that order. If your board/shield uses LEDs that require the data sent in a different order, the `color-mapping` property ordering should be changed to match. -::: - ### Other Boards Be sure to check the Zephyr documentation for the LED strip and necessary hardware bindings. Not every board has an `spi3` node, or configures `pinctrl` the same way. Reconcile this with any hardware restrictions found in the manufacturer's datasheet. Additional hardware interfaces may need to be enabled via Kconfig. diff --git a/docs/docs/hardware-integration/new-board.md b/docs/docs/hardware-integration/new-board.md index 3b1a98d0..3450cdfd 100644 --- a/docs/docs/hardware-integration/new-board.md +++ b/docs/docs/hardware-integration/new-board.md @@ -32,7 +32,7 @@ This guide assumes you already have a configured GitHub account. If you don't ye Follow these steps to create your new repository: -- Visit https://github.com/zmkfirmware/unified-zmk-config-template +- Visit - Click the green "Use this template" button - In the drop down that opens, click "Use this template". - In the following screen, provide the following information: diff --git a/docs/docs/hardware-integration/physical-layouts.md b/docs/docs/hardware-integration/physical-layouts.md index 4678e0f7..60a29a8d 100644 --- a/docs/docs/hardware-integration/physical-layouts.md +++ b/docs/docs/hardware-integration/physical-layouts.md @@ -62,11 +62,7 @@ A key description has the shape `<&key_physical_attrs w h x y r rx ry>` with the You can specify negative values in devicetree using parentheses around it, e.g. `(-3000)` for a 30 degree counterclockwise rotation. -:::tip - -We recommend the use of [this tool](https://zmk-physical-layout-converter.streamlit.app/) for writing a physical layout or converting one from a QMK JSON definition. If your keyboard already has a physical layout defined for the use with KLE, we recommend using [this other tool](https://nickcoutsos.github.io/keymap-layout-tools/) first to convert your existing layout into QMK JSON. The second tool can also import the position data from KiCAD, if said program was used to design the keyboard. - -::: +We recommend the use of for writing a physical layout or converting one from a QMK JSON definition. If your keyboard already has a physical layout defined for the use with KLE, we recommend using first to convert your existing layout into QMK JSON. The second tool can also import the position data from KiCAD, if said program was used to design the keyboard. ### Physical Layout with Keys Example @@ -207,11 +203,7 @@ The position map should be marked as `complete` if all desired binding transfers See also the [configuration section on position maps](../config/layout.md#physical-layout-position-map). -:::tip - -We recommend the use of [this tool](https://zmk-layout-helper.netlify.app/), distinct from the previous two mentioned, for the purposes of writing a position map. - -::: +We recommend the use of , distinct from the previous two mentioned, for the purposes of writing a position map. #### Writing a position map diff --git a/docs/docs/hardware-integration/pinctrl.mdx b/docs/docs/hardware-integration/pinctrl.mdx index f634cb14..67dec613 100644 --- a/docs/docs/hardware-integration/pinctrl.mdx +++ b/docs/docs/hardware-integration/pinctrl.mdx @@ -8,15 +8,11 @@ import TabItem from "@theme/TabItem"; import InterconnectTabs from "@site/src/components/interconnect-tabs"; import Metadata from "@site/src/data/hardware-metadata.json"; -:::info This page exists to provide a guide to [Pin Control](https://docs.zephyrproject.org/4.1.0/hardware/pinctrl/index.html#pin-control) for ZMK users and designers. Refer to [Zephyr's page on Pin Control](https://docs.zephyrproject.org/4.1.0/hardware/pinctrl/index.html#pin-control) for elaboration and more details on any of the points raised here. -::: A basic keyboard design as introduced in the [new shield guide](./new-shield.mdx) only uses its pins for the keyboard matrix. Many keyboard designs make use of advanced components or functionality, such as displays or shift registers. This results in the keyboard making use of communication protocols such as (but not limited to) SPI, I2C, or UART. Configuring pins for the usage of advanced functionality such as drivers for the previously named protocols is referred to as "Pin Control". -:::warning The details of pin control can vary from vendor to vendor. An attempt was made to be as general as possible, but it isn't possible to cover all possible cases. The approaches for the nRF52840 and RP2040 MCUs/SoCs are documented in their entirety below. For other MCUs/SoCs, please refer to the [Zephyr documentation](https://docs.zephyrproject.org/4.1.0/index.html) and the examples and other files found in-tree of [ZMK](https://github.com/zmkfirmware/zmk/tree/main/app/boards) and [ZMK's fork of Zephyr](https://github.com/zmkfirmware/zephyr). -::: ## Boards, Shields, and Modules @@ -33,10 +29,8 @@ Pin control is always defined for a _board_, never for a shield: ``` Note that you will need to define a separate overlay _for each_ of the boards to be used with the shield. -:::info Assume that the shield that you are using is found in-tree of ZMK or within an external module, and _does not_ contain the overlay for the board that you wish to use. If this is the case, then you should fork the source repository and add the overlay to the fork. Use said fork to build your firmware, and potentially submit a PR to upstream. -::: ## Predefined Nodes diff --git a/docs/docs/hardware-integration/shift-registers.md b/docs/docs/hardware-integration/shift-registers.md index 01bc35e6..4a5f02a9 100644 --- a/docs/docs/hardware-integration/shift-registers.md +++ b/docs/docs/hardware-integration/shift-registers.md @@ -9,9 +9,7 @@ Shift registers are the recommended method of adding additional GPIO pins to MCU This page assumes that you are using a SIPO shift register with the part number 74HC595. Other shift registers can work as well but this is the most commonly used one. ::: -:::tip To understand how shift registers work, we recommend reading through ["How does the 74HC595 Shift Register work?"](https://lastminuteengineers.com/74hc595-shift-register-arduino-tutorial/#how-does-the-74hc595-shift-register-work). -::: ## Design Guidelines diff --git a/docs/docs/keymaps/behaviors/hold-tap.mdx b/docs/docs/keymaps/behaviors/hold-tap.mdx index 2006a577..c4d27d9d 100644 --- a/docs/docs/keymaps/behaviors/hold-tap.mdx +++ b/docs/docs/keymaps/behaviors/hold-tap.mdx @@ -372,11 +372,9 @@ Including `hold-trigger-key-positions` in your hold-tap definition turns on the In all other situations, positional hold-tap will not modify the behavior of your hold-tap. Positional hold-tap is useful when used with home-row modifiers: for example, if you have a home-row modifier key in the left hand, by including only key positions from the right hand in `hold-trigger-key-positions`, you will only get hold behaviors during cross-hand key combinations unless you exceed `tapping-term-ms` when using "balanced" or "hold-preferred" flavors. -For home-row mods, it is recommended to use this property with `hold-trigger-on-release` so that modifiers on the same hand can be combined. - -:::info `hold-trigger-key-positions` is an array of key position indexes. Key positions are numbered sequentially according to your keymap, starting with 0. So if the first key in your keymap is Q, this key is in position 0. The next key (probably W) will be in position 1, et cetera. -::: + +For home-row mods, it is recommended to use this property with `hold-trigger-on-release` so that modifiers on the same hand can be combined.
The following example uses a hold-tap behavior definition configured with the `hold-preferred` flavor, and with positional hold-tap enabled: diff --git a/docs/docs/keymaps/behaviors/macros.md b/docs/docs/keymaps/behaviors/macros.md index a06efaf3..45780bfa 100644 --- a/docs/docs/keymaps/behaviors/macros.md +++ b/docs/docs/keymaps/behaviors/macros.md @@ -312,10 +312,6 @@ To avoid repetition or possible typos when declaring a **zero parameter macro**, ) ``` -:::note -`ZMK_MACRO()` **only supports declaring non-parameterized (zero parameter) macros**; parameterized declarations are not currently supported. -::: - This can be used instead of a complete macro definition. During the firmware build process, the example above would produce the complete macro definition below: ```dts diff --git a/docs/docs/keymaps/behaviors/power.md b/docs/docs/keymaps/behaviors/power.md index 1814e67c..f118d0ca 100644 --- a/docs/docs/keymaps/behaviors/power.md +++ b/docs/docs/keymaps/behaviors/power.md @@ -48,7 +48,7 @@ The on/off state that is set by the `&ext_power` behavior will be [saved to flas However it will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE`](../../config/system.md#general) milliseconds in order to reduce potential wear on the flash memory. ::: -### Example: +### Examples 1. Behavior binding to enable the external power diff --git a/docs/docs/keymaps/input-processors/behaviors.md b/docs/docs/keymaps/input-processors/behaviors.md index 9bda1dfa..032774c7 100644 --- a/docs/docs/keymaps/input-processors/behaviors.md +++ b/docs/docs/keymaps/input-processors/behaviors.md @@ -7,12 +7,8 @@ sidebar_label: Behaviors The behaviors input processor is used invoke standard behaviors when certain input events occur; most frequently this is used to trigger behaviors when certain mouse buttons are triggered by physical pointing devices. -:::note - This input processor is primarily intended for `INPUT_EV_KEY` type of events that have a binary on/off state, not vector types for relative or absolute movements. -::: - :::note[Source-specific behaviors on split keyboards] Invoking a [source-specific behavior](../../features/split-keyboards.md#source-locality-behaviors) such as one of the [reset behaviors](../behaviors/reset.md) using this input processor will always trigger it on the central side of the keyboard, regardless of the side includes the input device that originally generated the input event. ::: diff --git a/docs/docs/keymaps/list-of-keycodes.mdx b/docs/docs/keymaps/list-of-keycodes.mdx index c62d5875..3ee88367 100644 --- a/docs/docs/keymaps/list-of-keycodes.mdx +++ b/docs/docs/keymaps/list-of-keycodes.mdx @@ -9,11 +9,6 @@ import Table from "@site/src/components/codes/Table"; This is the reference page for keycodes used by behaviors. Use the table of contents (on the right or the top) for easy navigation. -:::warning -Take extra notice of the spelling of the keycodes, especially the shorthand spelling. -Otherwise, it will result in an elusive parsing error! -::: - :::info[Keyboard vs. Consumer keycodes] In the below tables, there are keycode pairs with similar names where one variant has a `K_` prefix and another `C_`. These variants correspond to similarly named usages from different [HID usage pages](https://usb.org/sites/default/files/hut1_2.pdf#page=16), diff --git a/docs/docs/troubleshooting/building-issues.md b/docs/docs/troubleshooting/building-issues.md index fb256ef8..ca53e9bf 100644 --- a/docs/docs/troubleshooting/building-issues.md +++ b/docs/docs/troubleshooting/building-issues.md @@ -53,12 +53,10 @@ A `devicetree_generated.h` error that follows with an "undeclared here" string i In this example, the error string `DT_N_S_keymap_S_symbol_layer_P_bindings_IDX_12_PH_P_label` indicates a problem with the key binding in position `12` in the `symbol_layer` of the keymap. -:::info Key positions are numbered starting from `0` at the top left key on the keymap, incrementing horizontally, row by row. -::: :::tip -A common mistake that leads to this error is to use [key press keycodes](keymaps/behaviors/key-press.md) without the leading `&kp` binding. That is, having entries such as `SPACE` that should have been `&kp SPACE`. +A common mistake that leads to this error is to use [key press keycodes](keymaps/behaviors/key-press.md) without the leading `&kp` binding. That is, having entries such as `&kp A SPACE &kp B` that should have been `&kp A &kp SPACE &kp B`. ::: ## Diagnosing Unexpected Build Results From 7fdae56f02f20d5c109f7e481e41e34bfb0d88dc Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 20 Jun 2026 06:47:57 +0200 Subject: [PATCH 07/12] chore(deps): bump launch-editor from 2.13.2 to 2.14.1 in /docs (#3394) Bumps [launch-editor](https://github.com/vitejs/launch-editor) from 2.13.2 to 2.14.1. - [Commits](https://github.com/vitejs/launch-editor/compare/v2.13.2...v2.14.1) --- updated-dependencies: - dependency-name: launch-editor dependency-version: 2.14.1 dependency-type: indirect ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- docs/package-lock.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/package-lock.json b/docs/package-lock.json index 10286434..26c00467 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -13847,13 +13847,13 @@ } }, "node_modules/launch-editor": { - "version": "2.13.2", - "resolved": "https://registry.npmjs.org/launch-editor/-/launch-editor-2.13.2.tgz", - "integrity": "sha512-4VVDnbOpLXy/s8rdRCSXb+zfMeFR0WlJWpET1iA9CQdlZDfwyLjUuGQzXU4VeOoey6AicSAluWan7Etga6Kcmg==", + "version": "2.14.1", + "resolved": "https://registry.npmjs.org/launch-editor/-/launch-editor-2.14.1.tgz", + "integrity": "sha512-QWBrQsMpH7gPr965dsKD/3cKWiNoTjpATQf++Xq63N6sKRGMwlVXz41O1IZTMfZQgBctD/K5Zt06+/I6pP6+HA==", "license": "MIT", "dependencies": { "picocolors": "^1.1.1", - "shell-quote": "^1.8.3" + "shell-quote": "^1.8.4" } }, "node_modules/layout-base": { @@ -20819,9 +20819,9 @@ } }, "node_modules/shell-quote": { - "version": "1.8.3", - "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.8.3.tgz", - "integrity": "sha512-ObmnIF4hXNg1BqhnHmgbDETF8dLPCggZWBjkQfhZpbszZnYur5DUljTcCHii5LC3J5E0yeO/1LIMyH+UvHQgyw==", + "version": "1.8.4", + "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.8.4.tgz", + "integrity": "sha512-VsC6n6vz1ihYYyZZwX7YZSF5l5x36ca17OC+a69h94YqB7X6XLwf+5MOgynYir2SLFUbl8gIYvBo8K8RoNQ6bQ==", "license": "MIT", "engines": { "node": ">= 0.4" From 45d6d67a04a6da08f2871e6c4e2be406f0eba20e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 20 Jun 2026 06:54:09 +0200 Subject: [PATCH 08/12] chore(deps): bump googleapis/release-please-action from 4 to 5 (#3333) Bumps [googleapis/release-please-action](https://github.com/googleapis/release-please-action) from 4 to 5. - [Release notes](https://github.com/googleapis/release-please-action/releases) - [Changelog](https://github.com/googleapis/release-please-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/googleapis/release-please-action/compare/v4...v5) --- updated-dependencies: - dependency-name: googleapis/release-please-action dependency-version: '5' dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/release-please.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml index 048d6a1d..8e8f1113 100644 --- a/.github/workflows/release-please.yml +++ b/.github/workflows/release-please.yml @@ -20,7 +20,7 @@ jobs: minor: ${{ steps.release.outputs.minor }} patch: ${{ steps.release.outputs.patch }} steps: - - uses: googleapis/release-please-action@v4 + - uses: googleapis/release-please-action@v5 id: release with: token: ${{ secrets.ZMK_RELEASE_PLEASE_TOKEN }} From fb1fad07a1351c3b7dcf412dca1cc7c86a338efc Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 20 Jun 2026 06:56:25 +0200 Subject: [PATCH 09/12] chore(deps): bump actions/github-script from 7 to 9 (#3324) Bumps [actions/github-script](https://github.com/actions/github-script) from 7 to 9. - [Release notes](https://github.com/actions/github-script/releases) - [Commits](https://github.com/actions/github-script/compare/v7...v9) --- updated-dependencies: - dependency-name: actions/github-script dependency-version: '9' dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/build.yml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 97a060df..716295c0 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -63,7 +63,7 @@ jobs: - name: Install @actions/artifact run: npm install @actions/artifact@5.0.3 - name: Build - uses: actions/github-script@v7 + uses: actions/github-script@v9 id: boards-list with: script: | @@ -95,7 +95,7 @@ jobs: throw new Error('Failed to build one or more configurations'); } - name: Upload artifacts - uses: actions/github-script@v7 + uses: actions/github-script@v9 continue-on-error: ${{ github.event_name == 'pull_request' }} id: boards-upload with: @@ -146,7 +146,7 @@ jobs: include-list: ${{ steps.compile-list.outputs.result }} steps: - name: Join build lists - uses: actions/github-script@v7 + uses: actions/github-script@v9 id: compile-list with: script: | @@ -196,7 +196,7 @@ jobs: node-version: "14.x" - name: Install js-yaml run: npm install js-yaml - - uses: actions/github-script@v7 + - uses: actions/github-script@v9 id: core-list with: script: | @@ -225,7 +225,7 @@ jobs: node-version: "14.x" - name: Install js-yaml run: npm install js-yaml - - uses: actions/github-script@v7 + - uses: actions/github-script@v9 id: boards-list with: script: | @@ -303,7 +303,7 @@ jobs: nightly-include: ${{ steps.nightly-list.outputs.result }} steps: - name: Create nightly list - uses: actions/github-script@v7 + uses: actions/github-script@v9 id: nightly-list with: script: | @@ -356,7 +356,7 @@ jobs: - name: Install js-yaml run: npm install js-yaml - name: Aggregate Metadata - uses: actions/github-script@v7 + uses: actions/github-script@v9 id: aggregate-metadata with: script: | @@ -374,7 +374,7 @@ jobs: result-encoding: string - name: Organize Metadata - uses: actions/github-script@v7 + uses: actions/github-script@v9 id: organize-metadata with: script: | @@ -436,7 +436,7 @@ jobs: with: json: true escape_json: false - - uses: actions/github-script@v7 + - uses: actions/github-script@v9 id: board-changes with: script: | @@ -444,7 +444,7 @@ jobs: const boardChanges = changedFiles.filter(f => f.startsWith('app/boards')); return boardChanges.length ? 'true' : 'false'; result-encoding: string - - uses: actions/github-script@v7 + - uses: actions/github-script@v9 id: core-changes with: script: | From f57e25565782feb7815f2a5284b0b28d7fe6b0e7 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 20 Jun 2026 06:58:21 +0200 Subject: [PATCH 10/12] chore(deps): bump actions/checkout from 6 to 7 (#3393) Bumps [actions/checkout](https://github.com/actions/checkout) from 6 to 7. - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](https://github.com/actions/checkout/compare/v6...v7) --- updated-dependencies: - dependency-name: actions/checkout dependency-version: '7' dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/ble-test.yml | 4 ++-- .github/workflows/build-user-config.yml | 4 ++-- .github/workflows/build.yml | 10 +++++----- .github/workflows/doc-checks.yml | 4 ++-- .github/workflows/hardware-metadata-validation.yml | 2 +- .github/workflows/pre-commit.yml | 2 +- .github/workflows/release-please.yml | 2 +- .github/workflows/test.yml | 4 ++-- 8 files changed, 16 insertions(+), 16 deletions(-) diff --git a/.github/workflows/ble-test.yml b/.github/workflows/ble-test.yml index 51450414..68cb1cb3 100644 --- a/.github/workflows/ble-test.yml +++ b/.github/workflows/ble-test.yml @@ -21,7 +21,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v6 + uses: actions/checkout@v7 - name: Find test directories id: test-dirs run: | @@ -38,7 +38,7 @@ jobs: image: docker.io/zmkfirmware/zmk-build-arm:4.1 steps: - name: Checkout - uses: actions/checkout@v6 + uses: actions/checkout@v7 - name: Cache west modules uses: actions/cache@v5 env: diff --git a/.github/workflows/build-user-config.yml b/.github/workflows/build-user-config.yml index 66226b5f..f6839819 100644 --- a/.github/workflows/build-user-config.yml +++ b/.github/workflows/build-user-config.yml @@ -33,7 +33,7 @@ jobs: has_valid_build_matrix: ${{ steps.fetch.outputs.has_valid_build_matrix }} steps: - name: Checkout - uses: actions/checkout@v6 + uses: actions/checkout@v7 - name: Fetch Build Matrix id: fetch @@ -67,7 +67,7 @@ jobs: curl -fsSL https://deb.nodesource.com/setup_22.x | bash && apt install -y nodejs - name: Checkout - uses: actions/checkout@v6 + uses: actions/checkout@v7 - name: Create build directory run: | diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 716295c0..0d2a5805 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -30,7 +30,7 @@ jobs: include: ${{ fromJSON(needs.compile-matrix.outputs.include-list) }} steps: - name: Checkout - uses: actions/checkout@v6 + uses: actions/checkout@v7 with: persist-credentials: false - name: Cache west modules @@ -187,7 +187,7 @@ jobs: core-include: ${{ steps.core-list.outputs.result }} steps: - name: Checkout - uses: actions/checkout@v6 + uses: actions/checkout@v7 with: persist-credentials: false - name: Use Node.js @@ -218,7 +218,7 @@ jobs: boards-include: ${{ steps.boards-list.outputs.result }} steps: - name: Checkout - uses: actions/checkout@v6 + uses: actions/checkout@v7 - name: Use Node.js uses: actions/setup-node@v6 with: @@ -346,7 +346,7 @@ jobs: organized-metadata: ${{ steps.organize-metadata.outputs.result }} steps: - name: Checkout - uses: actions/checkout@v6 + uses: actions/checkout@v7 with: persist-credentials: false - name: Use Node.js @@ -428,7 +428,7 @@ jobs: core-changes: ${{ steps.core-changes.outputs.result }} steps: - name: Checkout - uses: actions/checkout@v6 + uses: actions/checkout@v7 with: persist-credentials: false - uses: tj-actions/changed-files@9200e69727eb73eb060652b19946b8a2fdfb654b # pin to v45.0.8 due to https://github.com/tj-actions/changed-files/issues/2463 https://www.stepsecurity.io/blog/harden-runner-detection-tj-actions-changed-files-action-is-compromised diff --git a/.github/workflows/doc-checks.yml b/.github/workflows/doc-checks.yml index 6866ff79..a562ed39 100644 --- a/.github/workflows/doc-checks.yml +++ b/.github/workflows/doc-checks.yml @@ -14,7 +14,7 @@ jobs: lint: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - uses: bahmutov/npm-install@v1 with: working-directory: docs @@ -24,7 +24,7 @@ jobs: typecheck: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - uses: bahmutov/npm-install@v1 with: working-directory: docs diff --git a/.github/workflows/hardware-metadata-validation.yml b/.github/workflows/hardware-metadata-validation.yml index e212f627..406a1e63 100644 --- a/.github/workflows/hardware-metadata-validation.yml +++ b/.github/workflows/hardware-metadata-validation.yml @@ -20,7 +20,7 @@ jobs: container: image: docker.io/zmkfirmware/zmk-dev-arm:4.1 steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - name: Install dependencies run: pip install --break-system-packages -r app/scripts/requirements.txt - name: West init diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml index 42b42af0..52b82a62 100644 --- a/.github/workflows/pre-commit.yml +++ b/.github/workflows/pre-commit.yml @@ -8,7 +8,7 @@ jobs: pre-commit: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - uses: actions/setup-python@v6 with: python-version: 3.x diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml index 8e8f1113..5735eea7 100644 --- a/.github/workflows/release-please.yml +++ b/.github/workflows/release-please.yml @@ -35,7 +35,7 @@ jobs: ZMK_RELEASE_PLEASE_TOKEN: ${{ secrets.ZMK_RELEASE_PLEASE_TOKEN }} VERSION: v${{ needs.handle-commit.outputs.major }}.${{ needs.handle-commit.outputs.minor }} steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - name: Create major.minor branch if: ${{ needs.handle-commit.outputs.patch == '0' }} diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 1efc9cac..20bebf3b 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -23,7 +23,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v6 + uses: actions/checkout@v7 - name: Find test directories id: test-dirs run: | @@ -40,7 +40,7 @@ jobs: image: docker.io/zmkfirmware/zmk-build-arm:4.1 steps: - name: Checkout - uses: actions/checkout@v6 + uses: actions/checkout@v7 - name: Cache west modules uses: actions/cache@v5 env: From e695d94fdaeaf1687a280fdfbbf5d149165007c3 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 20 Jun 2026 09:12:26 +0200 Subject: [PATCH 11/12] chore(deps): bump webpack-dev-server from 5.2.4 to 5.2.5 in /docs (#3396) Bumps [webpack-dev-server](https://github.com/webpack/webpack-dev-server) from 5.2.4 to 5.2.5. - [Release notes](https://github.com/webpack/webpack-dev-server/releases) - [Changelog](https://github.com/webpack/webpack-dev-server/blob/main/CHANGELOG.md) - [Commits](https://github.com/webpack/webpack-dev-server/compare/v5.2.4...v5.2.5) --- updated-dependencies: - dependency-name: webpack-dev-server dependency-version: 5.2.5 dependency-type: indirect ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- docs/package-lock.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/package-lock.json b/docs/package-lock.json index 26c00467..9c79038f 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -23154,9 +23154,9 @@ } }, "node_modules/webpack-dev-server": { - "version": "5.2.4", - "resolved": "https://registry.npmjs.org/webpack-dev-server/-/webpack-dev-server-5.2.4.tgz", - "integrity": "sha512-GqDPGZN9bRqKBTkp4aWkobDDHMsrXKoGSdOH56smIri8qR0JG8gfL8/v/f/OZR3/OKXjG8uwJbFVhKm/FNU/UA==", + "version": "5.2.5", + "resolved": "https://registry.npmjs.org/webpack-dev-server/-/webpack-dev-server-5.2.5.tgz", + "integrity": "sha512-4wZtCquSuv9CKX8oybo+mqxtxZqWz47uM1Ch94lxowBztOhWCbhqvRbfC/mODOwxgV2brY+JGZpHq58/SuVFYg==", "license": "MIT", "dependencies": { "@types/bonjour": "^3.5.13", From 64daf698e073e37b6748ac54f4eb48d8666af0b9 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 20 Jun 2026 09:13:12 +0200 Subject: [PATCH 12/12] chore(deps): bump ws in /docs (#3398) Bumps and [ws](https://github.com/websockets/ws). These dependencies needed to be updated together. Updates `ws` from 7.5.10 to 7.5.11 - [Release notes](https://github.com/websockets/ws/releases) - [Commits](https://github.com/websockets/ws/compare/7.5.10...7.5.11) Updates `ws` from 8.20.0 to 8.21.0 - [Release notes](https://github.com/websockets/ws/releases) - [Commits](https://github.com/websockets/ws/compare/7.5.10...7.5.11) --- updated-dependencies: - dependency-name: ws dependency-version: 7.5.11 dependency-type: indirect - dependency-name: ws dependency-version: 8.21.0 dependency-type: indirect ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- docs/package-lock.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/package-lock.json b/docs/package-lock.json index 9c79038f..f046e505 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -23241,9 +23241,9 @@ } }, "node_modules/webpack-dev-server/node_modules/ws": { - "version": "8.20.0", - "resolved": "https://registry.npmjs.org/ws/-/ws-8.20.0.tgz", - "integrity": "sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA==", + "version": "8.21.0", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz", + "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==", "license": "MIT", "engines": { "node": ">=10.0.0" @@ -23636,9 +23636,9 @@ } }, "node_modules/ws": { - "version": "7.5.10", - "resolved": "https://registry.npmjs.org/ws/-/ws-7.5.10.tgz", - "integrity": "sha512-+dbF1tHwZpXcbOJdVOkzLDxZP1ailvSxM6ZweXTegylPny803bFhA+vqBYw4s31NSAk4S2Qz+AKXK9a4wkdjcQ==", + "version": "7.5.11", + "resolved": "https://registry.npmjs.org/ws/-/ws-7.5.11.tgz", + "integrity": "sha512-zS54Oen9bITtp7kp2XM3AydrCIq1D+HwJOuH+c+e4LfpL/lotP5osijd+UoMnxwAam1GN8R4KtLAyIrIcBNpiA==", "license": "MIT", "engines": { "node": ">=8.3.0"