diff --git a/.github/workflows/ble-test.yml b/.github/workflows/ble-test.yml index 68cb1cb3..51450414 100644 --- a/.github/workflows/ble-test.yml +++ b/.github/workflows/ble-test.yml @@ -21,7 +21,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@v6 - name: Find test directories id: test-dirs run: | @@ -38,7 +38,7 @@ jobs: image: docker.io/zmkfirmware/zmk-build-arm:4.1 steps: - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@v6 - name: Cache west modules uses: actions/cache@v5 env: diff --git a/.github/workflows/build-user-config.yml b/.github/workflows/build-user-config.yml index f6839819..66226b5f 100644 --- a/.github/workflows/build-user-config.yml +++ b/.github/workflows/build-user-config.yml @@ -33,7 +33,7 @@ jobs: has_valid_build_matrix: ${{ steps.fetch.outputs.has_valid_build_matrix }} steps: - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@v6 - name: Fetch Build Matrix id: fetch @@ -67,7 +67,7 @@ jobs: curl -fsSL https://deb.nodesource.com/setup_22.x | bash && apt install -y nodejs - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@v6 - name: Create build directory run: | diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 0d2a5805..97a060df 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -30,7 +30,7 @@ jobs: include: ${{ fromJSON(needs.compile-matrix.outputs.include-list) }} steps: - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@v6 with: persist-credentials: false - name: Cache west modules @@ -63,7 +63,7 @@ jobs: - name: Install @actions/artifact run: npm install @actions/artifact@5.0.3 - name: Build - uses: actions/github-script@v9 + uses: actions/github-script@v7 id: boards-list with: script: | @@ -95,7 +95,7 @@ jobs: throw new Error('Failed to build one or more configurations'); } - name: Upload artifacts - uses: actions/github-script@v9 + uses: actions/github-script@v7 continue-on-error: ${{ github.event_name == 'pull_request' }} id: boards-upload with: @@ -146,7 +146,7 @@ jobs: include-list: ${{ steps.compile-list.outputs.result }} steps: - name: Join build lists - uses: actions/github-script@v9 + uses: actions/github-script@v7 id: compile-list with: script: | @@ -187,7 +187,7 @@ jobs: core-include: ${{ steps.core-list.outputs.result }} steps: - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@v6 with: persist-credentials: false - name: Use Node.js @@ -196,7 +196,7 @@ jobs: node-version: "14.x" - name: Install js-yaml run: npm install js-yaml - - uses: actions/github-script@v9 + - uses: actions/github-script@v7 id: core-list with: script: | @@ -218,14 +218,14 @@ jobs: boards-include: ${{ steps.boards-list.outputs.result }} steps: - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@v6 - name: Use Node.js uses: actions/setup-node@v6 with: node-version: "14.x" - name: Install js-yaml run: npm install js-yaml - - uses: actions/github-script@v9 + - uses: actions/github-script@v7 id: boards-list with: script: | @@ -303,7 +303,7 @@ jobs: nightly-include: ${{ steps.nightly-list.outputs.result }} steps: - name: Create nightly list - uses: actions/github-script@v9 + uses: actions/github-script@v7 id: nightly-list with: script: | @@ -346,7 +346,7 @@ jobs: organized-metadata: ${{ steps.organize-metadata.outputs.result }} steps: - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@v6 with: persist-credentials: false - name: Use Node.js @@ -356,7 +356,7 @@ jobs: - name: Install js-yaml run: npm install js-yaml - name: Aggregate Metadata - uses: actions/github-script@v9 + uses: actions/github-script@v7 id: aggregate-metadata with: script: | @@ -374,7 +374,7 @@ jobs: result-encoding: string - name: Organize Metadata - uses: actions/github-script@v9 + uses: actions/github-script@v7 id: organize-metadata with: script: | @@ -428,7 +428,7 @@ jobs: core-changes: ${{ steps.core-changes.outputs.result }} steps: - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@v6 with: persist-credentials: false - uses: tj-actions/changed-files@9200e69727eb73eb060652b19946b8a2fdfb654b # pin to v45.0.8 due to https://github.com/tj-actions/changed-files/issues/2463 https://www.stepsecurity.io/blog/harden-runner-detection-tj-actions-changed-files-action-is-compromised @@ -436,7 +436,7 @@ jobs: with: json: true escape_json: false - - uses: actions/github-script@v9 + - uses: actions/github-script@v7 id: board-changes with: script: | @@ -444,7 +444,7 @@ jobs: const boardChanges = changedFiles.filter(f => f.startsWith('app/boards')); return boardChanges.length ? 'true' : 'false'; result-encoding: string - - uses: actions/github-script@v9 + - uses: actions/github-script@v7 id: core-changes with: script: | diff --git a/.github/workflows/doc-checks.yml b/.github/workflows/doc-checks.yml index a562ed39..6866ff79 100644 --- a/.github/workflows/doc-checks.yml +++ b/.github/workflows/doc-checks.yml @@ -14,7 +14,7 @@ jobs: lint: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@v6 - uses: bahmutov/npm-install@v1 with: working-directory: docs @@ -24,7 +24,7 @@ jobs: typecheck: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@v6 - uses: bahmutov/npm-install@v1 with: working-directory: docs diff --git a/.github/workflows/hardware-metadata-validation.yml b/.github/workflows/hardware-metadata-validation.yml index 406a1e63..e212f627 100644 --- a/.github/workflows/hardware-metadata-validation.yml +++ b/.github/workflows/hardware-metadata-validation.yml @@ -20,7 +20,7 @@ jobs: container: image: docker.io/zmkfirmware/zmk-dev-arm:4.1 steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@v6 - name: Install dependencies run: pip install --break-system-packages -r app/scripts/requirements.txt - name: West init diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml index 52b82a62..42b42af0 100644 --- a/.github/workflows/pre-commit.yml +++ b/.github/workflows/pre-commit.yml @@ -8,7 +8,7 @@ jobs: pre-commit: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@v6 - uses: actions/setup-python@v6 with: python-version: 3.x diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml index 5735eea7..048d6a1d 100644 --- a/.github/workflows/release-please.yml +++ b/.github/workflows/release-please.yml @@ -20,7 +20,7 @@ jobs: minor: ${{ steps.release.outputs.minor }} patch: ${{ steps.release.outputs.patch }} steps: - - uses: googleapis/release-please-action@v5 + - uses: googleapis/release-please-action@v4 id: release with: token: ${{ secrets.ZMK_RELEASE_PLEASE_TOKEN }} @@ -35,7 +35,7 @@ jobs: ZMK_RELEASE_PLEASE_TOKEN: ${{ secrets.ZMK_RELEASE_PLEASE_TOKEN }} VERSION: v${{ needs.handle-commit.outputs.major }}.${{ needs.handle-commit.outputs.minor }} steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@v6 - name: Create major.minor branch if: ${{ needs.handle-commit.outputs.patch == '0' }} diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 20bebf3b..1efc9cac 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -23,7 +23,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@v6 - name: Find test directories id: test-dirs run: | @@ -40,7 +40,7 @@ jobs: image: docker.io/zmkfirmware/zmk-build-arm:4.1 steps: - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@v6 - name: Cache west modules uses: actions/cache@v5 env: diff --git a/app/boards/shields/reviung34/reviung34-layouts.dtsi b/app/boards/shields/reviung34/reviung34-layouts.dtsi deleted file mode 100644 index cc331fee..00000000 --- a/app/boards/shields/reviung34/reviung34-layouts.dtsi +++ /dev/null @@ -1,114 +0,0 @@ -/* - * Copyright (c) 2026 The ZMK Contributors - * - * SPDX-License-Identifier: MIT - */ - -#include - -/ { - reviung34_dual_1u_layout: reviung34_dual_1u_layout { - compatible = "zmk,physical-layout"; - display-name = "Dual 1U (34 keys)"; - - keys // w h x y rot rx ry - = <&key_physical_attrs 100 100 35 2 1000 85 52> - , <&key_physical_attrs 100 100 136 1 1000 186 51> - , <&key_physical_attrs 100 100 238 0 1000 288 50> - , <&key_physical_attrs 100 100 333 35 1000 383 85> - , <&key_physical_attrs 100 100 429 71 1000 479 121> - , <&key_physical_attrs 100 100 555 71 (-1000) 605 121> - , <&key_physical_attrs 100 100 650 35 (-1000) 700 85> - , <&key_physical_attrs 100 100 746 0 (-1000) 796 50> - , <&key_physical_attrs 100 100 847 1 (-1000) 897 51> - , <&key_physical_attrs 100 100 949 1 (-1000) 999 51> - , <&key_physical_attrs 100 100 17 100 1000 67 150> - , <&key_physical_attrs 100 100 119 99 1000 169 149> - , <&key_physical_attrs 100 100 221 98 1000 271 148> - , <&key_physical_attrs 100 100 316 134 1000 366 184> - , <&key_physical_attrs 100 100 411 169 1000 461 219> - , <&key_physical_attrs 100 100 572 169 (-1000) 622 219> - , <&key_physical_attrs 100 100 668 134 (-1000) 718 184> - , <&key_physical_attrs 100 100 763 98 (-1000) 813 148> - , <&key_physical_attrs 100 100 865 99 (-1000) 915 149> - , <&key_physical_attrs 100 100 966 100 (-1000) 1016 150> - , <&key_physical_attrs 100 100 0 198 1000 50 248> - , <&key_physical_attrs 100 100 102 198 1000 152 248> - , <&key_physical_attrs 100 100 203 197 1000 253 247> - , <&key_physical_attrs 100 100 298 232 1000 348 282> - , <&key_physical_attrs 100 100 394 268 1000 444 318> - , <&key_physical_attrs 100 100 590 268 (-1000) 640 318> - , <&key_physical_attrs 100 100 685 232 (-1000) 735 282> - , <&key_physical_attrs 100 100 780 197 (-1000) 830 247> - , <&key_physical_attrs 100 100 882 198 (-1000) 932 248> - , <&key_physical_attrs 100 100 984 198 (-1000) 1034 248> - , <&key_physical_attrs 100 100 328 370 1500 378 420> - , <&key_physical_attrs 100 100 442 385 0 0 0> - , <&key_physical_attrs 100 100 542 385 0 0 0> - , <&key_physical_attrs 100 100 655 370 (-1500) 705 420> - ; - }; - - reviung34_single_2u_layout: reviung34_single_2u_layout { - compatible = "zmk,physical-layout"; - display-name = "Single 2U (33 keys)"; - - keys // w h x y rot rx ry - = <&key_physical_attrs 100 100 35 2 1000 85 52> - , <&key_physical_attrs 100 100 136 1 1000 186 51> - , <&key_physical_attrs 100 100 238 0 1000 288 50> - , <&key_physical_attrs 100 100 333 35 1000 383 85> - , <&key_physical_attrs 100 100 429 71 1000 479 121> - , <&key_physical_attrs 100 100 555 71 (-1000) 605 121> - , <&key_physical_attrs 100 100 650 35 (-1000) 700 85> - , <&key_physical_attrs 100 100 746 0 (-1000) 796 50> - , <&key_physical_attrs 100 100 847 1 (-1000) 897 51> - , <&key_physical_attrs 100 100 949 1 (-1000) 999 51> - , <&key_physical_attrs 100 100 17 100 1000 67 150> - , <&key_physical_attrs 100 100 119 99 1000 169 149> - , <&key_physical_attrs 100 100 221 98 1000 271 148> - , <&key_physical_attrs 100 100 316 134 1000 366 184> - , <&key_physical_attrs 100 100 411 169 1000 461 219> - , <&key_physical_attrs 100 100 572 169 (-1000) 622 219> - , <&key_physical_attrs 100 100 668 134 (-1000) 718 184> - , <&key_physical_attrs 100 100 763 98 (-1000) 813 148> - , <&key_physical_attrs 100 100 865 99 (-1000) 915 149> - , <&key_physical_attrs 100 100 966 100 (-1000) 1016 150> - , <&key_physical_attrs 100 100 0 198 1000 50 248> - , <&key_physical_attrs 100 100 102 198 1000 152 248> - , <&key_physical_attrs 100 100 203 197 1000 253 247> - , <&key_physical_attrs 100 100 298 232 1000 348 282> - , <&key_physical_attrs 100 100 394 268 1000 444 318> - , <&key_physical_attrs 100 100 590 268 (-1000) 640 318> - , <&key_physical_attrs 100 100 685 232 (-1000) 735 282> - , <&key_physical_attrs 100 100 780 197 (-1000) 830 247> - , <&key_physical_attrs 100 100 882 198 (-1000) 932 248> - , <&key_physical_attrs 100 100 984 198 (-1000) 1034 248> - , <&key_physical_attrs 100 100 328 370 1500 378 420> - , <&key_physical_attrs 200 100 442 385 0 0 0> - , <&key_physical_attrs 100 100 655 370 (-1500) 705 420> - ; - }; - - reviung34_position_map { - compatible = "zmk,physical-layout-position-map"; - - reviung34_dual_1u_posmap { - physical-layout = <&reviung34_dual_1u_layout>; - positions - = < 0 1 2 3 4 5 6 7 8 9> - , <10 11 12 13 14 15 16 17 18 19> - , <20 21 22 23 24 25 26 27 28 29> - , <30 31 33 32>; - }; - - reviung34_single_2u_posmap { - physical-layout = <&reviung34_single_2u_layout>; - positions - = < 0 1 2 3 4 5 6 7 8 9> - , <10 11 12 13 14 15 16 17 18 19> - , <20 21 22 23 24 25 26 27 28 29> - , <30 31 32>; - }; - }; -}; diff --git a/app/boards/shields/reviung34/reviung34.overlay b/app/boards/shields/reviung34/reviung34.overlay index 0e800a7d..0f58b99d 100644 --- a/app/boards/shields/reviung34/reviung34.overlay +++ b/app/boards/shields/reviung34/reviung34.overlay @@ -6,20 +6,10 @@ #include -#include "reviung34-layouts.dtsi" - -&reviung34_dual_1u_layout { - transform = <&dual_1u_transform>; -}; - -&reviung34_single_2u_layout { - transform = <&single_2u_transform>; -}; - / { chosen { zmk,kscan = &kscan0; - zmk,physical-layout = &reviung34_dual_1u_layout; + zmk,matrix-transform = &dual_1u_transform; }; dual_1u_transform: keymap_transform_0 { diff --git a/docs/docs/config/encoders.md b/docs/docs/config/encoders.md index 7f68a0e9..2052fc9d 100644 --- a/docs/docs/config/encoders.md +++ b/docs/docs/config/encoders.md @@ -55,8 +55,12 @@ Per sensor overrides can be added with ordered nested nodes with the correct ove }; ``` +:::note + The names of the child nodes are not important, and are applied in order to the sensors listed in the `sensors` property of the sensors node. +::: + Applies to the node and child nodes of: `compatible = "zmk,keymap-sensors"` Definition file: [zmk/app/drivers/zephyr/dts/bindings/zmk,keymap-sensors.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/drivers/zephyr/dts/bindings/zmk%2Ckeymap-sensors.yaml) diff --git a/docs/docs/development/contributing/documentation.md b/docs/docs/development/contributing/documentation.md index 26ba14fe..5bca6303 100644 --- a/docs/docs/development/contributing/documentation.md +++ b/docs/docs/development/contributing/documentation.md @@ -11,8 +11,6 @@ This document outlines how to test your documentation changes locally and prepar The documentation is written with [Docusaurus](https://docusaurus.io/). The ZMK source code has all of the necessary Docusaurus dependencies included, but referencing their documentation can be helpful at times. -The website is built using the latest LTS version of node, which is available at . - The general process for updating the ZMK documentation is: 1. Update the documentation @@ -20,6 +18,14 @@ The general process for updating the ZMK documentation is: 3. Ensure the sources are formatted properly and linted 4. Create a Pull Request for review and inclusion into the ZMK sources +:::note +If you are working with the documentation from within VS Code+Docker please be aware the documentation will not be auto-generated when making changes while the server is running. You'll need to restart the server when saving changes to the documentation. +::: + +:::note +You will need `Node.js` and `npm` installed to update the documentation. If you're using the ZMK dev container (Docker) the necessary dependencies are already installed. Otherwise, you must install these dependencies yourself. Since `Node.js` packages in Linux distributions tend to be outdated, it's recommended to install the current version from a repository like [NodeSource](https://github.com/nodesource/distributions) to avoid build errors. +::: + ## Testing Documentation Updates Locally To verify documentation updates locally, follow the following procedure. The `npm` commands and first step will need to be run from a terminal. @@ -46,9 +52,15 @@ The check commands can be run with the following procedure in a terminal that's 3. Run `npm run lint` 4. Run `npm run build` +:::danger If any of the above steps throw an error, they need to be addressed and all of the checks re-run prior to submitting a pull request. +::: -The documentation uses American English spelling and grammar conventions. Title case is used for the first three heading levels, with sentence case used beyond that. Please make sure your changes conform to these conventions. +:::note +The documentation uses American English spelling and grammar conventions. Title case is used for the first three heading levels, with sentence case used beyond that. + +Please make sure your changes conform to these conventions - prettier and lint are unfortunately unable to do this automatically. +::: ## Submitting a Pull Request diff --git a/docs/docs/development/module-creation.md b/docs/docs/development/module-creation.md index f3d351d7..f12a1944 100644 --- a/docs/docs/development/module-creation.md +++ b/docs/docs/development/module-creation.md @@ -12,7 +12,9 @@ sidebar_label: ZMK Module Creation See also Zephyr's [page on modules](https://docs.zephyrproject.org/4.1.0/develop/modules.html). -For open source hardware designs, it's recommended to **not** include the hardware design files in the ZMK module itself, since the module will be fetched by users during build and having design files in the module would likely make the module unnecessarily large and slow to fetch. +:::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. +::: ## Module Setup @@ -131,15 +133,15 @@ Note that the `include` and `src` folders are not mandated by the module system, Modules should expose all provided header files with an include path name beginning with the module-name, for example at `include/zmk__/
.h`. :::info -If your module requires adding drivers to existing subsystems in modules, you will need to use the `zephyr_library_amend()` CMake command, which requires you to have a specific directory structure. See [`zephyr/cmake/modules/extensions.cmake`](https://github.com/zephyrproject-rtos/zephyr/blob/main@%7B2025-Feb-15%7D/cmake/modules/extensions.cmake#L492) for the definition and some documentation in the comments, with an example in [`petejohanson/ec-support-zmk-module`](https://github.com/petejohanson/ec-support-zmk-module/tree/main/drivers/kscan). +If your module requires adding drivers to existing subsystems in modules, you will need to use the `zephyr_library_amend()` CMake command, which requires you to have a specific directory structure. See [here](https://github.com/zephyrproject-rtos/zephyr/blob/main/cmake/modules/extensions.cmake#L454) for the definition and some documentation in the comments, with an example [here](https://github.com/petejohanson/ec-support-zmk-module/tree/main/drivers/kscan). ::: ## Examples Below are some examples of modules for different types. Unless under the `zmkfirmware` project, these are not endorsed officially and may not follow our conventions perfectly. For such reason, the modules chosen to be presented here may change with time. -- Keyboard: -- Behavior: -- Driver: -- Feature: -- VFX: +- Keyboard: https://github.com/petejohanson/zmk-keyboards-katori +- Behavior: https://github.com/urob/zmk-leader-key +- Driver: https://github.com/petejohanson/cirque-input-module +- Feature: https://github.com/joelspadin/zmk-locales +- VFX: https://github.com/caksoylar/zmk-rgbled-widget diff --git a/docs/docs/features/led-indicators.md b/docs/docs/features/led-indicators.md index f017d5cd..b4a6ddab 100644 --- a/docs/docs/features/led-indicators.md +++ b/docs/docs/features/led-indicators.md @@ -54,10 +54,14 @@ For example, if you want the LED to be off when the indicator is active, 100% br }; ``` +:::note + If the LED is not configured to support brightness control, any value greater than 0 will result in maximum brightness. For most LEDs, you can enable PWM brightness control, though this will increase power usage slightly. See the [LED indicators hardware integration page](../hardware-integration/lighting/led-indicators.md) for details on configuring the LEDs. +::: + ## Adding LED Indicator Support to a Keyboard See the [LED indicators hardware integration page](../hardware-integration/lighting/led-indicators.md) for instructions to enable this feature on a keyboard. diff --git a/docs/docs/features/lighting.md b/docs/docs/features/lighting.md index 2276488e..c2a6699b 100644 --- a/docs/docs/features/lighting.md +++ b/docs/docs/features/lighting.md @@ -11,7 +11,7 @@ Your keyboard likely uses only one type, depending on the type of LED hardware i - [Backlight](#backlight) system controls parallel-connected, non-addressable, single color LEDs. These are found on keyboards that have a single color backlight that only allows for brightness control. -:::info +:::warning Although the naming of the systems might imply it, which system you use typically does _not_ depend on the physical location of the LEDs. Instead, you should use the one that supports the LED hardware type that your keyboard has, as described above. diff --git a/docs/docs/features/low-power-states.md b/docs/docs/features/low-power-states.md index d428d0eb..5e0a384b 100644 --- a/docs/docs/features/low-power-states.md +++ b/docs/docs/features/low-power-states.md @@ -44,9 +44,13 @@ It is recommended to add the `wakeup-source` property to `kscan` devices even if The soft off feature is used to turn the keyboard on and off explicitly, rather than through a timeout like the deep sleep feature. Depending on the keyboard, this may be through a dedicated on/off push button defined in hardware, or merely through an additional binding in the keymap to turn the device off and an existing reset button to turn the device back on. +The feature is intended as an alternative to using a hardware switch to physically cut power from the battery to the keyboard. This can be useful for existing PCBs not designed for wireless that don't have a power switch, or for new designs that favor a push button on/off like found on other devices. It yields power savings comparable to the deep sleep state. + +:::note + The device enters the same software power-off state as in deep sleep, but is significantly more restrictive in the sources which can wake it. Power is _not_ technically removed from the entire system, unlike a hardware switch. -The feature is intended as an alternative to using a hardware switch to physically cut power from the battery to the keyboard. This can be useful for existing PCBs not designed for wireless that don't have a power switch, or for new designs that favor a push button on/off like found on other devices. It yields power savings comparable to the deep sleep state. +::: A device can be put in the soft off state by: diff --git a/docs/docs/features/studio.md b/docs/docs/features/studio.md index 19760245..82e256e2 100644 --- a/docs/docs/features/studio.md +++ b/docs/docs/features/studio.md @@ -6,7 +6,7 @@ ZMK Studio provides runtime update functionality to ZMK powered devices, allowin :::info -To use ZMK Studio, a keyboard needs to be [configured appropriately](#adding-zmk-studio-support-to-a-keyboard). ZMK has updated some, but not all, of its in-tree keyboards for use with ZMK Studio, the list of which can be found in the [ZMK Studio blog post](/blog/2024/11/11/zmk-studio-mvp-ga). If your keyboard is supported by an external module/config, check with the maintainer to see if support has been added. +To use ZMK Studio, a keyboard needs to be [configured appropriately](#adding-zmk-studio-support-to-a-keyboard). ZMK has updated some, but not all, of its in-tree keyboards for use with ZMK Studio, the list of which can be found [here](/blog/2024/11/11/zmk-studio-mvp-ga). If your keyboard is supported by an external module/config, check with the maintainer to see if support has been added. ::: @@ -54,7 +54,7 @@ Generally, if you intend to use ZMK Studio, then you should not make any further ## Accessing ZMK Studio -You can use ZMK Studio with Chrome/Edge at . +You can use ZMK Studio with Chrome/Edge at https://zmk.studio/. To use the native app for Linux, macOS, or Windows, visit the [download page](https://zmk.studio/download). diff --git a/docs/docs/hardware-integration/lighting/underglow.md b/docs/docs/hardware-integration/lighting/underglow.md index 61ecacf6..f891c56e 100644 --- a/docs/docs/hardware-integration/lighting/underglow.md +++ b/docs/docs/hardware-integration/lighting/underglow.md @@ -15,10 +15,12 @@ For example: the `kyria` shield has a [`boards/nice_nano_nrf52840_zmk.overlay`]( ### nRF52-Based Boards -Using an SPI-based LED strip driver on the `&spi3` interface is the simplest option for nRF52-based boards. +Using an SPI-based LED strip driver on the `&spi3` interface is the simplest option for nRF52-based boards. If possible, avoid using pins which are limited to low-frequency I/O for this purpose. The resulting interference may result in poor wireless performance. :::info -If possible, avoid using pins which are limited to low-frequency I/O for this purpose. The resulting interference may result in poor wireless performance. The list of low frequency I/O pins for the nRF52840 can be found at . + +The list of low frequency I/O pins for the nRF52840 can be found [here](https://docs.nordicsemi.com/bundle/ps_nrf52840/page/pin.html). + ::: The following example uses `P0.06` as the "Data In" pin of a WS2812-compatible LED strip: @@ -67,9 +69,13 @@ The following example uses `P0.06` as the "Data In" pin of a WS2812-compatible L }; ``` +:::note + Standard WS2812 LEDs use a wire protocol where the bits for the colors green, red, and blue values are sent in that order. If your board/shield uses LEDs that require the data sent in a different order, the `color-mapping` property ordering should be changed to match. +::: + ### Other Boards Be sure to check the Zephyr documentation for the LED strip and necessary hardware bindings. Not every board has an `spi3` node, or configures `pinctrl` the same way. Reconcile this with any hardware restrictions found in the manufacturer's datasheet. Additional hardware interfaces may need to be enabled via Kconfig. diff --git a/docs/docs/hardware-integration/new-board.md b/docs/docs/hardware-integration/new-board.md index 3450cdfd..3b1a98d0 100644 --- a/docs/docs/hardware-integration/new-board.md +++ b/docs/docs/hardware-integration/new-board.md @@ -32,7 +32,7 @@ This guide assumes you already have a configured GitHub account. If you don't ye Follow these steps to create your new repository: -- Visit +- Visit https://github.com/zmkfirmware/unified-zmk-config-template - Click the green "Use this template" button - In the drop down that opens, click "Use this template". - In the following screen, provide the following information: diff --git a/docs/docs/hardware-integration/physical-layouts.md b/docs/docs/hardware-integration/physical-layouts.md index 60a29a8d..4678e0f7 100644 --- a/docs/docs/hardware-integration/physical-layouts.md +++ b/docs/docs/hardware-integration/physical-layouts.md @@ -62,7 +62,11 @@ A key description has the shape `<&key_physical_attrs w h x y r rx ry>` with the You can specify negative values in devicetree using parentheses around it, e.g. `(-3000)` for a 30 degree counterclockwise rotation. -We recommend the use of for writing a physical layout or converting one from a QMK JSON definition. If your keyboard already has a physical layout defined for the use with KLE, we recommend using first to convert your existing layout into QMK JSON. The second tool can also import the position data from KiCAD, if said program was used to design the keyboard. +:::tip + +We recommend the use of [this tool](https://zmk-physical-layout-converter.streamlit.app/) for writing a physical layout or converting one from a QMK JSON definition. If your keyboard already has a physical layout defined for the use with KLE, we recommend using [this other tool](https://nickcoutsos.github.io/keymap-layout-tools/) first to convert your existing layout into QMK JSON. The second tool can also import the position data from KiCAD, if said program was used to design the keyboard. + +::: ### Physical Layout with Keys Example @@ -203,7 +207,11 @@ The position map should be marked as `complete` if all desired binding transfers See also the [configuration section on position maps](../config/layout.md#physical-layout-position-map). -We recommend the use of , distinct from the previous two mentioned, for the purposes of writing a position map. +:::tip + +We recommend the use of [this tool](https://zmk-layout-helper.netlify.app/), distinct from the previous two mentioned, for the purposes of writing a position map. + +::: #### Writing a position map diff --git a/docs/docs/hardware-integration/pinctrl.mdx b/docs/docs/hardware-integration/pinctrl.mdx index 67dec613..f634cb14 100644 --- a/docs/docs/hardware-integration/pinctrl.mdx +++ b/docs/docs/hardware-integration/pinctrl.mdx @@ -8,11 +8,15 @@ import TabItem from "@theme/TabItem"; 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/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/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 @@ -29,8 +33,10 @@ Pin control is always defined for a _board_, never for a shield: ``` Note that you will need to define a separate overlay _for each_ of the boards to be used with the shield. +:::info Assume that the shield that you are using is found in-tree of ZMK or within an external module, and _does not_ contain the overlay for the board that you wish to use. If this is the case, then you should fork the source repository and add the overlay to the fork. Use said fork to build your firmware, and potentially submit a PR to upstream. +::: ## Predefined Nodes diff --git a/docs/docs/hardware-integration/shift-registers.md b/docs/docs/hardware-integration/shift-registers.md index 4a5f02a9..01bc35e6 100644 --- a/docs/docs/hardware-integration/shift-registers.md +++ b/docs/docs/hardware-integration/shift-registers.md @@ -9,7 +9,9 @@ Shift registers are the recommended method of adding additional GPIO pins to MCU This page assumes that you are using a SIPO shift register with the part number 74HC595. Other shift registers can work as well but this is the most commonly used one. ::: +:::tip To understand how shift registers work, we recommend reading through ["How does the 74HC595 Shift Register work?"](https://lastminuteengineers.com/74hc595-shift-register-arduino-tutorial/#how-does-the-74hc595-shift-register-work). +::: ## Design Guidelines diff --git a/docs/docs/keymaps/behaviors/hold-tap.mdx b/docs/docs/keymaps/behaviors/hold-tap.mdx index c4d27d9d..2006a577 100644 --- a/docs/docs/keymaps/behaviors/hold-tap.mdx +++ b/docs/docs/keymaps/behaviors/hold-tap.mdx @@ -372,10 +372,12 @@ Including `hold-trigger-key-positions` in your hold-tap definition turns on the In all other situations, positional hold-tap will not modify the behavior of your hold-tap. Positional hold-tap is useful when used with home-row modifiers: for example, if you have a home-row modifier key in the left hand, by including only key positions from the right hand in `hold-trigger-key-positions`, you will only get hold behaviors during cross-hand key combinations unless you exceed `tapping-term-ms` when using "balanced" or "hold-preferred" flavors. -`hold-trigger-key-positions` is an array of key position indexes. Key positions are numbered sequentially according to your keymap, starting with 0. So if the first key in your keymap is Q, this key is in position 0. The next key (probably W) will be in position 1, et cetera. - For home-row mods, it is recommended to use this property with `hold-trigger-on-release` so that modifiers on the same hand can be combined. +:::info +`hold-trigger-key-positions` is an array of key position indexes. Key positions are numbered sequentially according to your keymap, starting with 0. So if the first key in your keymap is Q, this key is in position 0. The next key (probably W) will be in position 1, et cetera. +::: +
The following example uses a hold-tap behavior definition configured with the `hold-preferred` flavor, and with positional hold-tap enabled: diff --git a/docs/docs/keymaps/behaviors/macros.md b/docs/docs/keymaps/behaviors/macros.md index 45780bfa..a06efaf3 100644 --- a/docs/docs/keymaps/behaviors/macros.md +++ b/docs/docs/keymaps/behaviors/macros.md @@ -312,6 +312,10 @@ To avoid repetition or possible typos when declaring a **zero parameter macro**, ) ``` +:::note +`ZMK_MACRO()` **only supports declaring non-parameterized (zero parameter) macros**; parameterized declarations are not currently supported. +::: + This can be used instead of a complete macro definition. During the firmware build process, the example above would produce the complete macro definition below: ```dts diff --git a/docs/docs/keymaps/behaviors/power.md b/docs/docs/keymaps/behaviors/power.md index f118d0ca..1814e67c 100644 --- a/docs/docs/keymaps/behaviors/power.md +++ b/docs/docs/keymaps/behaviors/power.md @@ -48,7 +48,7 @@ The on/off state that is set by the `&ext_power` behavior will be [saved to flas However it will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE`](../../config/system.md#general) milliseconds in order to reduce potential wear on the flash memory. ::: -### Examples +### Example: 1. Behavior binding to enable the external power diff --git a/docs/docs/keymaps/input-processors/behaviors.md b/docs/docs/keymaps/input-processors/behaviors.md index 032774c7..9bda1dfa 100644 --- a/docs/docs/keymaps/input-processors/behaviors.md +++ b/docs/docs/keymaps/input-processors/behaviors.md @@ -7,8 +7,12 @@ sidebar_label: Behaviors The behaviors input processor is used invoke standard behaviors when certain input events occur; most frequently this is used to trigger behaviors when certain mouse buttons are triggered by physical pointing devices. +:::note + This input processor is primarily intended for `INPUT_EV_KEY` type of events that have a binary on/off state, not vector types for relative or absolute movements. +::: + :::note[Source-specific behaviors on split keyboards] Invoking a [source-specific behavior](../../features/split-keyboards.md#source-locality-behaviors) such as one of the [reset behaviors](../behaviors/reset.md) using this input processor will always trigger it on the central side of the keyboard, regardless of the side includes the input device that originally generated the input event. ::: diff --git a/docs/docs/keymaps/list-of-keycodes.mdx b/docs/docs/keymaps/list-of-keycodes.mdx index 3ee88367..c62d5875 100644 --- a/docs/docs/keymaps/list-of-keycodes.mdx +++ b/docs/docs/keymaps/list-of-keycodes.mdx @@ -9,6 +9,11 @@ import Table from "@site/src/components/codes/Table"; This is the reference page for keycodes used by behaviors. Use the table of contents (on the right or the top) for easy navigation. +:::warning +Take extra notice of the spelling of the keycodes, especially the shorthand spelling. +Otherwise, it will result in an elusive parsing error! +::: + :::info[Keyboard vs. Consumer keycodes] In the below tables, there are keycode pairs with similar names where one variant has a `K_` prefix and another `C_`. These variants correspond to similarly named usages from different [HID usage pages](https://usb.org/sites/default/files/hut1_2.pdf#page=16), diff --git a/docs/docs/troubleshooting/building-issues.md b/docs/docs/troubleshooting/building-issues.md index ca53e9bf..fb256ef8 100644 --- a/docs/docs/troubleshooting/building-issues.md +++ b/docs/docs/troubleshooting/building-issues.md @@ -53,10 +53,12 @@ A `devicetree_generated.h` error that follows with an "undeclared here" string i In this example, the error string `DT_N_S_keymap_S_symbol_layer_P_bindings_IDX_12_PH_P_label` indicates a problem with the key binding in position `12` in the `symbol_layer` of the keymap. +:::info Key positions are numbered starting from `0` at the top left key on the keymap, incrementing horizontally, row by row. +::: :::tip -A common mistake that leads to this error is to use [key press keycodes](keymaps/behaviors/key-press.md) without the leading `&kp` binding. That is, having entries such as `&kp A SPACE &kp B` that should have been `&kp A &kp SPACE &kp B`. +A common mistake that leads to this error is to use [key press keycodes](keymaps/behaviors/key-press.md) without the leading `&kp` binding. That is, having entries such as `SPACE` that should have been `&kp SPACE`. ::: ## Diagnosing Unexpected Build Results diff --git a/docs/package-lock.json b/docs/package-lock.json index f046e505..d5b9cfa7 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -10230,9 +10230,9 @@ } }, "node_modules/dompurify": { - "version": "3.4.2", - "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.2.tgz", - "integrity": "sha512-lHeS9SA/IKeIFFyYciHBr2n0v1VMPlSj843HdLOwjb2OxNwdq9Xykxqhk+FE42MzAdHvInbAolSE4mhahPpjXA==", + "version": "3.4.11", + "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.11.tgz", + "integrity": "sha512-zhlUV12GsaRzMsf9q5M254YhA4+VuF0fG+QFqu6aYpoGlKtz+w8//jBcGVYBgQkR5GHjUomejY84AV+/uPbWdw==", "license": "(MPL-2.0 OR Apache-2.0)", "optionalDependencies": { "@types/trusted-types": "^2.0.7" @@ -13847,13 +13847,13 @@ } }, "node_modules/launch-editor": { - "version": "2.14.1", - "resolved": "https://registry.npmjs.org/launch-editor/-/launch-editor-2.14.1.tgz", - "integrity": "sha512-QWBrQsMpH7gPr965dsKD/3cKWiNoTjpATQf++Xq63N6sKRGMwlVXz41O1IZTMfZQgBctD/K5Zt06+/I6pP6+HA==", + "version": "2.13.2", + "resolved": "https://registry.npmjs.org/launch-editor/-/launch-editor-2.13.2.tgz", + "integrity": "sha512-4VVDnbOpLXy/s8rdRCSXb+zfMeFR0WlJWpET1iA9CQdlZDfwyLjUuGQzXU4VeOoey6AicSAluWan7Etga6Kcmg==", "license": "MIT", "dependencies": { "picocolors": "^1.1.1", - "shell-quote": "^1.8.4" + "shell-quote": "^1.8.3" } }, "node_modules/layout-base": { @@ -20819,9 +20819,9 @@ } }, "node_modules/shell-quote": { - "version": "1.8.4", - "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.8.4.tgz", - "integrity": "sha512-VsC6n6vz1ihYYyZZwX7YZSF5l5x36ca17OC+a69h94YqB7X6XLwf+5MOgynYir2SLFUbl8gIYvBo8K8RoNQ6bQ==", + "version": "1.8.3", + "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.8.3.tgz", + "integrity": "sha512-ObmnIF4hXNg1BqhnHmgbDETF8dLPCggZWBjkQfhZpbszZnYur5DUljTcCHii5LC3J5E0yeO/1LIMyH+UvHQgyw==", "license": "MIT", "engines": { "node": ">= 0.4" @@ -23154,9 +23154,9 @@ } }, "node_modules/webpack-dev-server": { - "version": "5.2.5", - "resolved": "https://registry.npmjs.org/webpack-dev-server/-/webpack-dev-server-5.2.5.tgz", - "integrity": "sha512-4wZtCquSuv9CKX8oybo+mqxtxZqWz47uM1Ch94lxowBztOhWCbhqvRbfC/mODOwxgV2brY+JGZpHq58/SuVFYg==", + "version": "5.2.4", + "resolved": "https://registry.npmjs.org/webpack-dev-server/-/webpack-dev-server-5.2.4.tgz", + "integrity": "sha512-GqDPGZN9bRqKBTkp4aWkobDDHMsrXKoGSdOH56smIri8qR0JG8gfL8/v/f/OZR3/OKXjG8uwJbFVhKm/FNU/UA==", "license": "MIT", "dependencies": { "@types/bonjour": "^3.5.13", @@ -23241,9 +23241,9 @@ } }, "node_modules/webpack-dev-server/node_modules/ws": { - "version": "8.21.0", - "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz", - "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==", + "version": "8.20.0", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.20.0.tgz", + "integrity": "sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA==", "license": "MIT", "engines": { "node": ">=10.0.0" @@ -23636,9 +23636,9 @@ } }, "node_modules/ws": { - "version": "7.5.11", - "resolved": "https://registry.npmjs.org/ws/-/ws-7.5.11.tgz", - "integrity": "sha512-zS54Oen9bITtp7kp2XM3AydrCIq1D+HwJOuH+c+e4LfpL/lotP5osijd+UoMnxwAam1GN8R4KtLAyIrIcBNpiA==", + "version": "7.5.10", + "resolved": "https://registry.npmjs.org/ws/-/ws-7.5.10.tgz", + "integrity": "sha512-+dbF1tHwZpXcbOJdVOkzLDxZP1ailvSxM6ZweXTegylPny803bFhA+vqBYw4s31NSAk4S2Qz+AKXK9a4wkdjcQ==", "license": "MIT", "engines": { "node": ">=8.3.0"