From 9a3d515583997a78b41ab9d2b84e8b56126dda09 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Thu, 1 Oct 2020 15:40:39 -0400 Subject: fix(docs): Link to nice!nano product page itself. --- docs/docs/hardware.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/hardware.md b/docs/docs/hardware.md index 236aa97..faac57c 100644 --- a/docs/docs/hardware.md +++ b/docs/docs/hardware.md @@ -16,7 +16,7 @@ That being said, there are currently only a few specific [boards](/docs/faq#what ## Boards -- [nice!nano](https://docs.nicekeyboards.com/#/nice!nano/) (`nice_nano`) +- [nice!nano](https://nicekeyboards.com/products/nice-nano-v1-0) (`nice_nano`) - [nrfMicro](https://github.com/joric/nrfmicro) (`nrfmicro_13`, `nrfmicro_11`, `nrfmicro_11_flipped`) - [BlueMicro840](https://store.jpconstantineau.com/#/group/bluemicro) (`bluemicro840_v1`) - [QMK Proton-C](https://qmk.fm/proton-c/) (`proton_c`) -- cgit v1.2.3 From dfb4f1277d66b58de5473c46ed04cf3d7c102b30 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Fri, 2 Oct 2020 23:17:53 -0400 Subject: fix(docs): Proper emphasis of MUST NOT. --- docs/docs/dev-clean-room.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-clean-room.md b/docs/docs/dev-clean-room.md index c11171c..2f301ec 100644 --- a/docs/docs/dev-clean-room.md +++ b/docs/docs/dev-clean-room.md @@ -6,7 +6,7 @@ sidebar_label: Clean Room :::warning -Anyone wanting to contribute code to ZMK _must_ read this, and adhere to the steps outlines in order to not violate any licenses/copyright of other projects +Anyone wanting to contribute code to ZMK _MUST_ read this, and adhere to the steps outlines in order to not violate any licenses/copyright of other projects ::: @@ -22,8 +22,8 @@ or duplicating any of the GPL code found in those other projects, even though th Contributors to ZMK must adhere to the following standard. -- Implementations of features for ZMK _MUST_ not reuse any existing code from any projects not licensed with the MIT license. -- Contributors _MUST_ not study or refer to any GPL licensed source code while working on ZMK. +- Implementations of features for ZMK _MUST NOT_ reuse any existing code from any projects not licensed with the MIT license. +- Contributors _MUST NOT_ study or refer to any GPL licensed source code while working on ZMK. - Contributors _MAY_ read the documentation from other GPL licensed projects, to gain a broad understanding of the behavior of certain features in order to implement equivalent features for ZMK. - Contributors _MAY_ refer to the [QMK Configurator](https://config.qmk.fm/) to inspect existing layouts/keymaps for keyboards, and re-implement them for ZMK. -- cgit v1.2.3 From 31e481954f1e22e42bde4b71753e279cdd4c77ed Mon Sep 17 00:00:00 2001 From: Kevin Date: Sun, 4 Oct 2020 17:03:56 -0700 Subject: fix(docs): Fixed Python environment variables and commands for Windows setup --- docs/docs/dev-setup.md | 111 +++++++++++++++++++++++++------------------------ 1 file changed, 57 insertions(+), 54 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 1d7d703..2e232f8 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -12,16 +12,16 @@ groupId="operating-systems" defaultValue="debian" values={[ {label: 'Debian/Ubuntu', value: 'debian'}, -{label: 'Raspberry OS', value: 'raspberryos'}, -{label: 'Fedora', value: 'fedora'}, {label: 'Windows', value: 'win'}, {label: 'macOS', value: 'mac'}, +{label: 'Raspberry OS', value: 'raspberryos'}, +{label: 'Fedora', value: 'fedora'}, ] }>{props.children}); ## Prerequisites -A unix-like environment with the following base packages installed: +ZMK requires the following base packages to first be installed: - Git - Python 3 @@ -34,6 +34,7 @@ A unix-like environment with the following base packages installed: + On Debian and Ubuntu, we'll use `apt` to install our base dependencies: First, if you haven't updated recently, or if this is a new install, @@ -74,7 +75,8 @@ or download and install CMake version 3.13.1 or newer manually. ::: -On Raspberry OS, we'll use apt to install our base dependencies: + +On Raspberry OS, we'll use `apt` to install our base dependencies: First, if you haven't updated recently, or if this is a new install, you should update to get the latest package information: @@ -185,14 +187,39 @@ brew install cmake ninja python3 ccache dtc git wget `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. +West can be installed by using the `pip` python package manager. The [Zephyr™ instructions](https://docs.zephyrproject.org/latest/guides/west/install.html#installing-west) are summarized here: + + + ```sh pip3 install --user -U west ``` -:::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` otherwise your computer will not be able to find the `west` command. + + + +In `cmd.exe` as **Administrator**: + +```sh +pip3 install -U west +``` + +Once `west` is installed, close Command Prompt and open a new session as a **user** for the remainder of the instructions. +:::note +**For Windows, do not use the `--user` argument** that Linux uses otherwise `west` will be installed in a different location and the below instructions for adding Python `pip` will no longer apply. +::: + + + + +:::danger `pip` user packages +If you haven't done so yet, you may need to add the Python `pip` package directory to your `PATH` otherwise your computer will not be able to find the `west` command. ::: 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`. +2. Under "System variables" select the "Path" variable. Click "Edit..." and then "New" to add the directory where your `west.exe` is located. By default this should be `C:\Python##\Scripts` where ## is your Python version number. +3. Close Command Prompt and open a new session for the changes to take effect, or run `refreshenv`. @@ -279,7 +307,7 @@ 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/2.3.0/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded). +Since the Zephyr™ SDK is not available for Windows, we recommending following the [Zephyr documentation](https://docs.zephyrproject.org/2.3.0/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded) to install a GNU ARM Embedded build. Note the warnings regarding installing the toolchain into a path with spaces, and make sure to follow the steps to add the environment variables which are also summarized with screenshots in the [Environment Variables](#environment-variables) section below. @@ -308,7 +336,7 @@ The transient instructions must be run to build firmware using the current shell ### Source Code -Next, you'll need to clone the ZMK source repository if you haven't already: +Next, you'll need to clone the ZMK source repository if you haven't already. Navigate to the folder you would like to place your `zmk` directory in and run the following command: ``` git clone https://github.com/zmkfirmware/zmk.git @@ -358,12 +386,17 @@ pip3 install --user -r zephyr/scripts/requirements-base.txt ### Environment Variables -#### 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`. +#### For GNU ARM Embedded on Windows -
- Steps to Update Environment Variables +On Windows, only two environment variables need to be set for ZMK to build properly: `ZEPHYR_TOOLCHAIN_VARIANT` and `GNUARMEMB_TOOLCHAIN_PATH`. 1. Open Start Menu and type 'env' to find the 'Edit the system environment variables' option. Open it. @@ -381,11 +414,15 @@ On Windows, you will have to set two environment variables for ZMK to build prop ![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. +5. Create another variable with variable name 'GNUARMEMB_TOOLCHAIN_PATH' and value set to wherever you installed your toolchain. **Make sure this path does not contain any spaces.** If it does, rename the folder and update here. Click OK to save. ![Adding GNUARMEMB variable](assets/env-var/gnuarmemb.png) -
+6. Close Command Prompt and reopen, or run `refreshenv` to apply the changes. + + + + #### For Zephyr @@ -396,48 +433,10 @@ We suggest two main [options](https://docs.zephyrproject.org/2.3.0/guides/env_va To load the Zephyr environment properly for just one transient shell, run the following from your ZMK checkout directory: - - - -``` -source zephyr/zephyr-env.sh -``` - - - - - -``` -source zephyr/zephyr-env.sh -``` - - - - - ``` source zephyr/zephyr-env.sh ``` - - - - -``` -source zephyr/zephyr-env.sh -``` - - - - - -``` -source zephyr/zephyr-env.cmd -``` - - - - ##### All Shells To load the environment variables for your shell every time, @@ -469,3 +468,7 @@ cat ~/.zephyrrc >> ~/.zshrc + + + + -- cgit v1.2.3 From 6427e64df3e889325ea471ff98f185f5eee27027 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sun, 4 Oct 2020 17:10:34 -0700 Subject: fix(docs): Reorganized section in Windows setup --- docs/docs/dev-setup.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 2e232f8..4891f5a 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -210,11 +210,12 @@ In `cmd.exe` as **Administrator**: pip3 install -U west ``` -Once `west` is installed, close Command Prompt and open a new session as a **user** for the remainder of the instructions. :::note **For Windows, do not use the `--user` argument** that Linux uses otherwise `west` will be installed in a different location and the below instructions for adding Python `pip` will no longer apply. ::: +Once `west` is installed, close Command Prompt and open a new session as a **user** for the remainder of the instructions. + -- cgit v1.2.3 From 4de7cc45de18f791ecbb361bfc2330a45e97d79e Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Mon, 5 Oct 2020 09:43:05 -0400 Subject: feat(setup): Add M.2 and M60 to setup scripts. --- docs/static/setup.ps1 | 10 +++++----- docs/static/setup.sh | 6 ++++-- 2 files changed, 9 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/static/setup.ps1 b/docs/static/setup.ps1 index 3946e66..dc7b18c 100644 --- a/docs/static/setup.ps1 +++ b/docs/static/setup.ps1 @@ -63,8 +63,8 @@ $repo_path = "https://github.com/zmkfirmware/zmk-config-split-template.git" $title = "ZMK Config Setup:" $prompt = "Pick an MCU board" -$options = "nice!nano", "QMK Proton-C", "BlueMicro840 (v1)" -$boards = "nice_nano", "proton_c", "bluemicro840_v1" +$options = "nice!nano", "QMK Proton-C", "BlueMicro840 (v1)", "makerdiary nRF52840 M.2" +$boards = "nice_nano", "proton_c", "bluemicro840_v1", "nrf52840_m2" Write-Host "$title" Write-Host "" @@ -78,9 +78,9 @@ Write-Host "Keyboard Shield Selection:" $prompt = "Pick a keyboard" # TODO: Add support for "Other" and linking to docs on adding custom shields in user config repos. -$options = "Kyria", "Lily58", "Corne", "Splitreus62", "Sofle", "Iris", "RoMac" -$names = "kyria", "lily58", "corne", "splitreus62", "sofle", "iris", "romac" -$splits = "y", "y", "y", "y", "y", "y", "n" +$options = "Kyria", "Lily58", "Corne", "Splitreus62", "Sofle", "Iris", "RoMac", "makerdiary M60" +$names = "kyria", "lily58", "corne", "splitreus62", "sofle", "iris", "romac", "m60" +$splits = "y", "y", "y", "y", "y", "y", "n", "n" $choice = Get-Choice-From-Options -Options $options -Prompt $prompt $shield_title = $($options[$choice]) diff --git a/docs/static/setup.sh b/docs/static/setup.sh index 5bf3645..9e98964 100644 --- a/docs/static/setup.sh +++ b/docs/static/setup.sh @@ -26,7 +26,7 @@ repo_path="https://github.com/zmkfirmware/zmk-config-split-template.git" title="ZMK Config Setup:" prompt="Pick an MCU board:" -options=("nice!nano" "QMK Proton-C" "BlueMicro840 (v1)") +options=("nice!nano" "QMK Proton-C" "BlueMicro840 (v1)" "makerdiary nRF52840 M.2") echo "$title" echo "" @@ -39,6 +39,7 @@ select opt in "${options[@]}" "Quit"; do 1 ) board="nice_nano"; break;; 2 ) board="proton_c"; break;; 3 ) board="bluemicro840_v1"; break;; + 3 ) board="nrf52840_m2"; break;; $(( ${#options[@]}+1 )) ) echo "Goodbye!"; exit 1;; *) echo "Invalid option. Try another one."; continue;; @@ -50,7 +51,7 @@ echo "" echo "Keyboard Shield Selection:" prompt="Pick an keyboard:" -options=("Kyria" "Lily58" "Corne" "Splitreus62" "Sofle" "Iris" "RoMac") +options=("Kyria" "Lily58" "Corne" "Splitreus62" "Sofle" "Iris" "RoMac" "makerdiary M60") PS3="$prompt " # TODO: Add support for "Other" and linking to docs on adding custom shields in user config repos. @@ -66,6 +67,7 @@ select opt in "${options[@]}" "Quit"; do 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;; + 7 ) shield_title="M60" shield="m60"; split="n"; 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 2300ce306afadebd5f1987acf8ded6ac228f68e8 Mon Sep 17 00:00:00 2001 From: Ben Huddleston <40238853+BenHuddleston@users.noreply.github.com> Date: Wed, 7 Oct 2020 22:25:21 +0100 Subject: Correct typo in previous profile behaviour binding in bluetooth.md --- docs/docs/behavior/bluetooth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/behavior/bluetooth.md b/docs/docs/behavior/bluetooth.md index f802a9a..8bde71b 100644 --- a/docs/docs/behavior/bluetooth.md +++ b/docs/docs/behavior/bluetooth.md @@ -66,7 +66,7 @@ The bluetooth behavior completes an bluetooth action given on press. 1. Behavior binding to select the previous profile: ``` - &bt BT_NXT + &bt BT_PRV ``` 1. Behavior binding to select the 2nd profile (passed parameters are [zero based](https://en.wikipedia.org/wiki/Zero-based_numbering)): -- cgit v1.2.3 From a8d48b043d0913e2f4e15d34547989d78b1b8088 Mon Sep 17 00:00:00 2001 From: Tyler Walker Date: Thu, 8 Oct 2020 18:42:55 -0400 Subject: add benign uf2 transfer error for macOS to troubleshooting --- docs/docs/assets/troubleshooting/filetransfer/mac.png | Bin 0 -> 26499 bytes docs/docs/troubleshooting.md | 4 ++++ 2 files changed, 4 insertions(+) create mode 100644 docs/docs/assets/troubleshooting/filetransfer/mac.png (limited to 'docs') diff --git a/docs/docs/assets/troubleshooting/filetransfer/mac.png b/docs/docs/assets/troubleshooting/filetransfer/mac.png new file mode 100644 index 0000000..f28ca8d Binary files /dev/null and b/docs/docs/assets/troubleshooting/filetransfer/mac.png differ diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md index deb89b6..2e5e989 100644 --- a/docs/docs/troubleshooting.md +++ b/docs/docs/troubleshooting.md @@ -19,6 +19,10 @@ Variations of the warnings shown below occur when flashing the `.uf2` | :-------------------------------------------------------------------------------: | | An example of the file transfer error on Linux | +| ![Example Error Screen](../docs/assets/troubleshooting/filetransfer/mac.png) | +| :-------------------------------------------------------------------------------: | +| An example of the file transfer error on MacOS | + ### CMake Error -- cgit v1.2.3 From ea05df029086a47d0b0e33fe882801009e3b6872 Mon Sep 17 00:00:00 2001 From: Kevin Date: Thu, 8 Oct 2020 21:44:32 -0700 Subject: docs: Added link to clarify where to add sensor-bindings code --- docs/docs/dev-guide-new-shield.md | 10 +++++++--- docs/docs/feature/encoders.md | 2 +- 2 files changed, 8 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index 01aad30..1ba572c 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -238,7 +238,6 @@ If building locally for split boards, you may need to add these lines to the spe 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"; @@ -248,6 +247,7 @@ left_encoder: encoder_left { 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. @@ -279,12 +279,15 @@ For split keyboards, make sure to add left hand encoders to the left .overlay fi -Add the following line to your keymap file to add default encoder behavior bindings: +Add the following line to each layer of 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. + +This should be placed after the regular key bindings but within the layer (see the [Default Keymap section](/docs/dev-guide-new-shield#default-keymap) above for an example of where). + +Add additional bindings as necessary to match the default number of encoders on your board. Details on the syntax can be found in the [Encoders](/docs/feature/encoders) and [Keymap](/docs/feature/keymaps) feature documentation. @@ -333,6 +336,7 @@ jobs: - board: proton_c shield: clueboard_california ``` + :::note Notice that both the left and right halves of a split board need to be added to the list of shields for proper error checking. :::note diff --git a/docs/docs/feature/encoders.md b/docs/docs/feature/encoders.md index 38ff9d3..9caccc2 100644 --- a/docs/docs/feature/encoders.md +++ b/docs/docs/feature/encoders.md @@ -41,4 +41,4 @@ Here, the left encoder is configured to control volume up and down while the rig ## Adding Encoder Support -See the [New Keyboard Shield](/docs/dev-guide-new-shield) documentation for how to add or modify additional encoders to your shield. +See the [New Keyboard Shield](/docs/dev-guide-new-shield#encoders) documentation for how to add or modify additional encoders to your shield. -- cgit v1.2.3 From a9ec1148e50ff0601f82c9eb55b90c33e7c70dab Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Thu, 8 Oct 2020 22:16:53 -0700 Subject: Added -DZMK_CONFIG Documentation --- docs/docs/dev-build.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'docs') diff --git a/docs/docs/dev-build.md b/docs/docs/dev-build.md index 816468e..a7c1cd9 100644 --- a/docs/docs/dev-build.md +++ b/docs/docs/dev-build.md @@ -84,6 +84,19 @@ west build -d build/right -b nice_nano -- -DSHIELD=kyria_right ``` This produces `left` and `right` subfolders under the `build` directory and two separate .uf2 files. For future work on a specific half, use the `-d` parameter again to ensure you are building into the correct location. +### Building from `zmk-config` Folder + +Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](user-setup.md) by adding +`-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build` command. **Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.** + + +For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this: + +``` +west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config" +``` + + ## Flashing Once built, the previously supplied parameters will be remembered so you can run the following to flash your -- cgit v1.2.3 From 49315c2f6df6c17966dafa5a97668774a6a65bb0 Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Thu, 8 Oct 2020 22:18:53 -0700 Subject: Addressing Issue #181 --- docs/docs/dev-guide-new-shield.md | 135 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) (limited to 'docs') diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index 01aad30..ee48915 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -21,6 +21,10 @@ The high level steps are: It may be helpful to review the upstream [shields documentation](https://docs.zephyrproject.org/2.3.0/guides/porting/shields.html#shields) to get a proper understanding of the underlying system before continuing. +:::note +ZMK support for split keyboards requires a few more files than single boards to ensure proper connectivity between the central and peripheral units. Check the following guides thoroughly to ensure that all the files are in place. +::: + ## New Shield Directory Shields for Zephyr applications go into the `boards/shields/` directory; since ZMK's Zephyr application lives in the `app/` subdirectory of the repository, that means the new shield directory should be: @@ -45,6 +49,16 @@ config SHIELD_MY_BOARD This will make sure the new configuration `SHIELD_MY_BOARD` is set to true whenever `my_board` is added as a shield in your build. + +**For split boards**, you will need to add configurations for the left and right sides. +``` +config SHIELD_MY_BOARD_LEFT + def_bool $(shields_list_contains,my_board_left) + +config SHIELD_MY_BOARD_RIGHT + def_bool $(shields_list_contains,my_board_right) +``` + ### Kconfig.defconfig The `Kconfig.defconfig` file is where overrides for various configuration settings @@ -63,6 +77,26 @@ config ZMK_KEYBOARD_NAME endif ``` + +Similarly to defining the halves of a split board in `Kconfig.shield` it is important to set the `ZMK_KEYBOARD_NAME` for each half of a split keyboard. + +``` +if SHIELD_MY_BOARD_LEFT + +config ZMK_KEYBOARD_NAME + default "My Awesome Keyboard Left" + +endif + +if SHIELD_MY_BOARD_RIGHT + +config ZMK_KEYBOARD_NAME + default "My Awesome Keyboard Right" + +endif +``` + + ## Shield Overlay ![Labelled Pro Micro pins](assets/pro-micro/pro-micro-pins-labelled.jpg) @@ -98,6 +132,74 @@ this might look something like: }; ``` +:::note +For split keyboards, it is preferred to define only the `col-gpios` or `row-gpios` in the common shield .dtsi, depending on the diode-direction. +For `col2row` directed boards like the iris, a sample kscan in the .dtsi folder would look like this: + +``` +kscan0: kscan { + compatible = "zmk,kscan-gpio-matrix"; + label = "KSCAN"; + + diode-direction = "col2row"; + row-gpios + = <&pro_micro_d 6 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&pro_micro_d 7 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&pro_micro_d 8 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&pro_micro_d 0 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&pro_micro_d 4 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + ; + + }; +``` + +The missing `col-gpios` would be defined in your `_left.overlay` and `_right.overlay` files. +Keep in mind that the mirrored position of the GPIOs means that the `col-gpios` will appear reversed when the .overlay files are compared to one another. +This is exemplified with the iris .overlay files. + +``` +// iris_left.overlay + +#include "iris.dtsi" // Notice that the main dtsi files are included in the overlay. + +&kscan0 { + col-gpios + = <&pro_micro_a 1 GPIO_ACTIVE_HIGH> + , <&pro_micro_a 0 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 15 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 14 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 16 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 10 GPIO_ACTIVE_HIGH> + ; +}; +``` + +``` +// iris_right.overlay + +#include "iris.dtsi" + +&default_transform { // The matrix transform for this board is 6 columns over because the matrix on the left side is 6 columns wide. + col-offset = <6>; +}; + +&kscan0 { + col-gpios + = <&pro_micro_d 10 GPIO_ACTIVE_HIGH> //&pro_micro_a 1 in the left side + , <&pro_micro_d 16 GPIO_ACTIVE_HIGH> //&pro_micro_a 0 in the left side + , <&pro_micro_d 14 GPIO_ACTIVE_HIGH> //&pro_micro_d 15 in the left side + , <&pro_micro_d 15 GPIO_ACTIVE_HIGH> //&pro_micro_d 14 in the left side + , <&pro_micro_a 0 GPIO_ACTIVE_HIGH> //&pro_micro_d 16 in the left side + , <&pro_micro_a 1 GPIO_ACTIVE_HIGH> //&pro_micro_d 10 in the left side + ; +}; + +``` + +Split keyboards, will often use [Matrix Transform](#optional-matrix-transform) to account for their thumb clusters and other oddities. + +::: + ## (Optional) Matrix Transform Internally ZMK translates all row/column events into "key position" events to maintain a consistent model that works no matter what any possible GPIO matrix may look like for a certain keyboard. This is particularly helpful when: @@ -289,6 +391,39 @@ Add additional bindings as necessary to match the default number of encoders on +## (Split Keyboards Only) .conf files + +While normal boards only have one .conf file that applies configuration characteristics to the entire board, split keyboards are unique in that they contain multiple .conf files +with different scopes. For example, a split board called `my_awesome_split_board` would have the following files: + +* `my_awesome_split_board.conf` - Configuration elements affect both halves +* `my_awesome_split_board_left.conf` - Configuration elements only affect left half +* `my_awesome_split_board_right.conf` - Configuration elements only affect right half + +The discrete .conf files for each half allows the user to define the central and peripheral sides of the split, like so: + +``` +// Central Half + +CONFIG_ZMK_SPLIT=y +CONFIG_ZMK_SPLIT_BLE_ROLE_CENTRAL=y +``` + +``` +// Peripheral Half + +CONFIG_ZMK_SPLIT=y +CONFIG_ZMK_SPLIT_BLE_ROLE_Peripheral=y +``` + +Using the .conf file that affects both halves of a split board would be for circumstances like deep-sleep or _. + +``` +// Global .conf + +CONFIG_ZMK_SLEEP=y +``` + ## Testing Once you've fully created the new keyboard shield definition, -- cgit v1.2.3 From dbda99a3788fb27d258a7c5b9c8f56638f190d65 Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Thu, 8 Oct 2020 22:19:26 -0700 Subject: Addressed Issue #181 --- docs/docs/dev-guide-new-shield.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index ee48915..b8f1a19 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -403,14 +403,14 @@ with different scopes. For example, a split board called `my_awesome_split_board The discrete .conf files for each half allows the user to define the central and peripheral sides of the split, like so: ``` -// Central Half +// Central Half (Usually the left side: my_awesome_split_board_left.conf) CONFIG_ZMK_SPLIT=y CONFIG_ZMK_SPLIT_BLE_ROLE_CENTRAL=y ``` ``` -// Peripheral Half +// Peripheral Half (Usually the right side: my_awesome_split_board_right.conf) CONFIG_ZMK_SPLIT=y CONFIG_ZMK_SPLIT_BLE_ROLE_Peripheral=y @@ -419,7 +419,7 @@ CONFIG_ZMK_SPLIT_BLE_ROLE_Peripheral=y Using the .conf file that affects both halves of a split board would be for circumstances like deep-sleep or _. ``` -// Global .conf +// my_awesome_split_board.conf CONFIG_ZMK_SLEEP=y ``` -- cgit v1.2.3 From c27d3c66f150a0adfa19a2dd6c2bd64544c261a7 Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Thu, 8 Oct 2020 22:21:49 -0700 Subject: Removed blank space --- 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 b8f1a19..9c0a265 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -416,7 +416,7 @@ CONFIG_ZMK_SPLIT=y CONFIG_ZMK_SPLIT_BLE_ROLE_Peripheral=y ``` -Using the .conf file that affects both halves of a split board would be for circumstances like deep-sleep or _. +Using the .conf file that affects both halves of a split board would be for circumstances like deep-sleep. ``` // my_awesome_split_board.conf -- cgit v1.2.3 From a58a8412c7335df27077cc9647444f014b6a094e Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Fri, 9 Oct 2020 08:15:38 -0700 Subject: Documented Issue #220 --- docs/docs/bond-reset.md | 4 ++-- docs/docs/troubleshooting.md | 13 +++++++++++++ docs/sidebars.js | 1 - 3 files changed, 15 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/docs/bond-reset.md b/docs/docs/bond-reset.md index 1ba79ee..504fd72 100644 --- a/docs/docs/bond-reset.md +++ b/docs/docs/bond-reset.md @@ -1,7 +1,7 @@ --- id: bond-reset -title: Reset BLE Connections -sidebar_label: BLE Reset +title: Reset BLE Connections (DEPRECATED) +sidebar_label: BLE Reset (DEPRECATED) --- Known as a 'bond reset', each keyboard has a special key combination independent of the user defined key map which will diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md index deb89b6..8dd1261 100644 --- a/docs/docs/troubleshooting.md +++ b/docs/docs/troubleshooting.md @@ -59,3 +59,16 @@ 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)| + +### Split Keyboard Halves Unable to Pair + +The previous method of pairing split keyboard halves involved a **BLE Reset** with a specific combination of held keys that would remove all bluetooth profile information from the keyboard. +Since then, a much simpler procedure of performing a bluetooth reset for split keyboards has come about, without the need for any file modification: + +1. Log into Github and download the "settings clear" UF2 image from latest GH actions from the `main` of ZMK +1. Put both sides into bootloader mode +1. Flash both sides with the "settings clear" UF2 images from step 1. After, put both sides into bootloader mode again. +1. Flash the actual image for each half of the split keyboard + +After completing these steps, pair the halves of the split keyboard together by resetting them at the same time. Most commonly, this is done by grounding the reset pins +for each of your keyboard's microcontrollers or pressing the reset buttons at the same time. \ No newline at end of file diff --git a/docs/sidebars.js b/docs/sidebars.js index ace7fa1..93ce226 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -6,7 +6,6 @@ module.exports = { "faq", "user-setup", "customization", - "bond-reset", "troubleshooting" ], Features: [ -- cgit v1.2.3 From aca801d90ffcc12076244626dc0d4b239df25ab4 Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Fri, 9 Oct 2020 08:19:08 -0700 Subject: Revert "Removed blank space" This reverts commit c27d3c66f150a0adfa19a2dd6c2bd64544c261a7. --- 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 9c0a265..b8f1a19 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -416,7 +416,7 @@ CONFIG_ZMK_SPLIT=y CONFIG_ZMK_SPLIT_BLE_ROLE_Peripheral=y ``` -Using the .conf file that affects both halves of a split board would be for circumstances like deep-sleep. +Using the .conf file that affects both halves of a split board would be for circumstances like deep-sleep or _. ``` // my_awesome_split_board.conf -- cgit v1.2.3 From 429c9dc464c38bb0604a3ebe55151b451580d8ca Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Fri, 9 Oct 2020 08:19:40 -0700 Subject: Revert "Addressed Issue #181" This reverts commit dbda99a3788fb27d258a7c5b9c8f56638f190d65. --- docs/docs/dev-guide-new-shield.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index b8f1a19..ee48915 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -403,14 +403,14 @@ with different scopes. For example, a split board called `my_awesome_split_board The discrete .conf files for each half allows the user to define the central and peripheral sides of the split, like so: ``` -// Central Half (Usually the left side: my_awesome_split_board_left.conf) +// Central Half CONFIG_ZMK_SPLIT=y CONFIG_ZMK_SPLIT_BLE_ROLE_CENTRAL=y ``` ``` -// Peripheral Half (Usually the right side: my_awesome_split_board_right.conf) +// Peripheral Half CONFIG_ZMK_SPLIT=y CONFIG_ZMK_SPLIT_BLE_ROLE_Peripheral=y @@ -419,7 +419,7 @@ CONFIG_ZMK_SPLIT_BLE_ROLE_Peripheral=y Using the .conf file that affects both halves of a split board would be for circumstances like deep-sleep or _. ``` -// my_awesome_split_board.conf +// Global .conf CONFIG_ZMK_SLEEP=y ``` -- cgit v1.2.3 From e03b51fe2ea5dfbedcc7747ac64899b5d0999a04 Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Fri, 9 Oct 2020 08:19:46 -0700 Subject: Revert "Addressing Issue #181" This reverts commit 49315c2f6df6c17966dafa5a97668774a6a65bb0. --- docs/docs/dev-guide-new-shield.md | 135 -------------------------------------- 1 file changed, 135 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index ee48915..01aad30 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -21,10 +21,6 @@ The high level steps are: It may be helpful to review the upstream [shields documentation](https://docs.zephyrproject.org/2.3.0/guides/porting/shields.html#shields) to get a proper understanding of the underlying system before continuing. -:::note -ZMK support for split keyboards requires a few more files than single boards to ensure proper connectivity between the central and peripheral units. Check the following guides thoroughly to ensure that all the files are in place. -::: - ## New Shield Directory Shields for Zephyr applications go into the `boards/shields/` directory; since ZMK's Zephyr application lives in the `app/` subdirectory of the repository, that means the new shield directory should be: @@ -49,16 +45,6 @@ config SHIELD_MY_BOARD This will make sure the new configuration `SHIELD_MY_BOARD` is set to true whenever `my_board` is added as a shield in your build. - -**For split boards**, you will need to add configurations for the left and right sides. -``` -config SHIELD_MY_BOARD_LEFT - def_bool $(shields_list_contains,my_board_left) - -config SHIELD_MY_BOARD_RIGHT - def_bool $(shields_list_contains,my_board_right) -``` - ### Kconfig.defconfig The `Kconfig.defconfig` file is where overrides for various configuration settings @@ -77,26 +63,6 @@ config ZMK_KEYBOARD_NAME endif ``` - -Similarly to defining the halves of a split board in `Kconfig.shield` it is important to set the `ZMK_KEYBOARD_NAME` for each half of a split keyboard. - -``` -if SHIELD_MY_BOARD_LEFT - -config ZMK_KEYBOARD_NAME - default "My Awesome Keyboard Left" - -endif - -if SHIELD_MY_BOARD_RIGHT - -config ZMK_KEYBOARD_NAME - default "My Awesome Keyboard Right" - -endif -``` - - ## Shield Overlay ![Labelled Pro Micro pins](assets/pro-micro/pro-micro-pins-labelled.jpg) @@ -132,74 +98,6 @@ this might look something like: }; ``` -:::note -For split keyboards, it is preferred to define only the `col-gpios` or `row-gpios` in the common shield .dtsi, depending on the diode-direction. -For `col2row` directed boards like the iris, a sample kscan in the .dtsi folder would look like this: - -``` -kscan0: kscan { - compatible = "zmk,kscan-gpio-matrix"; - label = "KSCAN"; - - diode-direction = "col2row"; - row-gpios - = <&pro_micro_d 6 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> - , <&pro_micro_d 7 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> - , <&pro_micro_d 8 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> - , <&pro_micro_d 0 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> - , <&pro_micro_d 4 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> - ; - - }; -``` - -The missing `col-gpios` would be defined in your `_left.overlay` and `_right.overlay` files. -Keep in mind that the mirrored position of the GPIOs means that the `col-gpios` will appear reversed when the .overlay files are compared to one another. -This is exemplified with the iris .overlay files. - -``` -// iris_left.overlay - -#include "iris.dtsi" // Notice that the main dtsi files are included in the overlay. - -&kscan0 { - col-gpios - = <&pro_micro_a 1 GPIO_ACTIVE_HIGH> - , <&pro_micro_a 0 GPIO_ACTIVE_HIGH> - , <&pro_micro_d 15 GPIO_ACTIVE_HIGH> - , <&pro_micro_d 14 GPIO_ACTIVE_HIGH> - , <&pro_micro_d 16 GPIO_ACTIVE_HIGH> - , <&pro_micro_d 10 GPIO_ACTIVE_HIGH> - ; -}; -``` - -``` -// iris_right.overlay - -#include "iris.dtsi" - -&default_transform { // The matrix transform for this board is 6 columns over because the matrix on the left side is 6 columns wide. - col-offset = <6>; -}; - -&kscan0 { - col-gpios - = <&pro_micro_d 10 GPIO_ACTIVE_HIGH> //&pro_micro_a 1 in the left side - , <&pro_micro_d 16 GPIO_ACTIVE_HIGH> //&pro_micro_a 0 in the left side - , <&pro_micro_d 14 GPIO_ACTIVE_HIGH> //&pro_micro_d 15 in the left side - , <&pro_micro_d 15 GPIO_ACTIVE_HIGH> //&pro_micro_d 14 in the left side - , <&pro_micro_a 0 GPIO_ACTIVE_HIGH> //&pro_micro_d 16 in the left side - , <&pro_micro_a 1 GPIO_ACTIVE_HIGH> //&pro_micro_d 10 in the left side - ; -}; - -``` - -Split keyboards, will often use [Matrix Transform](#optional-matrix-transform) to account for their thumb clusters and other oddities. - -::: - ## (Optional) Matrix Transform Internally ZMK translates all row/column events into "key position" events to maintain a consistent model that works no matter what any possible GPIO matrix may look like for a certain keyboard. This is particularly helpful when: @@ -391,39 +289,6 @@ Add additional bindings as necessary to match the default number of encoders on -## (Split Keyboards Only) .conf files - -While normal boards only have one .conf file that applies configuration characteristics to the entire board, split keyboards are unique in that they contain multiple .conf files -with different scopes. For example, a split board called `my_awesome_split_board` would have the following files: - -* `my_awesome_split_board.conf` - Configuration elements affect both halves -* `my_awesome_split_board_left.conf` - Configuration elements only affect left half -* `my_awesome_split_board_right.conf` - Configuration elements only affect right half - -The discrete .conf files for each half allows the user to define the central and peripheral sides of the split, like so: - -``` -// Central Half - -CONFIG_ZMK_SPLIT=y -CONFIG_ZMK_SPLIT_BLE_ROLE_CENTRAL=y -``` - -``` -// Peripheral Half - -CONFIG_ZMK_SPLIT=y -CONFIG_ZMK_SPLIT_BLE_ROLE_Peripheral=y -``` - -Using the .conf file that affects both halves of a split board would be for circumstances like deep-sleep or _. - -``` -// Global .conf - -CONFIG_ZMK_SLEEP=y -``` - ## Testing Once you've fully created the new keyboard shield definition, -- cgit v1.2.3 From 7128808bbafd198a2d3b7275a9a029d4a58d5bc6 Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Fri, 9 Oct 2020 08:19:50 -0700 Subject: Revert "Added -DZMK_CONFIG Documentation" This reverts commit a9ec1148e50ff0601f82c9eb55b90c33e7c70dab. --- docs/docs/dev-build.md | 13 ------------- 1 file changed, 13 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-build.md b/docs/docs/dev-build.md index a7c1cd9..816468e 100644 --- a/docs/docs/dev-build.md +++ b/docs/docs/dev-build.md @@ -84,19 +84,6 @@ west build -d build/right -b nice_nano -- -DSHIELD=kyria_right ``` This produces `left` and `right` subfolders under the `build` directory and two separate .uf2 files. For future work on a specific half, use the `-d` parameter again to ensure you are building into the correct location. -### Building from `zmk-config` Folder - -Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](user-setup.md) by adding -`-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build` command. **Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.** - - -For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this: - -``` -west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config" -``` - - ## Flashing Once built, the previously supplied parameters will be remembered so you can run the following to flash your -- cgit v1.2.3 From e53320a687a8b402fac3ed972a776993495a2f9a Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Fri, 9 Oct 2020 11:57:34 -0400 Subject: fix(docs): Remove hanging footnote. --- docs/docs/behavior/bluetooth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/behavior/bluetooth.md b/docs/docs/behavior/bluetooth.md index 8bde71b..be0fb23 100644 --- a/docs/docs/behavior/bluetooth.md +++ b/docs/docs/behavior/bluetooth.md @@ -24,7 +24,7 @@ Here is a table describing the command for each define: | Define | Action | | ------------ | ---------------------------------------------------------------------------------------------- | -| `BT_CLR_CMD` | Clear bond information between the keyboard and host for the selected profile [^1] | +| `BT_CLR_CMD` | Clear bond information between the keyboard and host for the selected profile. | | `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. | -- cgit v1.2.3 From 81a4ffef7efb45f30c74802dca97d949312a1785 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Fri, 9 Oct 2020 15:44:39 -0400 Subject: feat(setup): Add Microdox to setup scripts. --- docs/static/setup.ps1 | 6 +++--- docs/static/setup.sh | 5 +++-- 2 files changed, 6 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/static/setup.ps1 b/docs/static/setup.ps1 index dc7b18c..abdb698 100644 --- a/docs/static/setup.ps1 +++ b/docs/static/setup.ps1 @@ -78,9 +78,9 @@ Write-Host "Keyboard Shield Selection:" $prompt = "Pick a keyboard" # TODO: Add support for "Other" and linking to docs on adding custom shields in user config repos. -$options = "Kyria", "Lily58", "Corne", "Splitreus62", "Sofle", "Iris", "RoMac", "makerdiary M60" -$names = "kyria", "lily58", "corne", "splitreus62", "sofle", "iris", "romac", "m60" -$splits = "y", "y", "y", "y", "y", "y", "n", "n" +$options = "Kyria", "Lily58", "Corne", "Splitreus62", "Sofle", "Iris", "RoMac", "makerdiary M60", "Microdox" +$names = "kyria", "lily58", "corne", "splitreus62", "sofle", "iris", "romac", "m60", "microdox" +$splits = "y", "y", "y", "y", "y", "y", "n", "n", "y" $choice = Get-Choice-From-Options -Options $options -Prompt $prompt $shield_title = $($options[$choice]) diff --git a/docs/static/setup.sh b/docs/static/setup.sh index 9e98964..49ed3eb 100644 --- a/docs/static/setup.sh +++ b/docs/static/setup.sh @@ -51,7 +51,7 @@ echo "" echo "Keyboard Shield Selection:" prompt="Pick an keyboard:" -options=("Kyria" "Lily58" "Corne" "Splitreus62" "Sofle" "Iris" "RoMac" "makerdiary M60") +options=("Kyria" "Lily58" "Corne" "Splitreus62" "Sofle" "Iris" "RoMac" "makerdiary M60" "Microdox") PS3="$prompt " # TODO: Add support for "Other" and linking to docs on adding custom shields in user config repos. @@ -67,7 +67,8 @@ select opt in "${options[@]}" "Quit"; do 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;; - 7 ) shield_title="M60" shield="m60"; split="n"; break;; + 8 ) shield_title="M60" shield="m60"; split="n"; break;; + 9 ) shield_title="Microdox" shield="microdox"; 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 1f2bdf639f3790ef6d36575c4a477d340b9fd393 Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Fri, 9 Oct 2020 12:57:07 -0700 Subject: Adjusted Wording, Added link to GH Actions --- docs/docs/troubleshooting.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md index 8dd1261..7395ff5 100644 --- a/docs/docs/troubleshooting.md +++ b/docs/docs/troubleshooting.md @@ -62,13 +62,17 @@ After opening the `.dts.pre.tmp:` and scrolling down to the ### Split Keyboard Halves Unable to Pair -The previous method of pairing split keyboard halves involved a **BLE Reset** with a specific combination of held keys that would remove all bluetooth profile information from the keyboard. +Previously, pairing split keyboard halves involved a **BLE Reset** via a combination of held keys that removed all bluetooth profile information from the keyboard. Since then, a much simpler procedure of performing a bluetooth reset for split keyboards has come about, without the need for any file modification: -1. Log into Github and download the "settings clear" UF2 image from latest GH actions from the `main` of ZMK -1. Put both sides into bootloader mode -1. Flash both sides with the "settings clear" UF2 images from step 1. After, put both sides into bootloader mode again. -1. Flash the actual image for each half of the split keyboard +**New Procedure:** + +1. Log into Github and download the "settings clear" UF2 image from the [latest build in Github Actions](https://github.com/zmkfirmware/zmk/actions?query=workflow%3ABuild+branch%3Amain) +1. Put each half of the split keyboard into bootloader mode +1. Flash one of the halves of the split with the "settings clear" UF2 image from step 1. Immediately after flashing "settings clear" to the chosen half, immediately put it into bootloader mode +to avoid accidental bonding between the halves. +1. Repeat step 3 with the other half of the split keyboard +1. Flash the actual image for each half of the split keyboard (e.g `my_board_left.uf2` to the left half, `my_board_right.uf2` to the right half) After completing these steps, pair the halves of the split keyboard together by resetting them at the same time. Most commonly, this is done by grounding the reset pins for each of your keyboard's microcontrollers or pressing the reset buttons at the same time. \ No newline at end of file -- cgit v1.2.3 From 15614a946fac635a27ba94a4f32450c67016e5b2 Mon Sep 17 00:00:00 2001 From: Idan Gazit Date: Thu, 1 Oct 2020 00:41:33 -0700 Subject: WIP docs for docker development --- docs/docs/dev-setup.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'docs') diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 4891f5a..be3d6f9 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -16,6 +16,7 @@ values={[ {label: 'macOS', value: 'mac'}, {label: 'Raspberry OS', value: 'raspberryos'}, {label: 'Fedora', value: 'fedora'}, +{label: 'VS Code & Docker', value: 'docker'}, ] }>{props.children}); @@ -178,6 +179,20 @@ Homebrew is required to install the system dependencies. If you haven't done so, brew install cmake ninja python3 ccache dtc git wget ``` + + + +This setup leverages the same [image which is used by the GitHub action](https://github.com/zmkfirmware/zephyr-west-action) for local development. Beyond the benefits of [dev/prod parity](https://12factor.net/dev-prod-parity), this approach is also the easiest to set up. No toolchain or dependencies are necessary when using Docker; the container image you'll be using already has the toolchain installed and set up to use. + + +1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system. +2. Install [VS Code](https://code.visualstudio.com/) +3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) + +:::info +The docker container includes `west` and the compilation toolchain. If you're using docker and VS Code, you can skip right to [Source Code](#source-code). +::: + @@ -323,6 +338,11 @@ Please be sure to read the [additional setup instructions](https://docs.zephyrpr ::: + + + +You're already set up: the toolchain is installed and configured inside the docker container. + -- cgit v1.2.3 From 5c00c97e9a1647e2676586c303d19c5559e2e2f1 Mon Sep 17 00:00:00 2001 From: Idan Gazit Date: Fri, 9 Oct 2020 18:48:41 -0700 Subject: Wrap up documentation --- docs/docs/assets/dev-setup/vscode_devcontainer.png | Bin 0 -> 20773 bytes docs/docs/dev-setup.md | 62 +++++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 docs/docs/assets/dev-setup/vscode_devcontainer.png (limited to 'docs') diff --git a/docs/docs/assets/dev-setup/vscode_devcontainer.png b/docs/docs/assets/dev-setup/vscode_devcontainer.png new file mode 100644 index 0000000..e5c22b0 Binary files /dev/null and b/docs/docs/assets/dev-setup/vscode_devcontainer.png differ diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index be3d6f9..6ef0f02 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -369,12 +369,63 @@ Since ZMK is built as a Zephyr™ application, the next step is to use `west` to initialize and update your workspace. The ZMK Zephyr™ application is in the `app/` source directory: + #### Step into the repository + + + +```sh +cd zmk +``` + + + + +```sh +cd zmk +``` + + + + +```sh +cd zmk +``` + + + + +```sh +cd zmk +``` + + + + ```sh cd zmk ``` + + + + +Open the `zmk` checkout folder in VS Code. The repository includes a configuration for containerized development, so an alert will pop up: + +![VS Code Dev Container Configuration Alert](assets/dev-setup/vscode_devcontainer.png) + +Click `Reopen in Container` in order to reopen the VS Code with the running container. + +The first time you do this on your machine, it will pull the docker image down from the registry and build the container. Subsequent launches are much faster! + +:::caution +All subsequent steps must be performed from the VS Code terminal _inside_ the container. +::: + + + + #### Initialize West ```sh @@ -393,6 +444,17 @@ section again for links to how to do this west update ``` +:::tip +This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection! +::: + +:::info +If you're using Docker, you're done with setup! You must restart the container at this point. The easiest way to do so is to close the VS Code window, verify that the container has stopped in Docker Dashboard, and reopen the container with VS Code. + +Once your container is restarted, proceed to [Building and Flashing](./dev-build.md). +::: + + #### Export Zephyr™ Core ```sh -- cgit v1.2.3 From 5401afc002ba086ca964aa7a164fbc6dbd1898b1 Mon Sep 17 00:00:00 2001 From: Idan Gazit Date: Fri, 9 Oct 2020 19:10:07 -0700 Subject: Skip toolchain for docker --- docs/docs/dev-setup.md | 5 ----- 1 file changed, 5 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 6ef0f02..114fe0b 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -338,11 +338,6 @@ Please be sure to read the [additional setup instructions](https://docs.zephyrpr ::: - - - -You're already set up: the toolchain is installed and configured inside the docker container. - -- cgit v1.2.3 From fc6c01fd6941ec795710d66ead9e17d5dfbaa19d Mon Sep 17 00:00:00 2001 From: Kurtis Lew Date: Fri, 9 Oct 2020 20:56:52 -0700 Subject: -DZMK_CONFIG Documentation (#255) feat(docs): `-DZMK_CONFIG` Documentation --- docs/docs/dev-build.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'docs') diff --git a/docs/docs/dev-build.md b/docs/docs/dev-build.md index 816468e..83ed8cb 100644 --- a/docs/docs/dev-build.md +++ b/docs/docs/dev-build.md @@ -84,6 +84,19 @@ west build -d build/right -b nice_nano -- -DSHIELD=kyria_right ``` This produces `left` and `right` subfolders under the `build` directory and two separate .uf2 files. For future work on a specific half, use the `-d` parameter again to ensure you are building into the correct location. +### Building from `zmk-config` Folder + +Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](user-setup#github-repo) by adding +`-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build` command. **Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.** + + +For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this: + +``` +west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config" +``` + + ## Flashing Once built, the previously supplied parameters will be remembered so you can run the following to flash your -- cgit v1.2.3