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] 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