From 532c1987b2b464053d5e85c71a775e83e758c1e7 Mon Sep 17 00:00:00 2001 From: innovaker <66737976+innovaker@users.noreply.github.com> Date: Thu, 12 Nov 2020 12:18:45 +0000 Subject: refactor(docs): Move `dev-` documents into `/development` Aligns to conventions introduced by newer documentation. --- docs/docs/customization.md | 2 +- docs/docs/dev-boards-shields-keymaps.md | 52 --- docs/docs/dev-build-flash.md | 128 ------ docs/docs/dev-clean-room.md | 28 -- docs/docs/dev-guide-new-shield.md | 512 ---------------------- docs/docs/dev-guide-usb-logging.md | 103 ----- docs/docs/dev-posix-board.md | 38 -- docs/docs/dev-setup.md | 554 ------------------------ docs/docs/dev-tests.md | 20 - docs/docs/development/boards-shields-keymaps.md | 52 +++ docs/docs/development/build-flash.md | 128 ++++++ docs/docs/development/clean-room.md | 28 ++ docs/docs/development/guide-new-shield.md | 512 ++++++++++++++++++++++ docs/docs/development/guide-usb-logging.md | 103 +++++ docs/docs/development/posix-board.md | 38 ++ docs/docs/development/setup.md | 554 ++++++++++++++++++++++++ docs/docs/development/tests.md | 20 + docs/docs/features/encoders.md | 2 +- docs/docs/hardware.md | 2 +- docs/docs/troubleshooting.md | 2 +- docs/docs/user-setup.md | 2 +- docs/docusaurus.config.js | 2 +- docs/sidebars.js | 17 +- 23 files changed, 1451 insertions(+), 1448 deletions(-) delete mode 100644 docs/docs/dev-boards-shields-keymaps.md delete mode 100644 docs/docs/dev-build-flash.md delete mode 100644 docs/docs/dev-clean-room.md delete mode 100644 docs/docs/dev-guide-new-shield.md delete mode 100644 docs/docs/dev-guide-usb-logging.md delete mode 100644 docs/docs/dev-posix-board.md delete mode 100644 docs/docs/dev-setup.md delete mode 100644 docs/docs/dev-tests.md create mode 100644 docs/docs/development/boards-shields-keymaps.md create mode 100644 docs/docs/development/build-flash.md create mode 100644 docs/docs/development/clean-room.md create mode 100644 docs/docs/development/guide-new-shield.md create mode 100644 docs/docs/development/guide-usb-logging.md create mode 100644 docs/docs/development/posix-board.md create mode 100644 docs/docs/development/setup.md create mode 100644 docs/docs/development/tests.md (limited to 'docs') diff --git a/docs/docs/customization.md b/docs/docs/customization.md index d0d3749..626a291 100644 --- a/docs/docs/customization.md +++ b/docs/docs/customization.md @@ -39,7 +39,7 @@ If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https: ## Building from a local `zmk` fork using `zmk-config` -[As outlined here](dev-build-flash), firmware comes in the form of .uf2 files, which can be built locally using the command `west build`. Normally, +[As outlined here](development/build-flash), firmware comes in the form of .uf2 files, which can be built locally using the command `west build`. Normally, `west build` will default to using the in-tree .keymap and .conf files found in your local copy of the `zmk` repository. However, you can append the command, `-DZMK_CONFIG="C:/the/absolute/path/config"` to `west build` in order to use the contents of your `zmk-config` folder instead of the default keyboard settings. **Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.** diff --git a/docs/docs/dev-boards-shields-keymaps.md b/docs/docs/dev-boards-shields-keymaps.md deleted file mode 100644 index 119db42..0000000 --- a/docs/docs/dev-boards-shields-keymaps.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Boards, Shields, and Keymaps ---- - -## Architecture Overview - -The foundational elements needed to get a specific keyboard working with ZMK can be broken down into: - -- A [KSCAN driver](https://docs.zephyrproject.org/2.3.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. - -These three core architectural elements are defined per-keyboard, and _where_ they are defined depends on the specifics of how that -keyboard works. For an overview on the general concepts of boards and shields, please see the [FAQs on boards and shields](/docs/faq#why-boards-and-shields--why-not-just-keyboard). - -## Self-Contained Keyboard - -For a self-contained keyboard that includes the microprocessor, all of the above architecture components are included in the Zephyr _board_ definition. You can see an example for the [Planck V6](https://github.com/zmkfirmware/zmk/tree/main/app/boards/arm/planck) board directory. - -With this type of keyboard, the full ZMK definition for the keyboard exists -in the `app/boards/${arch}/${board_name}` directory, e.g. `app/boards/arm/planck/`. In that directory, you'll have the following: - -- A `Kconfig.board` file that defines the toplevel Kconfig item 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` to a value, for the product name to be used for USB/BLE info. - - Setting `ZMK_USB` and/or `ZMK_BLE` for the default values for which HID transport(s) to enable by default -- 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 `. - - A [chosen](https://docs.zephyrproject.org/2.3.0/guides/dts/intro.html#aliases-and-chosen-nodes) node named `zmk,kscan` which references the configured KSCAN driver (usually a GPIO matrix) - - (Optional) A [chosen](https://docs.zephyrproject.org/2.3.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 `keymap/keymap.overlay` file that includes the default keymap for that keyboard. Users will be able to override this keymap in their user configs. - -## Pro Micro Compatible Keyboard - -![Labelled Pro Micro pins](assets/pro-micro/pro-micro-pins-labelled.jpg) - -For keyboards that require a (usually Pro Micro compatible) add-on board to operate, the ZMK integration pieces are places -in the _shield_ definition for that keyboard, allowing users to -swap in different Pro Micro compatible boards (e.g. Proton-C, or nice!nano) and build a firmware the matches their actual -combination of physical components. - -With this type of keyboard, the partial definition for the keyboard exists -in the `app/boards/shields/${board_name}` directory, e.g. `app/boards/shields/clueboard_california/`. In that directory, you'll have the following: - -- A `Kconfig.shield` that defines the toplevel Kconfig value for the shield, which uses a supplied utility to function to default the value based on the shield list, e.g. `def_bool $(shields_list_contains,clueboard_california)`. -- A `Kconfig.defconfig` file to set default values for things like `ZMK_KEYBOARD_NAME` -- A `${shield_name}.overlay` file, which is a devicetree overlay file, that includes: - - A [chosen](https://docs.zephyrproject.org/2.3.0/guides/dts/intro.html#aliases-and-chosen-nodes) node named `zmk,kscan` which references the configured KSCAN driver (usually a GPIO matrix). For these keyboards, to be compatible with any Pro Micro compatible boards, the KSCAN configuration should reference the [nexus node](https://docs.zephyrproject.org/2.3.0/guides/porting/shields.html#gpio-nexus-nodes) that ZMK has standardized on. In particular, the `&pro_micro_a` and `&pro_micro_d` aliases can be used to reference the standard `A#` and `D#` pins in shields. - - (Optional) A [chosen](https://docs.zephyrproject.org/2.3.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. diff --git a/docs/docs/dev-build-flash.md b/docs/docs/dev-build-flash.md deleted file mode 100644 index 304ea32..0000000 --- a/docs/docs/dev-build-flash.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: Building and Flashing -sidebar_label: Building and Flashing ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -export const OsTabs = (props) => ({props.children}); - -## Building - -From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout: - -```sh -cd app -``` - -To build for your particular keyboard, the behaviour varies slightly depending on if you are building for a keyboard with -an onboard MCU, or one that uses an MCU board addon. - -### Keyboard (Shield) + MCU Board - -ZMK treats keyboards that take an MCU addon board as [shields](https://docs.zephyrproject.org/2.3.0/guides/porting/shields.html), and treats the smaller MCU board as the true [board](https://docs.zephyrproject.org/2.3.0/guides/porting/board_porting.html) - -Given the following: - -- MCU Board: Proton-C -- Keyboard PCB: kyria_left -- Keymap: default - -You can build ZMK with the following: - -```sh -west build -b proton_c -- -DSHIELD=kyria_left -``` - -### Keyboard With Onboard MCU - -Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/2.3.0/guides/porting/board_porting.html) as far as Zephyr™ is concerned. - -Given the following: - -- Keyboard: Planck (rev6) -- Keymap: default - -you can build ZMK with the following: - -```sh -west build -b planck_rev6 -``` - -### Pristine Building - -When building for a new board and/or shield after having built one previously, you may need to enable the pristine build option. This option removes all existing files in the build directory before regenerating them, and can be enabled by adding either --pristine or -p to the command: - -```sh -west build -p -b proton_c -- -DSHIELD=kyria_left -``` - -### Building For Split Keyboards - -:::note -For split keyboards, you will have to build and flash each side separately the first time you install ZMK. -::: - -By default, the `build` command outputs a single .uf2 file named `zmk.uf2` so building left and then right immediately after will overwrite your left firmware. In addition, you will need to pristine build each side to ensure the correct files are used. To avoid having to pristine build every time and separate the left and right build files, we recommend setting up separate build directories for each half. You can do this by using the `-d` parameter and first building left into `build/left`: - -``` -west build -d build/left -b nice_nano -- -DSHIELD=kyria_left -``` - -and then building right into `build/right`: - -``` -west build -d build/right -b nice_nano -- -DSHIELD=kyria_right -``` - -This produces `left` and `right` subfolders under the `build` directory and two separate .uf2 files. For future work on a specific half, use the `-d` parameter again to ensure you are building into the correct location. - -### Building from `zmk-config` Folder - -Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](user-setup#github-repo) by adding -`-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build` command. **Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.** - -For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this: - -``` -west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config" -``` - -In order to make your `zmk-config` folder available when building within the VSCode Remote Container, you need to create a docker volume named `zmk-config` -by binding it to the full path of your config directory. If you have run the VSCode Remote Container before, it is likely that docker has created this -volume automatically -- we need to delete the default volume before binding it to the correct path. Follow the following steps: - -1. Stop the container by exiting VSCode. You can verify no container is running via the command `docker ps`. -1. Remove all the containers that are not running via the command `docker container prune`. We need to remove the ZMK container before we can delete the default `zmk-config` volume referenced by it. If you do not want to delete all the containers that are not running, you can find the id of the ZMK container and use `docker rm` to delete that one only. -1. Remove the default volume via the command `docker volume rm zmk-config`. - -Then you can bind the `zmk-config` volume to the correct path pointing to your local [zmk-config](./customization.md) folder: - -``` -docker volume create --driver local -o o=bind -o type=none -o \ - device="/full/path/to/your/zmk-config/" zmk-config -``` - -Now start VSCode and rebuild the container after being prompted. You should be able to see your zmk-config mounted to `/workspaces/zmk-config` inside the container. So you can build your custom firmware with `-DZMK_CONFIG="/workspaces/zmk-config/config"`. - -## Flashing - -Once built, the previously supplied parameters will be remembered so you can run the following to flash your -board with it in bootloader mode: - -``` -west flash -``` - -For boards that have drag and drop .uf2 flashing capability, the .uf2 file to flash can be found in `build/zephyr` (or `build/left|right/zephyr` if you followed the instructions for splits) and is by default named `zmk.uf2`. diff --git a/docs/docs/dev-clean-room.md b/docs/docs/dev-clean-room.md deleted file mode 100644 index 82db3a0..0000000 --- a/docs/docs/dev-clean-room.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Clean Room Implementation -sidebar_label: Clean Room ---- - -:::warning - -Anyone wanting to contribute code to ZMK _MUST_ read this, and adhere to the steps outlines in order to not violate any licenses/copyright of other projects - -::: - -ZMK Firmware is a [clean room design](https://en.wikipedia.org/wiki/Clean_room_design) keyboard firmware, that -borrows/implements a lot of the features found in popular keyboard firmwares projects like [QMK](https://qmk.fm) -and [TMK](https://github.com/tmk/tmk_keyboard). However, in order for ZMK to use the MIT, it _must_ not -incorporate any of the GPL licensed code from those projects. - -In order to achieve this, all code for ZMK has been implemented completely fresh, _without_ referencing, copying, -or duplicating any of the GPL code found in those other projects, even though they are open source software. - -## Contributor Requirements - -Contributors to ZMK must adhere to the following standard. - -- Implementations of features for ZMK _MUST NOT_ reuse any existing code from any projects not licensed with the MIT license. -- Contributors _MUST NOT_ study or refer to any GPL licensed source code while working on ZMK. -- Contributors _MAY_ read the documentation from other GPL licensed projects, to gain a broad understanding of the behavior of certain features in order to implement equivalent features for ZMK. -- Contributors _MAY_ refer to the [QMK Configurator](https://config.qmk.fm/) to inspect existing layouts/keymaps for - keyboards, and re-implement them for ZMK. diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md deleted file mode 100644 index 0e8f9f0..0000000 --- a/docs/docs/dev-guide-new-shield.md +++ /dev/null @@ -1,512 +0,0 @@ ---- -title: New Keyboard Shield ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import KeymapExampleFile from './keymap-example-file.md'; - -## Overview - -This guide will walk through the steps necessary to add ZMK support for a keyboard the uses a (Pro Micro compatible) addon MCU board to provide the microprocessor. -The high level steps are: - -- 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. -- (Optional) Add the matrix transform for mapping KSCAN row/column values to sane key positions. This is needed for non-rectangular keyboards, or where the underlying row/column pin arrangement does not map one to one with logical locations on the keyboard. -- Add a default keymap, which users can override in their own configs as needed. -- Add support for features such as encoders, OLED displays, or RGB underglow. -- Update build.yml - -It may be helpful to review the upstream [shields documentation](https://docs.zephyrproject.org/2.3.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. -::: - -## New Shield Directory - -:::note -This guide describes how to add shield to the ZMK main repository. If you are building firmware for your -own prototype or handwired keyboard, it is recommended to use your own user config repository. Follow the -[user setup guide](./user-setup.md) to create your user config repository first. When following the rest -of this guide, replace the `app/` directory in the ZMK main repository with the `config/` directory in your -user config repository. For example, `app/boards/shields/` should now be -`config/boards/shields/`. -::: - -Shields for Zephyr applications go into the `boards/shields/` directory; since ZMK's Zephyr application lives in the `app/` subdirectory of the repository, that means the new shield directory should be: - -```bash -mkdir app/boards/shields/ -``` - -## Base Kconfig Files - -There are two required Kconfig files that need to be created for your new keyboard -shield to get it picked up for ZMK, `Kconfig.shield` and `Kconfig.defconfig`. - -### Kconfig.shield - -The `Kconfig.shield` file defines any additional Kconfig settings that may be relevant when using this keyboard. For most keyboards, there is just one additional configuration value for the shield itself, e.g.: - -``` -config SHIELD_MY_BOARD - def_bool $(shields_list_contains,my_board) -``` - -This will make sure the new configuration `SHIELD_MY_BOARD` is set to true whenever `my_board` is added as a shield in your build. - -**For split boards**, you will need to add configurations for the left and right sides. - -``` -config SHIELD_MY_BOARD_LEFT - def_bool $(shields_list_contains,my_board_left) - -config SHIELD_MY_BOARD_RIGHT - def_bool $(shields_list_contains,my_board_right) -``` - -### Kconfig.defconfig - -The `Kconfig.defconfig` file is where overrides for various configuration settings -that make sense to have different defaults when this shield is used. One main item -that usually has a new default value set here is the `ZMK_KEYBOARD_NAME` value, -which controls the display name of the device over USB and BLE. - -The updated new default values should always be wrapped inside a conditional on the shield config name defined in the `Kconfig.shield` file. Here's the simplest example file. - -:::warning -Do not make the keyboard name too long, otherwise the bluetooth advertising might fail and you will not be able to find your keyboard from your laptop / tablet. -::: - -``` -if SHIELD_MY_BOARD - -config ZMK_KEYBOARD_NAME - default "My Awesome Keyboard" - -endif -``` - -Similarly to defining the halves of a split board in `Kconfig.shield` it is important to set the `ZMK_KEYBOARD_NAME` for each half of a split keyboard. - -``` -if SHIELD_MY_BOARD_LEFT - -config ZMK_KEYBOARD_NAME - default "My Awesome Keyboard Left" - -endif - -if SHIELD_MY_BOARD_RIGHT - -config ZMK_KEYBOARD_NAME - default "My Awesome Keyboard Right" - -endif -``` - -## Shield Overlays - -![Labelled Pro Micro pins](assets/pro-micro/pro-micro-pins-labelled.jpg) - -ZMK uses the green color coded pin names to generate devicetree node references. For example, to refer to the node `D0` in the devicetree files, use `&pro_micro_d 0` or to refer to `A1`, use `&pro_micro_a 1`. - - - - - -The `.overlay` is the devicetree description of the keyboard shield that is merged with the primary board devicetree description before the build. For ZMK, this file at a minimum should include the chosen node named `zmk,kscan` that references a KSCAN driver instance. For a simple 3x3 macropad matrix, -this might look something like: - -``` -/ { - chosen { - zmk,kscan = &kscan0; - }; - - kscan0: kscan_0 { - compatible = "zmk,kscan-gpio-matrix"; - label = "KSCAN"; - diode-direction = "col2row"; - - col-gpios - = <&pro_micro_d 15 GPIO_ACTIVE_HIGH> - , <&pro_micro_d 14 GPIO_ACTIVE_HIGH> - , <&pro_micro_d 16 GPIO_ACTIVE_HIGH> - ; - - row-gpios - = <&pro_micro_a 1 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> - , <&pro_micro_a 2 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> - , <&pro_micro_a 3 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> - ; - }; -}; -``` - - - - - -### .dtsi files and Shield Overlays (Split Shields) - -Unlike unibody keyboards, split keyboards have a core .dtsi file with shield overlays for each half of the keyboard. -It is preferred to define only the `col-gpios` or `row-gpios` in the common shield .dtsi, depending on the `diode-direction` value. -For `col2row` directed boards like the iris, the shared .dtsi file may look like this: - -``` -#include - -/ { - chosen { - zmk,kscan = &kscan0; - zmk,matrix_transform = &default_transform; - }; - - default_transform: keymap_transform_0 { - compatible = "zmk,matrix-transform"; - columns = <16>; - rows = <4>; -// | SW6 | SW5 | SW4 | SW3 | SW2 | SW1 | | SW1 | SW2 | SW3 | SW4 | SW5 | SW6 | -// | SW12 | SW11 | SW10 | SW9 | SW8 | SW7 | | SW7 | SW8 | SW9 | SW10 | SW11 | SW12 | -// | SW18 | SW17 | SW16 | SW15 | SW14 | SW13 | | SW13 | SW14 | SW15 | SW16 | SW17 | SW18 | -// | SW24 | SW23 | SW22 | SW21 | SW20 | SW19 | SW25 | | SW25 | SW19 | SW20 | SW21 | SW22 | SW23 | SW24 | -// | SW29 | SW28 | SW27 | SW26 | | SW26 | SW27 | SW28 | SW29 | - map = < -RC(0,0) RC(0,1) RC(0,2) RC(0,3) RC(0,4) RC(0,5) RC(0,6) RC(0,7) RC(0,8) RC(0,9) RC(0,10) RC(0,11) -RC(1,0) RC(1,1) RC(1,2) RC(1,3) RC(1,4) RC(1,5) RC(1,6) RC(1,7) RC(1,8) RC(1,9) RC(1,10) RC(1,11) -RC(2,0) RC(2,1) RC(2,2) RC(2,3) RC(2,4) RC(2,5) RC(2,6) RC(2,7) RC(2,8) RC(2,9) RC(2,10) RC(2,11) -RC(3,0) RC(3,1) RC(3,2) RC(3,3) RC(3,4) RC(3,5) RC(4,2) RC(4,9) RC(3,6) RC(3,7) RC(3,8) RC(3,9) RC(3,10) RC(3,11) - RC(4,3) RC(4,4) RC(4,5) RC(4,6) RC(4,7) RC(4,8) - >; - }; - - kscan0: kscan { - compatible = "zmk,kscan-gpio-matrix"; - label = "KSCAN"; - - diode-direction = "col2row"; - row-gpios - = <&pro_micro_d 6 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row A from the schematic file - , <&pro_micro_d 7 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row B from the schematic file - , <&pro_micro_d 8 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row C from the schematic file - , <&pro_micro_d 0 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row D from the schematic file - , <&pro_micro_d 4 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row E from the schematic file - ; - - }; -``` - -:::note -Notice that in addition to the common `row-gpios` that are declared in the kscan, the [matrix transform](#optional-matrix-transform) is defined in the .dtsi. -::: - -The missing `col-gpios` would be defined in your `_left.overlay` and `_right.overlay` files. -Keep in mind that the mirrored position of the GPIOs means that the `col-gpios` will appear reversed when the .overlay files are compared to one another. -Furthermore, the column offset for the [matrix transform](#optional-matrix-transform) should be added to the right half of the keyboard's overlay -because the keyboard's switch matrix is read from left to right, top to bottom. -This is exemplified with the iris .overlay files. - -``` -// iris_left.overlay - -#include "iris.dtsi" // Notice that the main dtsi files are included in the overlay. - -&kscan0 { - col-gpios - = <&pro_micro_a 1 GPIO_ACTIVE_HIGH> // col1 in the schematic - , <&pro_micro_a 0 GPIO_ACTIVE_HIGH> // col2 in the schematic - , <&pro_micro_d 15 GPIO_ACTIVE_HIGH> // col3 in the schematic - , <&pro_micro_d 14 GPIO_ACTIVE_HIGH> // col4 in the schematic - , <&pro_micro_d 16 GPIO_ACTIVE_HIGH> // col5 in the schematic - , <&pro_micro_d 10 GPIO_ACTIVE_HIGH> // col6 in the schematic - ; -}; -``` - -``` -// iris_right.overlay - -#include "iris.dtsi" - -&default_transform { // The matrix transform for this board is 6 columns over because the left half is 6 columns wide according to the matrix. - col-offset = <6>; -}; - -&kscan0 { - col-gpios - = <&pro_micro_d 10 GPIO_ACTIVE_HIGH> // col6 in the schematic - , <&pro_micro_d 16 GPIO_ACTIVE_HIGH> // col5 in the schematic - , <&pro_micro_d 14 GPIO_ACTIVE_HIGH> // col4 in the schematic - , <&pro_micro_d 15 GPIO_ACTIVE_HIGH> // col3 in the schematic - , <&pro_micro_a 0 GPIO_ACTIVE_HIGH> // col2 in the schematic - , <&pro_micro_a 1 GPIO_ACTIVE_HIGH> // col1 in the schematic - ; -}; - -``` - -### .conf files (Split Shields) - -While unibody boards only have one .conf file that applies configuration characteristics to the entire keyboard, -split keyboards are unique in that they contain multiple .conf files with different scopes. -For example, a split board called `my_awesome_split_board` would have the following files: - -- `my_awesome_split_board.conf` - Configuration elements affect both halves -- `my_awesome_split_board_left.conf` - Configuration elements only affect left half -- `my_awesome_split_board_right.conf` - Configuration elements only affect right half - -For proper communication between keyboard halves and that between the central half and the computer, -the **the central and peripheral halves of the keyboard must be defined**. This can be seen below. - -``` -// Central Half (Usually the left side: my_awesome_split_board_left.conf) - -CONFIG_ZMK_SPLIT=y -CONFIG_ZMK_SPLIT_BLE_ROLE_CENTRAL=y -``` - -``` -// Peripheral Half (Usually the right side: my_awesome_split_board_right.conf) - -CONFIG_ZMK_SPLIT=y -CONFIG_ZMK_SPLIT_BLE_ROLE_Peripheral=y -``` - -Using the .conf file that affects both halves of a split board would be for adding features like deep-sleep or rotary encoders. - -``` -// my_awesome_split_board.conf - -CONFIG_ZMK_SLEEP=y -``` - - - - -## (Optional) Matrix Transform - -Internally ZMK translates all row/column events into "key position" events to maintain a consistent model that works no matter what any possible GPIO matrix may look like for a certain keyboard. This is particularly helpful when: - -1. To reduce the used pins, an "efficient" number of rows/columns for the GPIO matrix is used, that does _not_ match the physical layout of rows/columns of the actual key switches. -1. For non rectangular keyboards with thumb clusters, non `1u` locations, etc. - -A "key position" is the numeric index (zero-based) of a given key, which identifies -the logical key location as perceived by the end user. All _keymap_ mappings actually bind behaviors to _key positions_, not to row/column values. - -_Without_ a matrix transform, that intentionally map each key position to the row/column pair that position corresponds to, the default equation to determine that is: - -``` -($row * NUMBER_OF_COLUMNS) + $column -``` - -Which effectively amounts to numbering the key positions by traversing each row from top to bottom and assigning numerically incrementing key positions. - -Whenever that default key position mapping is insufficient, the `.overlay` file should _also_ include a matrix transform. - -Here is an example for the [nice60](https://github.com/Nicell/nice60), which uses an efficient 8x8 GPIO matrix, and uses a transform: - -``` -#include - -/ { - chosen { - zmk,kscan = &kscan0; - zmk,matrix_transform = &default_transform; - }; - - default_transform: keymap_transform_0 { - compatible = "zmk,matrix-transform"; - columns = <8>; - rows = <8>; -// | MX1 | MX2 | MX3 | MX4 | MX5 | MX6 | MX7 | MX8 | MX9 | MX10 | MX11 | MX12 | MX13 | MX14 | -// | MX15 | MX16 | MX17 | MX18 | MX19 | MX20 | MX21 | MX22 | MX23 | MX34 | MX25 | MX26 | MX27 | MX28 | -// | MX29 | MX30 | MX31 | MX32 | MX33 | MX34 | MX35 | MX36 | MX37 | MX38 | MX39 | MX40 | MX41 | -// | MX42 | MX43 | MX44 | MX45 | MX46 | MX47 | MX48 | MX49 | MX50 | MX51 | MX52 | MX53 | -// | MX54 | MX55 | MX56 | MX57 | MX58 | MX59 | MX60 | MX61 | - map = < -RC(3,0) RC(2,0) RC(1,0) RC(0,0) RC(1,1) RC(0,1) RC(0,2) RC(1,3) RC(0,3) RC(1,4) RC(0,4) RC(0,5) RC(1,6) RC(1,7) -RC(4,0) RC(4,1) RC(3,1) RC(2,1) RC(2,2) RC(1,2) RC(2,3) RC(3,4) RC(2,4) RC(2,5) RC(1,5) RC(2,6) RC(2,7) RC(3,7) -RC(5,0) RC(5,1) RC(5,2) RC(4,2) RC(3,2) RC(4,3) RC(3,3) RC(4,4) RC(4,5) RC(3,5) RC(4,6) RC(3,6) RC(4,7) -RC(6,0) RC(6,1) RC(6,2) RC(6,3) RC(5,3) RC(6,4) RC(5,4) RC(6,5) RC(5,5) RC(6,6) RC(5,6) RC(5,7) -RC(7,0) RC(7,1) RC(7,2) RC(7,3) RC(7,5) RC(7,6) RC(6,7) RC(7,7) - >; - }; -``` - -Some important things to note: - -- The `#include ` is critical. The `RC` macro is used to generate the internal storage in the matrix transform, and is actually replaced by a C preprocessor before the final devicetree is compiled into ZMK. -- `RC(row, column)` is placed sequentially to define what row and column values that position corresponds to. -- If you have a keyboard with options for `2u` keys in certain positions, or break away portions, it is a good idea to set the chosen `zmk,matrix_transform` to the default arrangement, and include _other_ possible matrix transform nodes in the devicetree that users can select in their user config by overriding the chosen node. - -## Default Keymap - -Each keyboard should provide an OOTB default keymap to be used when building the firmware, which can be overridden and customized by user configs. For "shield keyboards", this should be placed in the `app/boards/shields//.keymap` file. The keymap is configured as an additional devicetree overlay that includes the following: - -- A node with `compatible="zmk,keymap"` where each child node is a layer with a `bindings` array that binds each key position to a given behavior (e.g. key press, momentarily layer, etc). - -Here is an example simple keymap for the Kyria, with only one layer: - - - -:::note -The two `#include` lines at the top of the keymap are required in order to bring in the default set of behaviors to make them available to bind, and to import a set of defines for the key codes, so keymaps can use parameters like `N2` or `K` instead of the raw keycode numeric values. -::: - -### Keymap Behaviors - -Further documentation on behaviors and bindings is forthcoming, but a summary of the current behaviors you can bind to key positions is as follows: - -- `kp` is the "key press" behavior, and takes a single binding argument of the key code from the 'keyboard/keypad" HID usage table. -- `mo` is the "momentary layer" behaviour, and takes a single binding argument of the numeric ID of the layer to momentarily enable when that key is held. -- `trans` is the "transparent" behavior, useful to be place in higher layers above `mo` bindings to be sure the key release is handled by the lower layer. No binding arguments are required. -- `mt` is the "mod-tap" behavior, and takes two binding arguments, the modifier to use if held, and the keycode to send if tapped. - -## Adding Features - -### Encoders - -EC11 encoder support can be added to your board or shield by adding the appropriate lines to your board/shield's configuration (.conf), device tree (.dtsi), overlay (.overlay), and keymap (.keymap) files. - - - - -In your configuration file you will need to add the following lines so that the encoders can be enabled/disabled: - -``` -# Uncomment to enable encoder -# CONFIG_EC11=y -# CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y -``` - -These should be commented by default for encoders that are optional/can be swapped with switches, but can be uncommented if encoders are part of the default design. - -:::note -If building locally for split boards, you may need to add these lines to the specific half's configuration file as well as the combined configuration file. -::: - - - -In your device tree file you will need to add the following lines to define the encoder sensor: - -``` -left_encoder: encoder_left { - compatible = "alps,ec11"; - label = "LEFT_ENCODER"; - a-gpios = ; - b-gpios = ; - resolution = <4>; - }; -``` - -Here you will have to replace PIN_A and PIN_B with the appropriate pins that your PCB utilizes for the encoder(s). For keyboards that use the Pro Micro or any of the Pro Micro replacements, Sparkfun's [Pro Micro Hookup Guide](https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide/hardware-overview-pro-micro) has a pinout diagram that can be useful to determine the right pins. Reference either the blue numbers labeled "Arduino" (digital pins) or the green numbers labeled "Analog" (analog pins). For pins that are labeled as both digital and analog, refer to your specific board's .dtsi file to determine how you should refer to that pin. - -Add additional encoders as necessary by duplicating the above lines, replacing `left` with whatever you would like to call your encoder, and updating the pins. Note that support for peripheral (right) side sensors over BLE is still in progress. - -Once you have defined the encoder sensors, you will have to add them to the list of sensors: - -``` -sensors { - compatible = "zmk,keymap-sensors"; - sensors = <&left_encoder &right_encoder>; - }; -``` - -In this example, a left_encoder and right_encoder are both added. Additional encoders can be added with spaces separating each, and the order they are added here determines the order in which you define their behavior in your keymap. - - - -Add the following lines to your overlay file(s) to enable the encoder: - -``` -&left_encoder { - status = "okay"; -}; -``` - -:::note -For split keyboards, make sure to add left hand encoders to the left .overlay file and right hand encoders to the right .overlay file. -::: - - - -Add the following line to your keymap file to add default encoder behavior bindings: - -``` -sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN>; -``` - -Add additional bindings as necessary to match the default number of encoders on your board. See the [Encoders](/docs/features/encoders) and [Keymap](/docs/features/keymaps) feature documentation for more details. - - - - -## Testing - -Once you've fully created the new keyboard shield definition, -you should be able to test with a build command like: - -``` -west build --pristine -b proton_c -- -DSHIELD=my_board -``` - -and then flash with: - -``` -west flash -``` - -:::note -Further testing your keyboard shield without altering the root keymap file can be done with the use of `-DZMK_CONFIG` in your `west build` command, -shown [here](dev-build-flash#building-from-zmk-config-folder) -::: - -## Updating `build.yml` - -Before publishing your shield to the public via a PR, navigate to `build.yml` found in `.github/workflows` and add your shield to the appropriate list. An example edit to `build.yml` is shown below. - -``` -jobs: - build: - runs-on: ubuntu-latest - name: Build Test - strategy: - matrix: - board: [proton_c, nice_nano, bluemicro840_v1, nrfmicro_13] - shield: - - corne_left - - corne_right - - kyria_left - - kyria_right - - lily58_left - - lily58_right - - iris_left - - iris_right - - romac - - - - - - - include: - - board: proton_c - shield: clueboard_california -``` - -:::note -Notice that both the left and right halves of a split board need to be added to the list of shields for proper error checking. -:::note diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md deleted file mode 100644 index 3dc62e3..0000000 --- a/docs/docs/dev-guide-usb-logging.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: USB Logging ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -## Overview - -If you are developing ZMK on a device that does not have a built in UART for debugging and log/console output, -Zephyr can be configured to create a USB CDC ACM device and the direct all `printk`, console output, and log -messages to that device instead. - -:::warning Battery Life Impact - -Enabling logging increases the power usage of your keyboard, and can have a non-trivial impact to your time on battery. -It is recommended to only enable logging when needed, and not leaving it on by default. - -::: - -## Kconfig - -The following KConfig values need to be set, either by copy and pasting into the `app/prj.conf` file, or by running -`west build -t menuconfig` and manually enabling the various settings in that UI. - -:::note -If you are debugging your own keyboard in your [user config repository](./user-setup.md), use -`config/boards/shields//.conf` instead of `app/prj.conf`. In Github -Actions, you can search the `Kconfig file` build log to verify the options above have been enabled -for you successfully. -::: - -``` -# Turn on logging, and set ZMK logging to debug output -CONFIG_LOG=y -CONFIG_ZMK_LOG_LEVEL_DBG=y - -# Turn on USB CDC ACM device -CONFIG_USB=y -CONFIG_USB_DEVICE_STACK=y -CONFIG_USB_CDC_ACM=y -CONFIG_USB_CDC_ACM_RINGBUF_SIZE=1024 -CONFIG_USB_CDC_ACM_DEVICE_NAME="CDC_ACM" -CONFIG_USB_CDC_ACM_DEVICE_COUNT=1 - -# Enable serial console -CONFIG_SERIAL=y -CONFIG_CONSOLE=y -CONFIG_UART_INTERRUPT_DRIVEN=y -CONFIG_UART_LINE_CTRL=y - -# Enable USB UART, and set the console device -CONFIG_UART_CONSOLE=y -CONFIG_USB_UART_CONSOLE=y -CONFIG_UART_CONSOLE_ON_DEV_NAME="CDC_ACM_0" -CONFIG_USB_UART_DTR_WAIT=n -``` - -## Viewing Logs - -After flashing the updated ZMK image, the board should expose a USB CDC ACM device that you can connect to and view the logs. - - - - -On Linux, this should be a device like `/dev/ttyACM0` and you can connect with `minicom` or `tio` as usual, e.g.: - -``` -sudo tio /dev/ttyACM0 -``` - - - - -On Windows, you can use [PuTTY](https://www.putty.org/). Once installed, use Device Manager to figure out which COM port your controller is communicating on (listed under 'Ports (COM & LPT)') and specify that as the 'Serial line' in PuTTY. - -![Controller COM port](./assets/usb-logging/com.jpg) - -![PuTTY settings](assets/usb-logging/putty.jpg) - -If you already have the Ardunio IDE installed you can also use its built-in Serial Monitor. - - - - -On MacOS, the device name is something like `/dev/tty.usbmodemXXXXX` where `XXXXX` is some numerical ID. -You can connect to the device with [tio](https://tio.github.io/) (can be installed via [Homebrew](https://formulae.brew.sh/formula/tio)): - -``` -sudo tio /dev/tty.usbmodem14401 -``` - -You should see tio printing `Disconnected` or `Connected` when you disconnect or reconnect the USB cable. - - - -From there, you should see the various log messages from ZMK and Zephyr, depending on which systems you have set to what log levels. diff --git a/docs/docs/dev-posix-board.md b/docs/docs/dev-posix-board.md deleted file mode 100644 index 71460a8..0000000 --- a/docs/docs/dev-posix-board.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Native Posix board target ---- - -In order to iterate quickly on firmware features, it can -be helpful to build and run the firmware on your local -workstation, with generated virtual press/release events -flowing into the handler functions. - -## Prerequisites - -In order to build targeting the `native_posix` board, you need to setup your system -with a compiler that can target 32-bit POSIX. - -On Debian, you can do this with: - -``` -apt install -y gcc-multilib -``` - -## Building - -To do this, you can build ZMK targeting the -`native_posix` board. - -``` -west build --pristine --board native_posix -``` - -Once built, you can run the firmware locally: - -``` -./build/zephyr/zephyr.exe -``` - -## Virtual Key Events - -The virtual key presses are hardcoded in `boards/native_posix.overlay` file, should you want to change the sequence to test various actions like Mod-Tap, etc. diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md deleted file mode 100644 index 864574a..0000000 --- a/docs/docs/dev-setup.md +++ /dev/null @@ -1,554 +0,0 @@ ---- -title: Basic Setup -sidebar_label: Basic Setup ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -export const OsTabs = (props) => ({props.children}); - -## Prerequisites - -ZMK requires the following base packages to first be installed: - -- Git -- Python 3 -- `pip` -- `wget` -- devicetree compiler -- CMake -- `dfu-util` -- Various build essentials, e.g. gcc, automake, autoconf - - - - -On Debian and Ubuntu, we'll use `apt` to install our base dependencies: - -First, if you haven't updated recently, or if this is a new install, -you should update to get the latest package information: - -```sh -sudo apt update -``` - -With the latest package information, you can now install the base dependencies: - -```sh -sudo apt install -y \ - git \ - wget \ - autoconf \ - automake \ - build-essential \ - bzip2 \ - ccache \ - device-tree-compiler \ - dfu-util \ - g++ \ - gcc \ - libtool \ - make \ - ninja-build \ - cmake \ - python3-dev \ - python3-pip \ - python3-setuptools \ - xz-utils -``` - -:::note -Ubuntu 18.04 LTS release packages a version of CMake that is too old. Please upgrade to Ubuntu 20.04 LTS -or download and install CMake version 3.13.1 or newer manually. -::: - - - -On Raspberry OS, we'll use `apt` to install our base dependencies: - -First, if you haven't updated recently, or if this is a new install, -you should update to get the latest package information: - -```sh -sudo apt update -``` - -With the latest package information, you can now install the base dependencies: - -```sh -sudo apt install -y \ - git \ - wget \ - autoconf \ - automake \ - build-essential \ - bzip2 \ - ccache \ - device-tree-compiler \ - dfu-util \ - g++ \ - gcc \ - libtool \ - make \ - ninja-build \ - cmake \ - python3-dev \ - python3-pip \ - python3-setuptools \ - xz-utils -``` - - - - -On Fedora, we'll use `dnf` to install our base dependencies: - -#### DNF Update - -First, if you haven't updated recently, or if this is a new install, -you should update to get the latest package information: - -```sh -sudo dnf update -``` - -#### Install Dependencies - -With the latest package information, you can now install the base dependencies: - -```sh -sudo dnf install -y \ - git \ - wget \ - autoconf \ - automake \ - bzip2 \ - ccache \ - dtc \ - dfu-util \ - g++ \ - gcc \ - libtool \ - make \ - ninja-build \ - cmake \ - python3-devel \ - python3-pip \ - python3-setuptools \ - xz -``` - - - - -:::note -Use `cmd.exe` with these instructions rather than PowerShell. -::: - -Chocolatey is recommended and used for the following instructions. You can manually install each of these applications and add them to your `PATH` if you don't want to use Chocolatey. - -1. [Install Chocolatey](https://chocolatey.org/install) -2. Open `cmd.exe` as **Administrator** -3. Run the following `choco` commands: - ```shell - choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System' - choco install ninja gperf python git - ``` - -It is recommended to install `dfu-util` to avoid any later confusion while flashing devices. You can do this by running this command with chocolatey: - -```shell -choco install dfu-util -``` - - - - -#### Homebrew - -Homebrew is required to install the system dependencies. If you haven't done so, visit [Homebrew](https://brew.sh/) for instructions. Once installed, use it to install the base dependencies: - -``` -brew install cmake ninja python3 ccache dtc git wget dfu-util -``` - - - - -This setup leverages the same [image which is used by the GitHub action](https://github.com/zmkfirmware/zephyr-west-action) for local development. Beyond the benefits of [dev/prod parity](https://12factor.net/dev-prod-parity), this approach is also the easiest to set up. No toolchain or dependencies are necessary when using Docker; the container image you'll be using already has the toolchain installed and set up to use. - -1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system. -2. Install [VS Code](https://code.visualstudio.com/) -3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) - -:::info -The docker container includes `west` and the compilation toolchain. If you're using docker and VS Code, you can skip right to [Source Code](#source-code). -::: - - - - -## Setup - -### West Installation - -`west` is the [Zephyr™ meta-tool](https://docs.zephyrproject.org/2.3.0/guides/west/index.html) used to configure and build Zephyr™ applications. - -West can be installed by using the `pip` python package manager. The [Zephyr™ instructions](https://docs.zephyrproject.org/latest/guides/west/install.html#installing-west) are summarized here: - - - - -```sh -pip3 install --user -U west -``` - - - - -In `cmd.exe` as **Administrator**: - -```sh -pip3 install -U west -``` - -:::note -**For Windows, do not use the `--user` argument** that Linux uses otherwise `west` will be installed in a different location and the below instructions for adding Python `pip` will no longer apply. -::: - -Once `west` is installed, close Command Prompt and open a new session as a **user** for the remainder of the instructions. - - - - -:::danger `pip` user packages -If you haven't done so yet, you may need to add the Python `pip` package directory to your `PATH` otherwise your computer will not be able to find the `west` command. -::: - - - -Run the following commands: - -```sh -echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc -source ~/.bashrc -``` - - - - -1. See the [Environment Variables](#environment-variables) section on how to get to the Environment Variables page. -2. Under "System variables" select the "Path" variable. Click "Edit..." and then "New" to add the directory where your `west.exe` is located. By default this should be `C:\Python##\Scripts` where ## is your Python version number. -3. Close Command Prompt and open a new session for the changes to take effect, or run `refreshenv`. - - - - -### Toolchain Installation - -The toolchain provides the compiler, linker, etc., necessary to build for the target -platform. - - - - -#### Zephyr™ ARM SDK - -To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr™ ARM SDK to your system: - -``` -export ZSDK_VERSION=0.11.2 -wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" && \ - sh "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" --quiet -- -d ~/.local/zephyr-sdk-${ZSDK_VERSION} && \ - rm "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" -``` - -The installation will prompt with several questions about installation location, and creating a default `~/.zephyrrc` for you with various variables. The defaults should normally work as expected. - - - - -Because Raspberry OS (Raspbian) runs on the same architecture (but different ABI) as the keyboard MCUs, -the operating system's installed [cross compilers](https://docs.zephyrproject.org/2.3.0/getting_started/toolchain_other_x_compilers.html) can be used to target the different ABI. - -First, the cross compiler should be installed: - -```sh -sudo apt install gcc-arm-none-eabi -``` - -Next, we'll configure Zephyr™ with some extra environment variables needed to find the cross compiler by adding the following to `~/.zephyrrc`: - -```sh -export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile -export CROSS_COMPILE=/usr/bin/arm-none-eabi- -``` - - - - -#### Zephyr™ ARM SDK - -To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr™ ARM SDK to your system: - -``` -export ZSDK_VERSION=0.11.2 -wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" && \ - sh "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" --quiet -- -d ~/.local/zephyr-sdk-${ZSDK_VERSION} && \ - rm "zephyr-toolchain-arm-\${ZSDK_VERSION}-setup.run" -``` - -The installation will prompt with several questions about installation location, and creating a default `~/.zephyrrc` for you with various variables. The defaults should normally work as expected. - - - - -#### GNU ARM Embedded - -Since the Zephyr™ SDK is not available for Windows, we recommending following the [Zephyr documentation](https://docs.zephyrproject.org/2.3.0/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded) to install a GNU ARM Embedded build. Note the warnings regarding installing the toolchain into a path with spaces, and make sure to follow the steps to add the environment variables which are also summarized with screenshots in the [Environment Variables](#environment-variables) section below. - - - - -#### GNU ARM Embedded - -Since the Zephyr™ SDK is not available for macOS, we recommending following the steps to install the [GNU ARM Embedded](https://docs.zephyrproject.org/2.3.0/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded). - -:::warning Security Controls Workaround - -Please be sure to read the [additional setup instructions](https://docs.zephyrproject.org/2.3.0/getting_started/installation_mac.html#mac-gatekeeper) needed to address security controls found in macOS 10.15 Catalina and newer - -::: - - - - -:::note -If you intend to build firmware straight away, make sure to correctly setup the current shell. - -Notes on setting this up can be found in the [Environment Variables](#environment-variables) section. -The transient instructions can be used to setup the current shell, and the automatic instructions can setup any newly made shells automatically. - -The transient instructions must be run to build firmware using the current shell. -::: - -### Source Code - -Next, you'll need to clone the ZMK source repository if you haven't already. Navigate to the folder you would like to place your `zmk` directory in and run the following command: - -``` -git clone https://github.com/zmkfirmware/zmk.git -``` - -### Initialize & Update Zephyr Workspace - -Since ZMK is built as a Zephyr™ application, the next step is -to use `west` to initialize and update your workspace. The ZMK -Zephyr™ application is in the `app/` source directory: - -#### Step into the repository - - - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - - -```sh -cd zmk -``` - - - - - -Open the `zmk` checkout folder in VS Code. The repository includes a configuration for containerized development, so an alert will pop up: - -![VS Code Dev Container Configuration Alert](assets/dev-setup/vscode_devcontainer.png) - -Click `Reopen in Container` in order to reopen the VS Code with the running container. - -The first time you do this on your machine, it will pull the docker image down from the registry and build the container. Subsequent launches are much faster! - -:::caution -All subsequent steps must be performed from the VS Code terminal _inside_ the container. -::: - - - - -#### Initialize West - -```sh -west init -l app/ -``` - -:::caution Command Not Found? -If you encounter errors like `command not found: west` then your `PATH` environment variable is likely -missing the Python 3 user packages directory. See the [West Build Command](#west-build-command) -section again for links to how to do this -::: - -#### Update To Fetch Modules - -```sh -west update -``` - -:::tip -This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection! -::: - -:::info -If you're using Docker, you're done with setup! You must restart the container at this point. The easiest way to do so is to close the VS Code window, verify that the container has stopped in Docker Dashboard, and reopen the container with VS Code. - -Once your container is restarted, proceed to [Building and Flashing](./dev-build-flash.md). -::: - -#### Export Zephyr™ Core - -```sh -west zephyr-export -``` - -#### Install Zephyr Python Dependencies - -```sh -pip3 install --user -r zephyr/scripts/requirements-base.txt -``` - -### Environment Variables - - - - -#### For GNU ARM Embedded on Windows - -On Windows, only two environment variables need to be set for ZMK to build properly: `ZEPHYR_TOOLCHAIN_VARIANT` and `GNUARMEMB_TOOLCHAIN_PATH`. - -1. Open Start Menu and type 'env' to find the 'Edit the system environment variables' option. Open it. - -![Environment variables in Start Menu](assets/env-var/start_menu.png) - -2. Click 'Environment Variables...'. - -![Environment variables button](assets/env-var/env_var.png) - -3. Click "New..." under System variables to create a new system variable. - -![Environment variables menu](assets/env-var/new_variable.png) - -4. Set the variable name to 'ZEPHYR_TOOLCHAIN_VARIANT' and value to 'gnuarmemb'. Click OK to save. - -![Adding Zephyr toolchain variable](assets/env-var/zephyr_toolchain.png) - -5. Create another variable with variable name 'GNUARMEMB_TOOLCHAIN_PATH' and value set to wherever you installed your toolchain. **Make sure this path does not contain any spaces.** If it does, rename the folder and update here. Click OK to save. - -![Adding GNUARMEMB variable](assets/env-var/gnuarmemb.png) - -6. Close Command Prompt and reopen, or run `refreshenv` to apply the changes. - - - - - -#### For Zephyr - -By default, the Zephyr™ SDK will create a file named `~/.zephyrrc` with the correct environment variables to build ZMK. -We suggest two main [options](https://docs.zephyrproject.org/2.3.0/guides/env_vars.html?highlight=zephyrrc) for how to load those settings. - -##### Per Shell - -To load the Zephyr environment properly for just one transient shell, run the following from your ZMK checkout directory: - -``` -source zephyr/zephyr-env.sh -``` - -##### All Shells - -To load the environment variables for your shell every time, -append the existing `~/.zephyrrc` file to your shell's RC file and then start a new shell. - - - - - -``` -cat ~/.zephyrrc >> ~/.bashrc -``` - - - - - -``` -cat ~/.zephyrrc >> ~/.zshrc -``` - - - - - - - - diff --git a/docs/docs/dev-tests.md b/docs/docs/dev-tests.md deleted file mode 100644 index 98381d7..0000000 --- a/docs/docs/dev-tests.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Tests -sidebar_label: Tests ---- - -Running tests requires [native posix support](./dev-posix-board). Any folder under `/app/tests` -containing `native_posix.keymap` will be selected when running `./run-test.sh all`. - -## Creating a New Test Set - -1. Copy the test set that most closely resembles the tests you will be creating. -2. Rename the newly created test set to the behavior you're testing e.g, toggle-layer -3. Modify `behavior_keymap.dtsi` to create a keymap using the behavior and related behaviors -4. Modify `test_case/native_posix.keymap` for a simulated use case -5. Modify `test_case/events.patterns` to collect relevant logs to the test - - See: [sed manual](https://www.gnu.org/software/sed/manual/sed.html) and - [tutorial](https://www.digitalocean.com/community/tutorials/the-basics-of-using-the-sed-stream-editor-to-manipulate-text-in-linux) -6. Modify `test_case/keycode_events.snapshot` for to include the expected output -7. Rename the `test_case` folder to describe the test. -8. Repeat steps 4 to 7 for every test case diff --git a/docs/docs/development/boards-shields-keymaps.md b/docs/docs/development/boards-shields-keymaps.md new file mode 100644 index 0000000..e78f5d3 --- /dev/null +++ b/docs/docs/development/boards-shields-keymaps.md @@ -0,0 +1,52 @@ +--- +title: Boards, Shields, and Keymaps +--- + +## Architecture Overview + +The foundational elements needed to get a specific keyboard working with ZMK can be broken down into: + +- A [KSCAN driver](https://docs.zephyrproject.org/2.3.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. + +These three core architectural elements are defined per-keyboard, and _where_ they are defined depends on the specifics of how that +keyboard works. For an overview on the general concepts of boards and shields, please see the [FAQs on boards and shields](/docs/faq#why-boards-and-shields--why-not-just-keyboard). + +## Self-Contained Keyboard + +For a self-contained keyboard that includes the microprocessor, all of the above architecture components are included in the Zephyr _board_ definition. You can see an example for the [Planck V6](https://github.com/zmkfirmware/zmk/tree/main/app/boards/arm/planck) board directory. + +With this type of keyboard, the full ZMK definition for the keyboard exists +in the `app/boards/${arch}/${board_name}` directory, e.g. `app/boards/arm/planck/`. In that directory, you'll have the following: + +- A `Kconfig.board` file that defines the toplevel Kconfig item 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` to a value, for the product name to be used for USB/BLE info. + - Setting `ZMK_USB` and/or `ZMK_BLE` for the default values for which HID transport(s) to enable by default +- 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 `. + - A [chosen](https://docs.zephyrproject.org/2.3.0/guides/dts/intro.html#aliases-and-chosen-nodes) node named `zmk,kscan` which references the configured KSCAN driver (usually a GPIO matrix) + - (Optional) A [chosen](https://docs.zephyrproject.org/2.3.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 `keymap/keymap.overlay` file that includes the default keymap for that keyboard. Users will be able to override this keymap in their user configs. + +## Pro Micro Compatible Keyboard + +![Labelled Pro Micro pins](../assets/pro-micro/pro-micro-pins-labelled.jpg) + +For keyboards that require a (usually Pro Micro compatible) add-on board to operate, the ZMK integration pieces are places +in the _shield_ definition for that keyboard, allowing users to +swap in different Pro Micro compatible boards (e.g. Proton-C, or nice!nano) and build a firmware the matches their actual +combination of physical components. + +With this type of keyboard, the partial definition for the keyboard exists +in the `app/boards/shields/${board_name}` directory, e.g. `app/boards/shields/clueboard_california/`. In that directory, you'll have the following: + +- A `Kconfig.shield` that defines the toplevel Kconfig value for the shield, which uses a supplied utility to function to default the value based on the shield list, e.g. `def_bool $(shields_list_contains,clueboard_california)`. +- A `Kconfig.defconfig` file to set default values for things like `ZMK_KEYBOARD_NAME` +- A `${shield_name}.overlay` file, which is a devicetree overlay file, that includes: + - A [chosen](https://docs.zephyrproject.org/2.3.0/guides/dts/intro.html#aliases-and-chosen-nodes) node named `zmk,kscan` which references the configured KSCAN driver (usually a GPIO matrix). For these keyboards, to be compatible with any Pro Micro compatible boards, the KSCAN configuration should reference the [nexus node](https://docs.zephyrproject.org/2.3.0/guides/porting/shields.html#gpio-nexus-nodes) that ZMK has standardized on. In particular, the `&pro_micro_a` and `&pro_micro_d` aliases can be used to reference the standard `A#` and `D#` pins in shields. + - (Optional) A [chosen](https://docs.zephyrproject.org/2.3.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. diff --git a/docs/docs/development/build-flash.md b/docs/docs/development/build-flash.md new file mode 100644 index 0000000..e270a7c --- /dev/null +++ b/docs/docs/development/build-flash.md @@ -0,0 +1,128 @@ +--- +title: Building and Flashing +sidebar_label: Building and Flashing +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const OsTabs = (props) => ({props.children}); + +## Building + +From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout: + +```sh +cd app +``` + +To build for your particular keyboard, the behaviour varies slightly depending on if you are building for a keyboard with +an onboard MCU, or one that uses an MCU board addon. + +### Keyboard (Shield) + MCU Board + +ZMK treats keyboards that take an MCU addon board as [shields](https://docs.zephyrproject.org/2.3.0/guides/porting/shields.html), and treats the smaller MCU board as the true [board](https://docs.zephyrproject.org/2.3.0/guides/porting/board_porting.html) + +Given the following: + +- MCU Board: Proton-C +- Keyboard PCB: kyria_left +- Keymap: default + +You can build ZMK with the following: + +```sh +west build -b proton_c -- -DSHIELD=kyria_left +``` + +### Keyboard With Onboard MCU + +Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/2.3.0/guides/porting/board_porting.html) as far as Zephyr™ is concerned. + +Given the following: + +- Keyboard: Planck (rev6) +- Keymap: default + +you can build ZMK with the following: + +```sh +west build -b planck_rev6 +``` + +### Pristine Building + +When building for a new board and/or shield after having built one previously, you may need to enable the pristine build option. This option removes all existing files in the build directory before regenerating them, and can be enabled by adding either --pristine or -p to the command: + +```sh +west build -p -b proton_c -- -DSHIELD=kyria_left +``` + +### Building For Split Keyboards + +:::note +For split keyboards, you will have to build and flash each side separately the first time you install ZMK. +::: + +By default, the `build` command outputs a single .uf2 file named `zmk.uf2` so building left and then right immediately after will overwrite your left firmware. In addition, you will need to pristine build each side to ensure the correct files are used. To avoid having to pristine build every time and separate the left and right build files, we recommend setting up separate build directories for each half. You can do this by using the `-d` parameter and first building left into `build/left`: + +``` +west build -d build/left -b nice_nano -- -DSHIELD=kyria_left +``` + +and then building right into `build/right`: + +``` +west build -d build/right -b nice_nano -- -DSHIELD=kyria_right +``` + +This produces `left` and `right` subfolders under the `build` directory and two separate .uf2 files. For future work on a specific half, use the `-d` parameter again to ensure you are building into the correct location. + +### Building from `zmk-config` Folder + +Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](../user-setup#github-repo) by adding +`-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build` command. **Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.** + +For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this: + +``` +west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config" +``` + +In order to make your `zmk-config` folder available when building within the VSCode Remote Container, you need to create a docker volume named `zmk-config` +by binding it to the full path of your config directory. If you have run the VSCode Remote Container before, it is likely that docker has created this +volume automatically -- we need to delete the default volume before binding it to the correct path. Follow the following steps: + +1. Stop the container by exiting VSCode. You can verify no container is running via the command `docker ps`. +1. Remove all the containers that are not running via the command `docker container prune`. We need to remove the ZMK container before we can delete the default `zmk-config` volume referenced by it. If you do not want to delete all the containers that are not running, you can find the id of the ZMK container and use `docker rm` to delete that one only. +1. Remove the default volume via the command `docker volume rm zmk-config`. + +Then you can bind the `zmk-config` volume to the correct path pointing to your local [zmk-config](./customization.md) folder: + +``` +docker volume create --driver local -o o=bind -o type=none -o \ + device="/full/path/to/your/zmk-config/" zmk-config +``` + +Now start VSCode and rebuild the container after being prompted. You should be able to see your zmk-config mounted to `/workspaces/zmk-config` inside the container. So you can build your custom firmware with `-DZMK_CONFIG="/workspaces/zmk-config/config"`. + +## Flashing + +Once built, the previously supplied parameters will be remembered so you can run the following to flash your +board with it in bootloader mode: + +``` +west flash +``` + +For boards that have drag and drop .uf2 flashing capability, the .uf2 file to flash can be found in `build/zephyr` (or `build/left|right/zephyr` if you followed the instructions for splits) and is by default named `zmk.uf2`. diff --git a/docs/docs/development/clean-room.md b/docs/docs/development/clean-room.md new file mode 100644 index 0000000..82db3a0 --- /dev/null +++ b/docs/docs/development/clean-room.md @@ -0,0 +1,28 @@ +--- +title: Clean Room Implementation +sidebar_label: Clean Room +--- + +:::warning + +Anyone wanting to contribute code to ZMK _MUST_ read this, and adhere to the steps outlines in order to not violate any licenses/copyright of other projects + +::: + +ZMK Firmware is a [clean room design](https://en.wikipedia.org/wiki/Clean_room_design) keyboard firmware, that +borrows/implements a lot of the features found in popular keyboard firmwares projects like [QMK](https://qmk.fm) +and [TMK](https://github.com/tmk/tmk_keyboard). However, in order for ZMK to use the MIT, it _must_ not +incorporate any of the GPL licensed code from those projects. + +In order to achieve this, all code for ZMK has been implemented completely fresh, _without_ referencing, copying, +or duplicating any of the GPL code found in those other projects, even though they are open source software. + +## Contributor Requirements + +Contributors to ZMK must adhere to the following standard. + +- Implementations of features for ZMK _MUST NOT_ reuse any existing code from any projects not licensed with the MIT license. +- Contributors _MUST NOT_ study or refer to any GPL licensed source code while working on ZMK. +- Contributors _MAY_ read the documentation from other GPL licensed projects, to gain a broad understanding of the behavior of certain features in order to implement equivalent features for ZMK. +- Contributors _MAY_ refer to the [QMK Configurator](https://config.qmk.fm/) to inspect existing layouts/keymaps for + keyboards, and re-implement them for ZMK. diff --git a/docs/docs/development/guide-new-shield.md b/docs/docs/development/guide-new-shield.md new file mode 100644 index 0000000..306f1b3 --- /dev/null +++ b/docs/docs/development/guide-new-shield.md @@ -0,0 +1,512 @@ +--- +title: New Keyboard Shield +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import KeymapExampleFile from '../keymap-example-file.md'; + +## Overview + +This guide will walk through the steps necessary to add ZMK support for a keyboard the uses a (Pro Micro compatible) addon MCU board to provide the microprocessor. +The high level steps are: + +- 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. +- (Optional) Add the matrix transform for mapping KSCAN row/column values to sane key positions. This is needed for non-rectangular keyboards, or where the underlying row/column pin arrangement does not map one to one with logical locations on the keyboard. +- Add a default keymap, which users can override in their own configs as needed. +- Add support for features such as encoders, OLED displays, or RGB underglow. +- Update build.yml + +It may be helpful to review the upstream [shields documentation](https://docs.zephyrproject.org/2.3.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. +::: + +## New Shield Directory + +:::note +This guide describes how to add shield to the ZMK main repository. If you are building firmware for your +own prototype or handwired keyboard, it is recommended to use your own user config repository. Follow the +[user setup guide](./user-setup.md) to create your user config repository first. When following the rest +of this guide, replace the `app/` directory in the ZMK main repository with the `config/` directory in your +user config repository. For example, `app/boards/shields/` should now be +`config/boards/shields/`. +::: + +Shields for Zephyr applications go into the `boards/shields/` directory; since ZMK's Zephyr application lives in the `app/` subdirectory of the repository, that means the new shield directory should be: + +```bash +mkdir app/boards/shields/ +``` + +## Base Kconfig Files + +There are two required Kconfig files that need to be created for your new keyboard +shield to get it picked up for ZMK, `Kconfig.shield` and `Kconfig.defconfig`. + +### Kconfig.shield + +The `Kconfig.shield` file defines any additional Kconfig settings that may be relevant when using this keyboard. For most keyboards, there is just one additional configuration value for the shield itself, e.g.: + +``` +config SHIELD_MY_BOARD + def_bool $(shields_list_contains,my_board) +``` + +This will make sure the new configuration `SHIELD_MY_BOARD` is set to true whenever `my_board` is added as a shield in your build. + +**For split boards**, you will need to add configurations for the left and right sides. + +``` +config SHIELD_MY_BOARD_LEFT + def_bool $(shields_list_contains,my_board_left) + +config SHIELD_MY_BOARD_RIGHT + def_bool $(shields_list_contains,my_board_right) +``` + +### Kconfig.defconfig + +The `Kconfig.defconfig` file is where overrides for various configuration settings +that make sense to have different defaults when this shield is used. One main item +that usually has a new default value set here is the `ZMK_KEYBOARD_NAME` value, +which controls the display name of the device over USB and BLE. + +The updated new default values should always be wrapped inside a conditional on the shield config name defined in the `Kconfig.shield` file. Here's the simplest example file. + +:::warning +Do not make the keyboard name too long, otherwise the bluetooth advertising might fail and you will not be able to find your keyboard from your laptop / tablet. +::: + +``` +if SHIELD_MY_BOARD + +config ZMK_KEYBOARD_NAME + default "My Awesome Keyboard" + +endif +``` + +Similarly to defining the halves of a split board in `Kconfig.shield` it is important to set the `ZMK_KEYBOARD_NAME` for each half of a split keyboard. + +``` +if SHIELD_MY_BOARD_LEFT + +config ZMK_KEYBOARD_NAME + default "My Awesome Keyboard Left" + +endif + +if SHIELD_MY_BOARD_RIGHT + +config ZMK_KEYBOARD_NAME + default "My Awesome Keyboard Right" + +endif +``` + +## Shield Overlays + +![Labelled Pro Micro pins](../assets/pro-micro/pro-micro-pins-labelled.jpg) + +ZMK uses the green color coded pin names to generate devicetree node references. For example, to refer to the node `D0` in the devicetree files, use `&pro_micro_d 0` or to refer to `A1`, use `&pro_micro_a 1`. + + + + + +The `.overlay` is the devicetree description of the keyboard shield that is merged with the primary board devicetree description before the build. For ZMK, this file at a minimum should include the chosen node named `zmk,kscan` that references a KSCAN driver instance. For a simple 3x3 macropad matrix, +this might look something like: + +``` +/ { + chosen { + zmk,kscan = &kscan0; + }; + + kscan0: kscan_0 { + compatible = "zmk,kscan-gpio-matrix"; + label = "KSCAN"; + diode-direction = "col2row"; + + col-gpios + = <&pro_micro_d 15 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 14 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 16 GPIO_ACTIVE_HIGH> + ; + + row-gpios + = <&pro_micro_a 1 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&pro_micro_a 2 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&pro_micro_a 3 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + ; + }; +}; +``` + + + + + +### .dtsi files and Shield Overlays (Split Shields) + +Unlike unibody keyboards, split keyboards have a core .dtsi file with shield overlays for each half of the keyboard. +It is preferred to define only the `col-gpios` or `row-gpios` in the common shield .dtsi, depending on the `diode-direction` value. +For `col2row` directed boards like the iris, the shared .dtsi file may look like this: + +``` +#include + +/ { + chosen { + zmk,kscan = &kscan0; + zmk,matrix_transform = &default_transform; + }; + + default_transform: keymap_transform_0 { + compatible = "zmk,matrix-transform"; + columns = <16>; + rows = <4>; +// | SW6 | SW5 | SW4 | SW3 | SW2 | SW1 | | SW1 | SW2 | SW3 | SW4 | SW5 | SW6 | +// | SW12 | SW11 | SW10 | SW9 | SW8 | SW7 | | SW7 | SW8 | SW9 | SW10 | SW11 | SW12 | +// | SW18 | SW17 | SW16 | SW15 | SW14 | SW13 | | SW13 | SW14 | SW15 | SW16 | SW17 | SW18 | +// | SW24 | SW23 | SW22 | SW21 | SW20 | SW19 | SW25 | | SW25 | SW19 | SW20 | SW21 | SW22 | SW23 | SW24 | +// | SW29 | SW28 | SW27 | SW26 | | SW26 | SW27 | SW28 | SW29 | + map = < +RC(0,0) RC(0,1) RC(0,2) RC(0,3) RC(0,4) RC(0,5) RC(0,6) RC(0,7) RC(0,8) RC(0,9) RC(0,10) RC(0,11) +RC(1,0) RC(1,1) RC(1,2) RC(1,3) RC(1,4) RC(1,5) RC(1,6) RC(1,7) RC(1,8) RC(1,9) RC(1,10) RC(1,11) +RC(2,0) RC(2,1) RC(2,2) RC(2,3) RC(2,4) RC(2,5) RC(2,6) RC(2,7) RC(2,8) RC(2,9) RC(2,10) RC(2,11) +RC(3,0) RC(3,1) RC(3,2) RC(3,3) RC(3,4) RC(3,5) RC(4,2) RC(4,9) RC(3,6) RC(3,7) RC(3,8) RC(3,9) RC(3,10) RC(3,11) + RC(4,3) RC(4,4) RC(4,5) RC(4,6) RC(4,7) RC(4,8) + >; + }; + + kscan0: kscan { + compatible = "zmk,kscan-gpio-matrix"; + label = "KSCAN"; + + diode-direction = "col2row"; + row-gpios + = <&pro_micro_d 6 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row A from the schematic file + , <&pro_micro_d 7 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row B from the schematic file + , <&pro_micro_d 8 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row C from the schematic file + , <&pro_micro_d 0 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row D from the schematic file + , <&pro_micro_d 4 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row E from the schematic file + ; + + }; +``` + +:::note +Notice that in addition to the common `row-gpios` that are declared in the kscan, the [matrix transform](#optional-matrix-transform) is defined in the .dtsi. +::: + +The missing `col-gpios` would be defined in your `_left.overlay` and `_right.overlay` files. +Keep in mind that the mirrored position of the GPIOs means that the `col-gpios` will appear reversed when the .overlay files are compared to one another. +Furthermore, the column offset for the [matrix transform](#optional-matrix-transform) should be added to the right half of the keyboard's overlay +because the keyboard's switch matrix is read from left to right, top to bottom. +This is exemplified with the iris .overlay files. + +``` +// iris_left.overlay + +#include "iris.dtsi" // Notice that the main dtsi files are included in the overlay. + +&kscan0 { + col-gpios + = <&pro_micro_a 1 GPIO_ACTIVE_HIGH> // col1 in the schematic + , <&pro_micro_a 0 GPIO_ACTIVE_HIGH> // col2 in the schematic + , <&pro_micro_d 15 GPIO_ACTIVE_HIGH> // col3 in the schematic + , <&pro_micro_d 14 GPIO_ACTIVE_HIGH> // col4 in the schematic + , <&pro_micro_d 16 GPIO_ACTIVE_HIGH> // col5 in the schematic + , <&pro_micro_d 10 GPIO_ACTIVE_HIGH> // col6 in the schematic + ; +}; +``` + +``` +// iris_right.overlay + +#include "iris.dtsi" + +&default_transform { // The matrix transform for this board is 6 columns over because the left half is 6 columns wide according to the matrix. + col-offset = <6>; +}; + +&kscan0 { + col-gpios + = <&pro_micro_d 10 GPIO_ACTIVE_HIGH> // col6 in the schematic + , <&pro_micro_d 16 GPIO_ACTIVE_HIGH> // col5 in the schematic + , <&pro_micro_d 14 GPIO_ACTIVE_HIGH> // col4 in the schematic + , <&pro_micro_d 15 GPIO_ACTIVE_HIGH> // col3 in the schematic + , <&pro_micro_a 0 GPIO_ACTIVE_HIGH> // col2 in the schematic + , <&pro_micro_a 1 GPIO_ACTIVE_HIGH> // col1 in the schematic + ; +}; + +``` + +### .conf files (Split Shields) + +While unibody boards only have one .conf file that applies configuration characteristics to the entire keyboard, +split keyboards are unique in that they contain multiple .conf files with different scopes. +For example, a split board called `my_awesome_split_board` would have the following files: + +- `my_awesome_split_board.conf` - Configuration elements affect both halves +- `my_awesome_split_board_left.conf` - Configuration elements only affect left half +- `my_awesome_split_board_right.conf` - Configuration elements only affect right half + +For proper communication between keyboard halves and that between the central half and the computer, +the **the central and peripheral halves of the keyboard must be defined**. This can be seen below. + +``` +// Central Half (Usually the left side: my_awesome_split_board_left.conf) + +CONFIG_ZMK_SPLIT=y +CONFIG_ZMK_SPLIT_BLE_ROLE_CENTRAL=y +``` + +``` +// Peripheral Half (Usually the right side: my_awesome_split_board_right.conf) + +CONFIG_ZMK_SPLIT=y +CONFIG_ZMK_SPLIT_BLE_ROLE_Peripheral=y +``` + +Using the .conf file that affects both halves of a split board would be for adding features like deep-sleep or rotary encoders. + +``` +// my_awesome_split_board.conf + +CONFIG_ZMK_SLEEP=y +``` + + + + +## (Optional) Matrix Transform + +Internally ZMK translates all row/column events into "key position" events to maintain a consistent model that works no matter what any possible GPIO matrix may look like for a certain keyboard. This is particularly helpful when: + +1. To reduce the used pins, an "efficient" number of rows/columns for the GPIO matrix is used, that does _not_ match the physical layout of rows/columns of the actual key switches. +1. For non rectangular keyboards with thumb clusters, non `1u` locations, etc. + +A "key position" is the numeric index (zero-based) of a given key, which identifies +the logical key location as perceived by the end user. All _keymap_ mappings actually bind behaviors to _key positions_, not to row/column values. + +_Without_ a matrix transform, that intentionally map each key position to the row/column pair that position corresponds to, the default equation to determine that is: + +``` +($row * NUMBER_OF_COLUMNS) + $column +``` + +Which effectively amounts to numbering the key positions by traversing each row from top to bottom and assigning numerically incrementing key positions. + +Whenever that default key position mapping is insufficient, the `.overlay` file should _also_ include a matrix transform. + +Here is an example for the [nice60](https://github.com/Nicell/nice60), which uses an efficient 8x8 GPIO matrix, and uses a transform: + +``` +#include + +/ { + chosen { + zmk,kscan = &kscan0; + zmk,matrix_transform = &default_transform; + }; + + default_transform: keymap_transform_0 { + compatible = "zmk,matrix-transform"; + columns = <8>; + rows = <8>; +// | MX1 | MX2 | MX3 | MX4 | MX5 | MX6 | MX7 | MX8 | MX9 | MX10 | MX11 | MX12 | MX13 | MX14 | +// | MX15 | MX16 | MX17 | MX18 | MX19 | MX20 | MX21 | MX22 | MX23 | MX34 | MX25 | MX26 | MX27 | MX28 | +// | MX29 | MX30 | MX31 | MX32 | MX33 | MX34 | MX35 | MX36 | MX37 | MX38 | MX39 | MX40 | MX41 | +// | MX42 | MX43 | MX44 | MX45 | MX46 | MX47 | MX48 | MX49 | MX50 | MX51 | MX52 | MX53 | +// | MX54 | MX55 | MX56 | MX57 | MX58 | MX59 | MX60 | MX61 | + map = < +RC(3,0) RC(2,0) RC(1,0) RC(0,0) RC(1,1) RC(0,1) RC(0,2) RC(1,3) RC(0,3) RC(1,4) RC(0,4) RC(0,5) RC(1,6) RC(1,7) +RC(4,0) RC(4,1) RC(3,1) RC(2,1) RC(2,2) RC(1,2) RC(2,3) RC(3,4) RC(2,4) RC(2,5) RC(1,5) RC(2,6) RC(2,7) RC(3,7) +RC(5,0) RC(5,1) RC(5,2) RC(4,2) RC(3,2) RC(4,3) RC(3,3) RC(4,4) RC(4,5) RC(3,5) RC(4,6) RC(3,6) RC(4,7) +RC(6,0) RC(6,1) RC(6,2) RC(6,3) RC(5,3) RC(6,4) RC(5,4) RC(6,5) RC(5,5) RC(6,6) RC(5,6) RC(5,7) +RC(7,0) RC(7,1) RC(7,2) RC(7,3) RC(7,5) RC(7,6) RC(6,7) RC(7,7) + >; + }; +``` + +Some important things to note: + +- The `#include ` is critical. The `RC` macro is used to generate the internal storage in the matrix transform, and is actually replaced by a C preprocessor before the final devicetree is compiled into ZMK. +- `RC(row, column)` is placed sequentially to define what row and column values that position corresponds to. +- If you have a keyboard with options for `2u` keys in certain positions, or break away portions, it is a good idea to set the chosen `zmk,matrix_transform` to the default arrangement, and include _other_ possible matrix transform nodes in the devicetree that users can select in their user config by overriding the chosen node. + +## Default Keymap + +Each keyboard should provide an OOTB default keymap to be used when building the firmware, which can be overridden and customized by user configs. For "shield keyboards", this should be placed in the `app/boards/shields//.keymap` file. The keymap is configured as an additional devicetree overlay that includes the following: + +- A node with `compatible="zmk,keymap"` where each child node is a layer with a `bindings` array that binds each key position to a given behavior (e.g. key press, momentarily layer, etc). + +Here is an example simple keymap for the Kyria, with only one layer: + + + +:::note +The two `#include` lines at the top of the keymap are required in order to bring in the default set of behaviors to make them available to bind, and to import a set of defines for the key codes, so keymaps can use parameters like `N2` or `K` instead of the raw keycode numeric values. +::: + +### Keymap Behaviors + +Further documentation on behaviors and bindings is forthcoming, but a summary of the current behaviors you can bind to key positions is as follows: + +- `kp` is the "key press" behavior, and takes a single binding argument of the key code from the 'keyboard/keypad" HID usage table. +- `mo` is the "momentary layer" behaviour, and takes a single binding argument of the numeric ID of the layer to momentarily enable when that key is held. +- `trans` is the "transparent" behavior, useful to be place in higher layers above `mo` bindings to be sure the key release is handled by the lower layer. No binding arguments are required. +- `mt` is the "mod-tap" behavior, and takes two binding arguments, the modifier to use if held, and the keycode to send if tapped. + +## Adding Features + +### Encoders + +EC11 encoder support can be added to your board or shield by adding the appropriate lines to your board/shield's configuration (.conf), device tree (.dtsi), overlay (.overlay), and keymap (.keymap) files. + + + + +In your configuration file you will need to add the following lines so that the encoders can be enabled/disabled: + +``` +# Uncomment to enable encoder +# CONFIG_EC11=y +# CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y +``` + +These should be commented by default for encoders that are optional/can be swapped with switches, but can be uncommented if encoders are part of the default design. + +:::note +If building locally for split boards, you may need to add these lines to the specific half's configuration file as well as the combined configuration file. +::: + + + +In your device tree file you will need to add the following lines to define the encoder sensor: + +``` +left_encoder: encoder_left { + compatible = "alps,ec11"; + label = "LEFT_ENCODER"; + a-gpios = ; + b-gpios = ; + resolution = <4>; + }; +``` + +Here you will have to replace PIN_A and PIN_B with the appropriate pins that your PCB utilizes for the encoder(s). For keyboards that use the Pro Micro or any of the Pro Micro replacements, Sparkfun's [Pro Micro Hookup Guide](https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide/hardware-overview-pro-micro) has a pinout diagram that can be useful to determine the right pins. Reference either the blue numbers labeled "Arduino" (digital pins) or the green numbers labeled "Analog" (analog pins). For pins that are labeled as both digital and analog, refer to your specific board's .dtsi file to determine how you should refer to that pin. + +Add additional encoders as necessary by duplicating the above lines, replacing `left` with whatever you would like to call your encoder, and updating the pins. Note that support for peripheral (right) side sensors over BLE is still in progress. + +Once you have defined the encoder sensors, you will have to add them to the list of sensors: + +``` +sensors { + compatible = "zmk,keymap-sensors"; + sensors = <&left_encoder &right_encoder>; + }; +``` + +In this example, a left_encoder and right_encoder are both added. Additional encoders can be added with spaces separating each, and the order they are added here determines the order in which you define their behavior in your keymap. + + + +Add the following lines to your overlay file(s) to enable the encoder: + +``` +&left_encoder { + status = "okay"; +}; +``` + +:::note +For split keyboards, make sure to add left hand encoders to the left .overlay file and right hand encoders to the right .overlay file. +::: + + + +Add the following line to your keymap file to add default encoder behavior bindings: + +``` +sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN>; +``` + +Add additional bindings as necessary to match the default number of encoders on your board. See the [Encoders](/docs/features/encoders) and [Keymap](/docs/features/keymaps) feature documentation for more details. + + + + +## Testing + +Once you've fully created the new keyboard shield definition, +you should be able to test with a build command like: + +``` +west build --pristine -b proton_c -- -DSHIELD=my_board +``` + +and then flash with: + +``` +west flash +``` + +:::note +Further testing your keyboard shield without altering the root keymap file can be done with the use of `-DZMK_CONFIG` in your `west build` command, +shown [here](build-flash#building-from-zmk-config-folder) +::: + +## Updating `build.yml` + +Before publishing your shield to the public via a PR, navigate to `build.yml` found in `.github/workflows` and add your shield to the appropriate list. An example edit to `build.yml` is shown below. + +``` +jobs: + build: + runs-on: ubuntu-latest + name: Build Test + strategy: + matrix: + board: [proton_c, nice_nano, bluemicro840_v1, nrfmicro_13] + shield: + - corne_left + - corne_right + - kyria_left + - kyria_right + - lily58_left + - lily58_right + - iris_left + - iris_right + - romac + - + - + - + include: + - board: proton_c + shield: clueboard_california +``` + +:::note +Notice that both the left and right halves of a split board need to be added to the list of shields for proper error checking. +:::note diff --git a/docs/docs/development/guide-usb-logging.md b/docs/docs/development/guide-usb-logging.md new file mode 100644 index 0000000..6e4e2be --- /dev/null +++ b/docs/docs/development/guide-usb-logging.md @@ -0,0 +1,103 @@ +--- +title: USB Logging +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Overview + +If you are developing ZMK on a device that does not have a built in UART for debugging and log/console output, +Zephyr can be configured to create a USB CDC ACM device and the direct all `printk`, console output, and log +messages to that device instead. + +:::warning Battery Life Impact + +Enabling logging increases the power usage of your keyboard, and can have a non-trivial impact to your time on battery. +It is recommended to only enable logging when needed, and not leaving it on by default. + +::: + +## Kconfig + +The following KConfig values need to be set, either by copy and pasting into the `app/prj.conf` file, or by running +`west build -t menuconfig` and manually enabling the various settings in that UI. + +:::note +If you are debugging your own keyboard in your [user config repository](./user-setup.md), use +`config/boards/shields//.conf` instead of `app/prj.conf`. In Github +Actions, you can search the `Kconfig file` build log to verify the options above have been enabled +for you successfully. +::: + +``` +# Turn on logging, and set ZMK logging to debug output +CONFIG_LOG=y +CONFIG_ZMK_LOG_LEVEL_DBG=y + +# Turn on USB CDC ACM device +CONFIG_USB=y +CONFIG_USB_DEVICE_STACK=y +CONFIG_USB_CDC_ACM=y +CONFIG_USB_CDC_ACM_RINGBUF_SIZE=1024 +CONFIG_USB_CDC_ACM_DEVICE_NAME="CDC_ACM" +CONFIG_USB_CDC_ACM_DEVICE_COUNT=1 + +# Enable serial console +CONFIG_SERIAL=y +CONFIG_CONSOLE=y +CONFIG_UART_INTERRUPT_DRIVEN=y +CONFIG_UART_LINE_CTRL=y + +# Enable USB UART, and set the console device +CONFIG_UART_CONSOLE=y +CONFIG_USB_UART_CONSOLE=y +CONFIG_UART_CONSOLE_ON_DEV_NAME="CDC_ACM_0" +CONFIG_USB_UART_DTR_WAIT=n +``` + +## Viewing Logs + +After flashing the updated ZMK image, the board should expose a USB CDC ACM device that you can connect to and view the logs. + + + + +On Linux, this should be a device like `/dev/ttyACM0` and you can connect with `minicom` or `tio` as usual, e.g.: + +``` +sudo tio /dev/ttyACM0 +``` + + + + +On Windows, you can use [PuTTY](https://www.putty.org/). Once installed, use Device Manager to figure out which COM port your controller is communicating on (listed under 'Ports (COM & LPT)') and specify that as the 'Serial line' in PuTTY. + +![Controller COM port](../assets/usb-logging/com.jpg) + +![PuTTY settings](../assets/usb-logging/putty.jpg) + +If you already have the Ardunio IDE installed you can also use its built-in Serial Monitor. + + + + +On MacOS, the device name is something like `/dev/tty.usbmodemXXXXX` where `XXXXX` is some numerical ID. +You can connect to the device with [tio](https://tio.github.io/) (can be installed via [Homebrew](https://formulae.brew.sh/formula/tio)): + +``` +sudo tio /dev/tty.usbmodem14401 +``` + +You should see tio printing `Disconnected` or `Connected` when you disconnect or reconnect the USB cable. + + + +From there, you should see the various log messages from ZMK and Zephyr, depending on which systems you have set to what log levels. diff --git a/docs/docs/development/posix-board.md b/docs/docs/development/posix-board.md new file mode 100644 index 0000000..71460a8 --- /dev/null +++ b/docs/docs/development/posix-board.md @@ -0,0 +1,38 @@ +--- +title: Native Posix board target +--- + +In order to iterate quickly on firmware features, it can +be helpful to build and run the firmware on your local +workstation, with generated virtual press/release events +flowing into the handler functions. + +## Prerequisites + +In order to build targeting the `native_posix` board, you need to setup your system +with a compiler that can target 32-bit POSIX. + +On Debian, you can do this with: + +``` +apt install -y gcc-multilib +``` + +## Building + +To do this, you can build ZMK targeting the +`native_posix` board. + +``` +west build --pristine --board native_posix +``` + +Once built, you can run the firmware locally: + +``` +./build/zephyr/zephyr.exe +``` + +## Virtual Key Events + +The virtual key presses are hardcoded in `boards/native_posix.overlay` file, should you want to change the sequence to test various actions like Mod-Tap, etc. diff --git a/docs/docs/development/setup.md b/docs/docs/development/setup.md new file mode 100644 index 0000000..441299a --- /dev/null +++ b/docs/docs/development/setup.md @@ -0,0 +1,554 @@ +--- +title: Basic Setup +sidebar_label: Basic Setup +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const OsTabs = (props) => ({props.children}); + +## Prerequisites + +ZMK requires the following base packages to first be installed: + +- Git +- Python 3 +- `pip` +- `wget` +- devicetree compiler +- CMake +- `dfu-util` +- Various build essentials, e.g. gcc, automake, autoconf + + + + +On Debian and Ubuntu, we'll use `apt` to install our base dependencies: + +First, if you haven't updated recently, or if this is a new install, +you should update to get the latest package information: + +```sh +sudo apt update +``` + +With the latest package information, you can now install the base dependencies: + +```sh +sudo apt install -y \ + git \ + wget \ + autoconf \ + automake \ + build-essential \ + bzip2 \ + ccache \ + device-tree-compiler \ + dfu-util \ + g++ \ + gcc \ + libtool \ + make \ + ninja-build \ + cmake \ + python3-dev \ + python3-pip \ + python3-setuptools \ + xz-utils +``` + +:::note +Ubuntu 18.04 LTS release packages a version of CMake that is too old. Please upgrade to Ubuntu 20.04 LTS +or download and install CMake version 3.13.1 or newer manually. +::: + + + +On Raspberry OS, we'll use `apt` to install our base dependencies: + +First, if you haven't updated recently, or if this is a new install, +you should update to get the latest package information: + +```sh +sudo apt update +``` + +With the latest package information, you can now install the base dependencies: + +```sh +sudo apt install -y \ + git \ + wget \ + autoconf \ + automake \ + build-essential \ + bzip2 \ + ccache \ + device-tree-compiler \ + dfu-util \ + g++ \ + gcc \ + libtool \ + make \ + ninja-build \ + cmake \ + python3-dev \ + python3-pip \ + python3-setuptools \ + xz-utils +``` + + + + +On Fedora, we'll use `dnf` to install our base dependencies: + +#### DNF Update + +First, if you haven't updated recently, or if this is a new install, +you should update to get the latest package information: + +```sh +sudo dnf update +``` + +#### Install Dependencies + +With the latest package information, you can now install the base dependencies: + +```sh +sudo dnf install -y \ + git \ + wget \ + autoconf \ + automake \ + bzip2 \ + ccache \ + dtc \ + dfu-util \ + g++ \ + gcc \ + libtool \ + make \ + ninja-build \ + cmake \ + python3-devel \ + python3-pip \ + python3-setuptools \ + xz +``` + + + + +:::note +Use `cmd.exe` with these instructions rather than PowerShell. +::: + +Chocolatey is recommended and used for the following instructions. You can manually install each of these applications and add them to your `PATH` if you don't want to use Chocolatey. + +1. [Install Chocolatey](https://chocolatey.org/install) +2. Open `cmd.exe` as **Administrator** +3. Run the following `choco` commands: + ```shell + choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System' + choco install ninja gperf python git + ``` + +It is recommended to install `dfu-util` to avoid any later confusion while flashing devices. You can do this by running this command with chocolatey: + +```shell +choco install dfu-util +``` + + + + +#### Homebrew + +Homebrew is required to install the system dependencies. If you haven't done so, visit [Homebrew](https://brew.sh/) for instructions. Once installed, use it to install the base dependencies: + +``` +brew install cmake ninja python3 ccache dtc git wget dfu-util +``` + + + + +This setup leverages the same [image which is used by the GitHub action](https://github.com/zmkfirmware/zephyr-west-action) for local development. Beyond the benefits of [dev/prod parity](https://12factor.net/dev-prod-parity), this approach is also the easiest to set up. No toolchain or dependencies are necessary when using Docker; the container image you'll be using already has the toolchain installed and set up to use. + +1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system. +2. Install [VS Code](https://code.visualstudio.com/) +3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) + +:::info +The docker container includes `west` and the compilation toolchain. If you're using docker and VS Code, you can skip right to [Source Code](#source-code). +::: + + + + +## Setup + +### West Installation + +`west` is the [Zephyr™ meta-tool](https://docs.zephyrproject.org/2.3.0/guides/west/index.html) used to configure and build Zephyr™ applications. + +West can be installed by using the `pip` python package manager. The [Zephyr™ instructions](https://docs.zephyrproject.org/latest/guides/west/install.html#installing-west) are summarized here: + + + + +```sh +pip3 install --user -U west +``` + + + + +In `cmd.exe` as **Administrator**: + +```sh +pip3 install -U west +``` + +:::note +**For Windows, do not use the `--user` argument** that Linux uses otherwise `west` will be installed in a different location and the below instructions for adding Python `pip` will no longer apply. +::: + +Once `west` is installed, close Command Prompt and open a new session as a **user** for the remainder of the instructions. + + + + +:::danger `pip` user packages +If you haven't done so yet, you may need to add the Python `pip` package directory to your `PATH` otherwise your computer will not be able to find the `west` command. +::: + + + +Run the following commands: + +```sh +echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc +source ~/.bashrc +``` + + + + +1. See the [Environment Variables](#environment-variables) section on how to get to the Environment Variables page. +2. Under "System variables" select the "Path" variable. Click "Edit..." and then "New" to add the directory where your `west.exe` is located. By default this should be `C:\Python##\Scripts` where ## is your Python version number. +3. Close Command Prompt and open a new session for the changes to take effect, or run `refreshenv`. + + + + +### Toolchain Installation + +The toolchain provides the compiler, linker, etc., necessary to build for the target +platform. + + + + +#### Zephyr™ ARM SDK + +To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr™ ARM SDK to your system: + +``` +export ZSDK_VERSION=0.11.2 +wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" && \ + sh "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" --quiet -- -d ~/.local/zephyr-sdk-${ZSDK_VERSION} && \ + rm "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" +``` + +The installation will prompt with several questions about installation location, and creating a default `~/.zephyrrc` for you with various variables. The defaults should normally work as expected. + + + + +Because Raspberry OS (Raspbian) runs on the same architecture (but different ABI) as the keyboard MCUs, +the operating system's installed [cross compilers](https://docs.zephyrproject.org/2.3.0/getting_started/toolchain_other_x_compilers.html) can be used to target the different ABI. + +First, the cross compiler should be installed: + +```sh +sudo apt install gcc-arm-none-eabi +``` + +Next, we'll configure Zephyr™ with some extra environment variables needed to find the cross compiler by adding the following to `~/.zephyrrc`: + +```sh +export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile +export CROSS_COMPILE=/usr/bin/arm-none-eabi- +``` + + + + +#### Zephyr™ ARM SDK + +To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr™ ARM SDK to your system: + +``` +export ZSDK_VERSION=0.11.2 +wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" && \ + sh "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" --quiet -- -d ~/.local/zephyr-sdk-${ZSDK_VERSION} && \ + rm "zephyr-toolchain-arm-\${ZSDK_VERSION}-setup.run" +``` + +The installation will prompt with several questions about installation location, and creating a default `~/.zephyrrc` for you with various variables. The defaults should normally work as expected. + + + + +#### GNU ARM Embedded + +Since the Zephyr™ SDK is not available for Windows, we recommending following the [Zephyr documentation](https://docs.zephyrproject.org/2.3.0/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded) to install a GNU ARM Embedded build. Note the warnings regarding installing the toolchain into a path with spaces, and make sure to follow the steps to add the environment variables which are also summarized with screenshots in the [Environment Variables](#environment-variables) section below. + + + + +#### GNU ARM Embedded + +Since the Zephyr™ SDK is not available for macOS, we recommending following the steps to install the [GNU ARM Embedded](https://docs.zephyrproject.org/2.3.0/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded). + +:::warning Security Controls Workaround + +Please be sure to read the [additional setup instructions](https://docs.zephyrproject.org/2.3.0/getting_started/installation_mac.html#mac-gatekeeper) needed to address security controls found in macOS 10.15 Catalina and newer + +::: + + + + +:::note +If you intend to build firmware straight away, make sure to correctly setup the current shell. + +Notes on setting this up can be found in the [Environment Variables](#environment-variables) section. +The transient instructions can be used to setup the current shell, and the automatic instructions can setup any newly made shells automatically. + +The transient instructions must be run to build firmware using the current shell. +::: + +### Source Code + +Next, you'll need to clone the ZMK source repository if you haven't already. Navigate to the folder you would like to place your `zmk` directory in and run the following command: + +``` +git clone https://github.com/zmkfirmware/zmk.git +``` + +### Initialize & Update Zephyr Workspace + +Since ZMK is built as a Zephyr™ application, the next step is +to use `west` to initialize and update your workspace. The ZMK +Zephyr™ application is in the `app/` source directory: + +#### Step into the repository + + + + +```sh +cd zmk +``` + + + + +```sh +cd zmk +``` + + + + +```sh +cd zmk +``` + + + + +```sh +cd zmk +``` + + + + +```sh +cd zmk +``` + + + + + +Open the `zmk` checkout folder in VS Code. The repository includes a configuration for containerized development, so an alert will pop up: + +![VS Code Dev Container Configuration Alert](../assets/dev-setup/vscode_devcontainer.png) + +Click `Reopen in Container` in order to reopen the VS Code with the running container. + +The first time you do this on your machine, it will pull the docker image down from the registry and build the container. Subsequent launches are much faster! + +:::caution +All subsequent steps must be performed from the VS Code terminal _inside_ the container. +::: + + + + +#### Initialize West + +```sh +west init -l app/ +``` + +:::caution Command Not Found? +If you encounter errors like `command not found: west` then your `PATH` environment variable is likely +missing the Python 3 user packages directory. See the [West Build Command](#west-build-command) +section again for links to how to do this +::: + +#### Update To Fetch Modules + +```sh +west update +``` + +:::tip +This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection! +::: + +:::info +If you're using Docker, you're done with setup! You must restart the container at this point. The easiest way to do so is to close the VS Code window, verify that the container has stopped in Docker Dashboard, and reopen the container with VS Code. + +Once your container is restarted, proceed to [Building and Flashing](./development/build-flash.md). +::: + +#### Export Zephyr™ Core + +```sh +west zephyr-export +``` + +#### Install Zephyr Python Dependencies + +```sh +pip3 install --user -r zephyr/scripts/requirements-base.txt +``` + +### Environment Variables + + + + +#### For GNU ARM Embedded on Windows + +On Windows, only two environment variables need to be set for ZMK to build properly: `ZEPHYR_TOOLCHAIN_VARIANT` and `GNUARMEMB_TOOLCHAIN_PATH`. + +1. Open Start Menu and type 'env' to find the 'Edit the system environment variables' option. Open it. + +![Environment variables in Start Menu](../assets/env-var/start_menu.png) + +2. Click 'Environment Variables...'. + +![Environment variables button](../assets/env-var/env_var.png) + +3. Click "New..." under System variables to create a new system variable. + +![Environment variables menu](../assets/env-var/new_variable.png) + +4. Set the variable name to 'ZEPHYR_TOOLCHAIN_VARIANT' and value to 'gnuarmemb'. Click OK to save. + +![Adding Zephyr toolchain variable](../assets/env-var/zephyr_toolchain.png) + +5. Create another variable with variable name 'GNUARMEMB_TOOLCHAIN_PATH' and value set to wherever you installed your toolchain. **Make sure this path does not contain any spaces.** If it does, rename the folder and update here. Click OK to save. + +![Adding GNUARMEMB variable](../assets/env-var/gnuarmemb.png) + +6. Close Command Prompt and reopen, or run `refreshenv` to apply the changes. + + + + + +#### For Zephyr + +By default, the Zephyr™ SDK will create a file named `~/.zephyrrc` with the correct environment variables to build ZMK. +We suggest two main [options](https://docs.zephyrproject.org/2.3.0/guides/env_vars.html?highlight=zephyrrc) for how to load those settings. + +##### Per Shell + +To load the Zephyr environment properly for just one transient shell, run the following from your ZMK checkout directory: + +``` +source zephyr/zephyr-env.sh +``` + +##### All Shells + +To load the environment variables for your shell every time, +append the existing `~/.zephyrrc` file to your shell's RC file and then start a new shell. + + + + + +``` +cat ~/.zephyrrc >> ~/.bashrc +``` + + + + + +``` +cat ~/.zephyrrc >> ~/.zshrc +``` + + + + + + + + diff --git a/docs/docs/development/tests.md b/docs/docs/development/tests.md new file mode 100644 index 0000000..8df6cb1 --- /dev/null +++ b/docs/docs/development/tests.md @@ -0,0 +1,20 @@ +--- +title: Tests +sidebar_label: Tests +--- + +Running tests requires [native posix support](posix-board). Any folder under `/app/tests` +containing `native_posix.keymap` will be selected when running `./run-test.sh all`. + +## Creating a New Test Set + +1. Copy the test set that most closely resembles the tests you will be creating. +2. Rename the newly created test set to the behavior you're testing e.g, toggle-layer +3. Modify `behavior_keymap.dtsi` to create a keymap using the behavior and related behaviors +4. Modify `test_case/native_posix.keymap` for a simulated use case +5. Modify `test_case/events.patterns` to collect relevant logs to the test + - See: [sed manual](https://www.gnu.org/software/sed/manual/sed.html) and + [tutorial](https://www.digitalocean.com/community/tutorials/the-basics-of-using-the-sed-stream-editor-to-manipulate-text-in-linux) +6. Modify `test_case/keycode_events.snapshot` for to include the expected output +7. Rename the `test_case` folder to describe the test. +8. Repeat steps 4 to 7 for every test case diff --git a/docs/docs/features/encoders.md b/docs/docs/features/encoders.md index 52a4357..f962845 100644 --- a/docs/docs/features/encoders.md +++ b/docs/docs/features/encoders.md @@ -41,4 +41,4 @@ Here, the left encoder is configured to control volume up and down while the rig ## Adding Encoder Support -See the [New Keyboard Shield](/docs/dev-guide-new-shield#encoders) documentation for how to add or modify additional encoders to your shield. +See the [New Keyboard Shield](../development/guide-new-shield#encoders) documentation for how to add or modify additional encoders to your shield. diff --git a/docs/docs/hardware.md b/docs/docs/hardware.md index 46e9f88..2ad6c33 100644 --- a/docs/docs/hardware.md +++ b/docs/docs/hardware.md @@ -47,4 +47,4 @@ Until detailed documentation is available, feel free to ask questions about how ## Contributing -If you'd like to add support for a new keyboard shield, head over to the [New Keyboard Shield](/docs/dev-guide-new-shield) documentation. +If you'd like to add support for a new keyboard shield, head over to the [New Keyboard Shield](development/guide-new-shield) documentation. diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md index 7f7d994..0fe0b66 100644 --- a/docs/docs/troubleshooting.md +++ b/docs/docs/troubleshooting.md @@ -26,7 +26,7 @@ Variations of the warnings shown below occur when flashing the `.uf2` ### 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, click [here](../docs/dev-setup#environment-variables). +For more information, click [here](../docs/development/setup#environment-variables). ### dtlib.DTError diff --git a/docs/docs/user-setup.md b/docs/docs/user-setup.md index d155286..50074ad 100644 --- a/docs/docs/user-setup.md +++ b/docs/docs/user-setup.md @@ -105,7 +105,7 @@ Pick an MCU board: :::note If you are building firmware for a new keyboard shield that is not included in the built-in list of shields, you can choose any shield from the list that is similar to yours to generate the repository, -and edit / add necessary files according to the [guide for adding new keyboard shield](./dev-guide-new-shield.md). +and edit / add necessary files according to the [guide for adding new keyboard shield](./development/guide-new-shield). ::: When prompted, enter the number for the corresponding keyboard shield you would like to target: diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 9754834..2716039 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -45,7 +45,7 @@ module.exports = { }, { label: "Development", - to: "docs/dev-setup/", + to: "docs/development/setup/", }, ], }, diff --git a/docs/sidebars.js b/docs/sidebars.js index 59cfb1e..3e4d2e4 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -37,13 +37,16 @@ module.exports = { "codes/power", ], Development: [ - "dev-clean-room", - "dev-setup", - "dev-build-flash", - "dev-boards-shields-keymaps", - "dev-posix-board", - "dev-tests", + "development/clean-room", + "development/setup", + "development/build-flash", + "development/boards-shields-keymaps", + "development/posix-board", + "development/tests", + ], + "Dev Guides": [ + "development/guide-new-shield", + "development/guide-usb-logging", ], - "Dev Guides": ["dev-guide-new-shield", "dev-guide-usb-logging"], }, }; -- cgit v1.2.3