From 1a492f0f9847d4c4f7e992c32b52920074d76ee4 Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Mon, 14 Sep 2020 20:37:26 -0700 Subject: Updated dev guide --- docs/docs/dev-guide-new-shield.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) (limited to 'docs') diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index 6140b07..71af54e 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -18,6 +18,9 @@ The high level steps are: - Add a default keymap, which users can override in their own configs as needed. - Add support for features such as encoders, OLED displays, or RGB underglow. + +- Update build.yml + It may be helpful to review the upstream [shields documentation](https://docs.zephyrproject.org/2.3.0/guides/porting/shields.html#shields) to get a proper understanding of the underlying system before continuing. ## New Shield Directory @@ -302,3 +305,36 @@ and then flash with: ``` west flash ``` + +## Updating `build.yml` + +Before publishing your shield to the public via a PR, navigate to `build.yml` found in `.github/workflows` and add your shield to the appropriate list. An example edit to `build.yml` is shown below. + +``` +jobs: + build: + runs-on: ubuntu-latest + name: Build Test + strategy: + matrix: + board: [proton_c, nice_nano, bluemicro840_v1, nrfmicro_13] + shield: + - corne_left + - corne_right + - kyria_left + - kyria_right + - lily58_left + - lily58_right + - iris_left + - iris_right + - romac + - + - + - + include: + - board: proton_c + shield: clueboard_california +``` +:::note +Notice that both the left and right halves of a split board need to be added to the list of shields for proper error checking. +:::note \ No newline at end of file -- cgit v1.2.3 From 5383bdd4dfc85b7782c489341eff96d0abf7dc72 Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Mon, 14 Sep 2020 20:38:58 -0700 Subject: Revert "Merge pull request #1 from zmkfirmware/main" This reverts commit 36da21b8e334f70b6bd9986e9b31c8ec02b29f87, reversing changes made to 719db13c4150e0d09da2d3dbe90838fe604c2267. --- docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg | Bin 115573 -> 0 bytes docs/docs/behavior/hold-tap.md | 2 +- docs/docs/dev-boards-shields-keymaps.md | 2 -- docs/docs/dev-guide-new-shield.md | 4 ---- 4 files changed, 1 insertion(+), 7 deletions(-) delete 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 deleted file mode 100644 index f72d407..0000000 Binary files a/docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg and /dev/null differ diff --git a/docs/docs/behavior/hold-tap.md b/docs/docs/behavior/hold-tap.md index ab51022..fa68538 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`. \ No newline at end of file diff --git a/docs/docs/dev-boards-shields-keymaps.md b/docs/docs/dev-boards-shields-keymaps.md index 9ed5a32..cfe5252 100644 --- a/docs/docs/dev-boards-shields-keymaps.md +++ b/docs/docs/dev-boards-shields-keymaps.md @@ -35,8 +35,6 @@ in the `app/boards/${arch}/${board_name}` directory, e.g. `app/boards/arm/planck ## Pro Micro Compatible Keyboard -![Labelled Pro Micro pins](assets/pro-micro/pro-micro-pins-labelled.jpg) - For keyboards that require a (usually Pro Micro compatible) add-on board to operate, the ZMK integration pieces are places in the _shield_ definition for that keyboard, allowing users to swap in different Pro Micro compatible boards (e.g. Proton-C, or nice!nano) and build a firmware the matches their actual diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index 71af54e..f270199 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -67,10 +67,6 @@ endif ## Shield Overlay -![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 f6932992d213a9e5ef061a13e7b8ef1137e7aa2f Mon Sep 17 00:00:00 2001 From: kurtis-lew Date: Mon, 14 Sep 2020 20:39:30 -0700 Subject: Revert "Revert "Merge pull request #1 from zmkfirmware/main"" This reverts commit 5383bdd4dfc85b7782c489341eff96d0abf7dc72. --- docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg | Bin 0 -> 115573 bytes docs/docs/behavior/hold-tap.md | 2 +- docs/docs/dev-boards-shields-keymaps.md | 2 ++ docs/docs/dev-guide-new-shield.md | 4 ++++ 4 files changed, 7 insertions(+), 1 deletion(-) 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 diff --git a/docs/docs/behavior/hold-tap.md b/docs/docs/behavior/hold-tap.md index fa68538..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`. \ 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`. diff --git a/docs/docs/dev-boards-shields-keymaps.md b/docs/docs/dev-boards-shields-keymaps.md index cfe5252..9ed5a32 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 pins](assets/pro-micro/pro-micro-pins-labelled.jpg) + For keyboards that require a (usually Pro Micro compatible) add-on board to operate, the ZMK integration pieces are places in the _shield_ definition for that keyboard, allowing users to swap in different Pro Micro compatible boards (e.g. Proton-C, or nice!nano) and build a firmware the matches their actual diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index f270199..71af54e 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -67,6 +67,10 @@ endif ## Shield Overlay +![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 0f8561daa155c765b2c04fe012bc4fa3d38cdfd7 Mon Sep 17 00:00:00 2001 From: Kurtis Lew Date: Mon, 14 Sep 2020 20:46:42 -0700 Subject: Update dev-guide-new-shield.md --- docs/docs/dev-guide-new-shield.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index 71af54e..c5b9a3d 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -17,8 +17,6 @@ The high level steps are: - (Optional) Add the matrix transform for mapping KSCAN row/column values to sane key positions. This is needed for non-rectangular keyboards, or where the underlying row/column pin arrangement does not map one to one with logical locations on the keyboard. - Add a default keymap, which users can override in their own configs as needed. - Add support for features such as encoders, OLED displays, or RGB underglow. - - - Update build.yml It may be helpful to review the upstream [shields documentation](https://docs.zephyrproject.org/2.3.0/guides/porting/shields.html#shields) to get a proper understanding of the underlying system before continuing. @@ -337,4 +335,4 @@ jobs: ``` :::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 \ No newline at end of file +:::note -- cgit v1.2.3 From ec86500524239500552e0105a86dd62872b99fd7 Mon Sep 17 00:00:00 2001 From: Kurtis Lew Date: Mon, 14 Sep 2020 20:53:26 -0700 Subject: Update dev-guide-new-shield.md --- 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 c5b9a3d..01aad30 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -326,9 +326,9 @@ jobs: - iris_left - iris_right - romac - - - - - - + - + - + - include: - board: proton_c shield: clueboard_california -- cgit v1.2.3