chore(docs): Update Zephyr links to 3.5.0 versions.
This commit is contained in:
Peter Johanson
Pete Johanson
parent
4bcecd98f8
commit
edc72c1166
@ -26,7 +26,7 @@ The `*_START` settings only determine the initial backlight state. Any changes y
|
||||
|
||||
## Devicetree
|
||||
|
||||
Applies to: [`/chosen` node](https://docs.zephyrproject.org/latest/build/dts/intro.html#aliases-and-chosen-nodes)
|
||||
Applies to: [`/chosen` node](https://docs.zephyrproject.org/3.5.0/build/dts/intro.html#aliases-and-chosen-nodes)
|
||||
|
||||
| Property | Type | Description |
|
||||
| --------------- | ---- | -------------------------------------------- |
|
||||
@ -34,7 +34,7 @@ Applies to: [`/chosen` node](https://docs.zephyrproject.org/latest/build/dts/int
|
||||
|
||||
See the Zephyr devicetree bindings for LED drivers:
|
||||
|
||||
- [gpio-leds](https://docs.zephyrproject.org/3.0.0/reference/devicetree/bindings/gpio/gpio-leds.html)
|
||||
- [pwm-leds](https://docs.zephyrproject.org/latest/build/dts/api/bindings/led/pwm-leds.html)
|
||||
- [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)
|
||||
|
||||
See the [backlight feature page](../features/backlight.mdx) for examples of the properties that must be set to enable backlighting.
|
||||
|
||||
@ -30,7 +30,7 @@ On macOS the BLE battery reporting packets can cause the computer to wakeup from
|
||||
|
||||
### Devicetree
|
||||
|
||||
Applies to: [`/chosen` node](https://docs.zephyrproject.org/latest/guides/dts/intro.html#aliases-and-chosen-nodes)
|
||||
Applies to: [`/chosen` node](https://docs.zephyrproject.org/3.5.0/guides/dts/intro.html#aliases-and-chosen-nodes)
|
||||
|
||||
| Property | Type | Description |
|
||||
| ------------- | ---- | --------------------------------------------- |
|
||||
@ -44,7 +44,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/latest/build/dts/api/bindings/adc/voltage-divider.html).
|
||||
See [Zephyr's voltage divider documentation](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/adc/voltage-divider.html).
|
||||
|
||||
## nRF VDDH Battery Sensor
|
||||
|
||||
|
||||
@ -51,14 +51,14 @@ 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/latest/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/3.5.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/latest/build/dts/api/bindings/display/solomon,ssd1306fb-i2c.html)
|
||||
- [SSD1306 (spi)](https://docs.zephyrproject.org/latest/build/dts/api/bindings/display/solomon,ssd1306fb-spi.html)
|
||||
- [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)
|
||||
|
||||
A full list of drivers provided by Zephyr can be found in [Zephyr's Devicetree bindings index](https://docs.zephyrproject.org/latest/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/3.5.0/build/dts/api/bindings.html).
|
||||
|
||||
@ -44,7 +44,7 @@ ZMK will search the board folder for the following config files:
|
||||
|
||||
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/latest/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/3.5.0/hardware/porting/board_porting.html#write-kconfig-files).
|
||||
|
||||
### Shield Folder
|
||||
|
||||
@ -63,7 +63,7 @@ ZMK will search the shield folder for the following config files:
|
||||
|
||||
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/latest/hardware/porting/shields.html) and [ZMK's new keyboard shield](../development/new-shield.mdx) guide.
|
||||
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/new-shield.mdx) guide.
|
||||
|
||||
## Kconfig Files
|
||||
|
||||
@ -79,7 +79,7 @@ CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y
|
||||
|
||||
The list of available settings is determined by various files in ZMK whose names start with `Kconfig`. Files ending with `_defconfig` use the same syntax, but are intended for setting configuration specific to the hardware which users typically won't need to change. Note that options are _not_ prefixed with `CONFIG_` in these files.
|
||||
|
||||
See [Zephyr's Kconfig documentation](https://docs.zephyrproject.org/latest/build/kconfig/index.html) for more details on Kconfig files.
|
||||
See [Zephyr's Kconfig documentation](https://docs.zephyrproject.org/3.5.0/build/kconfig/index.html) for more details on Kconfig files.
|
||||
|
||||
### KConfig Value Types
|
||||
|
||||
@ -128,7 +128,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/latest/build/dts/index.html) for more details on Devicetree files.
|
||||
See [Zephyr's Devicetree guide](https://docs.zephyrproject.org/3.5.0/build/dts/index.html) for more details on Devicetree files.
|
||||
|
||||
### Changing Devicetree Properties
|
||||
|
||||
@ -149,7 +149,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/latest/build/dts/intro.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/3.5.0/build/dts/intro.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 (`;`).
|
||||
@ -174,7 +174,7 @@ If the node you want to edit doesn't have a label, you can also write a new tree
|
||||
|
||||
### Devicetree 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/latest/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/3.5.0/build/dts/bindings.html) provides more detailed information and a full list of types.
|
||||
|
||||
#### bool
|
||||
|
||||
@ -228,14 +228,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/latest/build/dts/bindings.html)
|
||||
See the documentation for "phandle-array" in [Zephyr's Devicetree bindings documentation](https://docs.zephyrproject.org/3.5.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/latest/hardware/peripherals/gpio.html) for a full list of flags.
|
||||
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.
|
||||
|
||||
Example:
|
||||
|
||||
|
||||
@ -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/latest/guides/dts/intro.html#aliases-and-chosen-nodes)
|
||||
Applies to: [`/chosen` node](https://docs.zephyrproject.org/3.5.0/guides/dts/intro.html#aliases-and-chosen-nodes)
|
||||
|
||||
| Property | Type | Description |
|
||||
| ---------------------- | ---- | ------------------------------------------------------------- |
|
||||
@ -84,7 +84,7 @@ By default, a switch will drain current through the internal pull up/down resist
|
||||
|
||||
`toggle-mode` applies to all switches handled by the instance of the driver. To use a toggle switch with other, non-toggle, direct GPIO switches, create two instances of the direct GPIO driver, one with `toggle-mode` and the other without. Then, use a [composite driver](#composite-driver) to combine them.
|
||||
|
||||
Assuming the switches connect each GPIO pin to the ground, the [GPIO flags](https://docs.zephyrproject.org/3.2.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/3.5.0/hardware/peripherals/gpio.html#api-reference) for the elements in `input-gpios` should be `(GPIO_ACTIVE_LOW | GPIO_PULL_UP)`:
|
||||
|
||||
```dts
|
||||
kscan0: kscan {
|
||||
@ -131,7 +131,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.2.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/3.5.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
|
||||
|
||||
@ -80,7 +80,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/latest/guides/bluetooth/bluetooth-arch.html)
|
||||
See [Zephyr's Bluetooth stack architecture documentation](https://docs.zephyrproject.org/3.5.0/connectivity/bluetooth/bluetooth-arch.html)
|
||||
for more information on configuring Bluetooth.
|
||||
|
||||
| Config | Type | Description | Default |
|
||||
|
||||
@ -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/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.
|
||||
- A [KSCAN driver](https://docs.zephyrproject.org/3.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.
|
||||
- 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/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 [chosen](https://docs.zephyrproject.org/3.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/3.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 `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/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 [chosen](https://docs.zephyrproject.org/3.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/3.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/3.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 `keymap/keymap.overlay` file that includes the default keymap for that keyboard. Users will be able to override this keymap in their user configs.
|
||||
|
||||
@ -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/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)
|
||||
ZMK treats keyboards that take an MCU addon board as [shields](https://docs.zephyrproject.org/3.5.0/guides/porting/shields.html), and treats the smaller MCU board as the true [board](https://docs.zephyrproject.org/3.5.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/3.2.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.5.0/guides/porting/board_porting.html) as far as Zephyr™ is concerned.
|
||||
|
||||
Given the following:
|
||||
|
||||
@ -79,7 +79,7 @@ Build times can be significantly reduced after the initial build by omitting all
|
||||
|
||||
### Building with external modules
|
||||
|
||||
ZMK supports loading additional boards, shields, code, etc. from [external Zephyr modules](https://docs.zephyrproject.org/3.2.0/develop/modules.html), facilitating out-of-tree management and versioning independent of the ZMK repository. To build with any additional modules, use the `ZMK_EXTRA_MODULES` define added to your `west build` command.
|
||||
ZMK supports loading additional boards, shields, code, etc. from [external Zephyr modules](https://docs.zephyrproject.org/3.5.0/develop/modules.html), facilitating out-of-tree management and versioning independent of the ZMK repository. To build with any additional modules, use the `ZMK_EXTRA_MODULES` define added to your `west build` command.
|
||||
|
||||
For instance, building with the `my-vendor-keebs-module` checked out to your documents directory, you would build like:
|
||||
|
||||
@ -144,7 +144,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.2.0/samples/bluetooth/hci_rpmsg/README.html), [SPI](https://docs.zephyrproject.org/3.2.0/samples/bluetooth/hci_spi/README.html), [UART](https://docs.zephyrproject.org/3.2.0/samples/bluetooth/hci_uart/README.html), and [USB](https://docs.zephyrproject.org/3.2.0/samples/bluetooth/hci_usb/README.html). See [Zephyr's Bluetooth Stack Architecture documentation](https://docs.zephyrproject.org/3.2.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/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.
|
||||
|
||||
The following documentation shows how to build and flash ZMK for boards that use a dual-chip configuration.
|
||||
|
||||
|
||||
@ -28,8 +28,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/latest/build/dts/api/api.html)
|
||||
- [Zephyr Device Driver Model](https://docs.zephyrproject.org/latest/kernel/drivers/index.html)
|
||||
- [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)
|
||||
|
||||
:::
|
||||
|
||||
@ -116,7 +116,7 @@ These are additional variables required to configure a particular instance of a
|
||||
- `phandles`
|
||||
|
||||
:::info
|
||||
For more information on additional `properties`, refer to [Zephyr's documentation on Devicetree bindings](https://docs.zephyrproject.org/latest/build/dts/bindings.html#properties).
|
||||
For more information on additional `properties`, refer to [Zephyr's documentation on Devicetree bindings](https://docs.zephyrproject.org/3.5.0/build/dts/bindings.html#properties).
|
||||
:::
|
||||
|
||||
### Creating the driver (`.c`)
|
||||
@ -124,8 +124,8 @@ For more information on additional `properties`, refer to [Zephyr's documentatio
|
||||
:::info
|
||||
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/latest/build/dts/api/api.html)
|
||||
- [Zephyr Device Driver Model](https://docs.zephyrproject.org/latest/kernel/drivers/index.html)
|
||||
- [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)
|
||||
|
||||
:::
|
||||
|
||||
@ -192,7 +192,7 @@ The dependencies required for any ZMK behavior are:
|
||||
|
||||
- `device.h`: [Zephyr Device APIs](https://docs.zephyrproject.org/apidoc/latest/group__device__model.html)
|
||||
- `drivers/behavior.h`: ZMK Behavior Functions (e.g. [`locality`](#api-structure), `behavior_keymap_binding_pressed`, `behavior_keymap_binding_released`, `behavior_sensor_keymap_binding_triggered`)
|
||||
- `logging/log.h`: [Zephyr Logging APIs](https://docs.zephyrproject.org/latest/services/logging/index.html) (for more information on USB Logging in ZMK, see [USB Logging](usb-logging.mdx)).
|
||||
- `logging/log.h`: [Zephyr Logging APIs](https://docs.zephyrproject.org/3.5.0/services/logging/index.html) (for more information on USB Logging in ZMK, see [USB Logging](usb-logging.mdx)).
|
||||
- `zmk/behavior.h`: ZMK Behavior Information (e.g. parameters, position and timestamp of events)
|
||||
- `return` values:
|
||||
- `ZMK_BEHAVIOR_OPAQUE`: Used to terminate `on_<behavior_name>_binding_pressed` and `on_<behavior_name>_binding_released` functions that accept `(struct zmk_behavior_binding *binding, struct zmk_behavior_binding_event event)` as parameters
|
||||
@ -249,7 +249,7 @@ Listeners, defined by the `ZMK_LISTENER(mod, cb)` function, take in a listener n
|
||||
`BEHAVIOR_DT_INST_DEFINE` is a special ZMK macro. It forwards all the parameters to Zephyr's `DEVICE_DT_INST_DEFINE` macro to define the driver instance, then it adds the driver to a list of ZMK behaviors so they can be found by `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/latest/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/3.5.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). For behaviors that can have multiple instances (e.g. hold-taps, tap-dances, sticky-keys), `BEHAVIOR_DT_INST_DEFINE` can be placed inside a `#define` statement, usually formatted as `#define <ABBREVIATED BEHAVIOR NAME>_INST(n)`, that sets up any [data pointers](#data-pointers-optional) and/or [configuration pointers](#configuration-pointers-optional) that are unique to each instance.
|
||||
@ -312,7 +312,7 @@ The fourth cell of `BEHAVIOR_DT_INST_DEFINE` can be set to `NULL` instead if ins
|
||||
|
||||
##### Configuration Pointers (Optional)
|
||||
|
||||
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_<behavior_name>_config_##n`, for each instance number, `n`, can be initialized using the [Zephyr Devicetree Instance-based APIs](https://docs.zephyrproject.org/latest/build/dts/api/api.html#instance-based-apis), which extract the values from the `properties` of each instance of the [devicetree binding](#creating-the-devicetree-binding-yaml) from a user's keymap or [predefined use-case `.dtsi` files](#defining-common-use-cases-for-the-behavior-dtsi-optional) stored in `app/dts/behaviors/`. We illustrate this further by comparing the [`#define KP_INST(n)` from the hold-tap driver](#behavior_dt_inst_define) and the [`properties` of the hold-tap devicetree binding.](#creating-the-devicetree-binding-yaml)
|
||||
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_<behavior_name>_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), which extract the values from the `properties` of each instance of the [devicetree binding](#creating-the-devicetree-binding-yaml) from a user's keymap or [predefined use-case `.dtsi` files](#defining-common-use-cases-for-the-behavior-dtsi-optional) stored in `app/dts/behaviors/`. We illustrate this further by comparing the [`#define KP_INST(n)` from the hold-tap driver](#behavior_dt_inst_define) and the [`properties` of the hold-tap devicetree binding.](#creating-the-devicetree-binding-yaml)
|
||||
|
||||
The fifth cell of `BEHAVIOR_DT_INST_DEFINE` can be set to `NULL` instead if instance-specific configurations are not required.
|
||||
|
||||
|
||||
@ -15,7 +15,7 @@ This guide will walk through the steps necessary to add ZMK support for a keyboa
|
||||
|
||||
The high level steps are:
|
||||
|
||||
- From a template, create a new [Zephyr module](https://docs.zephyrproject.org/3.2.0/develop/modules.html) housed in a git repository containing one or more custom shields.
|
||||
- From a template, create a new [Zephyr module](https://docs.zephyrproject.org/3.5.0/develop/modules.html) housed in a git repository containing one or more custom shields.
|
||||
- Create a new shield directory.
|
||||
- Add the base Kconfig files.
|
||||
- Add the shield overlay file to define the KSCAN driver for detecting key press/release.
|
||||
@ -25,7 +25,7 @@ The high level steps are:
|
||||
- Update the `build.yaml` file from the repository template to have some sample builds of the firmware to test.
|
||||
- Add support for features such as encoders, OLED displays, or RGB underglow.
|
||||
|
||||
It may be helpful to review the upstream [shields documentation](https://docs.zephyrproject.org/3.2.0/guides/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/3.5.0/guides/porting/shields.html#shields) to get a proper understanding of the underlying system before continuing.
|
||||
|
||||
:::note
|
||||
ZMK support for split keyboards requires a few more files than single boards to ensure proper connectivity between the central and peripheral units. Check the following guides thoroughly to ensure that all the files are in place.
|
||||
|
||||
@ -46,22 +46,22 @@ The docker container already includes `west`. Skip past the following section to
|
||||
</TabItem>
|
||||
<TabItem value="debian">
|
||||
|
||||
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html) and follow the instructions under these sections:
|
||||
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:
|
||||
|
||||
- [Select and Update OS](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#select-and-update-os)
|
||||
- [Install Dependencies](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#install-dependencies)
|
||||
- [Install Zephyr SDK](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#install-zephyr-sdk)
|
||||
- [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)
|
||||
- [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
|
||||
|
||||
Return to this guide once you are finished with each section.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="win">
|
||||
|
||||
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html) and follow the instructions under these sections:
|
||||
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:
|
||||
|
||||
- [Select and Update OS](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#select-and-update-os)
|
||||
- [Install Dependencies](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#install-dependencies)
|
||||
- [Install Zephyr SDK](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#install-zephyr-sdk)
|
||||
- [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)
|
||||
- [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
|
||||
|
||||
Return to this guide once you are finished with each section.
|
||||
|
||||
@ -70,11 +70,11 @@ Return to this guide once you are finished with each section.
|
||||
</TabItem>
|
||||
<TabItem value="mac">
|
||||
|
||||
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html) and follow the instructions under these sections:
|
||||
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:
|
||||
|
||||
- [Select and Update OS](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#select-and-update-os)
|
||||
- [Install Dependencies](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#install-dependencies)
|
||||
- [Install Zephyr SDK](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#install-zephyr-sdk)
|
||||
- [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)
|
||||
- [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
|
||||
|
||||
Return to this guide once you are finished with each section.
|
||||
|
||||
@ -83,16 +83,16 @@ Return to this guide once you are finished with each section.
|
||||
|
||||
#### Install Base Dependencies
|
||||
|
||||
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html) and follow the instructions for Ubuntu under these sections:
|
||||
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions for Ubuntu under these sections:
|
||||
|
||||
- [Select and Update OS](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#select-and-update-os)
|
||||
- [Install Dependencies](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#install-dependencies)
|
||||
- [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)
|
||||
|
||||
Return to this guide once you are finished with each section.
|
||||
|
||||
#### 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.2.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/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.
|
||||
|
||||
First, the cross compiler should be installed:
|
||||
|
||||
@ -100,7 +100,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.2.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/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:
|
||||
|
||||
```sh
|
||||
export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
|
||||
@ -110,16 +110,16 @@ export CROSS_COMPILE=/usr/bin/arm-none-eabi-
|
||||
</TabItem>
|
||||
<TabItem value="fedora">
|
||||
|
||||
Follow Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/3.2.0/develop/getting_started/installation_linux.html) documentation for Fedora.
|
||||
Follow Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/installation_linux.html) documentation for Fedora.
|
||||
|
||||
</TabItem>
|
||||
</OsTabs>
|
||||
|
||||
### Install West
|
||||
|
||||
`west` is the [Zephyr® Project's meta-tool](https://docs.zephyrproject.org/3.2.0/develop/west/index.html) used to configure and build Zephyr OS applications.
|
||||
`west` is the [Zephyr® Project's meta-tool](https://docs.zephyrproject.org/3.5.0/develop/west/index.html) used to configure and build Zephyr OS applications.
|
||||
|
||||
West can be installed by using the `pip` python package manager. The [Zephyr™ instructions](https://docs.zephyrproject.org/3.2.0/develop/west/install.html) are summarized here:
|
||||
West can be installed by using the `pip` python package manager. The [Zephyr™ instructions](https://docs.zephyrproject.org/3.5.0/develop/west/install.html) are summarized here:
|
||||
|
||||
<Tabs
|
||||
defaultValue="linux"
|
||||
|
||||
@ -24,7 +24,7 @@ The `CONFIG_ZMK_USB_LOGGING` Kconfig enables USB logging. This can be set at the
|
||||
file if you are using a [user config repository](user-setup.mdx). It can also be enabled at the ZMK level using the `app/prj.conf` file, or other
|
||||
search locations described in the [configuration overview](config/index.md#config-file-locations).
|
||||
|
||||
Logging can be further configured using Kconfig described in [the Zephyr documentation](https://docs.zephyrproject.org/3.2.0/services/logging/index.html).
|
||||
Logging can be further configured using Kconfig described in [the Zephyr documentation](https://docs.zephyrproject.org/3.5.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.
|
||||
|
||||
|
||||
@ -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/latest/boards/index.html) many architectures, processors and boards.
|
||||
- A _single_ platform [supporting](https://docs.zephyrproject.org/3.5.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/latest/guides/dts/index.html) and [Kconfig](https://docs.zephyrproject.org/latest/build/kconfig/index.html).
|
||||
- A BLE stack that periodically obtains [qualification](https://docs.zephyrproject.org/latest/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/3.5.0/guides/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.
|
||||
- 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/latest/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/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._
|
||||
|
||||
### Does ZMK compile for AVR?
|
||||
|
||||
|
||||
@ -46,7 +46,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/latest/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/3.5.0/kconfig.html#CONFIG_BT_CTLR_TX_PWR)
|
||||
|
||||
:::info
|
||||
This setting can also improve the connection strength between the keyboard halves for split keyboards.
|
||||
|
||||
@ -41,7 +41,7 @@ ZMK is currently missing some features found in other popular firmware. This tab
|
||||
| Shell over BLE | 💡 | | |
|
||||
| Realtime Keymap Updating | 💡 | | ✅ |
|
||||
| AVR/8 Bit | | | ✅ |
|
||||
| [Wide Range of ARM Chips Supported](https://docs.zephyrproject.org/latest/boards/index.html) | ✅ | | |
|
||||
| [Wide Range of ARM Chips Supported](https://docs.zephyrproject.org/3.5.0/boards/index.html) | ✅ | | |
|
||||
|
||||
[^2]: Tap-Dances are limited to single and double-tap on BlueMicro
|
||||
[^1]: OLEDs are currently proof of concept in ZMK.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user