6 posts tagged with "oss"

Welcome to the fourth ZMK "State Of The Firmware" (SOTF)!

This update will cover all the major activity since SOTF #3.

Recent Activity#

Here's a summary of the various major changes since last time, broken down by theme:

Keymaps/Behaviors#

Since last time, there have been several new powerful keymap features and behaviors added, including one of the most asked for features, combos!

Combos#

The initial combos work has landed! The amazing okke-formsma has once again delivered another powerful feature for ZMK. Combos are "position based", and are configured in a new toplevel node next to they keymap node in user's keymap files.

An example, that would send the ESC keycode when pressing both the first and second positions on your keyboard:

Sticky Keys (One-Shot Mods/Layers) Behavior#

okke-formsma also contributed the initial "sticky keys" behavior, which can be used for functionality sometimes called "one shot mods" or "one shot layers". In your keymap, this would like like:

for a sticky key/modifier, or:

for a sticky layer.

&to Layer Behavior#

mcrosson contributed the new &to layer related behavior. This can be used to completely replace the active layer with a new one.

This is most frequently used when using multiple core base layers with different layouts, e.g. QWERTY and DVORAK, to switch between them.

Grave Escape Behavior#

okke-formsma added an implementation of the "Grave Escape" behavior, developing a more generic "mod-morph" behavior to do so. Adding

