From bdeb6865e18c211a2d26a1f007711710f489db27 Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Sun, 6 Sep 2020 19:55:56 -0700 Subject: Update sidebars.js --- docs/sidebars.js | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/sidebars.js b/docs/sidebars.js index 3df183b..7da0f5b 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -7,6 +7,7 @@ module.exports = { "user-setup", "customization", "bond-reset", + "troubleshooting" ], Features: [ "feature/keymaps", -- cgit v1.2.3 From cb95b9f11a687cb165adaffdeed866e80c7fdc7b Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Sun, 6 Sep 2020 20:03:33 -0700 Subject: Restored Troubleshooting.md and associated files --- .../assets/troubleshooting/keymaps/errorscreen.png | Bin 0 -> 186351 bytes .../assets/troubleshooting/keymaps/healthyEDIT.png | Bin 0 -> 188078 bytes .../troubleshooting/keymaps/unhealthyEDIT.png | Bin 0 -> 187729 bytes docs/docs/behavior/key-press.md | 7 ++++- docs/docs/troubleshooting.md | 33 +++++++++++++++++++++ 5 files changed, 39 insertions(+), 1 deletion(-) create mode 100644 docs/docs/assets/troubleshooting/keymaps/errorscreen.png create mode 100644 docs/docs/assets/troubleshooting/keymaps/healthyEDIT.png create mode 100644 docs/docs/assets/troubleshooting/keymaps/unhealthyEDIT.png create mode 100644 docs/docs/troubleshooting.md (limited to 'docs') diff --git a/docs/docs/assets/troubleshooting/keymaps/errorscreen.png b/docs/docs/assets/troubleshooting/keymaps/errorscreen.png new file mode 100644 index 0000000..73b5b58 Binary files /dev/null and b/docs/docs/assets/troubleshooting/keymaps/errorscreen.png differ diff --git a/docs/docs/assets/troubleshooting/keymaps/healthyEDIT.png b/docs/docs/assets/troubleshooting/keymaps/healthyEDIT.png new file mode 100644 index 0000000..50d2c73 Binary files /dev/null and b/docs/docs/assets/troubleshooting/keymaps/healthyEDIT.png differ diff --git a/docs/docs/assets/troubleshooting/keymaps/unhealthyEDIT.png b/docs/docs/assets/troubleshooting/keymaps/unhealthyEDIT.png new file mode 100644 index 0000000..3fd8dc7 Binary files /dev/null and b/docs/docs/assets/troubleshooting/keymaps/unhealthyEDIT.png differ diff --git a/docs/docs/behavior/key-press.md b/docs/docs/behavior/key-press.md index f58225d..d427f9d 100644 --- a/docs/docs/behavior/key-press.md +++ b/docs/docs/behavior/key-press.md @@ -27,6 +27,11 @@ There is an [open issue](https://github.com/zmkfirmware/zmk/issues/21) to provid complete set of defines for the full keypad and consumer usage pages in the future for ZMK. ::: +### Improperly defined keymap - `dtlib.DTError: .dts.pre.tmp:` + +When compiling firmware from a keymap, it may be common to encounter an error in the form of a`dtlib.DTError: .dts.pre.tmp:`. +For instructions to resolve such an error, click [here](../troubleshooting###Improperly-defined-keymap) + ## Keypad Key Press The "keypad key press" behavior sends standard keypad keycodes on press/release. @@ -59,4 +64,4 @@ Example: ``` &cp M_PREV -``` +``` \ No newline at end of file diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md new file mode 100644 index 0000000..cecee25 --- /dev/null +++ b/docs/docs/troubleshooting.md @@ -0,0 +1,33 @@ +--- +id: troubleshooting +title: Troubleshooting +sidebar_title: Troubleshooting +--- +### Summary + +The following page provides suggestions for common errors that may occur during firmware compilation. If the information provided is insufficient to resolve the issue, feel free to seek out help from the [ZMK Discord](https://zmkfirmware.dev/community/discord/invite). + +### Environment Variables not Defined + +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). + +### Improperly defined keymap + +An error along the lines of `dtlib.DTError: .dts.pre.tmp:` during firmware compilation indicates an issue within the `.keymap` file. +This can be verified by checking the file in question, found in `mkdir/app/build`. + +| ![Example Error Screen](../docs/assets/troubleshooting/keymaps/errorscreen.png) | +| :-------------------------------------------------------------------------------: | +| An example of the dtlib.DTError when compiling an iris with the nice!nano while the keymap is not properly defined | + +After opening the `.dts.pre.tmp:` and scrolling down to the referenced line, one can locate errors within their shield's keymap by checking if the referenced keycodes were properly converted into the correct [USB HID Usage ID](https://www.usb.org/document-library/hid-usage-tables-12). + +| ![Unhealthy Keymap Temp](../docs/assets/troubleshooting/keymaps/unhealthyEDIT.png) | +| :-------------------------------------------------------------------------------: | +| An incorrectly defined keymap unable to compile. As shown in red, `&kp SPAC` is not a valid +reference to the [USB HID Usage ID](https://www.usb.org/document-library/hid-usage-tables-12) used for "Keyboard Spacebar" | + +| ![Healthy Keymap Temp](../docs/assets/troubleshooting/keymaps/healthyEDIT.png) | +| :-------------------------------------------------------------------------------: | +| A properly defined keymap with successful compilation. As shown in red, the corrected keycode (`&kp SPC`) references the proper Usage ID defined in the [USB HID Usage Tables](https://www.usb.org/document-library/hid-usage-tables-12)| \ No newline at end of file -- cgit v1.2.3 From 336cae9d0fd0aa84a30768f2629bbbf357e8cdaa Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Sun, 6 Sep 2020 20:13:45 -0700 Subject: Adjusted lines to fix caption format --- docs/docs/troubleshooting.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md index cecee25..61c6e79 100644 --- a/docs/docs/troubleshooting.md +++ b/docs/docs/troubleshooting.md @@ -24,9 +24,8 @@ This can be verified by checking the file in question, found in `mkdir/app/build After opening the `.dts.pre.tmp:` and scrolling down to the referenced line, one can locate errors within their shield's keymap by checking if the referenced keycodes were properly converted into the correct [USB HID Usage ID](https://www.usb.org/document-library/hid-usage-tables-12). | ![Unhealthy Keymap Temp](../docs/assets/troubleshooting/keymaps/unhealthyEDIT.png) | -| :-------------------------------------------------------------------------------: | -| An incorrectly defined keymap unable to compile. As shown in red, `&kp SPAC` is not a valid -reference to the [USB HID Usage ID](https://www.usb.org/document-library/hid-usage-tables-12) used for "Keyboard Spacebar" | +| :-------------------------------------------------------------------------------: | +| An incorrectly defined keymap unable to compile. As shown in red, `&kp SPAC` is not a valid reference to the [USB HID Usage ID](https://www.usb.org/document-library/hid-usage-tables-12) used for "Keyboard Spacebar" | | ![Healthy Keymap Temp](../docs/assets/troubleshooting/keymaps/healthyEDIT.png) | | :-------------------------------------------------------------------------------: | -- cgit v1.2.3 From 618c537be14e3bf8ba0515784078df1b42c60915 Mon Sep 17 00:00:00 2001 From: Kurtis Lew Date: Sun, 6 Sep 2020 20:45:28 -0700 Subject: Updated Headers --- docs/docs/troubleshooting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md index 61c6e79..cd8bfd6 100644 --- a/docs/docs/troubleshooting.md +++ b/docs/docs/troubleshooting.md @@ -7,12 +7,12 @@ sidebar_title: Troubleshooting The following page provides suggestions for common errors that may occur during firmware compilation. If the information provided is insufficient to resolve the issue, feel free to seek out help from the [ZMK Discord](https://zmkfirmware.dev/community/discord/invite). -### Environment Variables not Defined +### 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). -### Improperly defined keymap +### dtlib.DTError An error along the lines of `dtlib.DTError: .dts.pre.tmp:` during firmware compilation indicates an issue within the `.keymap` file. This can be verified by checking the file in question, found in `mkdir/app/build`. @@ -29,4 +29,4 @@ After opening the `.dts.pre.tmp:` and scrolling down to the | ![Healthy Keymap Temp](../docs/assets/troubleshooting/keymaps/healthyEDIT.png) | | :-------------------------------------------------------------------------------: | -| A properly defined keymap with successful compilation. As shown in red, the corrected keycode (`&kp SPC`) references the proper Usage ID defined in the [USB HID Usage Tables](https://www.usb.org/document-library/hid-usage-tables-12)| \ No newline at end of file +| A properly defined keymap with successful compilation. As shown in red, the corrected keycode (`&kp SPC`) references the proper Usage ID defined in the [USB HID Usage Tables](https://www.usb.org/document-library/hid-usage-tables-12)| -- cgit v1.2.3 From df2da813f1f50dbd20ef226a439208fbf5d23c17 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Tue, 8 Sep 2020 16:08:09 -0400 Subject: fix(docs): Remove broken Discord invite links. --- docs/docs/faq.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/docs/faq.md b/docs/docs/faq.md index 2ab158d..d8bbd71 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -76,7 +76,7 @@ Please note, many keyboards only have a single PCB which includes the “brains ### What bootloader does ZMK use? -ZMK isn’t designed for any particular bootloader, and supports flashing different boards with different flash utilities (e.g. OpenOCD, nrfjprog, etc.). So if you have any difficulties, please let us know on [Discord](https://discord.gg/VJnx9kr)! +ZMK isn’t designed for any particular bootloader, and supports flashing different boards with different flash utilities (e.g. OpenOCD, nrfjprog, etc.). So if you have any difficulties, please let us know on [Discord](https://zmkfirmware.dev/community/discord/invite)! ### Can I contribute? @@ -84,11 +84,11 @@ Of course! Please use the developer [documentation](/docs) to get started! ### I have an idea! What should I do? -Please join us on [Discord](https://discord.gg/VJnx9kr) and discuss it with us! +Please join us on [Discord](https://zmkfirmware.dev/community/discord/invite) and discuss it with us! ### I want to add a new keyboard! What should I do? -The exact process for the management of all the possible hardware is still being finalized, but any developer looking to contribute new keyboard definitions should chat with us on [Discord](https://discord.gg/VJnx9kr) to get started. +The exact process for the management of all the possible hardware is still being finalized, but any developer looking to contribute new keyboard definitions should chat with us on [Discord](https://zmkfirmware.dev/community/discord/invite) to get started. ### Does ZMK have a Code of Conduct? -- cgit v1.2.3 From 6456fab8e0278d3cd5b73ef4ddca49845c00c19d Mon Sep 17 00:00:00 2001 From: Alexander Elias Date: Wed, 9 Sep 2020 09:14:01 -0700 Subject: Should this be org instead of com? --- docs/docs/intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 29045f7..50a747c 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -5,7 +5,7 @@ sidebar_label: Introduction --- ZMK Firmware is an open source (MIT) keyboard -firmware built on the [Zephyr™ Project](https://zephyrproject.com/) Real Time Operating System (RTOS). +firmware built on the [Zephyr™ Project](https://zephyrproject.org/) Real Time Operating System (RTOS). The goal is to provider a powerful, featureful keyboard firmware that is free of licensing issues that prevent upstream BLE support as a first-class -- cgit v1.2.3 From 6a0e85ea726ac49bb95bdfd1c7770f7da826bf1a Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Thu, 10 Sep 2020 09:54:22 +0530 Subject: labelled image to be added --- docs/docs/pro-micro-labelled-image.jpg | Bin 0 -> 115573 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/docs/pro-micro-labelled-image.jpg (limited to 'docs') diff --git a/docs/docs/pro-micro-labelled-image.jpg b/docs/docs/pro-micro-labelled-image.jpg new file mode 100644 index 0000000..f72d407 Binary files /dev/null and b/docs/docs/pro-micro-labelled-image.jpg differ -- cgit v1.2.3 From 82ddf81fcb4f1f5e629fe2c2dd0c8c0ba803964f Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Thu, 10 Sep 2020 09:59:33 +0530 Subject: Update dev-guide-new-shield.md --- docs/docs/dev-guide-new-shield.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index bc5175b..8aa62da 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -64,6 +64,8 @@ endif ## Shield Overlay +![Labelled Pro Micro Image](pro-micro-labelled-image.jpg) + 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: -- cgit v1.2.3 From d02fc07c4f53868cc0b498cdc2fb6b0768cbe8cb Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Thu, 10 Sep 2020 10:02:25 +0530 Subject: Update dev-boards-shields-keymaps.md --- docs/docs/dev-boards-shields-keymaps.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/docs/dev-boards-shields-keymaps.md b/docs/docs/dev-boards-shields-keymaps.md index cfe5252..9810558 100644 --- a/docs/docs/dev-boards-shields-keymaps.md +++ b/docs/docs/dev-boards-shields-keymaps.md @@ -35,6 +35,8 @@ in the `app/boards/${arch}/${board_name}` directory, e.g. `app/boards/arm/planck ## Pro Micro Compatible Keyboard +![Labelled Pro Micro Image](pro-micro-labelled-image.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 -- cgit v1.2.3 From 3c9f58f9d40d21f5c0bec20b6da75e135503af0a Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Thu, 10 Sep 2020 10:03:48 +0530 Subject: Update dev-boards-shields-keymaps.md --- docs/docs/dev-boards-shields-keymaps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/dev-boards-shields-keymaps.md b/docs/docs/dev-boards-shields-keymaps.md index 9810558..17a3847 100644 --- a/docs/docs/dev-boards-shields-keymaps.md +++ b/docs/docs/dev-boards-shields-keymaps.md @@ -35,7 +35,7 @@ in the `app/boards/${arch}/${board_name}` directory, e.g. `app/boards/arm/planck ## Pro Micro Compatible Keyboard -![Labelled Pro Micro Image](pro-micro-labelled-image.jpg) +![Labelled Pro Micro pins](pro-micro-labelled-image.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 -- cgit v1.2.3 From 92b3ea8a6b75764acab216470050c8138acf2643 Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Thu, 10 Sep 2020 10:04:15 +0530 Subject: Update dev-guide-new-shield.md --- docs/docs/dev-guide-new-shield.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index 8aa62da..23d2387 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -64,7 +64,7 @@ endif ## Shield Overlay -![Labelled Pro Micro Image](pro-micro-labelled-image.jpg) +![Labelled Pro Micro pins](pro-micro-labelled-image.jpg) 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: -- cgit v1.2.3 From 073f5c8b98c5111d954fe5bfe98951b24983449d Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Thu, 10 Sep 2020 18:40:07 -0700 Subject: Added File Transfer Error/CMake Warning Docs --- .../assets/troubleshooting/filetransfer/linux.png | Bin 0 -> 40111 bytes .../troubleshooting/filetransfer/windows.png | Bin 0 -> 12077 bytes docs/docs/troubleshooting.md | 31 ++++++++++++++++++++- 3 files changed, 30 insertions(+), 1 deletion(-) create mode 100644 docs/docs/assets/troubleshooting/filetransfer/linux.png create mode 100644 docs/docs/assets/troubleshooting/filetransfer/windows.png (limited to 'docs') diff --git a/docs/docs/assets/troubleshooting/filetransfer/linux.png b/docs/docs/assets/troubleshooting/filetransfer/linux.png new file mode 100644 index 0000000..c192dfa Binary files /dev/null and b/docs/docs/assets/troubleshooting/filetransfer/linux.png differ diff --git a/docs/docs/assets/troubleshooting/filetransfer/windows.png b/docs/docs/assets/troubleshooting/filetransfer/windows.png new file mode 100644 index 0000000..91cb8a6 Binary files /dev/null and b/docs/docs/assets/troubleshooting/filetransfer/windows.png differ diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md index cd8bfd6..4820e11 100644 --- a/docs/docs/troubleshooting.md +++ b/docs/docs/troubleshooting.md @@ -7,11 +7,40 @@ sidebar_title: Troubleshooting The following page provides suggestions for common errors that may occur during firmware compilation. If the information provided is insufficient to resolve the issue, feel free to seek out help from the [ZMK Discord](https://zmkfirmware.dev/community/discord/invite). +### File Transfer Error + +Variations of the warnings shown below occur when flashing the `.uf2` onto the microcontroller. This is because the microcontroller resets itself before the OS receives confirmation that the file transfer is complete. Errors like this are normal and can generally be ignored. Verification of a functional board can be done by attempting to pair your computer to your newly flashed keyboard via Bluetooth or plugging in a USB cable if `ZMK_USB` is enabled in your Kconfig.defconfig. + +| ![Example Error Screen](../docs/assets/troubleshooting/filetransfer/windows.png) | +| :-------------------------------------------------------------------------------: | +| An example of the file transfer error on Windows 10 | + +| ![Example Error Screen](../docs/assets/troubleshooting/filetransfer/linux.png) | +| :-------------------------------------------------------------------------------: | +| An example of the file transfer error on Linux | + + ### 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. +``` +CMake Warning at C:/zmk/zephyr/subsys/usb/CMakeLists.txt:28 (message): + CONFIG_USB_DEVICE_VID has default value 0x2FE3. + + This value is only for testing and MUST be configured for USB products. + + +CMake Warning at C:/zmk/zephyr/subsys/usb/CMakeLists.txt:34 (message): + CONFIG_USB_DEVICE_PID has default value 0x100. + + This value is only for testing and MUST be configured for USB products. +``` + +CMake Warnings shown above during `west build` are normal occurrences. They should not negatively affect the firmware's ability to function as normal. + +On the other hand, 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). + ### dtlib.DTError An error along the lines of `dtlib.DTError: .dts.pre.tmp:` during firmware compilation indicates an issue within the `.keymap` file. -- cgit v1.2.3 From 5b38fcff71a0e22407dbd418fb1900614ecbfb6f Mon Sep 17 00:00:00 2001 From: Kurtis Lew Date: Thu, 10 Sep 2020 18:44:39 -0700 Subject: Reversed pairing instructions --- docs/docs/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md index 4820e11..deb89b6 100644 --- a/docs/docs/troubleshooting.md +++ b/docs/docs/troubleshooting.md @@ -9,7 +9,7 @@ The following page provides suggestions for common errors that may occur during ### File Transfer Error -Variations of the warnings shown below occur when flashing the `.uf2` onto the microcontroller. This is because the microcontroller resets itself before the OS receives confirmation that the file transfer is complete. Errors like this are normal and can generally be ignored. Verification of a functional board can be done by attempting to pair your computer to your newly flashed keyboard via Bluetooth or plugging in a USB cable if `ZMK_USB` is enabled in your Kconfig.defconfig. +Variations of the warnings shown below occur when flashing the `.uf2` onto the microcontroller. This is because the microcontroller resets itself before the OS receives confirmation that the file transfer is complete. Errors like this are normal and can generally be ignored. Verification of a functional board can be done by attempting to pair your newly flashed keyboard to your computer via Bluetooth or plugging in a USB cable if `ZMK_USB` is enabled in your Kconfig.defconfig. | ![Example Error Screen](../docs/assets/troubleshooting/filetransfer/windows.png) | | :-------------------------------------------------------------------------------: | -- cgit v1.2.3 From 89ba824b2b28d4fdbd174ba20b1183d6547c19f8 Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Fri, 11 Sep 2020 11:04:58 +0530 Subject: typo --- docs/docs/user-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/user-setup.md b/docs/docs/user-setup.md index 2aade82..c207136 100644 --- a/docs/docs/user-setup.md +++ b/docs/docs/user-setup.md @@ -179,7 +179,7 @@ storage device. Once the flash is complete, the controller should automatically ## Wirelessly Connecting Your Keyboard -Connecting your keyboard wirelessly is the same as adding other Bluetooth devides: press the reset button and scan for devices. However, pairing and bonding is still currently being worked on to increase relability and ease of use. In addition, users have in general reported that Bluetooth pairing with computers tends to be quite finnicky. Try out the connection with your tablet or phone first, as those devices seem to work much more consistently. See [BLE Reset](./bond-reset.md) for help on resetting your MCUs if you're experiencing connection issues. +Connecting your keyboard wirelessly is the same as adding other Bluetooth devices: press the reset button and scan for devices. However, pairing and bonding is still currently being worked on to increase relability and ease of use. In addition, users have in general reported that Bluetooth pairing with computers tends to be quite finnicky. Try out the connection with your tablet or phone first, as those devices seem to work much more consistently. See [BLE Reset](./bond-reset.md) for help on resetting your MCUs if you're experiencing connection issues. ### Connecting Split Keyboard Halves -- cgit v1.2.3 From cd00c0aad41e4aad369bbc12f68b888ab2d9ddd4 Mon Sep 17 00:00:00 2001 From: Cody McGinnis Date: Fri, 11 Sep 2020 02:28:55 -0400 Subject: fix(docs): Fix the example mod tap configuration --- docs/docs/behavior/mod-tap.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/docs/behavior/mod-tap.md b/docs/docs/behavior/mod-tap.md index dcac492..068928a 100644 --- a/docs/docs/behavior/mod-tap.md +++ b/docs/docs/behavior/mod-tap.md @@ -31,8 +31,8 @@ You can configure a different tapping term in your keymap: ``` &mt { - tapping_term_ms: <400>; -} + tapping_term_ms = <400>; +}; / { keymap { -- cgit v1.2.3 From ce862d148db09ed318c9d592bef4e29f59949b5e Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Fri, 11 Sep 2020 19:47:20 +0530 Subject: Delete pro-micro-labelled-image.jpg --- docs/docs/pro-micro-labelled-image.jpg | Bin 115573 -> 0 bytes 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 docs/docs/pro-micro-labelled-image.jpg (limited to 'docs') diff --git a/docs/docs/pro-micro-labelled-image.jpg b/docs/docs/pro-micro-labelled-image.jpg deleted file mode 100644 index f72d407..0000000 Binary files a/docs/docs/pro-micro-labelled-image.jpg and /dev/null differ -- cgit v1.2.3 From 69e6a99180b51c0d9bdca44741e71e54a162bf14 Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Fri, 11 Sep 2020 19:49:46 +0530 Subject: Add files via upload --- docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg | Bin 0 -> 115573 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg (limited to 'docs') diff --git a/docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg b/docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg new file mode 100644 index 0000000..f72d407 Binary files /dev/null and b/docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg differ -- cgit v1.2.3 From e660e56dfb428d58d6c6548ac804c8933495c22d Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Fri, 11 Sep 2020 19:52:32 +0530 Subject: Update dev-boards-shields-keymaps.md --- docs/docs/dev-boards-shields-keymaps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/dev-boards-shields-keymaps.md b/docs/docs/dev-boards-shields-keymaps.md index 17a3847..9ed5a32 100644 --- a/docs/docs/dev-boards-shields-keymaps.md +++ b/docs/docs/dev-boards-shields-keymaps.md @@ -35,7 +35,7 @@ in the `app/boards/${arch}/${board_name}` directory, e.g. `app/boards/arm/planck ## Pro Micro Compatible Keyboard -![Labelled Pro Micro pins](pro-micro-labelled-image.jpg) +![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 -- cgit v1.2.3 From 4ce70831dddfbe1c8fda8d23086388ad36a421a5 Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Fri, 11 Sep 2020 19:54:03 +0530 Subject: Update dev-guide-new-shield.md --- docs/docs/dev-guide-new-shield.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index 23d2387..832519d 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -64,7 +64,7 @@ endif ## Shield Overlay -![Labelled Pro Micro pins](pro-micro-labelled-image.jpg) +![Labelled Pro Micro pins](assets/pro-micro/pro-micro-pins-labelled.jpg) 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: -- cgit v1.2.3 From c20eb9abac1797ff94012863d2bec582b68e6ded Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Fri, 11 Sep 2020 20:01:46 +0530 Subject: Update hold-tap.md --- docs/docs/behavior/hold-tap.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/docs/behavior/hold-tap.md b/docs/docs/behavior/hold-tap.md index fa68538..6790e88 100644 --- a/docs/docs/behavior/hold-tap.md +++ b/docs/docs/behavior/hold-tap.md @@ -56,7 +56,7 @@ A code example which configures a mod-tap setting that works with homerow mods: If this config does not work for you, try the flavor "tap-preferred" and a short tapping_term_ms such as 120ms. -If you want to use a tap-hold with a keycode from a different code page, you have to define another behavior with another "bindings" parameter.For example, if you want to use SHIFT and volume up, define the bindings like `bindings = <&kp>, <&cp>;`. Only single-argument behaviors are supported at the moment. +If you want to use a tap-hold with a keycode from a different code page, you have to define another behavior with another "bindings" parameter. For example, if you want to use SHIFT and volume up, define the bindings like `bindings = <&kp>, <&cp>;`. Only single-argument behaviors are supported at the moment. #### Note -Astute readers may notice similarities between the possible behaviors in ZMK and other firmware, such as QMK. The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the `tap-preferred` flavor is similar to `IGNORE_MOD_TAP_INTERRUPT`. \ No newline at end of file +Astute readers may notice similarities between the possible behaviors in ZMK and other firmware, such as QMK. The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the `tap-preferred` flavor is similar to `IGNORE_MOD_TAP_INTERRUPT`. -- cgit v1.2.3 From 6d7fb6c48dcd62c9d436c08f545f065bb41f810f Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Fri, 11 Sep 2020 20:10:23 +0530 Subject: Update dev-clean-room.md --- docs/docs/dev-clean-room.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/dev-clean-room.md b/docs/docs/dev-clean-room.md index c11171c..89e9826 100644 --- a/docs/docs/dev-clean-room.md +++ b/docs/docs/dev-clean-room.md @@ -11,7 +11,7 @@ Anyone wanting to contribute code to ZMK _must_ read this, and adhere to the ste ::: 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) +borrows/implements a lot of the features found in popular keyboard firmware 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. -- cgit v1.2.3 From 178e5e5afbf5d9b4dabb1a247f36714f5234ad29 Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Fri, 11 Sep 2020 20:37:05 +0530 Subject: Reverting provious commit --- docs/docs/behavior/hold-tap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/behavior/hold-tap.md b/docs/docs/behavior/hold-tap.md index 6790e88..ab51022 100644 --- a/docs/docs/behavior/hold-tap.md +++ b/docs/docs/behavior/hold-tap.md @@ -56,7 +56,7 @@ A code example which configures a mod-tap setting that works with homerow mods: If this config does not work for you, try the flavor "tap-preferred" and a short tapping_term_ms such as 120ms. -If you want to use a tap-hold with a keycode from a different code page, you have to define another behavior with another "bindings" parameter. For example, if you want to use SHIFT and volume up, define the bindings like `bindings = <&kp>, <&cp>;`. Only single-argument behaviors are supported at the moment. +If you want to use a tap-hold with a keycode from a different code page, you have to define another behavior with another "bindings" parameter.For example, if you want to use SHIFT and volume up, define the bindings like `bindings = <&kp>, <&cp>;`. Only single-argument behaviors are supported at the moment. #### Note Astute readers may notice similarities between the possible behaviors in ZMK and other firmware, such as QMK. The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the `tap-preferred` flavor is similar to `IGNORE_MOD_TAP_INTERRUPT`. -- cgit v1.2.3 From 7f5235904a5c49cc79875541d313317c9c6856c0 Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Fri, 11 Sep 2020 20:37:57 +0530 Subject: Reverting previous commit --- docs/docs/dev-clean-room.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/dev-clean-room.md b/docs/docs/dev-clean-room.md index 89e9826..c11171c 100644 --- a/docs/docs/dev-clean-room.md +++ b/docs/docs/dev-clean-room.md @@ -11,7 +11,7 @@ Anyone wanting to contribute code to ZMK _must_ read this, and adhere to the ste ::: 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 firmware projects like [QMK](https://qmk.fm) +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. -- cgit v1.2.3 From 98bd4796cfa3888e0f91d295599e42524e8e07db Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Fri, 11 Sep 2020 20:40:19 +0530 Subject: Reverting previous commit --- docs/docs/user-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/user-setup.md b/docs/docs/user-setup.md index c207136..2aade82 100644 --- a/docs/docs/user-setup.md +++ b/docs/docs/user-setup.md @@ -179,7 +179,7 @@ storage device. Once the flash is complete, the controller should automatically ## Wirelessly Connecting Your Keyboard -Connecting your keyboard wirelessly is the same as adding other Bluetooth devices: press the reset button and scan for devices. However, pairing and bonding is still currently being worked on to increase relability and ease of use. In addition, users have in general reported that Bluetooth pairing with computers tends to be quite finnicky. Try out the connection with your tablet or phone first, as those devices seem to work much more consistently. See [BLE Reset](./bond-reset.md) for help on resetting your MCUs if you're experiencing connection issues. +Connecting your keyboard wirelessly is the same as adding other Bluetooth devides: press the reset button and scan for devices. However, pairing and bonding is still currently being worked on to increase relability and ease of use. In addition, users have in general reported that Bluetooth pairing with computers tends to be quite finnicky. Try out the connection with your tablet or phone first, as those devices seem to work much more consistently. See [BLE Reset](./bond-reset.md) for help on resetting your MCUs if you're experiencing connection issues. ### Connecting Split Keyboard Halves -- cgit v1.2.3 From 54437db0ba2809de5ef0b987f59cfe47c486c669 Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Fri, 11 Sep 2020 20:42:33 +0530 Subject: Update with the examples --- docs/docs/dev-guide-new-shield.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index 832519d..6140b07 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -66,6 +66,8 @@ endif ![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: -- cgit v1.2.3 From ce8ade4afaa4cc9fc2b94050e98680301e539e56 Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Fri, 11 Sep 2020 23:48:53 +0530 Subject: A bad commit --- docs/docs/behavior/hold-tap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/behavior/hold-tap.md b/docs/docs/behavior/hold-tap.md index ab51022..d51edd3 100644 --- a/docs/docs/behavior/hold-tap.md +++ b/docs/docs/behavior/hold-tap.md @@ -59,4 +59,4 @@ If this config does not work for you, try the flavor "tap-preferred" and a short If you want to use a tap-hold with a keycode from a different code page, you have to define another behavior with another "bindings" parameter.For example, if you want to use SHIFT and volume up, define the bindings like `bindings = <&kp>, <&cp>;`. Only single-argument behaviors are supported at the moment. #### Note -Astute readers may notice similarities between the possible behaviors in ZMK and other firmware, such as QMK. The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the `tap-preferred` flavor is similar to `IGNORE_MOD_TAP_INTERRUPT`. +Astute readers may notice similarities between the possible behaviors in ZMK and other firmware, such as QMK. The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the `tap-preferred` flavor is similar to `IGNORE_MOD_TAP_INTERRUPT` -- cgit v1.2.3 From e11cad9fde0e90a47c9b09f66c612ee946f597cf Mon Sep 17 00:00:00 2001 From: Mamoor Jaan Khan <56243233+LowNightSnack@users.noreply.github.com> Date: Fri, 11 Sep 2020 23:49:12 +0530 Subject: Update hold-tap.md --- docs/docs/behavior/hold-tap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/behavior/hold-tap.md b/docs/docs/behavior/hold-tap.md index d51edd3..ab51022 100644 --- a/docs/docs/behavior/hold-tap.md +++ b/docs/docs/behavior/hold-tap.md @@ -59,4 +59,4 @@ If this config does not work for you, try the flavor "tap-preferred" and a short If you want to use a tap-hold with a keycode from a different code page, you have to define another behavior with another "bindings" parameter.For example, if you want to use SHIFT and volume up, define the bindings like `bindings = <&kp>, <&cp>;`. Only single-argument behaviors are supported at the moment. #### Note -Astute readers may notice similarities between the possible behaviors in ZMK and other firmware, such as QMK. The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the `tap-preferred` flavor is similar to `IGNORE_MOD_TAP_INTERRUPT` +Astute readers may notice similarities between the possible behaviors in ZMK and other firmware, such as QMK. The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the `tap-preferred` flavor is similar to `IGNORE_MOD_TAP_INTERRUPT`. -- cgit v1.2.3 From 763d62f6f292bec20bd183f9ba4d0da65fb3f7b5 Mon Sep 17 00:00:00 2001 From: Okke Formsma Date: Fri, 4 Sep 2020 20:57:11 +0200 Subject: update intro page, add layer-tap docs and update hold-tap docs. --- docs/docs/behavior/hold-tap.md | 10 +++++++--- docs/docs/behavior/layers.md | 20 ++++++++++++++++++-- docs/docs/intro.md | 33 +++++++++++++++++++-------------- 3 files changed, 44 insertions(+), 19 deletions(-) (limited to 'docs') diff --git a/docs/docs/behavior/hold-tap.md b/docs/docs/behavior/hold-tap.md index ab51022..9f8f5fa 100644 --- a/docs/docs/behavior/hold-tap.md +++ b/docs/docs/behavior/hold-tap.md @@ -22,7 +22,11 @@ We call this the 'hold-preferred' flavor of hold-taps. While this flavor may wor ![Hold-tap comparison](../assets/hold-tap/comparison.png) -### Configuration +### Basic usage +For basic usage, please see [mod-tap](./mod-tap.md) and [layer-tap](./layers.md) pages. + + +### Advanced Configuration A code example which configures a mod-tap setting that works with homerow mods: ``` @@ -58,5 +62,5 @@ If this config does not work for you, try the flavor "tap-preferred" and a short If you want to use a tap-hold with a keycode from a different code page, you have to define another behavior with another "bindings" parameter.For example, if you want to use SHIFT and volume up, define the bindings like `bindings = <&kp>, <&cp>;`. Only single-argument behaviors are supported at the moment. -#### Note -Astute readers may notice similarities between the possible behaviors in ZMK and other firmware, such as QMK. The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the `tap-preferred` flavor is similar to `IGNORE_MOD_TAP_INTERRUPT`. +#### Comparison to QMK +The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting in QMK. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the `tap-preferred` flavor is similar to `IGNORE_MOD_TAP_INTERRUPT`. \ No newline at end of file diff --git a/docs/docs/behavior/layers.md b/docs/docs/behavior/layers.md index da7f07f..c769388 100644 --- a/docs/docs/behavior/layers.md +++ b/docs/docs/behavior/layers.md @@ -26,7 +26,7 @@ This allows you to use those defines, e.g. `LOWER` later in your keymap. ## Momentary Layer -The "momentary layer" behavior allows you to enable a layer while a certain key is pressed. Immediately upon +The "momentary layer" behavior enables a layer while a certain key is pressed. Immediately upon activation of the key, the layer is enabled, and immediately open release of the key, the layer is disabled again. @@ -41,9 +41,25 @@ Example: &mo LOWER ``` +## Layer-tap + +The "layer-tap" behavior enables a layer when a key is held, and output another key when the key is only tapped for a short time. For more information on the inner workings of layer-tap, see [hold-tap](./hold-tap.md). + +### Behavior Binding +- Reference: `<` +- Parameter: The layer number to enable when held, e.g. `1` +- Parameter: The keycode to send when tapped, e.g. `A` + +Example: + +``` +< LOWER SPC +``` + + ## Toggle Layer -The "toggle layer" behavior allows you to enable a layer until the layer is manually disabled. +The "toggle layer" behavior enables a layer until the layer is manually disabled. ### Behavior Binding diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 50a747c..8c1c043 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -7,31 +7,36 @@ sidebar_label: Introduction ZMK Firmware is an open source (MIT) keyboard firmware built on the [Zephyr™ Project](https://zephyrproject.org/) Real Time Operating System (RTOS). -The goal is to provider a powerful, featureful keyboard firmware that is free +The goal is to provide a powerful, featureful keyboard firmware that is free of licensing issues that prevent upstream BLE support as a first-class feature. ## Features -At this point, ZMK is _missing_ more features than it has. Currently, the mostly working bits +At this point, ZMK is still missing many features. Currently, the working bits include: -- HID Over GATT (HOG) - This is the official term for BLE HID devices -- Keymaps and layers with basic keycodes -- Some initial work on one "behavior", Mod-Tap -- Basic HID over USB -- Basic consumer (media) keycodes. -- Basic OLED display logic -- Basic Split support -- Encoders +- Wireless connectivity via BLE HID Over GATT (HOG) +- USB connectivity +- Low active power usage +- Split keyboard support +- [Keymaps and layers](behavior/layers) +- [Hold-tap](behavior/hold-tap) (which includes [mod-tap](behavior/mod-tap), [layer-tap](behavior/layers)) +- [Basic HID over USB](behavior/key-press) +- [Basic consumer (media) keycodes](behavior/key-press#consumer-key-press) +- [Encoders](feature/encoders) +- Basic [OLED display support](feature/displays) +- [RGB Underglow](feature/underglow) ## Missing Features -- One Shot -- Layer Tap -- Complete split support +- One Shot Keys +- Combo keys +- Macros +- Complete split support (encoders and RGB are not supported on the 'peripheral' side) - Battery reporting -- Low power mode +- Low power sleep states +- Low power mode (to toggle LEDs and screen off) - Shell over BLE ## Code Of Conduct -- cgit v1.2.3 From cf970efb98c5af97955bfffbcebb3b065b16edc4 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Fri, 28 Aug 2020 14:15:16 -0400 Subject: feat(bluetooth): Proper bond management, identity support for non-splits * Add `bt` behavior that can be used to perform certain actions, such as next/prev identity, reset identity, etc. NOTE: Multiple identities is only supported for non-split shields, due to missing Zephyr identity functionality for dual central/peripheral devices. * Proper bond reset tied to action, that honors peripheral bonds, so folks can reset and pair to other hosts, without breaking bonds between splt halves. --- docs/docs/behavior/bluetooth.md | 82 +++++++++++++++++++++++++++++++++++++++++ docs/sidebars.js | 1 + 2 files changed, 83 insertions(+) create mode 100644 docs/docs/behavior/bluetooth.md (limited to 'docs') diff --git a/docs/docs/behavior/bluetooth.md b/docs/docs/behavior/bluetooth.md new file mode 100644 index 0000000..df8ec26 --- /dev/null +++ b/docs/docs/behavior/bluetooth.md @@ -0,0 +1,82 @@ +--- +title: Bluetooth Behavior +sidebar_label: Bluetooth +--- + +## Summary + +The bluetooth behavior allows management of various settings and states related to the bluetooth connection(s) +between the keyboard and the host. + +## Bluetooth Command Defines + +Bluetooth command defines are provided through the [`dt-bindings/zmk/bt.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/bt.h) header, +which is added at the top of the keymap file: + +``` +#include +``` + +This will allow you to reference the actions defined in this header such as `BT_IDENT_CLR_CMD`. + +Here is a table describing the command for each define: + +| Define | Action | +| ------------------- | ----------------------------------------------------- | +| `BT_IDENT_CLR_CMD` | Clear paired keyboards (for the current identity)[^1] | +| `BT_IDENT_NEXT_CMD` | Switch to the next identity[^1] | +| `BT_IDENT_PREV_CMD` | Switch to the previous identity | +| `BT_IDENT_SEL_CMD` | Switch to a specific numbered identity | +| `BT_RST_CMD` | Hard reset of all bluetooth bonds | + +Because the `BT_IDENT_SEL_CMD` command takes an additional parameter, the numeric index of the identity to select, _all_ the commands for the bluetooth behavior must take that additional parameter, and ignore the value. To make this easier, +there are alias defines that add those default parameters for you: + +| Define | Action | +| --------------- | --------------------------------------------------------------------------------------- | +| `BT_IDENT_CLR` | Alias for `BT_IDENT_CLR_CMD 0` to clear paired keyboards (for the current identity)[^1] | +| `BT_IDENT_NEXT` | Alias for `BT_IDENT_NEXT_CMD 0` to switch to the next identity[^1] | +| `BT_IDENT_PREV` | Alias for `BT_IDENT_PREV_CMD 0` to switch to the previous identity | +| `BT_IDENT_SEL` | Alias for `BT_IDENT_SEL_CMD` to switch to a specific numbered identity | +| `BT_RST` | Alias for `BT_RST_CMD 0` to reset all bonds[^2] | + +[^1]: Multiple keyboard identities/profiles is only support on non-split keyboards as of this time. +[^2]: This may interrupt pairing between both halves of a split keyboard. For split keyboards, it is preferred to use the [/docs/bond-reset] combo to clear bonds on both devices + +## Bluetooth Behavior + +The bluetooth behavior completes an bluetooth action given on press. + +### Behavior Binding + +- Reference: `&bt` +- Parameter #1: The bluetooth command define, e.g. `BT_IDENT_CLR_CMD` or `BT_RST_CMD` +- Parameter #2: The parameter for the command, when used to identify an identity/profile to select, e.g. `0` + +### Examples + +1. Behavior to clear the paired host: + + ``` + &bt BT_IDENT_CLR + ``` + +1. Behavior to hard reset all bonded devices[^2]: + + ``` + &bt BT_IDENT_CLR + ``` + +Examples for non-split keyboards with multiple identities: + +1. Behavior to switch to the next identity: + + ``` + &bt BT_IDENT_NEXT + ``` + +1. Behavior to switch to the specific numbered identity: + + ``` + &bt BT_IDENT_SEL 1 + ``` diff --git a/docs/sidebars.js b/docs/sidebars.js index 6bd3aa4..ace7fa1 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -22,6 +22,7 @@ module.exports = { "behavior/hold-tap", "behavior/mod-tap", "behavior/reset", + "behavior/bluetooth", "behavior/lighting", ], Development: [ -- cgit v1.2.3 From fc0812bd2eb08d66819f38bafd1f5d00b933c87b Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Tue, 1 Sep 2020 23:22:30 -0400 Subject: fix(bluetooth): Remove identity, minimal `bt`. * Simplify the `bt` behavior to one current command `BT_CLEAR_BONDS_CMD`. * Simplify BLE code for split and non-split keyboards. * Remove keymap processing from split peripheral side. --- docs/docs/behavior/bluetooth.md | 58 ++++++++++------------------------------- 1 file changed, 14 insertions(+), 44 deletions(-) (limited to 'docs') diff --git a/docs/docs/behavior/bluetooth.md b/docs/docs/behavior/bluetooth.md index df8ec26..f605c96 100644 --- a/docs/docs/behavior/bluetooth.md +++ b/docs/docs/behavior/bluetooth.md @@ -6,7 +6,8 @@ sidebar_label: Bluetooth ## Summary The bluetooth behavior allows management of various settings and states related to the bluetooth connection(s) -between the keyboard and the host. +between the keyboard and the host. As of right now, there is only one such action support, but in the future +more will be added. ## Bluetooth Command Defines @@ -17,31 +18,20 @@ which is added at the top of the keymap file: #include ``` -This will allow you to reference the actions defined in this header such as `BT_IDENT_CLR_CMD`. +This will allow you to reference the actions defined in this header such as `BT_CLEAR_BONDS_CMD`. Here is a table describing the command for each define: -| Define | Action | -| ------------------- | ----------------------------------------------------- | -| `BT_IDENT_CLR_CMD` | Clear paired keyboards (for the current identity)[^1] | -| `BT_IDENT_NEXT_CMD` | Switch to the next identity[^1] | -| `BT_IDENT_PREV_CMD` | Switch to the previous identity | -| `BT_IDENT_SEL_CMD` | Switch to a specific numbered identity | -| `BT_RST_CMD` | Hard reset of all bluetooth bonds | +| Define | Action | +| -------------------- | --------------------------------------------------------- | +| `BT_CLEAR_BONDS_CMD` | Clear bond information between the keyboard and host [^1] | -Because the `BT_IDENT_SEL_CMD` command takes an additional parameter, the numeric index of the identity to select, _all_ the commands for the bluetooth behavior must take that additional parameter, and ignore the value. To make this easier, -there are alias defines that add those default parameters for you: +Because future bluetooth commands will take an additional parameter, it is recommended to use +the following alias in your keymap to avoid having to change it later. -| Define | Action | -| --------------- | --------------------------------------------------------------------------------------- | -| `BT_IDENT_CLR` | Alias for `BT_IDENT_CLR_CMD 0` to clear paired keyboards (for the current identity)[^1] | -| `BT_IDENT_NEXT` | Alias for `BT_IDENT_NEXT_CMD 0` to switch to the next identity[^1] | -| `BT_IDENT_PREV` | Alias for `BT_IDENT_PREV_CMD 0` to switch to the previous identity | -| `BT_IDENT_SEL` | Alias for `BT_IDENT_SEL_CMD` to switch to a specific numbered identity | -| `BT_RST` | Alias for `BT_RST_CMD 0` to reset all bonds[^2] | - -[^1]: Multiple keyboard identities/profiles is only support on non-split keyboards as of this time. -[^2]: This may interrupt pairing between both halves of a split keyboard. For split keyboards, it is preferred to use the [/docs/bond-reset] combo to clear bonds on both devices +| Define | Action | +| ---------------- | ---------------------------------------------------------------------- | +| `BT_CLEAR_BONDS` | Alias for `BT_CLEAR_BONDS_CMD 0` to clear the bond to the current host | ## Bluetooth Behavior @@ -50,33 +40,13 @@ The bluetooth behavior completes an bluetooth action given on press. ### Behavior Binding - Reference: `&bt` -- Parameter #1: The bluetooth command define, e.g. `BT_IDENT_CLR_CMD` or `BT_RST_CMD` -- Parameter #2: The parameter for the command, when used to identify an identity/profile to select, e.g. `0` +- Parameter #1: The bluetooth command define, e.g. `BT_CLEAR_BONDS_CMD` +- Parameter #2: (Reserved for future bluetooth command types) ### Examples 1. Behavior to clear the paired host: ``` - &bt BT_IDENT_CLR - ``` - -1. Behavior to hard reset all bonded devices[^2]: - - ``` - &bt BT_IDENT_CLR - ``` - -Examples for non-split keyboards with multiple identities: - -1. Behavior to switch to the next identity: - - ``` - &bt BT_IDENT_NEXT - ``` - -1. Behavior to switch to the specific numbered identity: - - ``` - &bt BT_IDENT_SEL 1 + &bt BT_CLEAR_BONDS ``` -- cgit v1.2.3 From 39f980a06dac1769e4f09abaf19d3ccbb4b34e67 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Tue, 8 Sep 2020 23:26:00 -0400 Subject: feat(bluetooth): Add back profiles, split fixes. * Add back in profiles, not using Zephyr BT identity infrastructure. * Restore additional `&bt` commands for profile operations. * Fix for split pairing and subscriptions, since Zephyr persists subscriptions across connects. * Remove keymap from peripheral builds, reduces firmware size, and avoids unneeded attempts to send HID data. --- docs/docs/behavior/bluetooth.md | 46 +++++++++++++++++++++++++++++++---------- 1 file changed, 35 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/docs/behavior/bluetooth.md b/docs/docs/behavior/bluetooth.md index f605c96..4a121a3 100644 --- a/docs/docs/behavior/bluetooth.md +++ b/docs/docs/behavior/bluetooth.md @@ -6,8 +6,8 @@ sidebar_label: Bluetooth ## Summary The bluetooth behavior allows management of various settings and states related to the bluetooth connection(s) -between the keyboard and the host. As of right now, there is only one such action support, but in the future -more will be added. +between the keyboard and the host. By default, ZMK supports five "profiles" for selecting which bonded host +computer/laptop/keyboard should receive the keyboard input; many of the commands here operation on those profiles. ## Bluetooth Command Defines @@ -22,16 +22,22 @@ This will allow you to reference the actions defined in this header such as `BT_ Here is a table describing the command for each define: -| Define | Action | -| -------------------- | --------------------------------------------------------- | -| `BT_CLEAR_BONDS_CMD` | Clear bond information between the keyboard and host [^1] | +| Define | Action | +| -------------------- | ---------------------------------------------------------------------------------------------- | +| `BT_CLEAR_BONDS_CMD` | Clear bond information between the keyboard and host for the selected profile [^1] | +| `BT_PROF_NEXT_CMD` | Switch to the next profile, cycling through to the first one when the end is reached. | +| `BT_PROF_PREV_CMD` | Switch to the previous profile, cycling through to the last one when the beginning is reached. | +| `BT_PROF_SEL_CMD` | Select the 0-indexed profile by number. | -Because future bluetooth commands will take an additional parameter, it is recommended to use -the following alias in your keymap to avoid having to change it later. +Because at least one bluetooth commands takes an additional parameter, it is recommended to use +the following aliases in your keymap to avoid having to specify an ignored second parameter: -| Define | Action | -| ---------------- | ---------------------------------------------------------------------- | -| `BT_CLEAR_BONDS` | Alias for `BT_CLEAR_BONDS_CMD 0` to clear the bond to the current host | +| Define | Action | +| ---------------- | ---------------------------------------------------------------------------------------- | +| `BT_CLEAR_BONDS` | Alias for `BT_CLEAR_BONDS_CMD 0` to clear the current profile's bond to the current host | +| `BT_PROF_NEXT` | Alias for `BT_PROF_NEXT_CMD 0` to select the next profile | +| `BT_PROF_PREV` | Alias for `BT_PROF_PREV_CMD 0` to select the previous profile | +| `BT_PROF_SEL` | Alias for `BT_PROF_SEL_CMD` to select the given profile, e.g. `&bt BT_PROF_SEL 1` | ## Bluetooth Behavior @@ -45,8 +51,26 @@ The bluetooth behavior completes an bluetooth action given on press. ### Examples -1. Behavior to clear the paired host: +1. Behavior binding to clear the paired host for the selected profile: ``` &bt BT_CLEAR_BONDS ``` + +1. Behavior binding to select the next profile: + + ``` + &bt BT_PROF_NEXT + ``` + +1. Behavior binding to select the previous profile: + + ``` + &bt BT_PROF_NEXT + ``` + +1. Behavior binding to select the 2nd profile (passed parameters are [zero based](https://en.wikipedia.org/wiki/Zero-based_numbering)): + + ``` + &bt BT_PROF_SEL 1 + ``` -- cgit v1.2.3 From 6c8b0b53f0dbec695ab967ee947916875ed49352 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Sun, 13 Sep 2020 22:20:25 -0400 Subject: refactor(bluetooth): More concise names. --- docs/docs/behavior/bluetooth.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) (limited to 'docs') diff --git a/docs/docs/behavior/bluetooth.md b/docs/docs/behavior/bluetooth.md index 4a121a3..f802a9a 100644 --- a/docs/docs/behavior/bluetooth.md +++ b/docs/docs/behavior/bluetooth.md @@ -18,26 +18,26 @@ which is added at the top of the keymap file: #include ``` -This will allow you to reference the actions defined in this header such as `BT_CLEAR_BONDS_CMD`. +This will allow you to reference the actions defined in this header such as `BT_CLR_CMD`. Here is a table describing the command for each define: -| Define | Action | -| -------------------- | ---------------------------------------------------------------------------------------------- | -| `BT_CLEAR_BONDS_CMD` | Clear bond information between the keyboard and host for the selected profile [^1] | -| `BT_PROF_NEXT_CMD` | Switch to the next profile, cycling through to the first one when the end is reached. | -| `BT_PROF_PREV_CMD` | Switch to the previous profile, cycling through to the last one when the beginning is reached. | -| `BT_PROF_SEL_CMD` | Select the 0-indexed profile by number. | +| Define | Action | +| ------------ | ---------------------------------------------------------------------------------------------- | +| `BT_CLR_CMD` | Clear bond information between the keyboard and host for the selected profile [^1] | +| `BT_NXT_CMD` | Switch to the next profile, cycling through to the first one when the end is reached. | +| `BT_PRV_CMD` | Switch to the previous profile, cycling through to the last one when the beginning is reached. | +| `BT_SEL_CMD` | Select the 0-indexed profile by number. | Because at least one bluetooth commands takes an additional parameter, it is recommended to use the following aliases in your keymap to avoid having to specify an ignored second parameter: -| Define | Action | -| ---------------- | ---------------------------------------------------------------------------------------- | -| `BT_CLEAR_BONDS` | Alias for `BT_CLEAR_BONDS_CMD 0` to clear the current profile's bond to the current host | -| `BT_PROF_NEXT` | Alias for `BT_PROF_NEXT_CMD 0` to select the next profile | -| `BT_PROF_PREV` | Alias for `BT_PROF_PREV_CMD 0` to select the previous profile | -| `BT_PROF_SEL` | Alias for `BT_PROF_SEL_CMD` to select the given profile, e.g. `&bt BT_PROF_SEL 1` | +| Define | Action | +| -------- | -------------------------------------------------------------------------------- | +| `BT_CLR` | Alias for `BT_CLR_CMD 0` to clear the current profile's bond to the current host | +| `BT_NXT` | Alias for `BT_NXT_CMD 0` to select the next profile | +| `BT_PRV` | Alias for `BT_PRV_CMD 0` to select the previous profile | +| `BT_SEL` | Alias for `BT_SEL_CMD` to select the given profile, e.g. `&bt BT_SEL 1` | ## Bluetooth Behavior @@ -46,7 +46,7 @@ The bluetooth behavior completes an bluetooth action given on press. ### Behavior Binding - Reference: `&bt` -- Parameter #1: The bluetooth command define, e.g. `BT_CLEAR_BONDS_CMD` +- Parameter #1: The bluetooth command define, e.g. `BT_CLR_CMD` - Parameter #2: (Reserved for future bluetooth command types) ### Examples @@ -54,23 +54,23 @@ The bluetooth behavior completes an bluetooth action given on press. 1. Behavior binding to clear the paired host for the selected profile: ``` - &bt BT_CLEAR_BONDS + &bt BT_CLR ``` 1. Behavior binding to select the next profile: ``` - &bt BT_PROF_NEXT + &bt BT_NXT ``` 1. Behavior binding to select the previous profile: ``` - &bt BT_PROF_NEXT + &bt BT_NXT ``` 1. Behavior binding to select the 2nd profile (passed parameters are [zero based](https://en.wikipedia.org/wiki/Zero-based_numbering)): ``` - &bt BT_PROF_SEL 1 + &bt BT_SEL 1 ``` -- cgit v1.2.3