From 8575fc8a9db0b6d75458d160cd4a8a3c9d1e2c71 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Mon, 17 Feb 2025 15:59:54 -0800 Subject: [PATCH] docs: Inline simple physical layout info in new shield guide (#2827) docs: Inline simple physical layouts in new shield guide docs: Fix broken anchor in module creation docs: Make physical layout transform label consistent and comment --- .../hardware-integration/new-shield.mdx | 30 +++++++++++++++++-- .../hardware-integration/physical-layouts.md | 4 +-- docs/docs/development/module-creation.md | 2 +- 3 files changed, 31 insertions(+), 5 deletions(-) diff --git a/docs/docs/development/hardware-integration/new-shield.mdx b/docs/docs/development/hardware-integration/new-shield.mdx index 6ef60c3dd..59a049ccc 100644 --- a/docs/docs/development/hardware-integration/new-shield.mdx +++ b/docs/docs/development/hardware-integration/new-shield.mdx @@ -448,13 +448,39 @@ Also see the [matrix transform section](../../config/layout.md#matrix-transform) ### Physical Layout Your keyboard will need to have a physical layout defined. -Read through our [dedicated page on physical layouts](./physical-layouts.md) for information on how to define a physical layout. -Once you have finished creating your physical layout, you should import the file in which it was created: +Physical layouts organize the matrix transform, kscan and optionally the physical description of key positions in a single entity. + + + + +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 +/ { + physical_layout0: physical_layout_0 { // First physical layout, use different naming for other layouts + compatible = "zmk,physical-layout"; + display-name = "Default Layout"; + kscan = <&kscan0>; // Label of the kscan node, optional if all layouts use the same + transform = <&default_transform>; // Label of the matrix transform for this layout + }; +}; +``` + +These nodes should be placed in `my_keyboard.overlay` for unibody keyboards and the shared `my_keyboard.dtsi` for splits. + + + + +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 #include "my_keyboard-layouts.dtsi" ``` + + + ### Chosen Node Set the `chosen` node to a defined "default" physical layout. This should also be placed in the same file as the physical layout, i.e. `my_keyboard.overlay` for unibodies and `my_keyboard.dtsi` for split keyboards. diff --git a/docs/docs/development/hardware-integration/physical-layouts.md b/docs/docs/development/hardware-integration/physical-layouts.md index eb71fe5bc..281b1c97c 100644 --- a/docs/docs/development/hardware-integration/physical-layouts.md +++ b/docs/docs/development/hardware-integration/physical-layouts.md @@ -30,8 +30,8 @@ Every physical layout needs a matrix transform, and optionally can also have a k ```dts title=".dts | .dtsi | .overlay" &physical_layout0 { - kscan = <&kscan0>; - transform = <&matrix_transform0>; + kscan = <&kscan0>; // Label of the kscan node this layout uses + transform = <&default_transform>; // Label of the matrix transform this layout uses }; ``` diff --git a/docs/docs/development/module-creation.md b/docs/docs/development/module-creation.md index 29cc6c443..17eb157db 100644 --- a/docs/docs/development/module-creation.md +++ b/docs/docs/development/module-creation.md @@ -65,7 +65,7 @@ name: Next, you need to define the options to build your module. These also go into `zephyr/module.yml`, as children of the `build` property. Commonly used options are: -- The `depends` child property is used to specify a list of modules which the module depends on. The dependencies are referred to by their [module name](#module-name). +- The `depends` child property is used to specify a list of modules which the module depends on. The dependencies are referred to by their [module name](#name). - The `cmake` child property is used to identify a folder containing a `CMakeLists.txt` file that lists the CMake commands used to build source files. - The `kconfig` child property is used to identify the `Kconfig` file that defines configuration settings used by the module. - `settings` is a child property containing additional child properties, two of which are particularly relevant: