From 5bb01c802b792dd016b2cd091b0983806b658f43 Mon Sep 17 00:00:00 2001 From: Derek Date: Sun, 16 Aug 2020 08:49:17 -0400 Subject: Update setup.sh --- docs/static/setup.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/static/setup.sh b/docs/static/setup.sh index 27dcb0b..45eccd6 100644 --- a/docs/static/setup.sh +++ b/docs/static/setup.sh @@ -37,7 +37,7 @@ echo "" echo "Keyboard Shield Selection:" prompt="Pick an keyboard:" -options=("Kyria" "Lily58" "Corne") +options=("Kyria" "Lily58" "Corne" "Splitreus62") PS3="$prompt " # TODO: Add support for "Other" and linking to docs on adding custom shields in user config repos. -- 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 94c7d27f04263b42669ae6d1777765ba811ed6bf Mon Sep 17 00:00:00 2001 From: Derek Date: Thu, 20 Aug 2020 15:13:51 -0400 Subject: Updated files as per request Updated --- docs/static/setup.sh | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/static/setup.sh b/docs/static/setup.sh index 45eccd6..e75b529 100644 --- a/docs/static/setup.sh +++ b/docs/static/setup.sh @@ -49,6 +49,7 @@ select opt in "${options[@]}" "Quit"; do 1 ) shield_title="Kyria" shield="kyria"; split="y"; break;; 2 ) shield_title="Lily58" shield="lily58"; split="y"; break;; 3 ) shield_title="Corne" shield="corne"; split="y"; break;; + 4 ) shield_title="Splitreus62" shield="splitreus62"; split="y"; break;; # Add link to docs on adding your own custom shield in your ZMK config! # $(( ${#options[@]}+1 )) ) echo "Other!"; break;; -- 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 From 0c255aee84155405741ba8fa0c81c6d711106033 Mon Sep 17 00:00:00 2001 From: crd Date: Sat, 22 Aug 2020 09:29:23 -0700 Subject: [docs] Add bzip to deps --- docs/docs/dev-setup.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 6e893b3..fae0aa0 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -52,6 +52,7 @@ sudo apt install -y \ autoconf \ automake \ build-essential \ + bzip2 \ ccache \ device-tree-compiler \ dfu-util \ @@ -91,6 +92,7 @@ sudo apt install -y \ autoconf \ automake \ build-essential \ + bzip2 \ ccache \ device-tree-compiler \ dfu-util \ @@ -130,6 +132,7 @@ sudo dnf install -y \ wget \ autoconf \ automake \ + bzip2 \ ccache \ dtc \ dfu-util \ -- cgit v1.2.3 From 26414a69824a37a65c0fb3a6c423f4cb6c1ef068 Mon Sep 17 00:00:00 2001 From: Cody McGinnis Date: Fri, 28 Aug 2020 16:21:31 -0400 Subject: fix(docs): move testing docs to website docs --- docs/docs/dev-tests.md | 23 +++++++++++++++++++++++ docs/sidebars.js | 1 + 2 files changed, 24 insertions(+) create mode 100644 docs/docs/dev-tests.md (limited to 'docs') diff --git a/docs/docs/dev-tests.md b/docs/docs/dev-tests.md new file mode 100644 index 0000000..1709ccd --- /dev/null +++ b/docs/docs/dev-tests.md @@ -0,0 +1,23 @@ +# Basics +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`. + +`test_case/events.patterns` contains sed patterns that will select the interesting output from the +application + +`test_case/keycode_events.snapshot` contains the expected output after applying `events.pattern` to +the output + +`test_case/native_posix.keymap` defines the keys and the mock key presses. Most tests include a +common keymap for their test set + +## 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. Repeat steps 4 to 6 for every test case \ No newline at end of file diff --git a/docs/sidebars.js b/docs/sidebars.js index 51313fc..d426667 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -20,6 +20,7 @@ module.exports = { "dev-setup", "dev-boards-shields-keymaps", "dev-posix-board", + "dev-tests", ], "Dev Guides": ["dev-guide-new-shield", "dev-guide-usb-logging"], }, -- cgit v1.2.3 From 205a54baeb75f631795c3de34948e5e9f1af0083 Mon Sep 17 00:00:00 2001 From: Cody McGinnis Date: Fri, 28 Aug 2020 16:21:31 -0400 Subject: fix(docs): update the testing docs --- docs/docs/dev-tests.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-tests.md b/docs/docs/dev-tests.md index 1709ccd..68d4725 100644 --- a/docs/docs/dev-tests.md +++ b/docs/docs/dev-tests.md @@ -1,15 +1,11 @@ -# Basics -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`. - -`test_case/events.patterns` contains sed patterns that will select the interesting output from the -application +--- +id: dev-tests +title: Tests +sidebar_label: Tests +--- -`test_case/keycode_events.snapshot` contains the expected output after applying `events.pattern` to -the output - -`test_case/native_posix.keymap` defines the keys and the mock key presses. Most tests include a -common keymap for their test set +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. @@ -20,4 +16,5 @@ common keymap for their test set - 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. Repeat steps 4 to 6 for every test case \ No newline at end of file +7. Rename the `test_case` folder to describe the test. +8. Repeat steps 4 to 7 for every test case \ No newline at end of file -- cgit v1.2.3 From ec6215f38e4f178740e0838bba3bf8ca6d9f1f0c Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 15:05:43 -0700 Subject: Added Arduino IDE to USB Logging --- docs/docs/dev-guide-usb-logging.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index 3bc8a0c..bb09364 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -3,6 +3,9 @@ id: dev-guide-usb-logging 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, @@ -11,7 +14,7 @@ messages to that device instead. ## Kconfig -The following KConfig values need to be set, either by copy and paste into the `app/prj.conf` file, or by running +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. ``` @@ -42,12 +45,26 @@ 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. +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.: + + +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 the Arduino IDE which contains a built-in Serial Monitor. Download and install it from [their website](https://www.arduino.cc/en/main/software), then connect your board and under Tools select "Serial Monitor". + + + From there, you should see the various log messages from ZMK and Zephyr, depending on which systems you have set to what log levels. -- cgit v1.2.3 From 35dc46bfbb472c01c2c791233bbe32734cb6dfd5 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 15:51:08 -0700 Subject: Made separate build and flash page with updated content --- docs/docs/dev-build.md | 88 ++++++++++++++++++++++++++++++++++++++ docs/docs/dev-guide-usb-logging.md | 4 +- docs/docs/dev-setup.md | 77 ++++++++++----------------------- docs/sidebars.js | 1 + 4 files changed, 113 insertions(+), 57 deletions(-) create mode 100644 docs/docs/dev-build.md (limited to 'docs') diff --git a/docs/docs/dev-build.md b/docs/docs/dev-build.md new file mode 100644 index 0000000..2df15cd --- /dev/null +++ b/docs/docs/dev-build.md @@ -0,0 +1,88 @@ +--- +id: dev-build-flash +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 -DKEYMAP=default +``` + +### 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 -- -DKEYMAP=default +``` + +### 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 and regenerates them, and can be enabled by adding either --pristine or -p to the command: + +```sh +west build -p -b proton_c -- -DSHIELD=kyria_left -DKEYMAP=default +``` + +## 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` and is by default named `zmk.uf2`. + +:::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 you will have to +1. Build the left side with the `build` command provided above +2. Flash `zmk.uf2` to the left side +3. Replace DSHIELD with the right side (for the above example, this would be `kyria_right`) and build again +4. Flash `zmk.uf2` the right side +::: diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index bb09364..fa4b63b 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -51,7 +51,7 @@ After flashing the updated ZMK image, the board should expose a USB CDC ACM devi defaultValue="linux" values={[ {label: 'Linux', value: 'linux'}, -{label: 'Windows', value: 'windows'}, +{label: 'Windows', value: 'win'}, ]}> @@ -60,7 +60,7 @@ On Linux, this should be a device like `/dev/ttyACM0` and you can connect with ` sudo tio /dev/ttyACM0 ``` - + On Windows, you can use the Arduino IDE which contains a built-in Serial Monitor. Download and install it from [their website](https://www.arduino.cc/en/main/software), then connect your board and under Tools select "Serial Monitor". diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index fae0aa0..1c5c9dd 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -181,7 +181,7 @@ brew install cmake ninja python3 ccache dtc git wget ## Setup -### West Build Command +### 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. @@ -192,14 +192,32 @@ pip3 install --user -U west ``` :::danger pip user packages -If you haven't done so yet, you may need to add the Python Pip user package directory to your `PATH`, e.g.: +If you haven't done so yet, you may need to add the Python Pip user 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. Go to the Start Menu and type "environment variables" to find and open the "Edit the system environment variables" option. +2. Click "Environment Variables...", and select the "Path" variable under System variables. +3. Click "Edit..." and then "New" to add the directory where your west.exe is located. By default this should be something like `C:\Python38\Scripts`. + + + ### Toolchain Installation @@ -428,54 +446,3 @@ cat ~/.zephyrrc >> ~/.zshrc - -## Build - -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 a MCU board addon. - -### Keyboard (Shield) + MCU Board - -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: - -- 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 -DKEYMAP=default -``` - -### 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 -- -DKEYMAP=default -``` - -## Flashing - -Once built, the previously supplied parameters will be remember, so you can simply run the following to flash your -board, with it in bootloader mode: - -``` -west flash -``` diff --git a/docs/sidebars.js b/docs/sidebars.js index d426667..3710137 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -18,6 +18,7 @@ module.exports = { Development: [ "dev-clean-room", "dev-setup", + "dev-build-flash", "dev-boards-shields-keymaps", "dev-posix-board", "dev-tests", -- cgit v1.2.3 From 96020a469a5524817732dec59c2b22e0e6172504 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 17:21:56 -0700 Subject: Added win environment variables instructions --- docs/docs/dev-setup.md | 45 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 34 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 1c5c9dd..151a032 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -212,8 +212,7 @@ source ~/.bashrc -1. Go to the Start Menu and type "environment variables" to find and open the "Edit the system environment variables" option. -2. Click "Environment Variables...", and select the "Path" variable under System variables. +1. See the [Environment Variables](#environment-variables) section on how to get to the Environment Variables page. 3. Click "Edit..." and then "New" to add the directory where your west.exe is located. By default this should be something like `C:\Python38\Scripts`. @@ -359,10 +358,41 @@ pip3 install --user -r zephyr/scripts/requirements-base.txt ### Environment Variables +#### GNU ARM Embedded on Windows + +On Windows, you will have to set two environment variables for ZMK to build properly: `ZEPHYR_TOOLCHAIN_VARIANT` and `GNUARMEMB_TOOLCHAIN_PATH`. + +
+ Steps to Update Environment Variables + +1. Open Start Menu and type 'env' to find the 'Edit the system environment variables' option. Open it. + +![start menu](assets/env-var/start_menu.png) + +2. Click 'Environment Variables...'. + +![start menu](assets/env-var/env_var.png) + +3. Click "New..." under System variables to create a new system variable. + +![start menu](assets/env-var/new_variable.png) + +4. Set the variable name to 'ZEPHYR_TOOLCHAIN_VARIANT' and value to 'gnuarmemb'. Click OK to save. + +![start menu](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. Click OK to save. + +![start menu](assets/env-var/gnuarmemb.png) + +
+ +#### 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 +##### Per Shell To load the Zephyr environment properly for just one transient shell, run the following from your ZMK checkout directory: @@ -408,7 +438,7 @@ source zephyr/zephyr-env.cmd -#### All Shells +##### 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. @@ -419,7 +449,6 @@ defaultValue="bash" values={[ {label: 'bash', value: 'bash'}, {label: 'zsh', value: 'zsh'}, -{label: 'cmd.exe', value: 'cmd'}, ] }> @@ -439,10 +468,4 @@ cat ~/.zephyrrc >> ~/.zshrc - - -`cmd.exe` instructions coming soon! - - - -- cgit v1.2.3 From 9b9174cc574b5d8d55cd2b4b583f44f0f7421404 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 17:22:39 -0700 Subject: Added lily58 reset photo --- docs/docs/assets/bond-clearing/lily58.jpg | Bin 0 -> 2566639 bytes docs/docs/bond-reset.md | 16 ++++++++++------ 2 files changed, 10 insertions(+), 6 deletions(-) create mode 100644 docs/docs/assets/bond-clearing/lily58.jpg (limited to 'docs') diff --git a/docs/docs/assets/bond-clearing/lily58.jpg b/docs/docs/assets/bond-clearing/lily58.jpg new file mode 100644 index 0000000..4087e7d Binary files /dev/null and b/docs/docs/assets/bond-clearing/lily58.jpg differ diff --git a/docs/docs/bond-reset.md b/docs/docs/bond-reset.md index 1d3732b..1ba79ee 100644 --- a/docs/docs/bond-reset.md +++ b/docs/docs/bond-reset.md @@ -4,8 +4,8 @@ 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. The keys must be held for 3 to 5 seconds after the device is +Known as a 'bond reset', each keyboard has a special key combination independent of the user defined key map which will +clear all wireless connection configurations. The keys must be held for 3 to 5 seconds after the device is reset. :::warning @@ -13,15 +13,19 @@ Currently, ZMK only supports a single BLE host. If you remove the keyboard from list, you will need to clear the bonds. ::: -### Split Keyboards +## 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 ![Kyria bond-reset combo](assets/bond-clearing/kyria.jpg) -## Corne +### Corne -![Corne bond-reset combo](assets/bond-clearing/corne.jpg) \ No newline at end of file +![Corne bond-reset combo](assets/bond-clearing/corne.jpg) + +### Lily58 + +![Lily58 bond-reset combo](assets/bond-clearing/lily58.jpg) \ No newline at end of file -- cgit v1.2.3 From 133166c392540f8496f2dd42671ddda1bd547d2f Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 17:23:17 -0700 Subject: Pictures for environment variables --- docs/docs/assets/env-var/env_var.png | Bin 0 -> 17317 bytes docs/docs/assets/env-var/gnuarmemb.png | Bin 0 -> 7914 bytes docs/docs/assets/env-var/new_variable.png | Bin 0 -> 60899 bytes docs/docs/assets/env-var/start_menu.png | Bin 0 -> 51108 bytes docs/docs/assets/env-var/zephyr_toolchain.png | Bin 0 -> 7282 bytes 5 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/docs/assets/env-var/env_var.png create mode 100644 docs/docs/assets/env-var/gnuarmemb.png create mode 100644 docs/docs/assets/env-var/new_variable.png create mode 100644 docs/docs/assets/env-var/start_menu.png create mode 100644 docs/docs/assets/env-var/zephyr_toolchain.png (limited to 'docs') diff --git a/docs/docs/assets/env-var/env_var.png b/docs/docs/assets/env-var/env_var.png new file mode 100644 index 0000000..77ebbc5 Binary files /dev/null and b/docs/docs/assets/env-var/env_var.png differ diff --git a/docs/docs/assets/env-var/gnuarmemb.png b/docs/docs/assets/env-var/gnuarmemb.png new file mode 100644 index 0000000..42e38ec Binary files /dev/null and b/docs/docs/assets/env-var/gnuarmemb.png differ diff --git a/docs/docs/assets/env-var/new_variable.png b/docs/docs/assets/env-var/new_variable.png new file mode 100644 index 0000000..3cc72bd Binary files /dev/null and b/docs/docs/assets/env-var/new_variable.png differ diff --git a/docs/docs/assets/env-var/start_menu.png b/docs/docs/assets/env-var/start_menu.png new file mode 100644 index 0000000..fc7d9b5 Binary files /dev/null and b/docs/docs/assets/env-var/start_menu.png differ diff --git a/docs/docs/assets/env-var/zephyr_toolchain.png b/docs/docs/assets/env-var/zephyr_toolchain.png new file mode 100644 index 0000000..5a8ec50 Binary files /dev/null and b/docs/docs/assets/env-var/zephyr_toolchain.png differ -- cgit v1.2.3 From 76095c64c6d51c2c7aaf9856d50847998a41b263 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 17:25:00 -0700 Subject: Fixed title --- docs/docs/dev-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 151a032..e9c635a 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -358,7 +358,7 @@ pip3 install --user -r zephyr/scripts/requirements-base.txt ### Environment Variables -#### GNU ARM Embedded on Windows +#### For GNU ARM Embedded on Windows On Windows, you will have to set two environment variables for ZMK to build properly: `ZEPHYR_TOOLCHAIN_VARIANT` and `GNUARMEMB_TOOLCHAIN_PATH`. -- cgit v1.2.3 From d7bd09149b347c71259eb299f8e8f7ddaa4055f7 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 17:25:37 -0700 Subject: Added info on connecting keyboard --- docs/docs/user-setup.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/docs/user-setup.md b/docs/docs/user-setup.md index be230d2..b1ffefa 100644 --- a/docs/docs/user-setup.md +++ b/docs/docs/user-setup.md @@ -11,8 +11,7 @@ Unlike other keyboard firmwares, ZMK Firmware has been built from the ground up their own keyboard configurations, including keymaps, specific hardware details, etc. all outside of the core ZMK Firmware source repository. -In addition to this, most users do not need to install any complicated toolchains or tools to build ZMK, -instead using GitHub Actions to automatically build the user's configured firmware for them. +In addition to this, most users will not need to install any complicated toolchains or tools to build ZMK. GitHub Actions is used instead to automatically build the user's configured firmware for them. ## Summary @@ -170,7 +169,7 @@ a link to download the `firmware` upload: Once downloaded, extract the zip and you can verify it should contain one or more `uf2` files, which will be copied to your keyboard. -### Installing UF2 Files +### Flashing UF2 Files To flash the firmware, first put your board into bootloader mode by double clicking the reset button (either on the MCU board itself, or the one that is part of your keyboard). The controller should appear in your OS as a new USB storage device. @@ -178,6 +177,14 @@ or the one that is part of your keyboard). The controller should appear in your Once this happens, copy the correct UF2 file (e.g. left or right if working on a split), and paste it onto the root of that USB mass storage device. Once the flash is complete, the controller should automatically restart, and load your newfly flashed firmware. +## 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 Split Keyboard Halves + +For split keyboards, after flashing each half individually you can connect them together by resetting them at the same time. Within a few seconds of resetting, both halves should automatically connect to each other. + ## Customization ### Configuration Changes @@ -199,3 +206,5 @@ GitHub Actions job to build your firmware which you can download once it complet :::note If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https://www.freecodecamp.org/news/learn-the-basics-of-git-in-under-10-minutes-da548267cc91/) will help you get these steps right. ::: + +For split keyboards, only the central (usually left) side will need to be reflashed after making updates to your keymap. -- cgit v1.2.3 From dad2d339b3fa038af1b87cdb60b79081d681a6c3 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 17:46:00 -0700 Subject: Added customization page --- docs/docs/customization.md | 33 +++++++++++++++++++++++++++++++++ docs/docs/feature/keymaps.md | 2 +- docs/docs/hardware.md | 2 +- docs/docs/intro.md | 2 +- docs/docs/user-setup.md | 24 ------------------------ docs/sidebars.js | 2 +- 6 files changed, 37 insertions(+), 28 deletions(-) create mode 100644 docs/docs/customization.md (limited to 'docs') diff --git a/docs/docs/customization.md b/docs/docs/customization.md new file mode 100644 index 0000000..0bb1794 --- /dev/null +++ b/docs/docs/customization.md @@ -0,0 +1,33 @@ +--- +id: customization +title: Customizing ZMK +sidebar_label: Customizing ZMK +--- + +After verifying you can successfully flash the default firmware, you will probably want to begin customizing your keymap and other keyboard options. + +## Configuration Changes + +The setup script creates a `config/.conf` file that allows you to add additional configuration options to +control what features and options are built into your firmware. Opening that file with your text editor will allow you to see the +various config settings that can be commented/uncommented to modify how your firmware is built. + +## Keymap + +Once you have the basic user config completed, you can find the keymap file in `config/.keymap` and customize from there. +Refer to the [Keymap](/docs/feature/keymaps) documentation to learn more. + +## Publishing + +After making any changes you want, you should commit the changes and then push them to GitHub. That will trigger a new +GitHub Actions job to build your firmware which you can download once it completes. + +:::note +If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https://www.freecodecamp.org/news/learn-the-basics-of-git-in-under-10-minutes-da548267cc91/) will help you get these steps right. +::: + +## Flashing Your Changes + +For normal keyboards, follow the same flashing instructions as before to flash your updated firmware. + +For split keyboards, only the central (left) side will need to be reflashed if you are just updating your keymap. diff --git a/docs/docs/feature/keymaps.md b/docs/docs/feature/keymaps.md index 020df17..367b03c 100644 --- a/docs/docs/feature/keymaps.md +++ b/docs/docs/feature/keymaps.md @@ -4,7 +4,7 @@ title: Keymaps & Behaviors sidebar_label: Keymaps --- -ZMK uses an declarative approach to keymaps, instead of using C code for all keymap configuration. +ZMK uses a declarative approach to keymaps instead of using C code for all keymap configuration. Right now, ZMK uses the devicetree syntax to declare those keymaps; future work is envisioned for supporting dynamic loading of declarative keymaps, e.g. over USB Mass Storage or via a custom BLE service. diff --git a/docs/docs/hardware.md b/docs/docs/hardware.md index 9e6a956..299d1f5 100644 --- a/docs/docs/hardware.md +++ b/docs/docs/hardware.md @@ -11,7 +11,7 @@ have had their hardware details codified in boards/shields for ZMK. ::: -Being built on a solid technical foundation of the Zephyr™ RTOS, it's possible to make ZMK support a wide diversity of hardware targets. +With the solid technical foundation of Zephyr™ RTOS, ZMK can support a wide diversity of hardware targets. That being said, there are currently only a few specific [boards](/docs/faq#what-is-a-board)/[shields](/docs/faq#what-is-a-shield) that have been written and tested by the ZMK contributors. ## Boards diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 514c76e..29045f7 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/) RTOS. +firmware built on the [Zephyr™ Project](https://zephyrproject.com/) 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 diff --git a/docs/docs/user-setup.md b/docs/docs/user-setup.md index b1ffefa..2aade82 100644 --- a/docs/docs/user-setup.md +++ b/docs/docs/user-setup.md @@ -184,27 +184,3 @@ Connecting your keyboard wirelessly is the same as adding other Bluetooth devide ### Connecting Split Keyboard Halves For split keyboards, after flashing each half individually you can connect them together by resetting them at the same time. Within a few seconds of resetting, both halves should automatically connect to each other. - -## Customization - -### Configuration Changes - -The setup script creates a `config/.conf` file that allows you to add additional configuration options to -control what features and options are built into your firmware. Opening that file with your text editor you should see -various config settings that can be commented/uncommented to modify how your firmware is built. - -### Keymap - -Once you have the basic user config completed, you can find the file in `config/.keymap` and customize from there. -Refer to the [Keymap](/docs/feature/keymaps) documentation to learn more. - -### Publishing - -After making any changes you want, you should commit the changes and then push them to GitHub. That will trigger a new -GitHub Actions job to build your firmware which you can download once it completes. - -:::note -If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https://www.freecodecamp.org/news/learn-the-basics-of-git-in-under-10-minutes-da548267cc91/) will help you get these steps right. -::: - -For split keyboards, only the central (usually left) side will need to be reflashed after making updates to your keymap. diff --git a/docs/sidebars.js b/docs/sidebars.js index 3710137..53c5cf3 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -1,6 +1,6 @@ module.exports = { someSidebar: { - "Getting Started": ["intro", "hardware", "faq", "user-setup", "bond-reset"], + "Getting Started": ["intro", "hardware", "faq", "user-setup","customization", "bond-reset"], Features: [ "feature/keymaps", "feature/displays", -- cgit v1.2.3 From 276a2620b9a5259dd15cd4a6038a6144e5da9432 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 17:47:41 -0700 Subject: Minor capitalization fix --- docs/docs/feature/keymaps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/feature/keymaps.md b/docs/docs/feature/keymaps.md index 367b03c..d991925 100644 --- a/docs/docs/feature/keymaps.md +++ b/docs/docs/feature/keymaps.md @@ -80,7 +80,7 @@ A keymap file is composed of several sections, that together make up a valid dev ### Includes -THe devicetree files are actually preprocessed before being finally leveraged by Zephyr. This allows using standard C defines to create meaningful placeholders +The devicetree files are actually preprocessed before being finally leveraged by Zephyr. This allows using standard C defines to create meaningful placeholders for what would otherwise be cryptic integer keycodes, etc. This also allows bringing in _other_ devicetree nodes from separate files. The top two lines of most keymaps should include: -- cgit v1.2.3 From 037970fe8c0122d156de4db92e3ef335e1902e55 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 18:43:13 -0700 Subject: Removed DKEYMAP and added split build directories --- docs/docs/dev-build.md | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-build.md b/docs/docs/dev-build.md index 2df15cd..393f483 100644 --- a/docs/docs/dev-build.md +++ b/docs/docs/dev-build.md @@ -43,7 +43,7 @@ Given the following: You can build ZMK with the following: ```sh -west build -b proton_c -- -DSHIELD=kyria_left -DKEYMAP=default +west build -b proton_c -- -DSHIELD=kyria_left ``` ### Keyboard With Onboard MCU @@ -58,14 +58,29 @@ Given the following: you can build ZMK with the following: ```sh -west build -b planck_rev6 -- -DKEYMAP=default +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 and regenerates them, and can be enabled by adding either --pristine or -p to the command: ```sh -west build -p -b proton_c -- -DSHIELD=kyria_left -DKEYMAP=default +west build -p -b proton_c -- -DSHIELD=kyria_left +``` +### 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 each time and separate the left and right build files, we recommend setting up separate build directories for each half. You can do this by 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 ``` ## Flashing @@ -79,10 +94,3 @@ west flash For boards that have drag and drop .uf2 flashing capability, the .uf2 file to flash can be found in `build\zephyr` and is by default named `zmk.uf2`. -:::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 you will have to -1. Build the left side with the `build` command provided above -2. Flash `zmk.uf2` to the left side -3. Replace DSHIELD with the right side (for the above example, this would be `kyria_right`) and build again -4. Flash `zmk.uf2` the right side -::: -- cgit v1.2.3 From bc13cd1de1b647a519d051ed44f69a09ad75bfbf Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 19:22:43 -0700 Subject: Added PuTTY to USB Logging --- docs/docs/assets/usb-logging/com_port.PNG | Bin 0 -> 14258 bytes docs/docs/assets/usb-logging/putty.PNG | Bin 0 -> 19822 bytes docs/docs/dev-guide-usb-logging.md | 8 +++++++- 3 files changed, 7 insertions(+), 1 deletion(-) create mode 100644 docs/docs/assets/usb-logging/com_port.PNG create mode 100644 docs/docs/assets/usb-logging/putty.PNG (limited to 'docs') diff --git a/docs/docs/assets/usb-logging/com_port.PNG b/docs/docs/assets/usb-logging/com_port.PNG new file mode 100644 index 0000000..35934b8 Binary files /dev/null and b/docs/docs/assets/usb-logging/com_port.PNG differ diff --git a/docs/docs/assets/usb-logging/putty.PNG b/docs/docs/assets/usb-logging/putty.PNG new file mode 100644 index 0000000..b53d536 Binary files /dev/null and b/docs/docs/assets/usb-logging/putty.PNG differ diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index fa4b63b..62977c7 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -62,7 +62,13 @@ sudo tio /dev/ttyACM0 -On Windows, you can use the Arduino IDE which contains a built-in Serial Monitor. Download and install it from [their website](https://www.arduino.cc/en/main/software), then connect your board and under Tools select "Serial Monitor". +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_port.png) + +![PuTTY settings](assets/usb-logging/putty.png) + +If you already have the Ardunio IDE installed you can also use its built-in Serial Monitor. -- cgit v1.2.3 From 8594d832b663c92d5d1ccfe14c65419835f4059e Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 19:23:25 -0700 Subject: Added split build directories --- docs/docs/dev-build.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-build.md b/docs/docs/dev-build.md index 393f483..b962a7d 100644 --- a/docs/docs/dev-build.md +++ b/docs/docs/dev-build.md @@ -62,26 +62,27 @@ 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 and regenerates them, and can be enabled by adding either --pristine or -p to the command: +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 ``` -### Split Keyboards +### 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 each time and separate the left and right build files, we recommend setting up separate build directories for each half. You can do this by first building left into `build\left`: +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`: +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. ## Flashing @@ -92,5 +93,5 @@ 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` and is by default named `zmk.uf2`. +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`. -- cgit v1.2.3 From 0a06760cda0cc9cbce4b4c188ea169194903a695 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 19:26:11 -0700 Subject: Updated alt text --- docs/docs/dev-setup.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index e9c635a..1d7d703 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -367,23 +367,23 @@ On Windows, you will have to set two environment variables for ZMK to build prop 1. Open Start Menu and type 'env' to find the 'Edit the system environment variables' option. Open it. -![start menu](assets/env-var/start_menu.png) +![Environment variables in Start Menu](assets/env-var/start_menu.png) 2. Click 'Environment Variables...'. -![start menu](assets/env-var/env_var.png) +![Environment variables button](assets/env-var/env_var.png) 3. Click "New..." under System variables to create a new system variable. -![start menu](assets/env-var/new_variable.png) +![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. -![start menu](assets/env-var/zephyr_toolchain.png) +![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. Click OK to save. -![start menu](assets/env-var/gnuarmemb.png) +![Adding GNUARMEMB variable](assets/env-var/gnuarmemb.png) -- cgit v1.2.3 From 0e04596ef610aa5c23cae5bdc80fd63ee28b3701 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 21:04:32 -0700 Subject: Renamed COM port image --- docs/docs/assets/usb-logging/com-port.PNG | Bin 0 -> 14258 bytes docs/docs/assets/usb-logging/com_port.PNG | Bin 14258 -> 0 bytes docs/docs/dev-guide-usb-logging.md | 2 +- 3 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 docs/docs/assets/usb-logging/com-port.PNG delete mode 100644 docs/docs/assets/usb-logging/com_port.PNG (limited to 'docs') diff --git a/docs/docs/assets/usb-logging/com-port.PNG b/docs/docs/assets/usb-logging/com-port.PNG new file mode 100644 index 0000000..35934b8 Binary files /dev/null and b/docs/docs/assets/usb-logging/com-port.PNG differ diff --git a/docs/docs/assets/usb-logging/com_port.PNG b/docs/docs/assets/usb-logging/com_port.PNG deleted file mode 100644 index 35934b8..0000000 Binary files a/docs/docs/assets/usb-logging/com_port.PNG and /dev/null differ diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index 62977c7..b63494d 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -64,7 +64,7 @@ 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_port.png) +![Controller COM port](assets/usb-logging/com-port.png) ![PuTTY settings](assets/usb-logging/putty.png) -- cgit v1.2.3 From af23445aa02cea100ba064770a139b4971a6fc39 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 21:13:48 -0700 Subject: COM image fix --- docs/docs/assets/usb-logging/com-port.PNG | Bin 14258 -> 0 bytes docs/docs/assets/usb-logging/com.PNG | Bin 0 -> 14258 bytes docs/docs/dev-guide-usb-logging.md | 2 +- 3 files changed, 1 insertion(+), 1 deletion(-) delete mode 100644 docs/docs/assets/usb-logging/com-port.PNG create mode 100644 docs/docs/assets/usb-logging/com.PNG (limited to 'docs') diff --git a/docs/docs/assets/usb-logging/com-port.PNG b/docs/docs/assets/usb-logging/com-port.PNG deleted file mode 100644 index 35934b8..0000000 Binary files a/docs/docs/assets/usb-logging/com-port.PNG and /dev/null differ diff --git a/docs/docs/assets/usb-logging/com.PNG b/docs/docs/assets/usb-logging/com.PNG new file mode 100644 index 0000000..35934b8 Binary files /dev/null and b/docs/docs/assets/usb-logging/com.PNG differ diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index b63494d..6eca165 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -64,7 +64,7 @@ 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-port.png) +![Controller COM port](./assets/usb-logging/com.png) ![PuTTY settings](assets/usb-logging/putty.png) -- cgit v1.2.3 From 06af711f57df20b195a1cf37b1a31ceee9a672b6 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 21:20:38 -0700 Subject: Replaced png with jpg --- docs/docs/assets/usb-logging/com.PNG | Bin 14258 -> 0 bytes docs/docs/assets/usb-logging/com.jpg | Bin 0 -> 10993 bytes docs/docs/dev-guide-usb-logging.md | 2 +- 3 files changed, 1 insertion(+), 1 deletion(-) delete mode 100644 docs/docs/assets/usb-logging/com.PNG create mode 100644 docs/docs/assets/usb-logging/com.jpg (limited to 'docs') diff --git a/docs/docs/assets/usb-logging/com.PNG b/docs/docs/assets/usb-logging/com.PNG deleted file mode 100644 index 35934b8..0000000 Binary files a/docs/docs/assets/usb-logging/com.PNG and /dev/null differ diff --git a/docs/docs/assets/usb-logging/com.jpg b/docs/docs/assets/usb-logging/com.jpg new file mode 100644 index 0000000..e2ab9a8 Binary files /dev/null and b/docs/docs/assets/usb-logging/com.jpg differ diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index 6eca165..11b568e 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -64,7 +64,7 @@ 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.png) +![Controller COM port](./assets/usb-logging/com.jpg) ![PuTTY settings](assets/usb-logging/putty.png) -- cgit v1.2.3 From 212dd91e2910e58e5a5c0c32e8726f2efc396c22 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 21:27:03 -0700 Subject: PuTTY image fix --- docs/docs/assets/bond-clearing/debug.log | 0 docs/docs/assets/usb-logging/putty.PNG | Bin 19822 -> 0 bytes docs/docs/assets/usb-logging/putty.jpg | Bin 0 -> 160650 bytes docs/docs/dev-guide-usb-logging.md | 2 +- 4 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 docs/docs/assets/bond-clearing/debug.log delete mode 100644 docs/docs/assets/usb-logging/putty.PNG create mode 100644 docs/docs/assets/usb-logging/putty.jpg (limited to 'docs') diff --git a/docs/docs/assets/bond-clearing/debug.log b/docs/docs/assets/bond-clearing/debug.log new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/assets/usb-logging/putty.PNG b/docs/docs/assets/usb-logging/putty.PNG deleted file mode 100644 index b53d536..0000000 Binary files a/docs/docs/assets/usb-logging/putty.PNG and /dev/null differ diff --git a/docs/docs/assets/usb-logging/putty.jpg b/docs/docs/assets/usb-logging/putty.jpg new file mode 100644 index 0000000..dfbb4bd Binary files /dev/null and b/docs/docs/assets/usb-logging/putty.jpg differ diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index 11b568e..c5fb4b9 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -66,7 +66,7 @@ On Windows, you can use [PuTTY](https://www.putty.org/). Once installed, use Dev ![Controller COM port](./assets/usb-logging/com.jpg) -![PuTTY settings](assets/usb-logging/putty.png) +![PuTTY settings](assets/usb-logging/putty.jpg) If you already have the Ardunio IDE installed you can also use its built-in Serial Monitor. -- cgit v1.2.3 From 45b1756a700ba0603f0a3b7708108c9ebc9fc945 Mon Sep 17 00:00:00 2001 From: Kevin Chen Date: Sat, 29 Aug 2020 21:36:00 -0700 Subject: Replaced \ with / Co-authored-by: Pete Johanson --- docs/docs/dev-build.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-build.md b/docs/docs/dev-build.md index b962a7d..816468e 100644 --- a/docs/docs/dev-build.md +++ b/docs/docs/dev-build.md @@ -93,5 +93,4 @@ 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`. - +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`. -- cgit v1.2.3 From 96fde775604be02f2aeee04f3cd6d4edff2815bd Mon Sep 17 00:00:00 2001 From: Kurtis Lew Date: Sun, 30 Aug 2020 20:12:53 -0700 Subject: Update key-press.md Specified keypress and consumer press pages --- docs/docs/behavior/key-press.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/behavior/key-press.md b/docs/docs/behavior/key-press.md index 2edce1d..f58225d 100644 --- a/docs/docs/behavior/key-press.md +++ b/docs/docs/behavior/key-press.md @@ -8,7 +8,7 @@ sidebar_label: Key Press The most basic of behaviors, is the ability to send certain keycode presses and releases in response to activating a certain key. -For reference on keycode values, see the [USB HID Usage Tables](https://www.usb.org/document-library/hid-usage-tables-12). +For reference on keycode values, see pages 83-89 of the [USB HID Usage Tables](https://www.usb.org/document-library/hid-usage-tables-12). ## Keycode Defines -- cgit v1.2.3 From ca0f2bb074a103b871a3e0f7f5e1fed8b6b4069b Mon Sep 17 00:00:00 2001 From: CrossR Date: Tue, 1 Sep 2020 18:32:45 +0100 Subject: Add to setup. --- docs/static/setup.sh | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/static/setup.sh b/docs/static/setup.sh index 4dc740a..a32718d 100644 --- a/docs/static/setup.sh +++ b/docs/static/setup.sh @@ -38,7 +38,7 @@ echo "" echo "Keyboard Shield Selection:" prompt="Pick an keyboard:" -options=("Kyria" "Lily58" "Corne" "Splitreus62") +options=("Kyria" "Lily58" "Corne" "Splitreus62" "Sofle") PS3="$prompt " # TODO: Add support for "Other" and linking to docs on adding custom shields in user config repos. @@ -51,6 +51,7 @@ select opt in "${options[@]}" "Quit"; do 2 ) shield_title="Lily58" shield="lily58"; split="y"; break;; 3 ) shield_title="Corne" shield="corne"; split="y"; break;; 4 ) shield_title="Splitreus62" shield="splitreus62"; split="y"; break;; + 5 ) shield_title="Sofle" shield="sofle"; split="y"; break;; # Add link to docs on adding your own custom shield in your ZMK config! # $(( ${#options[@]}+1 )) ) echo "Other!"; break;; -- cgit v1.2.3 From 29a23f018235ede8cfe65f5ede5014408eee879a Mon Sep 17 00:00:00 2001 From: Okke Formsma Date: Tue, 1 Sep 2020 16:04:58 +0200 Subject: Add tap-hold docs, update mod-tap docs --- docs/docs/assets/hold-tap/case1_2.png | Bin 0 -> 10323 bytes docs/docs/assets/hold-tap/case_hold_preferred.png | Bin 0 -> 6380 bytes docs/docs/assets/hold-tap/comparison.png | Bin 0 -> 158912 bytes docs/docs/behavior/hold-tap.md | 62 ++++++++++++++++++++++ docs/docs/behavior/mod-tap.md | 27 +++++++--- 5 files changed, 82 insertions(+), 7 deletions(-) create mode 100644 docs/docs/assets/hold-tap/case1_2.png create mode 100644 docs/docs/assets/hold-tap/case_hold_preferred.png create mode 100644 docs/docs/assets/hold-tap/comparison.png create mode 100644 docs/docs/behavior/hold-tap.md (limited to 'docs') diff --git a/docs/docs/assets/hold-tap/case1_2.png b/docs/docs/assets/hold-tap/case1_2.png new file mode 100644 index 0000000..818ac83 Binary files /dev/null and b/docs/docs/assets/hold-tap/case1_2.png differ diff --git a/docs/docs/assets/hold-tap/case_hold_preferred.png b/docs/docs/assets/hold-tap/case_hold_preferred.png new file mode 100644 index 0000000..6d7fd43 Binary files /dev/null and b/docs/docs/assets/hold-tap/case_hold_preferred.png differ diff --git a/docs/docs/assets/hold-tap/comparison.png b/docs/docs/assets/hold-tap/comparison.png new file mode 100644 index 0000000..419b204 Binary files /dev/null and b/docs/docs/assets/hold-tap/comparison.png differ diff --git a/docs/docs/behavior/hold-tap.md b/docs/docs/behavior/hold-tap.md new file mode 100644 index 0000000..b586b90 --- /dev/null +++ b/docs/docs/behavior/hold-tap.md @@ -0,0 +1,62 @@ +--- +title: Hold-tap behavior +sidebar_label: Hold-Tap +--- + +## Summary +Hold-tap is the basis for other behaviors such as layer-tap and mod-tap. + +Simply put, the hold-tap key will output the 'hold' behavior if it's held for a while, and output the 'tap' behavior when it's tapped quickly. + + +### Hold-Tap +The `tapping_term_ms` parameter decides between a 'tap' and a 'hold'. + +![Simple behavior](../assets/hold-tap/case1_2.png) + +By default, the hold-tap is configured to also select the 'hold' functionality if another key is tapped while it's active: + +![Hold preferred behavior](../assets/hold-tap/case1_2.png) + +We call this the 'hold-preferred' flavor of hold-taps. While this flavor may work very well for a ctrl/escape key, it's not very well suited for home-row mods or layer-taps. That's why there are two more flavors to choose from: 'tap-preferred' and 'balanced'. + +![Hold-tap comparison](../assets/hold-tap/comparison.png) + +### Configuration +A code example which configures a mod-tap setting that works with homerow mods: + +``` +#include +#include + +/ { + behaviors { + &hm: homerow_mods { + compatible = "zmk,behavior-hold-tap"; + label = "homerow_mods"; + #binding-cells = <2>; + tapping_term_ms = <175>; + flavor = "balanced"; + bindings = <&kp>, <&kp>; + }; + }; + + keymap { + compatible = "zmk,keymap"; + + default_layer { + bindings = < + &hm LCTL A &hm LGUI S &hm LALT D &hm LSFT F + >; + }; + }; +}; + +``` + +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. + +#### 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 diff --git a/docs/docs/behavior/mod-tap.md b/docs/docs/behavior/mod-tap.md index 08e9b65..cbe95e4 100644 --- a/docs/docs/behavior/mod-tap.md +++ b/docs/docs/behavior/mod-tap.md @@ -5,13 +5,9 @@ sidebar_label: Mod-Tap ## Summary -The Mod-Tap behavior allows varying the effect of pressing and releasing a key position depending -on whether it is used with other simultaneous key presses at the same time. +The Mod-Tap sends a different keypress, if it's tapped or held. When you tap the key shortly, the first keycode is sent. If you hold the key for longer than 200ms, the second keycode is sent. -If pressed and released independently, the Mod-Tap behavior will send the press and release events -for the configure keycode. If pressed and held while another key is pressed and released, then -the configured modifiers will be applied to that _other_ key press, and no press will be generated -on the release of the Mod-Tap key. +If you press another key within the 200ms, the 'mod' behavior is also activated. ## Mod-Tap @@ -20,7 +16,7 @@ The Mod-Tap behavior either acts as a held modifier, or as a tapped keycode. ### Behavior Binding - Reference: `&mt` -- Parameter #1: The modifiers to be used when activating as a modifier, e.g. `MOD_LSFT` +- Parameter #1: The keycode to be sent when activating as a modifier, e.g. `LSFT` - Parameter #2: The keycode to sent when used as a tap, e.g. `A`, `B`. Example: @@ -28,3 +24,20 @@ Example: ``` &mt MOD_LSFT A ``` + +### Configuration + +You can configure a different tapping term in your keymap: + +``` +&mt { + tapping_term_ms: <400>; +} + +/ { + keymap { + ... + } +} +``` + -- cgit v1.2.3 From 068626d1a74d3883a8ccb2cd514a217098e99420 Mon Sep 17 00:00:00 2001 From: Kevin Date: Tue, 1 Sep 2020 21:12:09 -0700 Subject: Some work on encoder docs --- docs/docs/dev-guide-add-encoders.md | 53 +++++++++++++++++++++++++++++++++++++ docs/docs/feature/encoders.md | 36 ++++++++++++++++++++++++- docs/sidebars.js | 5 +++- 3 files changed, 92 insertions(+), 2 deletions(-) create mode 100644 docs/docs/dev-guide-add-encoders.md (limited to 'docs') diff --git a/docs/docs/dev-guide-add-encoders.md b/docs/docs/dev-guide-add-encoders.md new file mode 100644 index 0000000..79f353f --- /dev/null +++ b/docs/docs/dev-guide-add-encoders.md @@ -0,0 +1,53 @@ +--- +id: dev-guide-add-encoders +title: Adding Encoders +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +EC11 encoder support can be added to your board or shield by adding the appropriate lines to your board/shield's .conf, .dtsi, and .overlay files. + + + + +In your .conf file you will need to add the following lines so that the EC11 drivers can be enabled: + +``` +# Uncomment to enable encoder +# CONFIG_EC11=y +# CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y +``` + +These should be commented by default if encoders are optional, but can be uncommented if encoders are part of the original design. + + + +In your .dtsi 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. + +Replace `left` with `right` to define a right-side encoder, although note that support for peripheral side sensors is still in progress. + + + + + diff --git a/docs/docs/feature/encoders.md b/docs/docs/feature/encoders.md index 16537ad..9f583cb 100644 --- a/docs/docs/feature/encoders.md +++ b/docs/docs/feature/encoders.md @@ -3,4 +3,38 @@ title: Encoders sidebar_label: Encoders --- -TODO: Documentation on encoders. +Existing support for encoders in ZMK is focused around the EC11 rotary encoder with push button design used in the majority of current keyboard and macropad designs. + +## Enabling EC11 Encoders + +To enable encoders for boards that have existing encoder support, uncomment the `EC11_CONFIG=y` and `CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y` lines in your board's .conf file in your `zmk-config/config` folder. Save and push your changes, then download and flash the new firmware. + +## Customizing EC11 Encoder Behavior + +Encoder behavior in ZMK is configured in two different locations as the push button and rotation behaviors are handled in two separate ways. + +### Push Button + +Keyboards and macropads with encoder support will typically take the two EC11 pins responsible for the push button and include them as part of the matrix for the keys. To configure what is sent by the push button, find the encoder's position in the keyboard matrix and assign it a behavior the same as you would any other key. + +### Rotation + +Rotation is handled separately as a type of sensor. The behavior for this is set by defining `sensor-bindings` within a layer but below the `bindings` for the regular keys in the following format: + +``` +sensor-bindings = ; +``` + +- `BINDING` is one of two rotation bindings that are currently defined, `&inc_dec_cp` for consumer key presses or `&inc_dec_kp` for normal key presses (see [Key Press](<(/docs/behavior/key-press)>) for the difference between the two). +- `CW_KEY` is the keycode activated by a clockwise turn. +- `CCW_KEY` is the keycode activated by a counter-clockwise turn. + +Behaviors for additional encoders can be configured by adding more `BINDING CW_KEY CCW_KEY` sets immediately after the first. + +As an example, a complete `sensor-bindings` for a Kyria would look like: + +``` +sensor-bindings = <&inc_dec_cp M_VOLU M_VOLD &inc_dec_kp PGUP PGDN>; +``` + +In this example, the left encoder is configured to control volume up and down while the right encoder sends either Page Up or Page Down. diff --git a/docs/sidebars.js b/docs/sidebars.js index 53c5cf3..924010e 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -23,6 +23,9 @@ module.exports = { "dev-posix-board", "dev-tests", ], - "Dev Guides": ["dev-guide-new-shield", "dev-guide-usb-logging"], + "Dev Guides": [ + "dev-guide-new-shield", + "dev-guide-add-encoders", + "dev-guide-usb-logging"], }, }; -- cgit v1.2.3 From c5ca66441172114b57ca7f7b27d13d0d342d4fcc Mon Sep 17 00:00:00 2001 From: Okke Formsma Date: Wed, 2 Sep 2020 15:11:56 +0200 Subject: some fixes based on feedback --- docs/docs/behavior/mod-tap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/behavior/mod-tap.md b/docs/docs/behavior/mod-tap.md index cbe95e4..dcac492 100644 --- a/docs/docs/behavior/mod-tap.md +++ b/docs/docs/behavior/mod-tap.md @@ -22,7 +22,7 @@ The Mod-Tap behavior either acts as a held modifier, or as a tapped keycode. Example: ``` -&mt MOD_LSFT A +&mt LSFT A ``` ### Configuration -- cgit v1.2.3 From c9a82d71d06146dfe706a2e8d223dab593dffffc Mon Sep 17 00:00:00 2001 From: Okke Formsma Date: Wed, 2 Sep 2020 16:41:39 +0200 Subject: fixes for feedback round 2 --- 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 b586b90..fa68538 100644 --- a/docs/docs/behavior/hold-tap.md +++ b/docs/docs/behavior/hold-tap.md @@ -31,9 +31,9 @@ A code example which configures a mod-tap setting that works with homerow mods: / { behaviors { - &hm: homerow_mods { + hm: homerow_mods { compatible = "zmk,behavior-hold-tap"; - label = "homerow_mods"; + label = "HOMEROW_MODS"; #binding-cells = <2>; tapping_term_ms = <175>; flavor = "balanced"; -- cgit v1.2.3 From 6f74e61dd383f7b62280f230dafa66014800bd78 Mon Sep 17 00:00:00 2001 From: Kevin Date: Wed, 2 Sep 2020 18:25:46 -0700 Subject: Added user and dev encoder docs --- docs/docs/dev-guide-new-shield.md | 79 +++++++++++++++++++++++++++++++++++++++ docs/docs/feature/encoders.md | 14 ++++--- docs/sidebars.js | 1 - 3 files changed, 88 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index 8556623..7825d8b 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -3,6 +3,9 @@ id: dev-guide-new-shield title: New Keyboard Shield --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## 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. @@ -13,6 +16,7 @@ The high level steps are: - 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. 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. @@ -195,6 +199,81 @@ Further documentation on behaviors and bindings is forthcoming, but a summary of - `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), and overlay (.overlay) 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. +::: + + + + ## Testing Once you've fully created the new keyboard shield definition, diff --git a/docs/docs/feature/encoders.md b/docs/docs/feature/encoders.md index 9f583cb..a5a796d 100644 --- a/docs/docs/feature/encoders.md +++ b/docs/docs/feature/encoders.md @@ -3,7 +3,7 @@ title: Encoders sidebar_label: Encoders --- -Existing support for encoders in ZMK is focused around the EC11 rotary encoder with push button design used in the majority of current keyboard and macropad designs. +Existing support for encoders in ZMK is focused around the five pin EC11 rotary encoder with push button design used in the majority of current keyboard and macropad designs. ## Enabling EC11 Encoders @@ -19,7 +19,7 @@ Keyboards and macropads with encoder support will typically take the two EC11 pi ### Rotation -Rotation is handled separately as a type of sensor. The behavior for this is set by defining `sensor-bindings` within a layer but below the `bindings` for the regular keys in the following format: +Rotation is handled separately as a type of sensor. The behavior for this is set in `sensor-bindings`, which is defined in each keymap layer in the following format: ``` sensor-bindings = ; @@ -29,12 +29,16 @@ sensor-bindings = ; - `CW_KEY` is the keycode activated by a clockwise turn. - `CCW_KEY` is the keycode activated by a counter-clockwise turn. -Behaviors for additional encoders can be configured by adding more `BINDING CW_KEY CCW_KEY` sets immediately after the first. +Additional encoders can be configured by adding more `BINDING CW_KEY CCW_KEY` sets immediately after the first. -As an example, a complete `sensor-bindings` for a Kyria would look like: +As an example, a complete `sensor-bindings` for a Kyria with two encoders could look like: ``` sensor-bindings = <&inc_dec_cp M_VOLU M_VOLD &inc_dec_kp PGUP PGDN>; ``` -In this example, the left encoder is configured to control volume up and down while the right encoder sends either Page Up or Page Down. +Here, the left encoder is configured to control volume up and down while the right encoder sends either Page Up or Page Down. + +## Adding Encoder Support + +See the [New Keyboard Shield](docs/dev-guide-new-shield) documentation for how to add or modify additional encoders to your shield. diff --git a/docs/sidebars.js b/docs/sidebars.js index 924010e..fb82dfa 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -25,7 +25,6 @@ module.exports = { ], "Dev Guides": [ "dev-guide-new-shield", - "dev-guide-add-encoders", "dev-guide-usb-logging"], }, }; -- cgit v1.2.3 From 2629aa354f3d908e3afc13e3cd12a79974d77234 Mon Sep 17 00:00:00 2001 From: Kevin Date: Wed, 2 Sep 2020 18:28:00 -0700 Subject: Removed old dev encoder page --- docs/docs/dev-guide-add-encoders.md | 53 ------------------------------------- 1 file changed, 53 deletions(-) delete mode 100644 docs/docs/dev-guide-add-encoders.md (limited to 'docs') diff --git a/docs/docs/dev-guide-add-encoders.md b/docs/docs/dev-guide-add-encoders.md deleted file mode 100644 index 79f353f..0000000 --- a/docs/docs/dev-guide-add-encoders.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -id: dev-guide-add-encoders -title: Adding Encoders ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -EC11 encoder support can be added to your board or shield by adding the appropriate lines to your board/shield's .conf, .dtsi, and .overlay files. - - - - -In your .conf file you will need to add the following lines so that the EC11 drivers can be enabled: - -``` -# Uncomment to enable encoder -# CONFIG_EC11=y -# CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y -``` - -These should be commented by default if encoders are optional, but can be uncommented if encoders are part of the original design. - - - -In your .dtsi 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. - -Replace `left` with `right` to define a right-side encoder, although note that support for peripheral side sensors is still in progress. - - - - - -- cgit v1.2.3 From 5eb50d7b181d2c61099b49f74b1b54c996370914 Mon Sep 17 00:00:00 2001 From: Kevin Date: Wed, 2 Sep 2020 18:36:35 -0700 Subject: Fixed links --- docs/docs/feature/encoders.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/docs/feature/encoders.md b/docs/docs/feature/encoders.md index a5a796d..38ff9d3 100644 --- a/docs/docs/feature/encoders.md +++ b/docs/docs/feature/encoders.md @@ -25,7 +25,7 @@ Rotation is handled separately as a type of sensor. The behavior for this is set sensor-bindings = ; ``` -- `BINDING` is one of two rotation bindings that are currently defined, `&inc_dec_cp` for consumer key presses or `&inc_dec_kp` for normal key presses (see [Key Press](<(/docs/behavior/key-press)>) for the difference between the two). +- `BINDING` is one of two rotation bindings that are currently defined, `&inc_dec_cp` for consumer key presses or `&inc_dec_kp` for normal key presses (see [Key Press](/docs/behavior/key-press) for the difference between the two). - `CW_KEY` is the keycode activated by a clockwise turn. - `CCW_KEY` is the keycode activated by a counter-clockwise turn. @@ -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) documentation for how to add or modify additional encoders to your shield. +See the [New Keyboard Shield](/docs/dev-guide-new-shield) documentation for how to add or modify additional encoders to your shield. -- cgit v1.2.3 From 9b1fd1323f4fe4a812a08f0d6b762250f54d191f Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Wed, 2 Sep 2020 20:53:14 -0700 Subject: Update setup.sh --- docs/static/setup.sh | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/static/setup.sh b/docs/static/setup.sh index a32718d..ad5416b 100644 --- a/docs/static/setup.sh +++ b/docs/static/setup.sh @@ -52,6 +52,7 @@ select opt in "${options[@]}" "Quit"; do 3 ) shield_title="Corne" shield="corne"; split="y"; break;; 4 ) shield_title="Splitreus62" shield="splitreus62"; split="y"; break;; 5 ) shield_title="Sofle" shield="sofle"; split="y"; break;; + 6 ) shield_title="Iris" shield="iris"; split="y"; break;; # Add link to docs on adding your own custom shield in your ZMK config! # $(( ${#options[@]}+1 )) ) echo "Other!"; break;; -- cgit v1.2.3 From f738fd7a670994bfbe20601a4de9a64cd98020ad Mon Sep 17 00:00:00 2001 From: Kurtis Lew Date: Wed, 2 Sep 2020 20:57:42 -0700 Subject: Update setup.sh --- docs/static/setup.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/static/setup.sh b/docs/static/setup.sh index ad5416b..70defdf 100644 --- a/docs/static/setup.sh +++ b/docs/static/setup.sh @@ -38,7 +38,7 @@ echo "" echo "Keyboard Shield Selection:" prompt="Pick an keyboard:" -options=("Kyria" "Lily58" "Corne" "Splitreus62" "Sofle") +options=("Kyria" "Lily58" "Corne" "Splitreus62" "Sofle" "Iris") PS3="$prompt " # TODO: Add support for "Other" and linking to docs on adding custom shields in user config repos. -- cgit v1.2.3 From e904a098b3ad2af28485e0f79287ac3b04947d1c Mon Sep 17 00:00:00 2001 From: Kevin Date: Wed, 2 Sep 2020 21:12:22 -0700 Subject: Added keymap update to encoder docs --- docs/docs/dev-guide-new-shield.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index 7825d8b..bc5175b 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -203,7 +203,7 @@ Further documentation on behaviors and bindings is forthcoming, but a summary of ### 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), and overlay (.overlay) files. +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. @@ -271,6 +272,15 @@ Add the following lines to your overlay file(s) to enable the encoder: 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_cp M_VOLU M_VOLD>; +``` +Add additional bindings as necessary to match the default number of encoders on your board. See the [Encoders](/docs/feature/encoders) and [Keymap](/docs/feature/keymaps) feature documentation for more details. + -- cgit v1.2.3 From e559cb2d713b4248697518f6bf3ece2e05b87ab3 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Thu, 3 Sep 2020 10:14:16 -0400 Subject: Add hold-tap to sidebar. --- docs/sidebars.js | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/sidebars.js b/docs/sidebars.js index 53c5cf3..3df183b 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -1,6 +1,13 @@ module.exports = { someSidebar: { - "Getting Started": ["intro", "hardware", "faq", "user-setup","customization", "bond-reset"], + "Getting Started": [ + "intro", + "hardware", + "faq", + "user-setup", + "customization", + "bond-reset", + ], Features: [ "feature/keymaps", "feature/displays", @@ -11,6 +18,7 @@ module.exports = { "behavior/key-press", "behavior/layers", "behavior/misc", + "behavior/hold-tap", "behavior/mod-tap", "behavior/reset", "behavior/lighting", -- cgit v1.2.3 From 0ede549a13d6f79ef30ef6cb6e056ae94034ea8d Mon Sep 17 00:00:00 2001 From: CrossR Date: Thu, 3 Sep 2020 22:54:06 +0100 Subject: Fix Sofle build, update Intro page. --- docs/docs/feature/keymaps.md | 2 +- docs/docs/intro.md | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/docs/feature/keymaps.md b/docs/docs/feature/keymaps.md index d991925..56fc2cc 100644 --- a/docs/docs/feature/keymaps.md +++ b/docs/docs/feature/keymaps.md @@ -55,7 +55,7 @@ in the stack _also_ get the event. ## Behavior Bindings Binding a behavior at a certain key position may include up to two extra parameters that are used to -alter the behavior when that specific key position is activated/deactived. For example, when binding +alter the behavior when that specific key position is activated/deactivated. For example, when binding the "key press" (`kp`) behavior at a certain key position, you must specific _which_ keycode should be used for that key position. diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 29045f7..e75ca3c 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -18,21 +18,23 @@ 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 +- Mod-Tap +- Layer Tap - Basic HID over USB - Basic consumer (media) keycodes. - Basic OLED display logic - Basic Split support +- Basic RGB Underglow - Encoders ## Missing Features - One Shot -- Layer Tap - Complete split support - Battery reporting - Low power mode - Shell over BLE +- Macros ## Code Of Conduct -- cgit v1.2.3 From 89d604b74bb3292af53dba7d67b2ae27edfed420 Mon Sep 17 00:00:00 2001 From: CrossR Date: Fri, 4 Sep 2020 19:31:04 +0100 Subject: Clarify low power mode wording. --- 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 e75ca3c..e20f053 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -32,7 +32,7 @@ include: - One Shot - Complete split support - Battery reporting -- Low power mode +- Low power sleep states - Shell over BLE - Macros -- cgit v1.2.3 From df422e0205a63110094bf8bbe1a839ab52c97abb Mon Sep 17 00:00:00 2001 From: CrossR Date: Fri, 4 Sep 2020 20:45:10 +0100 Subject: Revert changes to Intro page. --- docs/docs/intro.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/docs/intro.md b/docs/docs/intro.md index e20f053..29045f7 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -18,23 +18,21 @@ include: - HID Over GATT (HOG) - This is the official term for BLE HID devices - Keymaps and layers with basic keycodes -- Mod-Tap -- Layer Tap +- Some initial work on one "behavior", Mod-Tap - Basic HID over USB - Basic consumer (media) keycodes. - Basic OLED display logic - Basic Split support -- Basic RGB Underglow - Encoders ## Missing Features - One Shot +- Layer Tap - Complete split support - Battery reporting -- Low power sleep states +- Low power mode - Shell over BLE -- Macros ## Code Of Conduct -- cgit v1.2.3 From 80034c007826a026833d85d4fde7fc9be3898229 Mon Sep 17 00:00:00 2001 From: Richard Jones Date: Sun, 6 Sep 2020 15:51:12 +0100 Subject: Add RoMac / non-split template support --- docs/static/setup.sh | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/static/setup.sh b/docs/static/setup.sh index 70defdf..83e7451 100644 --- a/docs/static/setup.sh +++ b/docs/static/setup.sh @@ -38,7 +38,7 @@ echo "" echo "Keyboard Shield Selection:" prompt="Pick an keyboard:" -options=("Kyria" "Lily58" "Corne" "Splitreus62" "Sofle" "Iris") +options=("Kyria" "Lily58" "Corne" "Splitreus62" "Sofle" "Iris" "RoMac") PS3="$prompt " # TODO: Add support for "Other" and linking to docs on adding custom shields in user config repos. @@ -53,6 +53,7 @@ select opt in "${options[@]}" "Quit"; do 4 ) shield_title="Splitreus62" shield="splitreus62"; split="y"; break;; 5 ) shield_title="Sofle" shield="sofle"; split="y"; break;; 6 ) shield_title="Iris" shield="iris"; split="y"; break;; + 7 ) shield_title="RoMac" shield="romac"; split="n"; break;; # Add link to docs on adding your own custom shield in your ZMK config! # $(( ${#options[@]}+1 )) ) echo "Other!"; break;; @@ -62,6 +63,10 @@ select opt in "${options[@]}" "Quit"; do esac done +if [ "$split" == "n" ]; then + repo_path="https://github.com/bmcgavin/zmk-config-template.git" +fi + read -e -p "Copy in the stock keymap for customization? [Yn]: " copy_keymap if [ -z "$copy_keymap" ] || [ "$copy_keymap" == "Y" ] || [ "$copy_keymap" == "y" ]; then copy_keymap="yes"; fi -- cgit v1.2.3 From 01da54aadfe1ed9027e71754f9d897f68da900ea Mon Sep 17 00:00:00 2001 From: Richard Jones Date: Sun, 6 Sep 2020 17:54:45 +0100 Subject: point setup.sh at upstream --- docs/static/setup.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/static/setup.sh b/docs/static/setup.sh index 83e7451..5d203a4 100644 --- a/docs/static/setup.sh +++ b/docs/static/setup.sh @@ -64,7 +64,7 @@ select opt in "${options[@]}" "Quit"; do done if [ "$split" == "n" ]; then - repo_path="https://github.com/bmcgavin/zmk-config-template.git" + repo_path="https://github.com/zmkfirmware/zmk-config-template.git" fi read -e -p "Copy in the stock keymap for customization? [Yn]: " copy_keymap -- cgit v1.2.3 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