to your keymap will send ESC when pressed on its own, but will send ` when pressed with a GUI or Shift modifier held.

RGB Underglow Color Selection#

mcrosson updated the RGB Underglow behavior to allow binding an explicit color selection to a key position.

Keymap Upgrader#

joelspadin completed the Keymap Upgrader which can be used to update your keymap to using the latest supported codes, and move away from the old deprecated codes.

If you've made keymap customizations, please make sure to run your keymaps through the upgrader, since the old deprecated codes will be removed in a future version of ZMK.

Displays#

There has been lots of work to get display support complete enough for use by end users. Although not quite ready for prime time, it is incredibly close, and we are looking forward to having the last few items completed and the feature documented!

Idle Blanking#

petejohanson added idle blanking for displays, which ensures they will go blank, and into low power mode, after a short period of inactivity from the user. This ensures we avoid burn-in for OLEDs, and helps improve battery life.

Battery and Output Widgets#

petejohanson implemented the first two complete, dynamic "widgets" for the displays for ZMK, adding a small battery indicator, which includes charging status, and a small output indicator, showing the currently active output (USB or BLE). When using BLE, the indicator also shows the active profile slot, as well as if the profile slot is open, awaiting connection from the paired host, or is actively connected to the host for that profile slot.

Highest Layer Display#

mcrosson has contributed the next display widget, showing the highest active layer in the keymap. petejohanson then added a small follow up to allow layers in keymaps to add a label property to each layer, e.g. label = "Nav"; and have that label be displayed in the widget instead of the numeric layer number.

WPM#

New contributor allymparker added our fourth widget, a words-per-minute display! This widget work also included creating the core state logic for tracking the WPM.

For now, this widget is only working on the central side of split keyboards.

Miscellaneous#

Zephyr 2.4#

innovaker is at it again with some crucial core fixes, helping prepare and test the upgrade of ZMK to Zephyr 2.4. The updated Zephyr release brings with it some key BLE stability fixes, as well as various other core improvements that improve ZMK. This was a huge undertaking!

BLE Deadlock Fixes#

petejohanson was heads down diagnosing and fixing a deadlock issue on BLE that was frustrating and plaguing many users. After finally pinpointing the underlying root cause, he developed a fix and roped in many testers on Discord to help stress test things before merging.

Central/Peripheral Selection#

Previously overriding the selection of left as central, and right as peripheral for wireless splits required making local edits to the configuration files, and maintaining them in a ZMK fork.

petejohanson updated the config files to allow users to override this in their <board>_left.conf/<board>_right.conf files in their user repos.

Improved Docker Containers#

As part of the Zephyr 2.4. prep work, innovaker, along with lots of testing and input from mcrosson, developed a brand new pair of Docker images which is now published to Docker Hub as zmkfirmware/zmk-build-arm and zmkfirmware/zmk-dev-arm.

The previously blogged VSCode + Docker integration, as well as our GH Action build automation was all moved over to the new images.

Settings Debounce#

nicell contributed settings debounce work, to help avoid unnecessary extra writes to flash when making various changes that should be saved, such as the active BLE profile, external VCC on/off, etc.

New Shields#

• Jorne & Jian in #331 - krikun98
• tidbit in #424 - mcrosson
• Helix in #429 - KingCoinless
• BFO-9000 in #472 - pbz
• CRBN in #493 - ReFil
• Eek in #529 - MangoIV

New Boards#

• BDN9 Rev2 in #557 - petejohanson

Sponsorship#

Since it's inception, quite a few users have inquired whether they could sponsor any of the contributors involved in ZMK. Although we are not intending to directly fund any individual contributors for their work on ZMK, there is good that can come from folks sponsoring ZMK.

You can see the full discussion on #497, but some items that are being considered with sponsorship funds:

• Hiring a designer to complete the logo/mascot work.
• Creating stickers to send as thank-yous to first time contributors.
• Hosting costs for GitHub Pro.
• Other hosting costs, e.g. Docker Hub.

For anyone looking to contribute, you can find the ZMK Firmware project is now set up on Open Collective.

Coming Soon!#

Some items listed in the last coming soon section are still under active development.

• A power profiler page for the website, to help users estimate their battery life for a given keyboard - Nicell
• Behavior "locality", allowing improved split usage for things like &reset, and controlling external power and RGB underglow for both sides - petejohanson
• 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)
  • 389 Closed PRs
  • 199 Stars
  • 163 Forks
• Discord Chat
  • 702 total registered
• Website (last 30 days)
  • 11.5K page views
  • 1K new users

Thanks!#

Thanks again to the numerous contributors, testers, and users who have made working on ZMK such a pleasure!

Welcome to the third ZMK "State Of The Firmware" (SOTF)!

This update will cover all the major activity since SOTF #2. This edition comes a bit later than planned, but the amount of features and changes will hopefully make it worth it!

Recent Activity#

Here's a summary of the various major changes since last time, broken down by theme:

Keymaps/Behaviors#

Tons of activity related to keymaps, so we'll go into more detail this time.

Codes Overhaul#

innovaker completely overhauled the set of available codes for keymaps, and simultaneously has created beautiful documentation to help users visualize the codes, and also understand if they are supported on their particular operating system.

This also laid the foundation for the other keymap related changes that are now available.

Modified (Shifted) Codes#

okke-formsma added the ability to apply modifiers to a code, e.g.:

which sends Control + c when pressed. This feature is often used on smaller keyboards to achieve "shifted keycodes", e.g. LS(N1) to send a !. To make this easier, in addition to all the normal codes, we now have defines for common shifted codes, e.g. EXCL for !, AT for @, etc.

To learn more, check out the Modifiers documentation.

Simplified Key Press Behavior#

In previous versions of ZMK, users needed to be careful to select between the &kp and &cp behaviors in their keymaps, depending on whether the particular keycode they wanted to send was in the "HID consumer page" or not. Forcing users to understand the difference and get this right was awkward and error prone.

petejohanson and innovaker have reduced this complexity. Users can now simply use &kp with all available codes and ZMK will handle sending the right events to the connected host.

Power Management#

Several important power management features have been added to ZMK, helping save power for many use cases.

BLE Battery Level Reporting#

Nicell added the necessary driver and core code to send BLE battery level notifications to hosts that support displaying them. Testing seems to show this works with Windows and GNOME, but macOS does not display the battery info.

External Power Control#

megamind4089 added a new driver and behavior to allow users to toggle (on/off) the external power supplied by boards such as the nRFMicro and nice!nano that have specialized hardware for this purpose.

With this change, you can add

to toggle (on/off) the power to external hardware like RGB underglow or OLEDs. Check out the external power control docs for more info.

Deep Sleep#

petejohanson has contributed the initial deep sleep support to ZMK. This work also included some automatic power savings by switching to PORT events on the nRF52 chips, which reduces the idle power draw, even without deep sleep. Deep sleep is currently not turned on by default, but will be soon.

Miscellaneous#

Output Selection#

joelspadin added output selection to allow selecting whether to send output over USB or BLE if both are connected. This should now help avoid having "double keypresses" when your keyboard is plugged into a host.

Bootloader Corruption Fix#

Nicell has already blogged about this, but for those that missed it, a major, and incredibly difficult to pin down bug involving corruption of the bootloader on devices using the Adafruit nRF52 bootloader has been fixed by Nicell. If you've encountered this bug, flashing the latest firmware should prevent it from reoccurring. Unfortunately, due to the nature of this fix, you will need to re-pair your keyboard with your hosts, as the fix involves changing where settings are stored in the flash of the controller.

Official USB Product ID#

petejohanson has gotten an official USB product ID assigned to the ZMK Firmware. For anyone looking to uniquely identify a USB device running the ZMK Firmware, you can match on:

• Vendor ID: 0x1d50
• Product ID: 0x615e

We are incredibly grateful that Openmoko Inc., in the wake of discontinuing the openmoko projects, has made this an option for OSS projects.

Development: Remote Docker Container Integration#

idan contributed VSCode devcontainer integration to make it easier for developers to build and develop ZMK without having to do complicated local toolchain setup and configuration. This also opens up some amazing future flexibility for things like GitHub Codespaces.

There's some follow up tweaks necessary for better supporting using this with user config repositories, which will be available soon.

New Shields#

• Reviung41 in #297 - Nicell
• Boardsource 3x4 in #296 - neegool
• NIBBLE in #292 - jaygreco
• Microdox in #245 - careyk007
• MakerDiary M60 in #233 - megamind4089
• TGX4 in #226 - mubeenkhan94
• Quefrency V1 in #216 - noar-t
• Cradio in #224 - davidphilipbarr
• Romac+ in #198 - reizero00

New Boards#

• MakerDiary nRF52840 M.2 Module in #233 - megamind4089

Testing#

There has been an amazing amount of testing from various users as we develop new features. In particular, we'd like to give a shout out to tominabox1 who has been tireless in providing detailed and thorough testing of changes as they are being developed.

Coming Soon!#

Some items listed in the last coming soon section are still under active development.

• OLED work, including battery and USB/BLE connection status - petejohanson
• One shot mod/layer behaviors - okke-formsma
• A power profiler page for the website, to help users estimate their battery life for a given keyboard - Nicell
• A keymap converter to automatically update keymaps to the new codes and use of &kp everywhere - joelspadin

Statistics#

Some statistics of interest for ZMK:

• GitHub (lifetime stats)
  • 210 Closed PRs
  • 116 Stars
  • 101 Forks
• Discord Chat
  • 363 total registered
• Website (last 30 days)
  • 8.5K page views
  • 766 new users

Thanks!#

Thanks again to the numerous contributors and users who have made working on ZMK such a pleasure!

Recently I was able to fix the "stuck in the bootloader" issue in #322 that had been plaguing us for quite some time. I want to go over what the issue was, how the issue was diagnosed, and how it was fixed.

Background#

What exactly is the "stuck in the bootloader" issue? Seemingly randomly, users' keyboards would suddenly stop working and when they would reset their keyboard they would get put into the bootloader instead of back into the firmware. This would require the user to re-flash the firmware again to get into the firmware. That wouldn't be so bad except for the fact that once this occurs, every reset would require the user to re-flash the firmware again. The only way to really fix this issue was to re-flash the bootloader itself, which is a huge pain.

Going into this, all we knew was that this issue was most likely introduced somewhere in the #133, which added Bluetooth profile management. We've had quite a few attempts at trying to recreate the issue, but we never were able to get it to happen consistently.

Diagnosing the issue#

This issue had been happening sporadically for the past month, and I finally decided to dig in to see what was going on. We started in the Discord and discussed what was common between all of the people who have experienced this issue. Everyone who had this issue reported that they did quite a bit of profile switching. This lined up with the possible connection to the Bluetooth profile management pull request.

Pinpointing the cause#

I had a hunch that this was related to the settings system. The settings system is used by profile Bluetooth switching, and the settings system works directly with the system flash. Based on this hunch, I tried spamming the RGB underglow cycle behavior on my main keyboard. Sure enough after a couple minutes, I got stuck in the bootloader. I was even able to reproduce it again.

This was an important discovery for two reasons. First, I was able to recreate the issue consistently, which meant I could set up logging and more closely monitor what the board was doing. Second, this more or less proved that it was specifically the settings system at fault. Both Bluetooth profile switching and RGB underglow cycling trigger it, and the one common piece is they save their state to settings.

Settings system overview#

To understand what's going wrong, we first need to understand how the settings system works. Here's a diagram to explain the flash space that the settings system holds for our nRF52840 based boards (nice!nano, nRFMicro, BlueMicro).

The settings flash space lives at the end of the flash of the chip. In this case it starts at 0xF8000 and is 0x8000 bytes long, which is 32KB in more comprehensible units. Then due to the chip's architecture, this flash space is broken into pages, which are 0x1000 bytes in size (4KB).

The backend that carries out the settings save and read operation in ZMK is called NVS. NVS calls these pages sectors. Due to how flash works, you can't write to the same bytes multiple times without erasing them first, and to erase bytes, you need to erase the entire sector of flash. This means when NVS writes to the settings flash if there's no erased space available for the new value, it will need to erase a sector.

Logging discoveries#

So first I enabled logging of the NVS module by adding CONFIG_NVS_LOG_LEVEL_DBG=y to my .conf file. I repeated the same test of spamming RGB underglow effect cycle and the resulting logs I got were this:

So at start up, we can see that the 8 sectors of 4KB are found by NVS properly, however, I wasn't sure what the second and third lines meant, but we'll get back to that. Nonetheless the next two logs from NVS showed erasing the sector at 0xFD000 and then erasing the 0xFF000 sector.

It's really odd that the third to last sector and the last sector are erased, and then shortly after the bootloader issue is hit. I really had no explanation for this behavior.

Reaching out to Zephyr#

At this point, I nor anyone else working on the ZMK project knew enough about NVS to explain what was going on here. Pete Johanson, project founder, reached out on the Zephyr Project's Slack (ZMK is built on top of Zephyr if you weren't aware). Justin B and Laczen assisted by first explaining that those alloc wra and data wra logs from earlier are showing what data NVS found at startup.

More specifically, data wra should be 0 when it first starts up on a clean flash. As we can see from my earlier logging on a clean flash I was instead getting f40. NVS is finding data in our settings sectors when they should be blank! We were then given the advice to double check our bootloader.

The Adafruit nRF52 Bootloader#

Most of the boards the contributors of ZMK use have the Adafruit nRF52 Bootloader, which allows for extremely easy flashing by dragging and dropping .uf2 files onto the board as a USB drive. Every bootloader takes up a portion of the flash, and in the README explains that the first 0x26000 is reserved for the bootloader with the nRF52840, and we've properly allocated that.

However, there isn't a full explanation of the flash allocation of the bootloader in the README. There's a possibility that the bootloader is using part of the same flash area we're using. I reached out on the Adafruit Discord, and Dan Halbert pointed me towards the linker map of the nRF52840. Let's take a look.

Here's a diagram to show this a bit better.

We've found the issue! As you can see from the red bar (representing our settings flash area), we've put the settings flash area right on top of the Adafruit bootloader's flash space. Oops!

This also shines some light on why NVS erased 0xFD000 and 0xFF000 sectors. It's possible there was no flash written to 0xFD000 because the bootloader didn't use up all of that space it has, and then there possibly weren't any bootloader settings set yet, so 0xFF000 could be used and erased by NVS too.

After erasing 0xFF000, NVS probably next erased a rather important part of the bootloader that resulted in this issue at hand. In my opinion, we're pretty lucky that it didn't delete an even more vital part of the bootloader. At least we could still get to it, so that we could re-flash the bootloader easily!

The solution#

Now that we've found the issue, we can pretty easily fix this. We'll need to move the settings flash area back so that it doesn't overlap with the bootloader. First we calculate the size of the of flash area the bootloader is using.

So the bootloader is using the last 48KB of the flash, this means all we need to do is shift back the settings area and code space 0xC000 bytes. We'll apply this to all of the .dts files for the boards that were affected by this issue.

And with those changes, we should no longer run into this issue! In the process of these changes, we lost 48KB of space for application code, but we're only using around 20% of it anyways. 🎉

Welcome to the second ZMK "State Of The Firmware" (SOTF)!

This update will cover all the major activity since 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 in #146 which now powers mod-tap, layer-tap, etc. - okke-formsma
• BLE profile/connection management in #133 - petejohanson
• Integration tests were added to automate testing of behaviors in #131 by BrainWart & petejohanson
• Toggle layer behavior, e.g. &tog LOWER, in #98 - BrainWart
• Key fix for dropped press/release over HID #93/#96 - careyk007 & petejohanson
• Code formatting standardized using clang-format in #183 - petejohanson
• Bootloader reset behavior, e.g. &bootloader, in #116 - petejohanson
• Various bug fixes and documentation

New Shields#

• QAZ in #130 - tominabox1
• Iris in #151 - kurtis-lew
• RoMac 2.1 in #122 - bmcgavin
• Sofle in #118 - CrossR
• splitreus62 in #92 - Na-Cly

New Boards#

• DZ60RGB rev1 in #166 - Nicell
• nrfMicro in #101 - okke-formsma
• BlueMicro840 #91 - Na-Cly

Hacktoberfest Preparation#

Hacktoberfest 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 to help newcomers get oriented, and get up to speed.
• The Hacktoberfest issue label will help participants discover good issues to work on. (The existing good first issue 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 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
• 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!

Welcome to the first ZMK "State Of The Firmware"!

With interest and Discord activity growing, it seemed important to lay out the progress made recently, current major bugs/showstoppers, and planned next steps.

Recent Activity#

There's been lots of various activity in ZMK land!

• Nicell (nice!nano creator) contributed initial RGB Underglow (#64) support to ZMK.
• Tons of documentation work.
• Refactoring (#73, #74) of keymaps to make them simpler for users.
• Mod-Tap Behavior (docs coming!) is much improved (#69) and usable now.
• An initial setup.sh script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you.
• Corne shield (#80) shield definition was added.
• Initial encoder support (#61) was added.

Bugs and Showstoppers#

Despite the flurry of activity, there are still some serious bugs and show stoppers that potential ZMK users should be aware of:

• Bluetooth Related - There are several key bugs and fixes needed, including one complete show stopper:
  • Fully working split wireless is not working. In particular, both split halves can properly pair, but once they do so, pairing with the _central_ host will not work. Workaround: You can currently have both halves pair, and use USB on the central side (Left side right now for Kyria, Corne, Lily58) and receive HID events over USB. - Fixed in 8b61beb.
  • BT bond information is not currently stored to the devices, so after powering off or restarting your device, users need to re-pair
• USB - There is one important USB related bug which is a showstopper:
  • The Zephyr USB stack does not have a built in queue for endpoint data being written. As a result, HID events sent by ZMK are sometimes dropped, or lost. - Fixed by careyk007 in #93.

Next Steps#

There's plenty of places to go next! To help keep folks in the loop for what's next, I've created a Core Functionality project/kanban board in GitHub, where users should be able to get some visibility into items being focused on.

Of course, at the top of that list currently is the above bugs/showstoppers, and then from there, I hope to:

• Work on power management.
• Improve our documentation on various aspects of the system, mostly around:
  • End user documentation for understanding how to use ZMK, better installation docs, etc.
  • Developer focused documentation, so interested contributors can start building out more behaviors and ZMK functionality.
• Implement true "hold" detection, useful for several behaviors such as Mod-Tap and Layer-Tap.
• Hopefully acquire a proper and official USB Product ID for use for the project.
• Fun things that come up along the way!

Thanks!#

A big thanks for everyone who has shown interest in the project, tested things, asked questions, and contributed PRs (Nicell, CrossR, careyk007).

This blog is a work-in-progress as I work on basic docs + blog on this nascent keyboard firmware.

As is, there are more features missing from ZMK than features it has. As always with pre-alpha software, if something breaks, you get to keep both halves! (especially if it is a split KB)