diff --git a/docs/blog/2023-10-05-zmk-sotf-6.md b/docs/blog/2023-10-05-zmk-sotf-6.md new file mode 100644 index 00000000..18a52a85 --- /dev/null +++ b/docs/blog/2023-10-05-zmk-sotf-6.md @@ -0,0 +1,295 @@ +--- +title: "ZMK State Of The Firmware #6" +author: Cem Aksoylar +author_title: Documentation maintainer +author_url: https://github.com/caksoylar +author_image_url: https://avatars.githubusercontent.com/u/7876996 +tags: [SOTF, keyboards, firmware, oss, ble] +--- + +Welcome to the sixth ZMK "State Of The Firmware" (SOTF)! + +This update will cover all the major activity since [SOTF #5](/blog/2022/04/10/zmk-sotf-5). That was over a year ago (again!), so there are many new exciting features and plenty of improvements to cover! + +## Recent Activity + +Here's a summary of the various major changes since last time, broken down by theme: + +### Keymaps/Behaviors + +#### Hold-tap improvements + +[andrewjrae] added the [`require-prior-idle-ms` property](/docs/behaviors/hold-tap#require-prior-idle-ms) to the hold-tap behavior in [#1187](https://github.com/zmkfirmware/zmk/pull/1187) and [#1387](https://github.com/zmkfirmware/zmk/pull/1387), which prevents the hold behavior from triggering if it hasn't been a certain duration since the last key press. This is a useful feature to prevent accidental hold activations during quick typing and made its way into many keymaps! The same property was added to [combos](/docs/features/combos#configuration) as well to help prevent false combo activations. + +Note that an earlier iteration of this feature was supported with the `global-quick-tap` property, which did not allow customizing the timeout and used the value of `tapping-term-ms` for it. This property is now deprecated and users are encouraged to use `require-prior-idle-ms` instead. + +[urob] added the [`hold-trigger-on-release` property](/docs/behaviors/hold-tap#positional-hold-tap-and-hold-trigger-key-positions) in [#1423](https://github.com/zmkfirmware/zmk/pull/1423). This significantly increases the usefulness of positional constraints on hold-taps, since it allows combining multiple holds such as different modifiers for home row mods usage. + +#### Masking mods in mod-morphs + +[aumuell](https://github.com/aumuell), [vrinek](https://github.com/vrinek) and [urob] contributed to improving the behavior of [mod-morphs](/docs/behaviors/mod-morph) by masking the triggering modifiers and added `keep-mods` property in [#1412](https://github.com/zmkfirmware/zmk/pull/1412). This unlocks more use cases for mod-morphs, since you are no longer constrained to emitting keycodes that work well with the triggering modifier keycodes. + +As an example, you can now define a mod-morph that swaps `;` and `:` so that the former is the shifted version of the latter, which wasn't previously possible: + +```dts + col_semi: colon_semicolon { + compatible = "zmk,behavior-mod-morph"; + label = "COLON_SEMICOLON"; + #binding-cells = <0>; + bindings = <&kp COLON>, <&kp SEMI>; + mods = <(MOD_LSFT|MOD_RSFT)>; + }; +``` + +#### Parameterized macros + +[petejohanson] added [macros that can be parameterized](/docs/behaviors/macros#parameterized-macros) with one or two parameters in [#1232](https://github.com/zmkfirmware/zmk/pull/1232). This allows users to define macros in a more modular way and is a nice quality-of-life improvement. + +As a simple example, you could define a macro that puts any keycode provided between double quotes as below, then use it like `&ql A` in your keymap: + +```dts + ql: quoted_letter_macro { + #binding-cells = <1>; + label = "QUOTED_LETTER"; + compatible = "zmk,behavior-macro-one-param"; + bindings = + <&kp DQT>, + <¯o_param_1to1 &kp MACRO_PLACEHOLDER>, + <&kp DQT>; + }; +``` + +Please see the documentation page linked above for usage and more examples. + +#### Arbitrary behaviors on encoder rotation + +[nickconway](https://github.com/nickconway) and [petejohanson] added [sensor rotation behaviors](/docs/behaviors/sensor-rotate) to allow invoking arbitrary behaviors from encoders [#1758](https://github.com/zmkfirmware/zmk/pull/1758). Previously encoder rotations could only invoke the key-press behavior `&kp` through the `&inc_dec_kp` binding, whereas now you can define new sensor rotation behaviors to invoke others. + +(Note that currently behaviors that have "locality" such as `&rgb_ug` do not work as expected via encoder rotation bindings in split keyboards, due to issue [#1494](https://github.com/zmkfirmware/zmk/issues/1494).) + +#### Pre-releasing already pressed keys + +[andrewjrae] contributed a tweak to emitting keycodes in [#1828](https://github.com/zmkfirmware/zmk/pull/1828), where rolling multiple keys that involve the same keycode now releases the keycode before sending a press event again. While this might sound like a technical distinction, it leads to more correct behavior when quickly typing sequences like `+=` and makes the [key repeat behavior](/docs/behaviors/key-repeat) work properly when it is pressed before the previous key is released. + +#### Key toggle behavior + +[cgoates](https://github.com/cgoates) added the [key toggle behavior](/docs/behaviors/key-toggle) in [#1278](https://github.com/zmkfirmware/zmk/pull/1278), which can be used via its `&kt` binding to toggle the state of a keycode between pressed and released. + +#### Apple Globe key + +[ReFil] added support for the `C_AC_NEXT_KEYBOARD_LAYOUT_SELECT` keycode with alias `GLOBE` which acts as the Globe key in macOS and iOS in [#1938](https://github.com/zmkfirmware/zmk/pull/1938). Note that this keycode doesn't exactly behave like a Globe key that is present on an Apple keyboard and its limitations are documented in [this comment](https://github.com/zmkfirmware/zmk/pull/1938#issuecomment-1744579039) thanks to testing by [SethMilliken](https://github.com/SethMilliken). These limitations will be noted in the official [keycodes documentation](/docs/codes/applications) shortly. + +#### Bug fixes and other improvements + +[petejohanson], [andrewjrae] and [okke-formsma] tracked down and fixed an issue causing stuck keys when there are combos on key positions involving hold-tap behaviors in [#1411](https://github.com/zmkfirmware/zmk/pull/1411). This was an elusive bug that took a lot of effort from the community to nail down and fix! + +[nguyendown](https://github.com/nguyendown) and [joelspadin] tracked down and fixed a couple issues causing stuck keys with [sticky keys](/docs/behaviors/sticky-key) in [#1586](https://github.com/zmkfirmware/zmk/pull/1586), [#1745](https://github.com/zmkfirmware/zmk/pull/1745). + +[okke-formsma] fixed an issue allowing tap dances to be invoked by combos in [#1518](https://github.com/zmkfirmware/zmk/pull/1518). + +[petejohanson] tweaked the caps word behavior to ignore modifiers in [#1330](https://github.com/zmkfirmware/zmk/pull/1330). + +[HelloThisIsFlo](https://github.com/HelloThisIsFlo) documented a bug with combos involving overlapping keys and different timeouts, produced a reproducing unit test, then proceeded to fix it in [#1945](https://github.com/zmkfirmware/zmk/pull/1945). + +### Bluetooth and Split Improvements + +#### Multiple peripherals + +[xudongzheng] contributed to add support for more than one peripheral per keyboard in [#836](https://github.com/zmkfirmware/zmk/pull/836). This allows setups such as split keyboards with more than two halves, or enable a BLE-based "dongle mode" via a third device running ZMK that can stay connected to a computer via USB. + +Note that documentation is still lacking for utilizing more than one peripheral and there will potentially be future changes in the build system to allow for more seamless configuration. + +#### Pairing passkey requirement + +[petejohanson] added [the option to require passkey input](/docs/config/bluetooth) while pairing to new devices in [#1822](https://github.com/zmkfirmware/zmk/pull/1822). Enabling this will require you to enter a six digit passcode via the number keys on your keymap and press enter when pairing to a new device, enhancing security during the pairing procedure. + +#### Split keyboard improvements + +[petejohanson] contributed a fix to release held keys on peripheral disconnect [#1340](https://github.com/zmkfirmware/zmk/pull/1340), which makes scenarios where a split disconnects unexpectedly less painful. + +[petejohanson] also improved [the `settings_reset` shield](/docs/troubleshooting#split-keyboard-halves-unable-to-pair) by making it clear bonds more reliably, and allow it to build for all boards in [#1879](https://github.com/zmkfirmware/zmk/pull/1879). + +[petejohanson] and [xudongzheng] contributed additional split connectivity improvements, via using directed advertising in [#1913](https://github.com/zmkfirmware/zmk/pull/1913) and improving the robustness of central scanning in [#1912](https://github.com/zmkfirmware/zmk/pull/1912). + +### Hardware Support + +#### Encoders + +[petejohanson] contributed a major refactor of encoder (and more generally sensor) functionality in [#1039](https://github.com/zmkfirmware/zmk/pull/1039). While the documentation for these changes are still in progress, check out the [dedicated blog post](/blog/2023/06/18/encoder-refactors) for more details. + +This refactor paved way to implementing a long-awaited feature, encoder support in peripheral halves of split keyboards! Building upon the work by [stephen](https://github.com/stephen) in [#728](https://github.com/zmkfirmware/zmk/pull/728), [petejohanson] implemented support in [#1841](https://github.com/zmkfirmware/zmk/pull/1841). + +#### Direct GPIO driver + +[joelspadin] extended the comprehensive debouncing framework used for matrix scan driver to the [direct GPIO driver](/docs/config/kscan#direct-gpio-driver) in [#1288](https://github.com/zmkfirmware/zmk/pull/1288). + +[kurtis-lew] added toggle mode support for direct GPIO driver in [#1305](https://github.com/zmkfirmware/zmk/pull/1305). This allows for adding toggle switches to a keyboard, by properly reading their initial state on boot and making sure the power use is efficient. + +#### IO peripheral drivers + +[petejohanson] added support for the 595 shift register commonly used with smaller controllers like Seeeduino Xiaos, in [#1325](https://github.com/zmkfirmware/zmk/pull/1325). + +[zhiayang](https://github.com/zhiayang) added the driver for the MAX7318 GPIO expander in [#1295](https://github.com/zmkfirmware/zmk/pull/1295). + +#### Underglow auto-off options + +[ReFil] added two [new RGB auto off options](/docs/config/underglow), one using an idle timeout and the other USB status in [#1010](https://github.com/zmkfirmware/zmk/pull/1010). + +#### nice!view support + +[nicell] added support for nice!view, a memory display optimized for low power use in [#1462](https://github.com/zmkfirmware/zmk/pull/1462). +He also contributed a custom vertically-oriented status screen that is automatically enabled when the `nice_view` shield is used in [#1768](https://github.com/zmkfirmware/zmk/pull/1768), since the default status screen has a horizontal orientation. +Please see the instructions in the [nice!view README](https://github.com/zmkfirmware/zmk/blob/main/app/boards/shields/nice_view/README.md) if you would like to restore the stock status screen. + +#### E-paper display initialization + +[petejohanson] contributed EPD initialization improvements in [#1098](https://github.com/zmkfirmware/zmk/pull/1098), which makes the keyboards using slow refresh displays such as the Corne-ish Zen much more responsive during initial boot. + +#### Xiao BLE improvements + +Various improvements were made for the Seeeduino Xiao BLE board in [#1293](https://github.com/zmkfirmware/zmk/pull/1293), [d0176f36](https://github.com/zmkfirmware/zmk/commit/d0176f36), [#1545](https://github.com/zmkfirmware/zmk/pull/1545) and [#1927](https://github.com/zmkfirmware/zmk/pull/1927) by [petejohanson] and [caksoylar], enabling features necessary for ZMK and improving its power use. + +### Zephyr 3.2 Upgrade + +[petejohanson] once again contributed the massive work necessary for upgrading ZMK to Zephyr 3.2 in [#1499](https://github.com/zmkfirmware/zmk/pull/1499), with review help from [joelspadin] and testing by the community. This Zephyr release brings with it upgrades to the display library LVGL, adds official support for the RP2040 controllers and many internal refactors to help future development. +Check out the [dedicated blog post](/blog/2023/04/06/zephyr-3-2) for more details! + +### Documentation + +#### Configuration docs + +[joelspadin], through a massive amount of work in [#722](https://github.com/zmkfirmware/zmk/pull/722), contributed a whole new section to the documentation: [configuration](/docs/config)! It enumerates the configuration options for each ZMK feature that might be relevant to users in dedicated pages, making it a very handy reference. + +In addition, the [overview page](/docs/config) presents an overview of how configuration works in Zephyr in the context of ZMK, in terms of devicetree files (like the keymap files or shield overlays), and Kconfig ones (like the `.conf` files). It is very helpful in de-mystifying what the various files do and what syntax is expected in them. + +#### New behavior guide + +For users or future contributors that might want to dive into writing their own ZMK behaviors, [kurtis-lew] wrote a useful [guide on how to create new behaviors](/docs/development/new-behavior) in [#1268](https://github.com/zmkfirmware/zmk/pull/1268). + +#### Tap dance and hold-tap documentation improvements + +[kurtis-lew] also improved the documentation for these two behaviors in [#1298](https://github.com/zmkfirmware/zmk/pull/1298), by updating the diagrams to better clarify how their timings work and adding examples for scenarios that are frequently asked by users. + +#### Battery sensor documentation + +[joelspadin] also added documentation for setting up battery sensors, typically required for new boards, in [#868](https://github.com/zmkfirmware/zmk/pull/868). + +#### Shield interconnects + +[petejohanson] updated the [new shield guide](/docs/development/new-shield) for non-Pro Micro interconnects including Xiao, Arduino Uno and Blackpill in [#1607](https://github.com/zmkfirmware/zmk/pull/1607). + +#### Bluetooth feature page + +[petejohanson] and [caksoylar] added a new [Bluetooth feature page](/docs/features/bluetooth) as part of [#1499](https://github.com/zmkfirmware/zmk/pull/1499) and in [#1818](https://github.com/zmkfirmware/zmk/pull/1499), detailing ZMK's Bluetooth implementation and troubleshooting for common problems. + +In addition to the specific contributions listed above, various improvements and fixes to documentation are made by many users from the community, including but not limited to [kurtis-lew], [joelspadin], [filterpaper], [byran.tech](https://github.com/byran.tech), [dxmh] and [caksoylar]. These contributions are are all very appreciated! + +### Miscellaneous + +#### Reusable GitHub build workflow + +[elagil](https://github.com/elagil) helped switch the build workflow used by the [user config repos](/docs/user-setup) to a reusable one in [#1183](https://github.com/zmkfirmware/zmk/pull/1183) and it was further tweaked by [filterpaper] in [#1258](https://github.com/zmkfirmware/zmk/pull/1258). This allows any changes in the workflow to be propagated automatically to users, rather than requiring them to make the updates. The build workflow can be customized by the users [using input parameters](https://github.com/zmkfirmware/zmk/blob/main/.github/workflows/build-user-config.yml#L5) if desired. + +#### Pre-commit hooks + +[joelspadin] added various [pre-commit](https://pre-commit.com/) hooks and added checks to the repo to run them for each commit in [#1651](https://github.com/zmkfirmware/zmk/pull/1651). These hooks and resulting updates standardize formatting across devicetree and other source files, reducing busywork on both contributors and reviewers. + +#### Zephyr usage and other refactors + +[joelspadin] also contributed a few refactor PRs such as [#1269](https://github.com/zmkfirmware/zmk/pull/1269), [#1255](https://github.com/zmkfirmware/zmk/pull/1255) and [#1803](https://github.com/zmkfirmware/zmk/pull/1803), generally improving code quality and bringing the codebase in line with the latest Zephyr conventions. + +[petejohanson] refactored the drivers structure to bring it in line with the current Zephyr conventions for out-of-tree drivers in [#1919](https://github.com/zmkfirmware/zmk/pull/1919). + +#### Updated USB polling interval default + +USB HID polling interval now defaults to 1 ms, i.e. a 1000Hz polling rate, thanks to [joelspadin]'s tweak in [#1271](https://github.com/zmkfirmware/zmk/pull/1271). + +#### Additional display config options + +[caksoylar] added a couple configuration options for displays, including a setting to invert display colors in [#1754](https://github.com/zmkfirmware/zmk/pull/1754) and an option to display the battery percentage for the stock status screen in [#1563](https://github.com/zmkfirmware/zmk/pull/1563). + +## New Shields + +- Eternal keypad [#1136](https://github.com/zmkfirmware/zmk/pull/1136) - [halcyonCorsair](https://github.com/halcyonCorsair) +- nullbits SNAP [#1319](https://github.com/zmkfirmware/zmk/pull/1319) - [jaygreco](https://github.com/jaygreco) +- Aurora Sweep [#1504](https://github.com/zmkfirmware/zmk/pull/1504), Corne [#1520](https://github.com/zmkfirmware/zmk/pull/1520), Lily58 [#1553](https://github.com/zmkfirmware/zmk/pull/1553), Sofle [#1864](https://github.com/zmkfirmware/zmk/pull/1864), and Helix [#1873](https://github.com/zmkfirmware/zmk/pull/1873) - [petejohanson] +- ZMK Uno shield [#1576](https://github.com/zmkfirmware/zmk/pull/1576) - [petejohanson] +- Waterfowl [#1554](https://github.com/zmkfirmware/zmk/pull/1554) - [JW2586](https://github.com/JW2586) +- Kyria Rev 3 [#1627](https://github.com/zmkfirmware/zmk/pull/1627) - [petejohanson] +- Leeloo v2 and Leeloo-Micro [#1762](https://github.com/zmkfirmware/zmk/pull/1762) - [ClicketySplit](https://github.com/ClicketySplit) +- Spaceman Pancake [#1400](https://github.com/zmkfirmware/zmk/pull/1400) - [jasonhazel](https://github.com/jasonhazel) +- Reviung5 [#1548](https://github.com/zmkfirmware/zmk/pull/1548) - [zblesk](https://github.com/zblesk) + +## New Boards + +- RP2040 boards, including Sparkfun Pro Micro, Adafruit KB2040 and Seeeduino Xiao RP2040 were added as part of the Zephyr 3.2 upgrade in [#1499](https://github.com/zmkfirmware/zmk/pull/1499) - [petejohanson] +- Puchi BLE [#1445](https://github.com/zmkfirmware/zmk/pull/1445) - [BenRoe](https://github.com/BenRoe) +- nRFMicro 1.3/1.4 (nRF52833) [#912](https://github.com/zmkfirmware/zmk/pull/912) - [pashutk](https://github.com/pashutk) +- nRF5340 DK [#1562](https://github.com/zmkfirmware/zmk/pull/1562) - [joelspadin] +- PillBug [#1530](https://github.com/zmkfirmware/zmk/pull/1530) - [kylemccreery](https://github.com/kylemccreery) +- Preonic Rev 3 [#1575](https://github.com/zmkfirmware/zmk/pull/1575) - [jeromeOlivier](https://github.com/jeromeOlivier) +- Corne-ish Zen v2 [#1498](https://github.com/zmkfirmware/zmk/pull/1498) and v1 [#1593](https://github.com/zmkfirmware/zmk/pull/1593) - [LOWPROKB](https://github.com/LOWPROKB) and [caksoylar] +- Polarity Works CKP family of boards [#1547](https://github.com/zmkfirmware/zmk/pull/1547) - [ReFil] + +## Coming Soon! + +Some items listed in the last coming soon section are still under active development and other new exciting items are in progress: + +- Automatic/simple BLE profile management +- Soft off support for turning the keyboard "off" through firmware +- Improved automatic power management for devices with multiple peripherals, e.g. OLED displays and RGB LEDs +- Caps/Scroll/Num Lock LED support +- Mouse keys +- Wired split support +- More modular approach to external boards/shields, custom code, user keymaps, etc. +- More shields and boards + +## Statistics + +Some statistics of interest for ZMK: + +- GitHub (lifetime stats) + - 166 Contributors + - 1256 Closed PRs + - 1883 Stars + - 1949 Forks +- Discord Chat + - 8055 total registered (130% up from last SOTF!) +- Website (last 30 days) + - 52K page views + - 4.7K new users + +## Sponsorship + +While ZMK is an open source project that uses the permissive MIT license, below are opportunities for anyone who would like to show their support to the project financially. + +### Open Collective + +The ZMK project has an [Open Collective sponsorship](https://opencollective.com/zmkfirmware) that has been going for two and a half years. +This fund helps pay for project costs like domain registration or development of hardware such as the [ZMK Uno shield](https://github.com/zmkfirmware/zmk-uno). +Note that donations to this fund do _not_ pay for the work of any individual contributor directly. + +### Contributor sponsorships + +Project creator and lead Pete Johanson has a [GitHub sponsorship](https://github.com/sponsors/petejohanson) set up that you can contribute to, in order to directly support his time and efforts in developing and maintaining ZMK. +He has also been traveling full time while focusing on ZMK and keyboard hardware design for more than a year now! +If you are curious, you can check out [his blog post](https://petejohanson.dev/blog/new-journey-2022) on deciding to embark on this adventure, in addition to his thoughts on contributor vs. project sponsorship, and sustainability of open source projects in general. + +## Thanks! + +As the first person to author a State Of The Firmware post besides Pete, I'd like to take the opportunity to thank him for his efforts on leading and developing ZMK, along with fostering a great community of contributors and users around it. + +Also a big thank you to contributors that submit patches and perform reviews, testers that help validate changes, and users that take time out of their day to help out folks with ZMK usage on [Discord channels](https://zmk.dev/community/discord/invite), GitHub issues and other communities. + +[okke-formsma]: https://github.com/okke-formsma +[andrewjrae]: https://github.com/andrewjrae +[xudongzheng]: https://github.com/xudongzheng +[nicell]: https://github.com/Nicell +[petejohanson]: https://github.com/petejohanson +[kurtis-lew]: https://github.com/kurtis-lew +[joelspadin]: https://github.com/joelspadin +[dxmh]: https://github.com/dxmh +[caksoylar]: https://github.com/caksoylar +[urob]: https://github.com/urob +[filterpaper]: https://github.com/filterpaper +[ReFil]: https://github.com/ReFil