tgrosinger/zmk
1
0
Fork 0
Code Actions Packages

docs: suggest zmk,matrix-transform over zmk,matrix_transform

Browse Source 
* 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.
This commit is contained in:
honorless 2024-01-07 21:15:27 -05:00 committed by Joel Spadin
parent 19613128b9
commit a3fbc2a5ba
4 changed files with 14 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/docs/config/kscan.md
View File

@ -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 {

10
docs/docs/development/boards-shields-keymaps.md
View File

@ -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 <st/f3/stm32f303Xc.dtsi>`.
- 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.

4
docs/docs/development/build-flash.mdx
View File

@ -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:

6
docs/docs/development/new-shield.mdx
View File

@ -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 <dt-bindings/zmk/matrix_transform.h>` 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.