From a3fbc2a5ba36db982c32fafbd6dcf0437477bb48 Mon Sep 17 00:00:00 2001 From: honorless <86894501+lesshonor@users.noreply.github.com> Date: Sun, 7 Jan 2024 21:15:27 -0500 Subject: [PATCH] docs: suggest zmk,matrix-transform over zmk,matrix_transform * While functionally equivalent, the hyphenated form of this property is more consistent with other ZMK properties and adheres to DTS style guidelines. * Additionally, update links to use Zephyr 3.2 documentation instead of 2.5 where appropriate. --- docs/docs/config/kscan.md | 8 ++++---- docs/docs/development/boards-shields-keymaps.md | 10 +++++----- docs/docs/development/build-flash.mdx | 4 ++-- docs/docs/development/new-shield.mdx | 6 +++--- 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/docs/config/kscan.md b/docs/docs/config/kscan.md index 5aa9bc0f..045c35ca 100644 --- a/docs/docs/config/kscan.md +++ b/docs/docs/config/kscan.md @@ -30,7 +30,7 @@ Applies to: [`/chosen` node](https://docs.zephyrproject.org/latest/guides/dts/in | Property | Type | Description | | ---------------------- | ---- | ------------------------------------------------------------- | | `zmk,kscan` | path | The node for the keyboard scan driver to use | -| `zmk,matrix_transform` | path | The node for the [matrix transform](#matrix-transform) to use | +| `zmk,matrix-transform` | path | The node for the [matrix transform](#matrix-transform) to use | ## Demux Driver @@ -347,7 +347,7 @@ Any keyboard which is not a grid of 1 unit keys will likely have some unused pos / { chosen { zmk,kscan = &kscan0; - zmk,matrix_transform = &default_transform; + zmk,matrix-transform = &default_transform; }; kscan0: kscan { @@ -407,7 +407,7 @@ Consider a keyboard with a [duplex matrix](https://wiki.ai03.com/books/pcb-desig / { chosen { zmk,kscan = &kscan0; - zmk,matrix_transform = &default_transform; + zmk,matrix-transform = &default_transform; }; kscan0: kscan { @@ -446,7 +446,7 @@ Note that the entire addressable space does not need to be mapped. / { chosen { zmk,kscan = &kscan0; - zmk,matrix_transform = &default_transform; + zmk,matrix-transform = &default_transform; }; kscan0: kscan { diff --git a/docs/docs/development/boards-shields-keymaps.md b/docs/docs/development/boards-shields-keymaps.md index 8b5e7762..3595cb17 100644 --- a/docs/docs/development/boards-shields-keymaps.md +++ b/docs/docs/development/boards-shields-keymaps.md @@ -6,7 +6,7 @@ title: Boards, Shields, and Keymaps The foundational elements needed to get a specific keyboard working with ZMK can be broken down into: -- A [KSCAN driver](https://docs.zephyrproject.org/2.5.0/reference/peripherals/kscan.html), which uses `compatible="zmk,kscan-gpio-matrix"` for GPIO matrix based keyboards, or uses `compatible="zmk,kscan-gpio-direct"` for small direct wires. +- A [KSCAN driver](https://docs.zephyrproject.org/3.2.0/reference/peripherals/kscan.html), which uses `compatible="zmk,kscan-gpio-matrix"` for GPIO matrix based keyboards, or uses `compatible="zmk,kscan-gpio-direct"` for small direct wires. - An optional matrix transform, which defines how the KSCAN row/column events are translated into logical "key positions". This is required for non-rectangular keyboards/matrices, where the key positions don't naturally follow the row/columns from the GPIO matrix. - A keymap, which binds each key position to a behavior, e.g. key press, mod-tap, momentary layer, in a set of layers. @@ -27,8 +27,8 @@ in the `app/boards/${arch}/${board_name}` directory, e.g. `app/boards/arm/planck - A `${board_name}_defconfig` file that forces specific Kconfig settings that are specific to this hardware configuration. Mostly this is SoC settings around the specific hardware configuration. - `${board_name}.dts` which contains all the devicetree definitions, including: - An `#include` line that pulls in the specific microprocessor that is used, e.g. `#include `. - - A [chosen](https://docs.zephyrproject.org/2.5.0/guides/dts/intro.html#aliases-and-chosen-nodes) node named `zmk,kscan` which references the configured KSCAN driver (usually a GPIO matrix) - - (Optional) A [chosen](https://docs.zephyrproject.org/2.5.0/guides/dts/intro.html#aliases-and-chosen-nodes) node named `zmk,matrix_transform` that defines the mapping from KSCAN row/column values to the logical key position for the keyboard. + - A [chosen](https://docs.zephyrproject.org/3.2.0/guides/dts/intro.html#aliases-and-chosen-nodes) node named `zmk,kscan` which references the configured KSCAN driver (usually a GPIO matrix) + - (Optional) A [chosen](https://docs.zephyrproject.org/3.2.0/guides/dts/intro.html#aliases-and-chosen-nodes) node named `zmk,matrix-transform` that defines the mapping from KSCAN row/column values to the logical key position for the keyboard. - A `board.cmake` file with CMake directives for how to flash to the device. - A `${board_name}.keymap` file that includes the default keymap for that keyboard. Users will be able to override this keymap in their user configs. @@ -47,6 +47,6 @@ in the `app/boards/shields/${board_name}` directory, e.g. `app/boards/shields/cl - 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 things like `ZMK_KEYBOARD_NAME` - A `${shield_name}.overlay` file, which is a devicetree overlay file, that includes: - - A [chosen](https://docs.zephyrproject.org/2.5.0/guides/dts/intro.html#aliases-and-chosen-nodes) node named `zmk,kscan` which references the configured KSCAN driver (usually a GPIO matrix). For these keyboards, to be compatible with any Pro Micro compatible boards, the KSCAN configuration should reference the [nexus node](https://docs.zephyrproject.org/2.5.0/guides/porting/shields.html#gpio-nexus-nodes) that ZMK has standardized on. In particular, the `&pro_micro` aliases can be used to reference the standard digital pins of a Pro Micro for shields. - - (Optional) A [chosen](https://docs.zephyrproject.org/2.5.0/guides/dts/intro.html#aliases-and-chosen-nodes) node named `zmk,matrix_transform` that defines the mapping from KSCAN row/column values to the logical key position for the keyboard. + - A [chosen](https://docs.zephyrproject.org/3.2.0/guides/dts/intro.html#aliases-and-chosen-nodes) node named `zmk,kscan` which references the configured KSCAN driver (usually a GPIO matrix). For these keyboards, to be compatible with any Pro Micro compatible boards, the KSCAN configuration should reference the [nexus node](https://docs.zephyrproject.org/3.2.0/guides/porting/shields.html#gpio-nexus-nodes) that ZMK has standardized on. In particular, the `&pro_micro` aliases can be used to reference the standard digital pins of a Pro Micro for shields. + - (Optional) A [chosen](https://docs.zephyrproject.org/3.2.0/guides/dts/intro.html#aliases-and-chosen-nodes) node named `zmk,matrix-transform` that defines the mapping from KSCAN row/column values to the logical key position for the keyboard. - A `keymap/keymap.overlay` file that includes the default keymap for that keyboard. Users will be able to override this keymap in their user configs. diff --git a/docs/docs/development/build-flash.mdx b/docs/docs/development/build-flash.mdx index 25655c8e..ece474bd 100644 --- a/docs/docs/development/build-flash.mdx +++ b/docs/docs/development/build-flash.mdx @@ -16,7 +16,7 @@ an onboard MCU, or one that uses an MCU board addon. ### Keyboard (Shield) + MCU Board -ZMK treats keyboards that take an MCU addon board as [shields](https://docs.zephyrproject.org/2.5.0/guides/porting/shields.html), and treats the smaller MCU board as the true [board](https://docs.zephyrproject.org/2.5.0/guides/porting/board_porting.html) +ZMK treats keyboards that take an MCU addon board as [shields](https://docs.zephyrproject.org/3.2.0/guides/porting/shields.html), and treats the smaller MCU board as the true [board](https://docs.zephyrproject.org/3.2.0/guides/porting/board_porting.html) Given the following: @@ -32,7 +32,7 @@ west build -b proton_c -- -DSHIELD=kyria_left ### Keyboard With Onboard MCU -Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/2.5.0/guides/porting/board_porting.html) as far as Zephyr™ is concerned. +Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/3.2.0/guides/porting/board_porting.html) as far as Zephyr™ is concerned. Given the following: diff --git a/docs/docs/development/new-shield.mdx b/docs/docs/development/new-shield.mdx index 340db330..2f52839b 100644 --- a/docs/docs/development/new-shield.mdx +++ b/docs/docs/development/new-shield.mdx @@ -201,7 +201,7 @@ For `col2row` directed boards like the iris, the shared .dtsi file may look like / { chosen { zmk,kscan = &kscan0; - zmk,matrix_transform = &default_transform; + zmk,matrix-transform = &default_transform; }; default_transform: keymap_transform_0 { @@ -336,7 +336,7 @@ Here is an example for the [nice60](https://github.com/Nicell/nice60), which use / { chosen { zmk,kscan = &kscan0; - zmk,matrix_transform = &default_transform; + zmk,matrix-transform = &default_transform; }; default_transform: keymap_transform_0 { @@ -362,7 +362,7 @@ Some important things to note: - The `#include ` is critical. The `RC` macro is used to generate the internal storage in the matrix transform, and is actually replaced by a C preprocessor before the final devicetree is compiled into ZMK. - `RC(row, column)` is placed sequentially to define what row and column values that position corresponds to. -- If you have a keyboard with options for `2u` keys in certain positions, or break away portions, it is a good idea to set the chosen `zmk,matrix_transform` to the default arrangement, and include _other_ possible matrix transform nodes in the devicetree that users can select in their user config by overriding the chosen node. +- If you have a keyboard with options for `2u` keys in certain positions, or break away portions, it is a good idea to set the chosen `zmk,matrix-transform` to the default arrangement, and include _other_ possible matrix transform nodes in the devicetree that users can select in their user config by overriding the chosen node. See the [matrix transform section](../config/kscan.md#matrix-transform) in the Keyboard Scan configuration documentation for details and more examples of matrix transforms.