From feadfc93dc5cae23afbca1cfeb6433463aee4b43 Mon Sep 17 00:00:00 2001 From: Cody McGinnis Date: Wed, 19 Aug 2020 00:07:08 -0400 Subject: feat(docs): create a bond clearing page --- docs/docs/assets/bond-clearing/corne.jpg | Bin 0 -> 147244 bytes docs/docs/assets/bond-clearing/kyria.jpg | Bin 0 -> 140236 bytes docs/docs/bond-reset.md | 26 ++++++++++++++++++++++++++ docs/sidebars.js | 2 +- 4 files changed, 27 insertions(+), 1 deletion(-) create mode 100644 docs/docs/assets/bond-clearing/corne.jpg create mode 100644 docs/docs/assets/bond-clearing/kyria.jpg create mode 100644 docs/docs/bond-reset.md (limited to 'docs') diff --git a/docs/docs/assets/bond-clearing/corne.jpg b/docs/docs/assets/bond-clearing/corne.jpg new file mode 100644 index 0000000..1e070a2 Binary files /dev/null and b/docs/docs/assets/bond-clearing/corne.jpg differ diff --git a/docs/docs/assets/bond-clearing/kyria.jpg b/docs/docs/assets/bond-clearing/kyria.jpg new file mode 100644 index 0000000..9fa22a0 Binary files /dev/null and b/docs/docs/assets/bond-clearing/kyria.jpg differ diff --git a/docs/docs/bond-reset.md b/docs/docs/bond-reset.md new file mode 100644 index 0000000..03d6dd1 --- /dev/null +++ b/docs/docs/bond-reset.md @@ -0,0 +1,26 @@ +--- +id: bond-reset +title: Reset BLE Connections +sidebar_label: BLE Reset +--- + +Known as a 'bond reset', a special key combination, that is not related to the user defined key map, which +clears all wireless connection configurations. + +:::warning +Currently, ZMK only supports a single BLE host. If you remove the keyboard from the host's bluetooth devices +list, you will need to clear the bonds. +::: + +### Split Keyboards + +Split keyboards will need to be cleared on both halves. For best results try to reset them at the same time. + + +## Kyria + +![Kyria bond-reset combo](assets/bond-clearing/kyria.jpg) + +## Corne + +![Corne bond-reset combo](assets/bond-clearing/corne.jpg) \ No newline at end of file diff --git a/docs/sidebars.js b/docs/sidebars.js index be02a65..8c7c97f 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -1,6 +1,6 @@ module.exports = { someSidebar: { - "Getting Started": ["intro", "hardware", "faq", "user-setup"], + "Getting Started": ["intro", "hardware", "faq", "user-setup", "bond-reset"], Features: [ "feature/keymaps", "feature/displays", -- cgit v1.2.3 From 02f541969cc74ec86fba3c3b01679f93fa86d698 Mon Sep 17 00:00:00 2001 From: Cody McGinnis Date: Wed, 19 Aug 2020 00:11:44 -0400 Subject: fix(docs): make time to clear explicit --- docs/docs/bond-reset.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/bond-reset.md b/docs/docs/bond-reset.md index 03d6dd1..1d3732b 100644 --- a/docs/docs/bond-reset.md +++ b/docs/docs/bond-reset.md @@ -5,7 +5,8 @@ sidebar_label: BLE Reset --- Known as a 'bond reset', a special key combination, that is not related to the user defined key map, which -clears all wireless connection configurations. +clears all wireless connection configurations. The keys must be held for 3 to 5 seconds after the device is +reset. :::warning Currently, ZMK only supports a single BLE host. If you remove the keyboard from the host's bluetooth devices -- cgit v1.2.3 From 506c3b031e042430149cd663a561a13cd6e5835b Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Wed, 19 Aug 2020 16:35:18 -0400 Subject: refactor(boards): Rename to bluemicro840_v1. --- docs/docs/hardware.md | 2 ++ docs/static/setup.sh | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/docs/hardware.md b/docs/docs/hardware.md index 951cee0..9e6a956 100644 --- a/docs/docs/hardware.md +++ b/docs/docs/hardware.md @@ -17,6 +17,8 @@ That being said, there are currently only a few specific [boards](/docs/faq#what ## Boards - [nice!nano](https://docs.nicekeyboards.com/#/nice!nano/) (`nice_nano`) +- [nrfMicro](https://github.com/joric/nrfmicro) (`nrfmicro_13`, `nrfmicro_11`, `nrfmicro_11_flipped`) +- [BlueMicro840](https://store.jpconstantineau.com/#/group/bluemicro) (`bluemicro840_v1`) - [QMK Proton-C](https://qmk.fm/proton-c/) (`proton_c`) ## Keyboard Shields diff --git a/docs/static/setup.sh b/docs/static/setup.sh index 55c96ff..bb61df6 100644 --- a/docs/static/setup.sh +++ b/docs/static/setup.sh @@ -11,7 +11,7 @@ title="ZMK Config Setup:" # TODO: Check for user.name and user.email git configs being set prompt="Pick an MCU board:" -options=("nice!nano" "QMK Proton-C" "BlueMicro52840 (v1)") +options=("nice!nano" "QMK Proton-C" "BlueMicro840 (v1)") echo "$title" echo "" @@ -23,7 +23,7 @@ select opt in "${options[@]}" "Quit"; do 1 ) board="nice_nano"; break;; 2 ) board="proton_c"; break;; - 3 ) board="bluemicro52840_v1"; break;; + 3 ) board="bluemicro840_v1"; break;; $(( ${#options[@]}+1 )) ) echo "Goodbye!"; exit;; *) echo "Invalid option. Try another one.";continue;; -- cgit v1.2.3 From 11e3566277eac787f00ad479dc8a9eeffcfd1504 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Thu, 20 Aug 2020 00:11:07 -0400 Subject: fix(docs): Link to 2.3.0 docs, macOS toolchain fix * Link explicitly to the 2.3.0 docs from upstream Zephyr. * Update the macOS toolchain section to properly refer to the 3rd party toolchain setup. --- docs/docs/dev-setup.md | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 5cceb73..6e893b3 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -180,7 +180,7 @@ brew install cmake ninja python3 ccache dtc git wget ### West Build Command -`west` is the [Zephyr™ meta-tool](https://docs.zephyrproject.org/latest/guides/west/index.html) used to configure and build Zephyr™ applications. +`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. @@ -223,7 +223,7 @@ The installation will prompt with several questions about installation location, 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/latest/getting_started/toolchain_other_x_compilers.html) can be used to target the different ABI. +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: @@ -259,23 +259,20 @@ The installation will prompt with several questions about installation location, #### GNU ARM Embedded -Since the Zephyr™ SDK is not available for Windows, we recommending following the steps to install the [GNU ARM Embedded](https://docs.zephyrproject.org/latest/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded). +Since the Zephyr™ SDK is not available for Windows, 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). -#### Zephyr™ ARM SDK +#### GNU ARM Embedded -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: +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). -``` -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" -``` +:::warning Security Controls Workaround -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. +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 + +::: @@ -342,7 +339,7 @@ pip3 install --user -r zephyr/scripts/requirements-base.txt ### Environment Variables 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/latest/guides/env_vars.html?highlight=zephyrrc) for how to load those settings. +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 @@ -442,7 +439,7 @@ an onboard MCU, or one that uses a MCU board addon. ### Keyboard (Shield) + MCU Board -ZMK treats keyboards that take a MCU addon board as [shields](https://docs.zephyrproject.org/latest/guides/porting/shields.html), and treats the smaller MCU board as the true [board](https://docs.zephyrproject.org/latest/guides/porting/board_porting.html) +ZMK treats keyboards that take a 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: @@ -458,7 +455,7 @@ west build -b proton_c -- -DSHIELD=kyria_left -DKEYMAP=default ### Keyboard With Onboard MCU -Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/latest/guides/porting/board_porting.html) as far as Zephyr™ is concerned. +Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/2.3.0/guides/porting/board_porting.html) as far as Zephyr™ is concerned. Given the following: -- cgit v1.2.3 From 1ff13676f7fbab5c0d69317be0d186709a7872c8 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Fri, 21 Aug 2020 00:31:28 -0400 Subject: fix(docs): Better behavior sidebar label/titles. --- docs/docs/behavior/key-press.md | 3 ++- docs/docs/behavior/layers.md | 8 +++++--- docs/docs/behavior/lighting.md | 11 ++++++----- docs/docs/behavior/misc.md | 3 ++- docs/docs/behavior/mod-tap.md | 3 ++- 5 files changed, 17 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/docs/behavior/key-press.md b/docs/docs/behavior/key-press.md index 1ae7e31..2edce1d 100644 --- a/docs/docs/behavior/key-press.md +++ b/docs/docs/behavior/key-press.md @@ -1,5 +1,6 @@ --- -title: Key Presses +title: Key Press Behaviors +sidebar_label: Key Press --- ## Summary diff --git a/docs/docs/behavior/layers.md b/docs/docs/behavior/layers.md index 3e520ca..da7f07f 100644 --- a/docs/docs/behavior/layers.md +++ b/docs/docs/behavior/layers.md @@ -1,5 +1,6 @@ --- -title: Layers +title: Layer Behaviors +sidebar_label: Layers --- ## Summary @@ -56,12 +57,13 @@ Example: ``` "Toggle layer" for a : + ``` #define DEFAULT 0 #define NAVI 1 #define NONE 0 - + / { keymap { compatible = "zmk,keymap"; @@ -89,4 +91,4 @@ Example: }; ``` -It is possible to use "toggle layer" to have keys that raise and lower the layers as well. \ No newline at end of file +It is possible to use "toggle layer" to have keys that raise and lower the layers as well. diff --git a/docs/docs/behavior/lighting.md b/docs/docs/behavior/lighting.md index 432960e..2d4f532 100644 --- a/docs/docs/behavior/lighting.md +++ b/docs/docs/behavior/lighting.md @@ -1,15 +1,16 @@ --- -title: Lighting +title: Lighting Behavior +sidebar_label: Lighting --- ## Summary -Lighting is often used for either aesthetics or for the practical purposes of lighting up keys in the dark. +Lighting is often used for either aesthetics or for the practical purposes of lighting up keys in the dark. Currently ZMK supports RGB underglow, which can be changed and configured using its behavior. ## RGB Action Defines -RGB actions defines are provided through the [`dt-bindings/zmk/rgb.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/rgb.h) header, +RGB actions defines are provided through the [`dt-bindings/zmk/rgb.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/rgb.h) header, which is added at the top of the keymap file: ``` @@ -21,7 +22,7 @@ This will allow you to reference the actions defined in this header such as `RGB Here is a table describing the action for each define: | Define | Action | -|-----------|-----------------------------------------------------------| +| --------- | --------------------------------------------------------- | | `RGB_TOG` | Toggles the RGB feature on and off | | `RGB_HUI` | Increases the hue of the RGB feature | | `RGB_HUD` | Decreases the hue of the RGB feature | @@ -47,4 +48,4 @@ Example: ``` &rgb_ug RGB_TOG -``` \ No newline at end of file +``` diff --git a/docs/docs/behavior/misc.md b/docs/docs/behavior/misc.md index 799c91c..446ba33 100644 --- a/docs/docs/behavior/misc.md +++ b/docs/docs/behavior/misc.md @@ -1,5 +1,6 @@ --- -title: Miscellaneous +title: Miscellaneous Behaviors +sidebar_label: Miscellaneous --- ## Summary diff --git a/docs/docs/behavior/mod-tap.md b/docs/docs/behavior/mod-tap.md index cae667e..08e9b65 100644 --- a/docs/docs/behavior/mod-tap.md +++ b/docs/docs/behavior/mod-tap.md @@ -1,5 +1,6 @@ --- -title: Mod-Tap +title: Mod-Tap Behavior +sidebar_label: Mod-Tap --- ## Summary -- cgit v1.2.3 From 805ea770053269278fe0ed443b68f600021d82d1 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Fri, 21 Aug 2020 00:33:48 -0400 Subject: feat(behaviors): Add `&bootloader` behavior. * Allow reset behavior to have a type property. * Add `bootloader` node that triggers DFU UF2 bootloader mode using the AdaFruit nrf52 bootloader. --- docs/docs/behavior/reset.md | 43 +++++++++++++++++++++++++++++++++++++++++++ docs/sidebars.js | 1 + 2 files changed, 44 insertions(+) create mode 100644 docs/docs/behavior/reset.md (limited to 'docs') diff --git a/docs/docs/behavior/reset.md b/docs/docs/behavior/reset.md new file mode 100644 index 0000000..8cf122b --- /dev/null +++ b/docs/docs/behavior/reset.md @@ -0,0 +1,43 @@ +--- +title: Reset Behaviors +sidebar_label: Reset +--- + +## Summary + +There are two available behaviors that can be used to trigger a reset of the keyboard. +The first is a soft reset, that will simply reset and re-run the currently flashed +firmware; the second when triggered will reset into the bootloader, allowing you to +flash a new firmware to the keyboard. + +## Reset + +The basic reset behavior will reset the keyboard and re-run the firmware flashed +to the device + +### Behavior Binding + +- Reference: `&reset` +- Parameters: None + +Example: + +``` +&reset +``` + +## Bootloader Reset + +The bootloader reset behavior will reset the keyboard and put it into bootloader mode, allowing +you to flash a new firmware. + +### Behavior Binding + +- Reference: `&bootloader` +- Parameters: None + +Example: + +``` +&bootloader +``` diff --git a/docs/sidebars.js b/docs/sidebars.js index 8c7c97f..51313fc 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -12,6 +12,7 @@ module.exports = { "behavior/layers", "behavior/misc", "behavior/mod-tap", + "behavior/reset", "behavior/lighting", ], Development: [ -- cgit v1.2.3