zmkfirmware
/
zmk
mirror of https://github.com/zmkfirmware/zmk.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: Update Zephyr docs links to 4.1.0 version. 

Update all links to the Zephyr docs to the 4.1.0 versions to match our
Zephyr version in use.
This commit is contained in:
Peter Johanson 2025-10-13 16:59:20 -06:00
parent 33c675a835
commit 2f2f4fe37e
29 changed files with 104 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/docs/config/battery.md
View File

@ -41,7 +41,7 @@ Host support for multiple battery levels is undefined. It appears that in most o
### Devicetree
Applies to: [`/chosen` node](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
Applies to: [`/chosen` node](https://docs.zephyrproject.org/4.1.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
| Property | Type | Description |
| ------------- | ---- | --------------------------------------------- |
@ -55,7 +55,7 @@ Driver for reading the voltage of a battery using an ADC connected to a voltage
Applies to: `compatible = "zmk,battery-voltage-divider"`
See [Zephyr's voltage divider documentation](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/iio/afe/voltage-divider.html).
See [Zephyr's voltage divider documentation](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings/iio/afe/voltage-divider.html).
## nRF VDDH Battery Sensor

4
docs/docs/config/behaviors.md
View File

@ -403,8 +403,8 @@ Applies to: `compatible = "zmk,behavior-input-two-axis"`
| Property | Type | Description | Default |
| ----------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `#binding-cells` | int | Must be `<1>` | |
| `x-input-code` | int | The [relative event code](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245) for generated input events for the X-axis. | |
| `y-input-code` | int | The [relative event code](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245) for generated input events for the Y-axis. | |
| `x-input-code` | int | The [relative event code](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245) for generated input events for the X-axis. | |
| `y-input-code` | int | The [relative event code](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245) for generated input events for the Y-axis. | |
| `trigger-period-ms` | int | How many milliseconds between generated input events based on the current speed/direction. | 16 |
| `delay-ms` | int | How many milliseconds to delay any processing or event generation when first pressed. | 0 |
| `time-to-max-speed-ms` | int | How many milliseconds it takes to accelerate to the curren max speed. | 0 |

10
docs/docs/config/displays.md
View File

@ -53,21 +53,21 @@ You must also configure the driver for your display. ZMK provides the following
- [IL0323](https://github.com/zmkfirmware/zmk/blob/main/app/module/drivers/display/Kconfig.il0323)
Zephyr provides several display drivers as well. Search for the name of your display in [Zephyr's Kconfig options](https://docs.zephyrproject.org/3.5.0/kconfig.html) documentation.
Zephyr provides several display drivers as well. Search for the name of your display in [Zephyr's Kconfig options](https://docs.zephyrproject.org/4.1.0/kconfig.html) documentation.
## Devicetree
See the Devicetree bindings for your display. Here are the bindings for common displays:
- [IL0323](https://github.com/zmkfirmware/zmk/blob/main/app/module/dts/bindings/display/gooddisplay%2Cil0323.yaml)
- [SSD1306 (i2c)](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/display/solomon,ssd1306fb-i2c.html)
- [SSD1306 (spi)](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/display/solomon,ssd1306fb-spi.html)
- [SSD1306 (i2c)](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings/display/solomon,ssd1306fb-i2c.html)
- [SSD1306 (spi)](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings/display/solomon,ssd1306fb-spi.html)
A full list of drivers provided by Zephyr can be found in [Zephyr's Devicetree bindings index](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings.html).
A full list of drivers provided by Zephyr can be found in [Zephyr's Devicetree bindings index](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings.html).
### Chosen nodes
Applies to: [`/chosen` node](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
Applies to: [`/chosen` node](https://docs.zephyrproject.org/4.1.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
| Property | Type | Description |
| ----------------- | ---- | -------------------------------------------------------------------------------------------------------- |

14
docs/docs/config/index.md
View File

@ -37,14 +37,14 @@ ZMK will search for config files in:
...where `<board>` is the name of the board and `<module>` is the root directory of any [included module](../features/modules.mdx). These files describe the hardware of the board.
ZMK will search the board folder for the following config files _in addition_ to [Zephyr board-defining files](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html#create-your-board-directory):
ZMK will search the board folder for the following config files _in addition_ to [Zephyr board-defining files](https://docs.zephyrproject.org/4.1.0/hardware/porting/board_porting.html#create-your-board-directory):
- `<board>.conf` (Kconfig)
- `<board>.keymap` (Devicetree, keyboards with onboard controllers only)
Shared config files (excluding any `_left` or `_right` suffix) are not currently supported in board folders.
For more documentation on creating and configuring a new board, see [Zephyr's board porting guide](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html#write-kconfig-files).
For more documentation on creating and configuring a new board, see [Zephyr's board porting guide](https://docs.zephyrproject.org/4.1.0/hardware/porting/board_porting.html#write-kconfig-files).
### Shield Folder
@ -57,14 +57,14 @@ When building with a shield, ZMK will search for config files in:
...where `<shield>` is the name of the shield and `<module>` is the root directory of any [included module](../features/modules.mdx). These files describe the hardware of the shield that the board is plugged into.
ZMK will search the shield folder for the following config files _in addition_ to [Zephyr shield-defining files](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html#shield-porting-and-configuration):
ZMK will search the shield folder for the following config files _in addition_ to [Zephyr shield-defining files](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html#shield-porting-and-configuration):
- `<shield>.conf` (Kconfig)
- `<shield>.keymap` (Devicetree)
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/3.5.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](../development/hardware-integration/new-shield.mdx) guide.
## Kconfig Files
@ -82,7 +82,7 @@ Files ending with `_defconfig` use the same syntax as `.conf` files. They set th
The list of available settings is determined by various files in ZMK whose names start with `Kconfig`. Note that options are _not_ prefixed with `CONFIG_` in these files.
See [Zephyr's Kconfig documentation](https://docs.zephyrproject.org/3.5.0/build/kconfig/index.html) for more details on Kconfig files.
See [Zephyr's Kconfig documentation](https://docs.zephyrproject.org/4.1.0/build/kconfig/index.html) for more details on Kconfig files.
:::tip
@ -139,7 +139,7 @@ Devicetree files look like this:
Devicetree properties apply to specific nodes in the tree instead of globally. The properties that can be set for each node are determined by `.yaml` files in ZMK in the various `dts/bindings` folders.
See [Zephyr's Devicetree guide](https://docs.zephyrproject.org/3.5.0/build/dts/index.html) for more details on Devicetree files.
See [Zephyr's Devicetree guide](https://docs.zephyrproject.org/4.1.0/build/dts/index.html) for more details on Devicetree files.
:::tip
@ -166,7 +166,7 @@ The part before the colon, `kscan0`, is a label. This is optional, and it provid
The `compatible` property indicates what type of node it is. Search this documentation for the text inside the quotes to see which properties the node
supports. You can also search ZMK for a file whose name is the value of the `compatible` property with a `.yaml` file extension.
To set a property, see below for examples for common property types, or see [Zephyr's Devicetree documentation](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#writing-property-values) for more details on the syntax for properties.
To set a property, see below for examples for common property types, or see [Zephyr's Devicetree documentation](https://docs.zephyrproject.org/4.1.0/build/dts/intro-syntax-structure.html#writing-property-values) for more details on the syntax for properties.
To change a property for an existing node, first find the node you want to change and find its label. Next, outside of any other node, write an ampersand (`&`)
followed by the node's label, an opening curly brace (`{`), one or more new property values, a closing curly brace (`}`), and a semicolon (`;`).

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

@ -25,7 +25,7 @@ If the debounce press/release values are set to any value other than `-1`, they
### Devicetree
Applies to: [`/chosen` node](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
Applies to: [`/chosen` node](https://docs.zephyrproject.org/4.1.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
| Property | Type | Description |
| ---------------------- | ---- | ---------------------------------------------------------------------- |
@ -81,7 +81,7 @@ Definition file: [zmk/app/module/dts/bindings/kscan/zmk,kscan-gpio-direct.yaml](
| `toggle-mode` | bool | Use toggle switch mode | n |
| `wakeup-source` | bool | Mark this kscan instance as able to wake the keyboard | n |
Assuming the switches connect each GPIO pin to the ground, the [GPIO flags](https://docs.zephyrproject.org/3.5.0/hardware/peripherals/gpio.html#api-reference) for the elements in `input-gpios` should be `(GPIO_ACTIVE_LOW | GPIO_PULL_UP)`:
Assuming the switches connect each GPIO pin to the ground, the [GPIO flags](https://docs.zephyrproject.org/4.1.0/hardware/peripherals/gpio.html#api-reference) for the elements in `input-gpios` should be `(GPIO_ACTIVE_LOW | GPIO_PULL_UP)`:
```dts
kscan0: kscan {
@ -151,7 +151,7 @@ The `diode-direction` property must be one of:
| `"row2col"` | Diodes point from rows to columns (cathodes are connected to columns) |
| `"col2row"` | Diodes point from columns to rows (cathodes are connected to rows) |
Given the `diode-direction`, the [GPIO flags](https://docs.zephyrproject.org/3.5.0/hardware/peripherals/gpio.html#api-reference) for the elements in `row-` and `col-gpios` should be set appropriately.
Given the `diode-direction`, the [GPIO flags](https://docs.zephyrproject.org/4.1.0/hardware/peripherals/gpio.html#api-reference) for the elements in `row-` and `col-gpios` should be set appropriately.
The output pins (e.g. columns for `col2row`) should have the flag `GPIO_ACTIVE_HIGH`, and input pins (e.g. rows for `col2row`) should have the flags `(GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)`:
```dts
@ -204,7 +204,7 @@ Define the transform with a [matrix transform](layout.md#matrix-transform). The
For example, in `RC(5,0)` power flows from the 6th pin in `gpios` to the 1st pin in `gpios`.
Exclude all positions where the row and column are the same as these pairs will never be triggered, since no pin can be both input and output at the same time.
The [GPIO flags](https://docs.zephyrproject.org/3.5.0/hardware/peripherals/gpio.html#api-reference) for the elements in `gpios` should be `GPIO_ACTIVE_HIGH`, and interrupt pins set in `interrupt-gpios` should have the flags `(GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)`.
The [GPIO flags](https://docs.zephyrproject.org/4.1.0/hardware/peripherals/gpio.html#api-reference) for the elements in `gpios` should be `GPIO_ACTIVE_HIGH`, and interrupt pins set in `interrupt-gpios` should have the flags `(GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)`.
## Composite Driver

6
docs/docs/config/lighting.md
View File

@ -79,7 +79,7 @@ The `*_START` settings only determine the initial backlight state. Any changes y
### Devicetree
Applies to: [`/chosen` node](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
Applies to: [`/chosen` node](https://docs.zephyrproject.org/4.1.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
| Property | Type | Description |
| --------------- | ---- | -------------------------------------------- |
@ -87,7 +87,7 @@ Applies to: [`/chosen` node](https://docs.zephyrproject.org/3.5.0/build/dts/intr
See the Zephyr devicetree bindings for LED drivers:
- [gpio-leds](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/led/gpio-leds.html)
- [pwm-leds](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/led/pwm-leds.html)
- [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.

2
docs/docs/config/settings.md
View File

@ -3,7 +3,7 @@ title: Persistent Settings
sidebar_label: Settings
---
ZMK uses [Zephyr's settings subsystem](https://docs.zephyrproject.org/3.5.0/services/settings/index.html) to store certain runtime settings in the "storage" partition of the controller's flash memory.
ZMK uses [Zephyr's settings subsystem](https://docs.zephyrproject.org/4.1.0/services/settings/index.html) to store certain runtime settings in the "storage" partition of the controller's flash memory.
These settings will be saved after certain events and loaded on boot.
For instance, bond information for [paired Bluetooth hosts](../features/bluetooth.md) are stored in this partition so that users do not need to pair to each device again after the controller loses power.

6
docs/docs/config/system.md
View File

@ -21,7 +21,7 @@ Definition file: [zmk/app/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/
:::info
Because ZMK enables [the Zephyr setting](https://docs.zephyrproject.org/3.5.0/kconfig.html#CONFIG_BT_DEVICE_NAME_DYNAMIC) that allows for runtime modification of the device BT name,
Because ZMK enables [the Zephyr setting](https://docs.zephyrproject.org/4.1.0/kconfig.html#CONFIG_BT_DEVICE_NAME_DYNAMIC) that allows for runtime modification of the device BT name,
changing `CONFIG_ZMK_KEYBOARD_NAME` requires [clearing the stored settings](./settings.md#clearing-persisted-settings) on the controller in order to take effect.
:::
@ -93,7 +93,7 @@ By default USB Boot protocol support is disabled, however certain situations suc
### Bluetooth
See [Zephyr's Bluetooth stack architecture documentation](https://docs.zephyrproject.org/3.5.0/connectivity/bluetooth/bluetooth-arch.html)
See [Zephyr's Bluetooth stack architecture documentation](https://docs.zephyrproject.org/4.1.0/connectivity/bluetooth/bluetooth-arch.html)
for more information on configuring Bluetooth.
| Config | Type | Description | Default |
@ -139,7 +139,7 @@ The only way to restore functionality after that is to re-flash the bootloader.
Re-flashing a bootloader built without the SoftDevice will require firmware built with these snippets.
:::
[Snippets](https://docs.zephyrproject.org/3.5.0/build/snippets/index.html) are a way to save common configuration separately when it applies to multiple different applications.
[Snippets](https://docs.zephyrproject.org/4.1.0/build/snippets/index.html) are a way to save common configuration separately when it applies to multiple different applications.
Enable snippets by adding `snippet: <snippet>` to your `build.yaml` for the appropriate board:

10
docs/docs/development/devicetree.md
View File

@ -70,7 +70,7 @@ What properties a node may have varies drastically. Of the standard properties,
#### Property types
These are some of the property types you will see most often when working with ZMK. [Zephyr's Devicetree bindings documentation](https://docs.zephyrproject.org/3.5.0/build/dts/bindings.html) provides more detailed information and a full list of types.
These are some of the property types you will see most often when working with ZMK. [Zephyr's Devicetree bindings documentation](https://docs.zephyrproject.org/4.1.0/build/dts/bindings.html) provides more detailed information and a full list of types.
##### bool
@ -124,14 +124,14 @@ Example: `property = <&none &mo 1>;`
Values can also be split into multiple blocks, e.g. `property = <&none>, <&mo 1>;`
See the documentation for "phandle-array" in [Zephyr's Devicetree bindings documentation](https://docs.zephyrproject.org/3.5.0/build/dts/bindings.html)
See the documentation for "phandle-array" in [Zephyr's Devicetree bindings documentation](https://docs.zephyrproject.org/4.1.0/build/dts/bindings.html)
for more details on how parameters are associated with nodes.
##### GPIO array
This is just a phandle array. The documentation lists this as a different type to make it clear which properties expect an array of GPIOs.
Each item in the array should be a label for a GPIO node (the names of which differ between hardware platforms) followed by an index and configuration flags. See [Zephyr's GPIO documentation](https://docs.zephyrproject.org/3.5.0/hardware/peripherals/gpio.html) for a full list of flags. Phandles and labels will be explained in more detail in a [later section](#labels-and-phandles).
Each item in the array should be a label for a GPIO node (the names of which differ between hardware platforms) followed by an index and configuration flags. See [Zephyr's GPIO documentation](https://docs.zephyrproject.org/4.1.0/hardware/peripherals/gpio.html) for a full list of flags. Phandles and labels will be explained in more detail in a [later section](#labels-and-phandles).
Example:
@ -187,7 +187,7 @@ properties:
required: false
```
The properties the node can have are listed under `properties`. Some additional properties are imported from [zero_param.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zero_param.yaml). Bindings files are **the authority** on node properties, with our [documentation of said properties](https://zmk.dev/docs/config/behaviors#devicetree-7) sometimes omitting things like the `#binding-cells` property (imported from the previously mentioned file, describing the number of parameters that the behavior accepts). A full description of the bindings file syntax can be found in [Zephyr's documentation](https://docs.zephyrproject.org/3.5.0/build/dts/bindings-syntax.html).
The properties the node can have are listed under `properties`. Some additional properties are imported from [zero_param.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zero_param.yaml). Bindings files are **the authority** on node properties, with our [documentation of said properties](https://zmk.dev/docs/config/behaviors#devicetree-7) sometimes omitting things like the `#binding-cells` property (imported from the previously mentioned file, describing the number of parameters that the behavior accepts). A full description of the bindings file syntax can be found in [Zephyr's documentation](https://docs.zephyrproject.org/4.1.0/build/dts/bindings-syntax.html).
Note that binding files can also specify properties for children, like the [`zmk,keymap.yaml` bindings file](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/zmk%2Ckeymap.yaml) specifying properties for layers in the keymap.
@ -260,7 +260,7 @@ A devicetree is almost always constructed from multiple files. These files are g
- `.dtsi` files, which exist exclusively to be included via the C preprocessor (their contents get "pasted" at the location of the `#include` command) and are not used by the build sytem otherwise.
- A `.dts` file, which forms the "base" of the devicetree. A single one of these is always present when a devicetree is constructed. For ZMK, the `.dts` file contains the sections of the devicetree describing the [_board_](hardware-integration/index.mdx#what-is-a-board). This includes importing a number of `.dtsi` files describing the specific SoC that the board uses.
- Any number of `.overlay` files. These files can come from various sources, such as [shields](hardware-integration/index.mdx#what-is-a-shield) or [snippets](https://docs.zephyrproject.org/3.5.0/build/snippets/index.html). An overlay is applied to a `.dts` file by appending its contents to the end of the `.dts` file, i.e. it is placed at the bottom of the file. Multiple overlays are applied by doing so repeatedly in a particular order. Without going into the details of the exact order in which overlays are applied, it is enough to know that if you specify e.g. `shield: corne_left nice_view_adapter nice_view` in your `build.yaml`, then the overlays are applied left to right.
- Any number of `.overlay` files. These files can come from various sources, such as [shields](hardware-integration/index.mdx#what-is-a-shield) or [snippets](https://docs.zephyrproject.org/4.1.0/build/snippets/index.html). An overlay is applied to a `.dts` file by appending its contents to the end of the `.dts` file, i.e. it is placed at the bottom of the file. Multiple overlays are applied by doing so repeatedly in a particular order. Without going into the details of the exact order in which overlays are applied, it is enough to know that if you specify e.g. `shield: corne_left nice_view_adapter nice_view` in your `build.yaml`, then the overlays are applied left to right.
- A single `.keymap` file. This file being included is ZMK-specific, and is treated as the "final" `.overlay` file, appended after all other overlays.
#### Merging and overwriting nodes

14
docs/docs/development/hardware-integration/index.mdx
View File

@ -23,7 +23,7 @@ These core architectural elements are defined per-keyboard, and _where_ they are
## Boards & Shields
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.
Also see the Zephyr documentation on [boards](https://docs.zephyrproject.org/3.5.0/glossary.html#term-board) and [shields](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html).
Also see the Zephyr documentation on [boards](https://docs.zephyrproject.org/4.1.0/glossary.html#term-board) and [shields](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html).
### What is a "board"?
@ -84,9 +84,9 @@ In that directory you'll have the following files, where there can be multiples
└── <keyboard_name>.zmk.yml
```
These files include [base Kconfig files](https://docs.zephyrproject.org/3.5.0/build/kconfig/index.html):
These files include [base Kconfig files](https://docs.zephyrproject.org/4.1.0/build/kconfig/index.html):
- A `Kconfig.board` file that defines the toplevel [Kconfig](https://docs.zephyrproject.org/3.5.0/build/kconfig/index.html) items for the board, including which SoC Kconfig setting it depends on.
- A `Kconfig.board` file that defines the toplevel [Kconfig](https://docs.zephyrproject.org/4.1.0/build/kconfig/index.html) items for the board, including which SoC Kconfig setting it depends on.
- 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_USB`](../../config/system.md#usb) and/or [`ZMK_BLE`](../../config/system.md#bluetooth) for the default values for which HID transport(s) to enable by default
@ -101,7 +101,7 @@ These files include [base Kconfig files](https://docs.zephyrproject.org/3.5.0/bu
- `<board_name>.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 <st/f3/stm32f303Xc.dtsi>`,
- Kscan, matrix transform and physical layout devicetree nodes as described above,
- A [chosen](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes) node including `zmk,physical-layout` property among others, where each property references the nodes defined in the file.
- A [chosen](https://docs.zephyrproject.org/4.1.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes) node including `zmk,physical-layout` property among others, where each property references the nodes defined in the file.
- A `<keyboard_name>.keymap` file that includes the default keymap for that keyboard. Users will be able to override this keymap in their user configs.
And other miscellaneous ones:
@ -109,7 +109,7 @@ And other miscellaneous ones:
- A `board.cmake` file with CMake directives for how to flash to the device.
- A `<keyboard_name>.zmk.yml` file containing [metadata](hardware-metadata-files.md) for the keyboard.
See Zephyr's [board porting guide](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html) for information on creating a new board.
See Zephyr's [board porting guide](https://docs.zephyrproject.org/4.1.0/hardware/porting/board_porting.html) for information on creating a new board.
Also see the [new keyboard shield guide](new-shield.mdx#shield-overlays) for information on parts of the devicetree specifically related to ZMK.
[^1]:
@ -142,8 +142,8 @@ These files include [base Kconfig files](new-shield.mdx#base-kconfig-files):
[Devicetree files](../../config/index.md#devicetree-files):
- A `<shield_name>.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/3.5.0/hardware/porting/shields.html#gpio-nexus-nodes) aliases such as `&pro_micro` for GPIO pins.
- A [chosen](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes) node including at least the `zmk,physical-layout` property, referring to the defined node.
- 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.
- A [chosen](https://docs.zephyrproject.org/4.1.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes) node including at least the `zmk,physical-layout` property, referring to the defined node.
- A `<keyboard_name>.keymap` file that includes the default keymap for that keyboard. Users will be able to override this keymap in their user configs.
And other miscellaneous ones:

4
docs/docs/development/hardware-integration/new-shield.mdx
View File

@ -61,7 +61,7 @@ The high level steps are:
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/3.5.0/hardware/porting/shields.html#shields) to get a proper understanding of the underlying system before continuing.
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.
## New ZMK Module Repository
@ -106,7 +106,7 @@ mkdir boards/shields/<keyboard_name>
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/3.5.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`.
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`.
<SplitTabs></SplitTabs>

8
docs/docs/development/hardware-integration/pinctrl.mdx
View File

@ -9,13 +9,13 @@ import InterconnectTabs from "@site/src/components/interconnect-tabs";
import Metadata from "@site/src/data/hardware-metadata.json";
:::info
This page exists to provide a guide to [Pin Control](https://docs.zephyrproject.org/3.5.0/hardware/pinctrl/index.html#pin-control) for ZMK users and designers. Refer to [Zephyr's page on Pin Control](https://docs.zephyrproject.org/3.5.0/hardware/pinctrl/index.html#pin-control) for elaboration and more details on any of the points raised here.
This page exists to provide a guide to [Pin Control](https://docs.zephyrproject.org/4.1.0/hardware/pinctrl/index.html#pin-control) for ZMK users and designers. Refer to [Zephyr's page on Pin Control](https://docs.zephyrproject.org/4.1.0/hardware/pinctrl/index.html#pin-control) for elaboration and more details on any of the points raised here.
:::
A basic keyboard design as introduced in the [new shield guide](./new-shield.mdx) only uses its pins for the keyboard matrix. Many keyboard designs make use of advanced components or functionality, such as displays or shift registers. This results in the keyboard making use of communication protocols such as (but not limited to) SPI, I2C, or UART. Configuring pins for the usage of advanced functionality such as drivers for the previously named protocols is referred to as "Pin Control".
:::warning
The details of pin control can vary from vendor to vendor. An attempt was made to be as general as possible, but it isn't possible to cover all possible cases. The approaches for the nRF52840 and RP2040 MCUs/SoCs are documented in their entirety below. For other MCUs/SoCs, please refer to the [Zephyr documentation](https://docs.zephyrproject.org/3.5.0/index.html) and the examples and other files found in-tree of [ZMK](https://github.com/zmkfirmware/zmk/tree/main/app/boards) and [ZMK's fork of Zephyr](https://github.com/zmkfirmware/zephyr).
The details of pin control can vary from vendor to vendor. An attempt was made to be as general as possible, but it isn't possible to cover all possible cases. The approaches for the nRF52840 and RP2040 MCUs/SoCs are documented in their entirety below. For other MCUs/SoCs, please refer to the [Zephyr documentation](https://docs.zephyrproject.org/4.1.0/index.html) and the examples and other files found in-tree of [ZMK](https://github.com/zmkfirmware/zmk/tree/main/app/boards) and [ZMK's fork of Zephyr](https://github.com/zmkfirmware/zephyr).
:::
## Boards, Shields, and Modules
@ -110,7 +110,7 @@ All of your configuration will happen by adjusting the `pinctrl` node. Changes a
Within said node, you will configure one or more child nodes for the buses. You will want to define the child nodes according to the instructions in the `pinctrl.yaml` file.
The child nodes that you define should be named appropriately. The common naming schema is `usageNumber_state`. For example, `uart0_default`.
Child nodes are (generally, there are [exceptions](https://docs.zephyrproject.org/3.5.0/hardware/pinctrl/index.html#pin-configuration)) expected to contain one or more subnodes typically named "groupX". These are for grouping together pins that should be assigned the same state, such as enabling an internal pull-up.
Child nodes are (generally, there are [exceptions](https://docs.zephyrproject.org/4.1.0/hardware/pinctrl/index.html#pin-configuration)) expected to contain one or more subnodes typically named "groupX". These are for grouping together pins that should be assigned the same state, such as enabling an internal pull-up.
Below are some examples of SPI child nodes for the nRF52840 and the RP2040. Further examples are contained within the comments of the respecting `pinctrl.yaml` files.
<Tabs
@ -281,7 +281,7 @@ Once you have defined your node, you make use of it by further adjusting the nod
};
```
You would then want to make any adjustments to the node that are necessary, for example adjusting the clock speed. See the Zephyr API documentation for your `compatible` property to see the available properties for customisation. It is recommended to read through the [description of important properties](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#dt-important-props), potentially with the addition of [this blog post](https://interrupt.memfault.com/blog/practical_zephyr_dt#zephyrs-dts-skeleton-and-addressing) if `#address-cells` is confusing you.
You would then want to make any adjustments to the node that are necessary, for example adjusting the clock speed. See the Zephyr API documentation for your `compatible` property to see the available properties for customisation. It is recommended to read through the [description of important properties](https://docs.zephyrproject.org/4.1.0/build/dts/intro-syntax-structure.html#dt-important-props), potentially with the addition of [this blog post](https://interrupt.memfault.com/blog/practical_zephyr_dt#zephyrs-dts-skeleton-and-addressing) if `#address-cells` is confusing you.
For SPI specifically, you would create a child node within your SPI bus for each device making use of the SPI bus.

10
docs/docs/development/hardware-integration/pointing.mdx
View File

@ -6,7 +6,7 @@ toc_max_heading_level: 2
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/3.5.0/services/input/index.html) to offer pointing/mouse functionality with various hardware.
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.
Pointing devices are also supported on split peripherals, with some additional configuration using the [input split device](../../config/pointing.md#input-split).
@ -42,17 +42,17 @@ This node should always be set up in the `.overlay`/`.dts` file for the keyboard
<SplitTabs>
<TabItem value="unibody">
For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml), a node like following would be added to the `.overlay`/`.dts` file for the keyboard, like `<keyboard>.overlay`:
For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml), a node like following would be added to the `.overlay`/`.dts` file for the keyboard, like `<keyboard>.overlay`:
</TabItem>
<TabItem value="central">
For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml) on a central part, a node like following would be added to the `.overlay`/`.dts` file for the central part of the keyboard, like `<central>.overlay`:
For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml) on a central part, a node like following would be added to the `.overlay`/`.dts` file for the central part of the keyboard, like `<central>.overlay`:
</TabItem>
<TabItem value="peripheral">
For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml) on one of the peripheral parts, a node like following would be added to the `.overlay`/`.dts` file for that peripheral part, like `<peripheral>.overlay`:
For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml) on one of the peripheral parts, a node like following would be added to the `.overlay`/`.dts` file for that peripheral part, like `<peripheral>.overlay`:
</TabItem>
</SplitTabs>
@ -264,7 +264,7 @@ As an example, you could enhance the listener defined in the previous section wi
## Configuration Setting
If your keyboard hardware includes a pointing device by default, you can enable the [`ZMK_POINTING` config](../../config/pointing.md#general) in your keyboard definition.
You can do that in your [`Kconfig.defconfig` file](new-shield.mdx#kconfigdefconfig), where you can also enable the config for the communication protocol (e.g. [SPI](https://docs.zephyrproject.org/3.5.0/kconfig.html#CONFIG_SPI), [I2C](https://docs.zephyrproject.org/3.5.0/hardware/peripherals/i2c.html#configuration-options)) used by the pointing device:
You can do that in your [`Kconfig.defconfig` file](new-shield.mdx#kconfigdefconfig), where you can also enable the config for the communication protocol (e.g. [SPI](https://docs.zephyrproject.org/4.1.0/kconfig.html#CONFIG_SPI), [I2C](https://docs.zephyrproject.org/4.1.0/hardware/peripherals/i2c.html#configuration-options)) used by the pointing device:
<SplitTabs>
<TabItem value="unibody">

4
docs/docs/development/hardware-integration/soft-off-setup.mdx
View File

@ -75,7 +75,7 @@ For this approach, you will need to make sure that the [soft off behavior](../..
### GPIO key
Zephyr's basic [GPIO Key](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/input/gpio-keys.html) concept is used to configure the soft off GPIO pin.
Zephyr's basic [GPIO Key](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings/input/gpio-keys.html) concept is used to configure the soft off GPIO pin.
{/* secrettabs hides this tab selector. GPIO key changes its "orientation" between simple pin and matrix integrated. */}
<Tabs
@ -97,7 +97,7 @@ Zephyr's basic [GPIO Key](https://docs.zephyrproject.org/3.5.0/build/dts/api/bin
GPIO keys are defined using child nodes under the `gpio-keys` compatible node. Each child needs just one property defined:
- The `gpios` property should be a [phandle-array](https://docs.zephyrproject.org/3.5.0/build/dts/phandles.html#zero-or-more-nodes-with-metadata-phandle-array-type) with a fully defined GPIO pin and with the correct pull up/down and active high/low flags set.
- The `gpios` property should be a [phandle-array](https://docs.zephyrproject.org/4.1.0/build/dts/phandles.html#zero-or-more-nodes-with-metadata-phandle-array-type) with a fully defined GPIO pin and with the correct pull up/down and active high/low flags set.
<Tabs
groupId="advanced-methods"

12
docs/docs/development/local-toolchain/build-flash.mdx
View File

@ -21,7 +21,7 @@ If this is not done, you will encounter errors such as: `ERROR: source directory
## Building
Building a particular keyboard is done using the
[`west build`](https://docs.zephyrproject.org/3.5.0/develop/west/build-flash-debug.html#building-west-build)
[`west build`](https://docs.zephyrproject.org/4.1.0/develop/west/build-flash-debug.html#building-west-build)
command. Its usage slightly changes depending on if your build is for a keyboard
with an onboard MCU or one that uses an MCU board add-on.
@ -32,7 +32,7 @@ with an onboard MCU or one that uses an MCU board add-on.
]}>
<TabItem value="onboardMcu">
Keyboards with onboard MCU chips are simply treated as the
[board](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html)
[board](https://docs.zephyrproject.org/4.1.0/hardware/porting/board_porting.html)
as far as Zephyr™ is concerned.
Given the following:
@ -49,9 +49,9 @@ with an onboard MCU or one that uses an MCU board add-on.
</TabItem>
<TabItem value="addonMcu">
ZMK treats keyboards that take an MCU addon board as
[shields](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html),
[shields](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html),
and treats the smaller MCU board as the true
[board](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html).
[board](https://docs.zephyrproject.org/4.1.0/hardware/porting/board_porting.html).
Given the following:
@ -94,7 +94,7 @@ west build -d <build_dir>
:::
You can also add permanent CMake arguments to `west build` by using the
[`west config`](https://docs.zephyrproject.org/3.5.0/develop/west/config.html#west-config-cmd)
[`west config`](https://docs.zephyrproject.org/4.1.0/develop/west/config.html#west-config-cmd)
command. These are invoked whenever a new build system is generated. To add
permanent arguments, set the `build.cmake-args` configuration option.
@ -198,7 +198,7 @@ west flash
## Multi-CPU and Dual-Chip Bluetooth Boards
Zephyr supports running the Bluetooth host and controller on separate processors. In such a configuration, ZMK always runs on the host processor, but you may need to build and flash separate firmware for the controller. Zephyr provides sample code which can be used as the controller firmware for Bluetooth HCI over [RPMsg](https://docs.zephyrproject.org/3.5.0/samples/bluetooth/hci_rpmsg/README.html), [SPI](https://docs.zephyrproject.org/3.5.0/samples/bluetooth/hci_spi/README.html), [UART](https://docs.zephyrproject.org/3.5.0/samples/bluetooth/hci_uart/README.html), and [USB](https://docs.zephyrproject.org/3.5.0/samples/bluetooth/hci_usb/README.html). See [Zephyr's Bluetooth Stack Architecture documentation](https://docs.zephyrproject.org/3.5.0/connectivity/bluetooth/bluetooth-arch.html) for more details.
Zephyr supports running the Bluetooth host and controller on separate processors. In such a configuration, ZMK always runs on the host processor, but you may need to build and flash separate firmware for the controller. Zephyr provides sample code which can be used as the controller firmware for Bluetooth HCI over [RPMsg](https://docs.zephyrproject.org/4.1.0/samples/bluetooth/hci_rpmsg/README.html), [SPI](https://docs.zephyrproject.org/4.1.0/samples/bluetooth/hci_spi/README.html), [UART](https://docs.zephyrproject.org/4.1.0/samples/bluetooth/hci_uart/README.html), and [USB](https://docs.zephyrproject.org/4.1.0/samples/bluetooth/hci_usb/README.html). See [Zephyr's Bluetooth Stack Architecture documentation](https://docs.zephyrproject.org/4.1.0/connectivity/bluetooth/bluetooth-arch.html) for more details.
The following documentation shows how to build and flash ZMK for boards that use a dual-chip configuration.

20
docs/docs/development/local-toolchain/setup/native.mdx
View File

@ -73,13 +73,13 @@ export const WinTermTabs = (props) => (
## 1. Install Zephyr Dependencies
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections:
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/4.1.0/develop/getting_started/index.html) and follow the instructions under these sections:
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
- [Select and Update OS](https://docs.zephyrproject.org/4.1.0/develop/getting_started/index.html#select-and-update-os)
- [Install Dependencies](https://docs.zephyrproject.org/4.1.0/develop/getting_started/index.html#install-dependencies)
:::info
Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/installation_linux.html) page may be of use for users of Linux distributions which are not based on Ubuntu.
Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/4.1.0/develop/getting_started/installation_linux.html) page may be of use for users of Linux distributions which are not based on Ubuntu.
:::
## 2. Source Code
@ -99,7 +99,7 @@ cd zmk
## 3. Get Zephyr and install Python dependencies
:::note
These steps are very similar to Zephyr's [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies) instructions, but specialized for ZMK.
These steps are very similar to Zephyr's [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/4.1.0/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies) instructions, but specialized for ZMK.
:::
<EnvTabs>
@ -191,7 +191,7 @@ west update
This step pulls down quite a bit of tooling, be patient!
:::
6. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
6. Export a [Zephyr CMake package](https://docs.zephyrproject.org/4.1.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
```sh
west zephyr-export
@ -280,7 +280,7 @@ west update
This step pulls down quite a bit of tooling, be patient!
:::
3. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
3. Export a [Zephyr CMake package](https://docs.zephyrproject.org/4.1.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
```sh
west zephyr-export
@ -321,7 +321,7 @@ west packages pip --install
## 4. Install Zephyr SDK
Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk).
Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.zephyrproject.org/4.1.0/develop/getting_started/index.html#install-zephyr-sdk).
### OS-Specific Notes
@ -336,7 +336,7 @@ Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.z
<TabItem value="raspberryos">
#### Install cross-compile toolchain
Because Raspberry OS runs on the same architecture (but different ABI) as ARM keyboard MCUs, the operating system's installed [cross compilers](https://docs.zephyrproject.org/3.5.0/develop/toolchains/other_x_compilers.html) can be used to target the different ABI. Building for non-ARM MCUs has not been tested.
Because Raspberry OS runs on the same architecture (but different ABI) as ARM keyboard MCUs, the operating system's installed [cross compilers](https://docs.zephyrproject.org/4.1.0/develop/toolchains/other_x_compilers.html) can be used to target the different ABI. Building for non-ARM MCUs has not been tested.
First, the cross compiler should be installed:
@ -344,7 +344,7 @@ First, the cross compiler should be installed:
sudo apt install gcc-arm-none-eabi
```
Next, we'll configure Zephyr with some [environment variables](https://docs.zephyrproject.org/3.5.0/develop/env_vars.html#env-vars) needed to find the cross compiler. Create a file named `~/.zephyrrc` if it doesn't exist, and add these lines to it:
Next, we'll configure Zephyr with some [environment variables](https://docs.zephyrproject.org/4.1.0/develop/env_vars.html#env-vars) needed to find the cross compiler. Create a file named `~/.zephyrrc` if it doesn't exist, and add these lines to it:
```sh
export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile

8
docs/docs/development/module-creation.md
View File

@ -10,7 +10,7 @@ sidebar_label: ZMK Module Creation
- Modules containing drivers
- Modules containing other features, such as visual effects
See also Zephyr's [page on modules](https://docs.zephyrproject.org/3.5.0/develop/modules.html).
See also Zephyr's [page on modules](https://docs.zephyrproject.org/4.1.0/develop/modules.html).
:::tip
For open source hardware designs, it can be convenient to use [Git submodules](https://github.blog/open-source/git/working-with-submodules/) to have the ZMK module also be a Git submodule of the repository hosting the hardware design.
@ -71,13 +71,13 @@ Next, you need to define the options to build your module. These also go into `z
- `settings` is a child property containing additional child properties, two of which are particularly relevant:
- `board_root` points to the parent directory of a `boards` directory, which contains additional board/shield definitions.
- `dts_root` points to the parent directory of a `dts` directory, which contains additional devicetree bindings.
- `snippet_root` points to the parent directory of a `snippets` directory, which contains [snippets](https://docs.zephyrproject.org/3.5.0/build/snippets/index.html).
- `snippet_root` points to the parent directory of a `snippets` directory, which contains [snippets](https://docs.zephyrproject.org/4.1.0/build/snippets/index.html).
See the `zephyr/module.yml` found in the template for a usage example.
### Dependencies
If `zephyr/module.yml` has anything listed under `depends`, then you should also define a [west manifest](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html) file. While the `zephyr/module.yml` file defines _which_ modules your module depends on, the west manifest file defines _where_ said modules are found. This then allows automatic tooling to fetch the modules when building firmware. If `depends` is not present in `zephyr/module.yml`, then this file (named `west.yml` in the template) should be removed.
If `zephyr/module.yml` has anything listed under `depends`, then you should also define a [west manifest](https://docs.zephyrproject.org/4.1.0/develop/west/manifest.html) file. While the `zephyr/module.yml` file defines _which_ modules your module depends on, the west manifest file defines _where_ said modules are found. This then allows automatic tooling to fetch the modules when building firmware. If `depends` is not present in `zephyr/module.yml`, then this file (named `west.yml` in the template) should be removed.
It is recommended that you place the manifest file at the root of your module, though you can place it elsewhere. Be sure to note in your `README.md` that your module uses dependencies, so that users import these correctly.
Below is an example `west.yml` file for a user that would be using your module, with the necessary `import` field if the module has dependencies:
@ -126,7 +126,7 @@ The below table reminds of the purpose of each of these files and folders, if yo
| `Kconfig` | Kconfig file for the module |
| `include/` | Folder for C header files |
| `src/` | Folder for C source files |
| `snippets/` | Folder for [snippets](https://docs.zephyrproject.org/3.5.0/build/snippets/index.html) |
| `snippets/` | Folder for [snippets](https://docs.zephyrproject.org/4.1.0/build/snippets/index.html) |
Note that the `include` and `src` folders are not mandated by the module system, and all of these can be positioned anywhere in your module's filetree if you adjust the `zephyr/module.yml` accordingly. The `west.yml` file is not commonly present in any of the types.

14
docs/docs/development/new-behavior.mdx
View File

@ -39,8 +39,8 @@ Before developing new behaviors, developers should have a working knowledge of t
The following resources are provided for those seeking further understanding:
- [Embedded Linux Wiki - Device Tree Usage](https://elinux.org/Device_Tree_Usage)
- [Zephyr Devicetree API](https://docs.zephyrproject.org/3.5.0/build/dts/api/api.html)
- [Zephyr Device Driver Model](https://docs.zephyrproject.org/3.5.0/kernel/drivers/index.html)
- [Zephyr Devicetree API](https://docs.zephyrproject.org/4.1.0/build/dts/api/api.html)
- [Zephyr Device Driver Model](https://docs.zephyrproject.org/4.1.0/kernel/drivers/index.html)
:::
@ -174,7 +174,7 @@ See [Behavior Metadata](#behavior-metadata) for more information.
#### `properties` (Optional)
These are additional variables required to configure a particular instance of a behavior.
More information can be found in [ZMK's Devicetree primer](./devicetree.md) or [Zephyr's own documentation on Devicetree bindings](https://docs.zephyrproject.org/3.5.0/build/dts/bindings-syntax.html#properties).
More information can be found in [ZMK's Devicetree primer](./devicetree.md) or [Zephyr's own documentation on Devicetree bindings](https://docs.zephyrproject.org/4.1.0/build/dts/bindings-syntax.html#properties).
### Behavior Source Files (`.c`)
@ -497,8 +497,8 @@ We will review the components from the [behavior source templates](#behavior-sou
Developing drivers for behaviors in ZMK makes extensive use of the Zephyr Devicetree API and Device Driver Model.
Links to the Zephyr Project Documentation for both of these concepts can be found below:
- [Zephyr Devicetree API](https://docs.zephyrproject.org/3.5.0/build/dts/api/api.html)
- [Zephyr Device Driver Model](https://docs.zephyrproject.org/3.5.0/kernel/drivers/index.html)
- [Zephyr Devicetree API](https://docs.zephyrproject.org/4.1.0/build/dts/api/api.html)
- [Zephyr Device Driver Model](https://docs.zephyrproject.org/4.1.0/kernel/drivers/index.html)
:::
@ -672,7 +672,7 @@ The API struct's metadata-specific fields are shown below.
`BEHAVIOR_DT_INST_DEFINE` is a special ZMK macro which uses Zephyr's `DEVICE_DT_INST_DEFINE` macro to define the driver instance, before adding it to a list of ZMK behaviors so that can be found by the function `zmk_behavior_get_binding()`.
:::info
For more information on this function, refer to [Zephyr's documentation on the Device Driver Model](https://docs.zephyrproject.org/3.5.0/kernel/drivers/index.html#c.DEVICE_DT_INST_DEFINE).
For more information on this function, refer to [Zephyr's documentation on the Device Driver Model](https://docs.zephyrproject.org/4.1.0/kernel/drivers/index.html#c.DEVICE_DT_INST_DEFINE).
:::
The example `BEHAVIOR_DT_INST_DEFINE` call can be left as is with the first parameter, the instance number, equal to `0` for behaviors that only require a single instance (e.g. external power, backlighting, accessing layers).
@ -730,7 +730,7 @@ The **fourth** argument of `BEHAVIOR_DT_INST_DEFINE` can be set to `NULL` instea
#### Optional: Configuration pointers
The configuration `struct` stores the properties declared from the behavior's `.yaml` for **each new instance** of the behavior.
As seen in the `#define KP_INST(n)` of the hold-tap example, the configuration `struct`, `behavior_<name_of_behavior>_config_##n`, for each instance number, `n`, can be initialized using the [Zephyr Devicetree Instance-based APIs](https://docs.zephyrproject.org/3.5.0/build/dts/api/api.html#instance-based-apis),
As seen in the `#define KP_INST(n)` of the hold-tap example, the configuration `struct`, `behavior_<name_of_behavior>_config_##n`, for each instance number, `n`, can be initialized using the [Zephyr Devicetree Instance-based APIs](https://docs.zephyrproject.org/4.1.0/build/dts/api/api.html#instance-based-apis),
which extract the values from the `properties` of each instance of the [devicetree binding](#devicetree-bindings-yaml) from a user's keymap or [predefined use-case `.dtsi` files](#optional-defining-common-use-cases-for-the-behavior-dtsi) stored in `app/dts/behaviors/`.
We illustrate this further by comparing the [`#define KP_INST(n)` from the hold-tap driver](#invoking-behavior_dt_inst_define) and the [`properties` of the hold-tap devicetree binding](#devicetree-bindings-yaml).
The config structure instances should always be declared `const`

4
docs/docs/development/usb-logging.mdx
View File

@ -41,7 +41,7 @@ west build -b nice_nano_v2 -S zmk-usb-logging -- -DSHIELD="corne_left"
### Additional Config
Logging can be further configured using Kconfig described in [the Zephyr documentation](https://docs.zephyrproject.org/3.5.0/services/logging/index.html).
Logging can be further configured using Kconfig described in [the Zephyr documentation](https://docs.zephyrproject.org/4.1.0/services/logging/index.html).
For instance, setting `CONFIG_LOG_PROCESS_THREAD_STARTUP_DELAY_MS` to a large value such as `8000` might help catch issues that happen near keyboard
boot, before you can connect to view the logs.
@ -103,7 +103,7 @@ From there, you should see the various log messages from ZMK and Zephyr, dependi
Standard boards such as the nice!nano and Seeed Studio XIAO family have the necessary configuration for logging already added, however if you are developing your own standalone board you may wish to add the ability to use USB logging in the future.
To do so, you need to follow the upstream Zephyr [`cdc-acm-console` snippet requirements](https://docs.zephyrproject.org/3.5.0/snippets/cdc-acm-console/README.html#requirements) steps.
To do so, you need to follow the upstream Zephyr [`cdc-acm-console` snippet requirements](https://docs.zephyrproject.org/4.1.0/snippets/cdc-acm-console/README.html#requirements) steps.
Usually, this just requires ensuring that the USB node has been tagged with the `zephyr_udc0` label, e.g.

8
docs/docs/faq.md
View File

@ -7,10 +7,10 @@ sidebar_label: FAQs
As a best-in-class RTOS, Zephyr™ brings many [benefits](https://www.zephyrproject.org/benefits) to ZMK, such as:
- A _single_ platform [supporting](https://docs.zephyrproject.org/3.5.0/boards/index.html) many architectures, processors and boards.
- A _single_ platform [supporting](https://docs.zephyrproject.org/4.1.0/boards/index.html) many architectures, processors and boards.
- Optimization for low-powered, small memory footprint devices.
- Powerful hardware abstraction and configuration using [DeviceTree](https://docs.zephyrproject.org/3.5.0/build/dts/index.html) and [Kconfig](https://docs.zephyrproject.org/3.5.0/build/kconfig/index.html).
- A BLE stack that periodically obtains [qualification](https://docs.zephyrproject.org/3.5.0/connectivity/bluetooth/bluetooth-qual.html) listings, making it easier for final products to obtain qualification from the Bluetooth® SIG.
- Powerful hardware abstraction and configuration using [DeviceTree](https://docs.zephyrproject.org/4.1.0/build/dts/index.html) and [Kconfig](https://docs.zephyrproject.org/4.1.0/build/kconfig/index.html).
- A BLE stack that periodically obtains [qualification](https://docs.zephyrproject.org/4.1.0/connectivity/bluetooth/bluetooth-qual.html) listings, making it easier for final products to obtain qualification from the Bluetooth® SIG.
- Multi-processor support, which is critical for power efficiency in upcoming MCUs.
- Permissive licensing with its Apache 2.0 open source [license](https://www.apache.org/licenses/LICENSE-2.0).
- A buzzing developer [community](https://github.com/zephyrproject-rtos/zephyr) including many leading [embedded technology](https://www.zephyrproject.org/project-members) companies.
@ -37,7 +37,7 @@ ZMK uses the MIT [license](https://github.com/zmkfirmware/zmk/blob/main/LICENSE)
ZMK has the potential to run on any platform supported by Zephyr™. However, it’s impractical for the ZMK contributors to test all possible hardware.
The Zephyr™ [documentation](https://docs.zephyrproject.org/3.5.0/boards/index.html) describes which hardware is currently natively supported by the Zephyr™ platform. _Similar documentation covering which keyboards have been integrated into ZMK is currently being planned._
The Zephyr™ [documentation](https://docs.zephyrproject.org/4.1.0/boards/index.html) describes which hardware is currently natively supported by the Zephyr™ platform. _Similar documentation covering which keyboards have been integrated into ZMK is currently being planned._
### Does ZMK compile for AVR?

8
docs/docs/features/modules.mdx
View File

@ -6,7 +6,7 @@ sidebar_label: Modules
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
ZMK makes use of [Zephyr modules](https://docs.zephyrproject.org/3.5.0/develop/modules.html) to include additional source code or configuration files into its build. You can think of them as similar to plugins or themes. The most common uses of this feature are:
ZMK makes use of [Zephyr modules](https://docs.zephyrproject.org/4.1.0/develop/modules.html) to include additional source code or configuration files into its build. You can think of them as similar to plugins or themes. The most common uses of this feature are:
- Building firmware for a keyboard external to ZMK's tree
- Adding functionality to ZMK, such as a driver or a behavior
@ -27,11 +27,11 @@ The shift to using modules for keyboards is a relatively recent one, and not all
When [using GitHub Actions to build ZMK](../user-setup.mdx), adding modules is as simple as modifying the `west.yml` found in your `zmk-config`'s `config` directory. The recommended way of doing so is:
1. Find the URL base (the parent URL) for the module and add it as an entry to the [remotes](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html#remotes).
2. Add the module as an entry to the [projects](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html#projects).
1. Find the URL base (the parent URL) for the module and add it as an entry to the [remotes](https://docs.zephyrproject.org/4.1.0/develop/west/manifest.html#remotes).
2. Add the module as an entry to the [projects](https://docs.zephyrproject.org/4.1.0/develop/west/manifest.html#projects).
Aside from the mandatory `name`, `remote`, and the commonly used `revision` properties, take note of the `import` property under `projects`. Some modules may have other modules as dependencies. This property allows the specifying of an additional west manifest file found in the tree of the module, which will automatically import all dependencies.
For more information on `west.yml`, see [West Manifests](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html).
For more information on `west.yml`, see [West Manifests](https://docs.zephyrproject.org/4.1.0/develop/west/manifest.html).
#### Examples

2
docs/docs/features/studio.md
View File

@ -176,7 +176,7 @@ To allow ZMK Studio to be used with a keyboard, the keyboard will need to have a
- The [new shield guide](../development/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/3.5.0/snippets/cdc-acm-console/README.html).
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.

2
docs/docs/intro.mdx
View File

@ -40,7 +40,7 @@ Below table lists major features/capabilities currently supported in ZMK, as wel
| [Low Power Mode (VCC Shutoff) for Peripherals](keymaps/behaviors/power.md) | ✅ |
| Improved Power Handling for Multiple Peripherals | 🚧 |
| [Battery Level Reporting](features/battery.md) | ✅ |
| [Support for a Wide Range of 32-bit Microcontrollers](https://docs.zephyrproject.org/3.5.0/boards/index.html) | ✅ |
| [Support for a Wide Range of 32-bit Microcontrollers](https://docs.zephyrproject.org/4.1.0/boards/index.html) | ✅ |
| Support for AVR/8-bit Chips | ❌ |
</Column>

4
docs/docs/keymaps/input-processors/behaviors.md
View File

@ -76,6 +76,6 @@ The behaviors input processor uses a `compatible` property of `"zmk,input-proces
### User Properties
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to scale. Usually, this is `INPUT_EV_KEY` for key/button events. The default value if omitted is `INPUT_EV_KEY`.
- `codes` - The specific codes of the given type to capture, e.g. [button event codes](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L180). This list must be the same length as the `bindings` property.
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to scale. Usually, this is `INPUT_EV_KEY` for key/button events. The default value if omitted is `INPUT_EV_KEY`.
- `codes` - The specific codes of the given type to capture, e.g. [button event codes](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L180). This list must be the same length as the `bindings` property.
- `bindings` - The bindings to trigger when an event with the corresponding code is processed.

4
docs/docs/keymaps/input-processors/code-mapper.md
View File

@ -59,5 +59,5 @@ The code mapper input processor uses a `compatible` property of `"zmk,input-proc
### User Properties
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to scale. Usually, this is `INPUT_EV_REL` for relative events and `INPUT_EV_KEY` for key/button events.
- `map` - The specific codes of the given type to map, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245). This list must be an even number of entries which is processed as a list of pairs of codes. The first code in the pair is the source code, and the second is the code to map it to.
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to scale. Usually, this is `INPUT_EV_REL` for relative events and `INPUT_EV_KEY` for key/button events.
- `map` - The specific codes of the given type to map, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245). This list must be an even number of entries which is processed as a list of pairs of codes. The first code in the pair is the source code, and the second is the code to map it to.

4
docs/docs/keymaps/input-processors/scaler.md
View File

@ -73,5 +73,5 @@ The scaler input processor uses a `compatible` property of `"zmk,input-processor
### User Properties
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to scale. Usually, this is `INPUT_EV_REL` for relative events.
- `codes` - The specific codes within the given type to scale, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245)
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to scale. Usually, this is `INPUT_EV_REL` for relative events.
- `codes` - The specific codes within the given type to scale, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245)

6
docs/docs/keymaps/input-processors/transformer.md
View File

@ -70,6 +70,6 @@ The transform input processor uses a `compatible` property of `"zmk,input-proces
### User Properties
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to transform. Usually, this is `INPUT_EV_REL` for relative events.
- `x-codes` - The specific X codes within the given type to transform, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245)
- `y-codes` - The specific Y codes within the given type to transform, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245)
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to transform. Usually, this is `INPUT_EV_REL` for relative events.
- `x-codes` - The specific X codes within the given type to transform, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245)
- `y-codes` - The specific Y codes within the given type to transform, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245)

2
docs/docs/troubleshooting/building-issues.md
View File

@ -7,7 +7,7 @@ description: Troubleshooting issues when compiling ZMK firmware.
## CMake Error
An error along the lines of `CMake Error at (zmk directory)/zephyr/cmake/generic_toolchain.cmake:64 (include): include could not find load file:` during firmware compilation indicates that the Zephyr Environment Variables are not properly defined.
For more information, see [Zephyr's CMake Package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html).
For more information, see [Zephyr's CMake Package](https://docs.zephyrproject.org/4.1.0/build/zephyr_cmake_package.html).
## West Build Errors

6
docs/docs/troubleshooting/connection-issues.mdx
View File

@ -77,7 +77,7 @@ For connectivity problems caused by hardware, please see [the appropriate sectio
Some devices and operating systems may have additional restrictions that they require be met before allowing a bluetooth peripheral to pair with them. If your keyboard is visible to your host but you are having issues trouble connecting or no input is registered, this might be the cause. Some of ZMK's [experimental bluetooth settings](../config/bluetooth.md) may suffice to resolve the issue. In particular:
- Disabling PHY 2Mbps ([`CONFIG_BT_CTLR_PHY_2M=n`](https://docs.zephyrproject.org/3.5.0/kconfig.html#CONFIG_BT_CTLR_PHY_2M)) helps to pair and connect for certain wireless chipset firmware versions, particularly on Windows (Realtek and Intel chips) and older Intel Macs with Broadcom chipsets.
- Disabling PHY 2Mbps ([`CONFIG_BT_CTLR_PHY_2M=n`](https://docs.zephyrproject.org/4.1.0/kconfig.html#CONFIG_BT_CTLR_PHY_2M)) helps to pair and connect for certain wireless chipset firmware versions, particularly on Windows (Realtek and Intel chips) and older Intel Macs with Broadcom chipsets.
- Enabling passkey entry ([`CONFIG_ZMK_BLE_PASSKEY_ENTRY=y`](../config/bluetooth.md)) helps for certain Windows computers (work-managed ones in particular). This may also manifest in not sending keystrokes.
### Issues With Dual Boot Setups
@ -95,7 +95,7 @@ For the `nRF52840`, the flag to set to use the internal oscillator is:
CONFIG_CLOCK_CONTROL_NRF_K32SRC_RC=y
```
Other microcontrollers may have similar configuration options [found in the Zephyr documentation](https://docs.zephyrproject.org/3.5.0/search.html?q=CONFIG_CLOCK_CONTROL&check_keywords=yes&area=default). Do note that not all microcontrollers allow for the use of an internal oscillator, though.
Other microcontrollers may have similar configuration options [found in the Zephyr documentation](https://docs.zephyrproject.org/4.1.0/search.html?q=CONFIG_CLOCK_CONTROL&check_keywords=yes&area=default). Do note that not all microcontrollers allow for the use of an internal oscillator, though.
## Issues While Connected
@ -107,7 +107,7 @@ Some users may experience a poor connection between the keyboard and the host. T
CONFIG_BT_CTLR_TX_PWR_PLUS_8=y
```
For the `nRF52840`, the value `PLUS_8` can be set to any multiple of four between `MINUS_20` and `PLUS_8`. The default value for this config is `0`, but if you are having connection issues it is recommended to set it to `PLUS_8` because the power consumption difference is negligible. For more information on changing the transmit power of your BLE device, please refer to [the Zephyr docs.](https://docs.zephyrproject.org/3.5.0/kconfig.html#CONFIG_BT_CTLR_TX_PWR)
For the `nRF52840`, the value `PLUS_8` can be set to any multiple of four between `MINUS_20` and `PLUS_8`. The default value for this config is `0`, but if you are having connection issues it is recommended to set it to `PLUS_8` because the power consumption difference is negligible. For more information on changing the transmit power of your BLE device, please refer to [the Zephyr docs.](https://docs.zephyrproject.org/4.1.0/kconfig.html#CONFIG_BT_CTLR_TX_PWR)
:::info
This setting can also improve the connection strength between the keyboard halves for split keyboards.