diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/blog/2020-09-21-zmk-sotf-2.md | 106 | ||||
| -rw-r--r-- | docs/docs/behavior/bluetooth.md | 76 | ||||
| -rw-r--r-- | docs/docs/behavior/hold-tap.md | 10 | ||||
| -rw-r--r-- | docs/docs/behavior/layers.md | 20 | ||||
| -rw-r--r-- | docs/docs/dev-guide-new-shield.md | 34 | ||||
| -rw-r--r-- | docs/docs/hardware.md | 5 | ||||
| -rw-r--r-- | docs/docs/intro.md | 33 | ||||
| -rw-r--r-- | docs/sidebars.js | 1 |
8 files changed, 266 insertions, 19 deletions
diff --git a/docs/blog/2020-09-21-zmk-sotf-2.md b/docs/blog/2020-09-21-zmk-sotf-2.md new file mode 100644 index 0000000..82278ad --- /dev/null +++ b/docs/blog/2020-09-21-zmk-sotf-2.md @@ -0,0 +1,106 @@ +--- +title: ZMK State Of The Firmware \#2 +author: Pete Johanson +author_title: Project Creator +author_url: https://gitlab.com/petejohanson +author_image_url: https://www.gravatar.com/avatar/2001ceff7e9dc753cf96fcb2e6f41110 +tags: [SOTF, keyboards, firmware, oss, ble] +--- + +Welcome to the second ZMK "State Of The Firmware" (SOTF)! + +This update will cover all the major activity since [SOTF #1](/blog/2020/08/12/zmk-sotf-1), preparations for the upcoming +Hacktoberfest activity, and a current open call for community feedback on a ZMK mascot. + +## Recent Activity + +So much going on in ZMK! + +- Added a new generic [Hold Tap behavior](https://zmkfirmware.dev/docs/behavior/hold-tap) + in [#146](https://github.com/zmkfirmware/zmk/pull/146) which now powers mod-tap, layer-tap, etc. - [okke-formsma] +- [BLE profile/connection management](https://zmkfirmware.dev/docs/behavior/bluetooth) + in [#133](https://github.com/zmkfirmware/zmk/pull/133) - [petejohanson] +- Integration tests were added to automate testing of behaviors in [#131](https://github.com/zmkfirmware/zmk/pull/131) by [BrainWart] & [petejohanson] +- [Toggle layer behavior](https://zmkfirmware.dev/docs/behavior/layers#toggle-layer), e.g. `&tog LOWER`, in + [#98](https://github.com/zmkfirmware/zmk/pull/98) - [BrainWart] +- Key fix for dropped press/release over HID [#93](https://github.com/zmkfirmware/zmk/pull/93)/[#96](https://github.com/zmkfirmware/zmk/pull/96) - [careyk007](https://github.com/careyk007) & [petejohanson] +- Code formatting standardized using `clang-format` in [#183](https://github.com/zmkfirmware/zmk/pull/183) - [petejohanson] +- [Bootloader reset behavior](https://zmkfirmware.dev/docs/behavior/reset#bootloader-reset), e.g. `&bootloader`, in [#116](https://github.com/zmkfirmware/zmk/pull/116) - [petejohanson] +- Various bug fixes and documentation + +## New Shields + +- QAZ in [#130](https://github.com/zmkfirmware/zmk/pull/130) - [tominabox1](https://github.com/tominabox1) +- Iris in [#151](https://github.com/zmkfirmware/zmk/pull/151) - [kurtis-lew](https://github.com/kurtis-lew) +- RoMac 2.1 in [#122](https://github.com/zmkfirmware/zmk/pull/122) - [bmcgavin](https://github.com/bmcgavin) +- Sofle in [#118](https://github.com/zmkfirmware/zmk/pull/118) - [CrossR](https://github.com/CrossR) +- splitreus62 in [#92](https://github.com/zmkfirmware/zmk/pull/92) - [Na-Cly](https://github.com/Na-Cly) + +## New Boards + +- DZ60RGB rev1 in [#166](https://github.com/zmkfirmware/zmk/pull/166) - [Nicell] +- nrfMicro in [#101](https://github.com/zmkfirmware/zmk/pull/101) - [okke-formsma] +- BlueMicro840 [#91](https://github.com/zmkfirmware/zmk/pull/91) - [Na-Cly](https://github.com/Na-Cly) + +## Hacktoberfest Preparation + +[Hacktoberfest](https://hacktoberfest.digitalocean.com/) is a yearly celebration of open source, +which encourages participation in OSS, especially from new contributors. + +The ZMK contributors have been busy preparing for folks to join in on the fun by contributing to +ZMK! + +- There is now a basic [Contributing Guide](https://github.com/zmkfirmware/zmk/blob/main/CONTRIBUTING.md) to help newcomers get oriented, and get up to speed. +- The [`Hacktoberfest`](https://github.com/zmkfirmware/zmk/issues?q=is%3Aissue+is%3Aopen+label%3AHacktoberfest) + issue label will help participants discover good issues to work on. + (The existing [`good first issue`](https://github.com/zmkfirmware/zmk/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) label also helps with this) + +We're looking forward to the launch of Hacktoberfest! + +## Mascot Selection Feedback + +The ZMK project would like to settle on a mascot! We're soliciting community feedback as part of +the process before a final mascot is selected. + +The current mascots up for consideration are: + +- Griffin +- Peregrine Falcon +- Zapata Wren +- Zorro (south american fox) + +If you're interested in helping with the decision, head over to [Issue #195](https://github.com/zmkfirmware/zmk/issues/195) and add a reaction! + +## Coming Soon! + +There still lots of activity in ZMK, and plenty of exciting upcoming changes. + +- Improved modifier infrastructure, including "shifted keycodes" - [okke-formsma] +- Battery percentage reporting over BLE - [Nicell] +- Complete defines for HID keycodes/usage IDs - [innovaker](https://github.com/innovaker) +- Additional core BLE connection/bond management work - [petejohanson] +- Improved power management - [petejohanson], [Nicell] +- One shot mod/layer behaviors - [okke-formsma] + +## Statistics + +Some statistics of interest for ZMK: + +- GitHub + - 115 Closed PRs + - 64 Stars + - 48 Forks +- Discord Chat + - 186 total registered +- Website (last 30 days) + - 7.4K page views + - 474 new users + +## Thanks! + +Thanks again to the numerous contributors and users who have made working on ZMK such a pleasure! + +[okke-formsma]: https://github.com/okke-formsma +[nicell]: https://github.com/Nicell +[petejohanson]: https://github.com/petejohanson +[brainwart]: https://github.com/BrainWart diff --git a/docs/docs/behavior/bluetooth.md b/docs/docs/behavior/bluetooth.md new file mode 100644 index 0000000..f802a9a --- /dev/null +++ b/docs/docs/behavior/bluetooth.md @@ -0,0 +1,76 @@ +--- +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. 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 + +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 <dt-bindings/zmk/bt.h> +``` + +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_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_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 + +The bluetooth behavior completes an bluetooth action given on press. + +### Behavior Binding + +- Reference: `&bt` +- Parameter #1: The bluetooth command define, e.g. `BT_CLR_CMD` +- Parameter #2: (Reserved for future bluetooth command types) + +### Examples + +1. Behavior binding to clear the paired host for the selected profile: + + ``` + &bt BT_CLR + ``` + +1. Behavior binding to select the next profile: + + ``` + &bt BT_NXT + ``` + +1. Behavior binding to select the previous profile: + + ``` + &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_SEL 1 + ``` 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  -### 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/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index 6140b07..01aad30 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -17,6 +17,7 @@ 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. @@ -302,3 +303,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 + - <MY_BOARD> + - <MY_SPLIT_BOARD_left> + - <MY_SPLIT_BOARD_right> + 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 diff --git a/docs/docs/hardware.md b/docs/docs/hardware.md index 299d1f5..236aa97 100644 --- a/docs/docs/hardware.md +++ b/docs/docs/hardware.md @@ -26,6 +26,11 @@ That being said, there are currently only a few specific [boards](/docs/faq#what - [Kyria](https://splitkb.com/products/kyria-pcb-kit) (`kyria_left` and `kyria_right`) - [Corne](https://github.com/foostan/crkbd) (`corne_left` and `corne_right`) - [Lily58](https://github.com/kata0510/Lily58) (`lily58_left` and `lily58_right`) +- [Sofle](https://github.com/josefadamcik/SofleKeyboard) (`sofle_left` and `sofle_right`) +- [Splitreus62](https://github.com/Na-Cly/splitreus62) (`splitreus62_left` and `splitreus62_right`) +- [RoMac+ v4](https://www.littlekeyboards.com/products/romac) (`romac_plus`) +- [RoMac v2](https://mechboards.co.uk/shop/kits/romac-macro-pad/) (`romac') +- [QAZ](https://www.cbkbd.com/product/qaz-keyboard-kit) (`qaz`) ## Other Hardware 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 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: [ |