Agent 2: Next-level UHK and module configuration

TL;DR: Say hi to 12 layers per keymap, module speed and acceleration settings, and loads of advanced features, mostly enabled by the new smart macros functionality of the latest UHK Agent and firmware releases.

I don’t usually write dedicated posts about new releases, but this is a major one, we’ve been working on it for a year, and it delivers a huge punch that can elevate your UHK experience to the next level, so it mustn’t go unnoticed.

A summary of new features to whet your appetite:

• Extended the original four layers per keymap with four regular layers (Fn2, Fn3, Fn4, Fn5) and four modifier layers (Shift, Ctrl, Alt, Super).
• All modules: speed and acceleration settings, axis locking settings, per-layer navigation modes
• Key cluster module: Added the ability to fine-tune or disable the behavior of the mini trackball.
• Trackpoint module: Fixed occasional trackpoint pointer jumps and made it easy to stop drifting if it occurred.
• Touchpad module: Implemented pinch-to-zoom, two-finger scrolling, doubletap-to-drag, and made the tap action configurable.
• Advanced configuration scenarios via smart macros, such as configurable modifier layer triggers, mouse key axis skew, and LED fade timeout
• Super-advanced configuration scenarios via extended macro commands, such as variables, loops, double tap actions, and runtime macro recording.
• Implemented N-key rollover.
• Made accelerate and decelerate actions work with modules.
• Fixed USB descriptors which caused high CPU load on Macintosh computers.

Let’s go over the main features, but first, install the new Agent. Then it’ll upgrade your UHK to the new firmware.

12 layers per keymap

Instead of 4 layers, you can now have 12 layers per keymap.

You can enable/disable any of the above layers per keymap except for the base layer, which is mandatory.

The Fn2, Fn3, Fn4, and Fn5 layers work just like the existing layers, but Shift, Ctrl, Alt, and Super are modifier layers.

On modifier layers, you can map alternative actions per key, which trigger when the key is pressed with the relevant modifier. For example, now you can implement the Programmer Dvorak layout solely on the UHK.

Smart macros introduction

You’re probably already familiar with regular macros, which are a sequence of macro actions, such as keypresses and mouse movements.

Smart macros, however, enable the advanced customization of your UHK and its modules. See the following screenshot, which shows a macro named $onInit containing a command macro action that contains multiple macro commands:

$onInit is a special macro name. It's a macro event that executes each time your UHK gets powered and when you save its configuration.

"set module.trackball.baseSpeed 1" is a macro command that sets the base speed of the trackball module to 1.

Macro commands work in any macros, not only in macro events, and you can bind them to any key. This way, you can make Fn+1 set your trackball base speed to 1, and make Fn+2 set it to 2, for example.

Interactive smart macro editing

Adjusting values by editing text is tedious. This is why we created a smart macro sidebar that can be opened on macro pages. This sidebar contains easy-to-read documentation and provides interactive widgets that make configuration a breeze.

When clicking on a macro command action, the widgets of the smart macro sidebar display the actual values of the commands, and module-specific widgets appear. You just have to interact with these widgets, hit the usual “Save to keyboard” button, and your settings will be applied immediately.

I strongly recommend you delve into these settings, as they can make a huge difference. The default sensitivity settings of the modules are reasonable, but by tweaking them to your needs, you can make them so much more usable. Maybe, just maybe, you can finally get rid of your mouse.

Advanced configuration scenarios

Besides $onInit, there’s also the “$onKeymapChange {keymapId}” macro event, such as $onKeymapChange QWR, which is executed when the QWR keymap is activated.

This event enables you to have keymap-specific settings, which allows for many advanced use cases. For example, different operating systems have different mouse sensitivity. This feature allows you to have different speed and acceleration settings for your mouse keys and modules via different operating system-specific keymaps.

Believe it or not, I’m still scratching the surface. If you really want to go crazy, you can use the set "macroEngine.extendedCommands 1" command to enable the extended macro engine, allowing for variables, loops, and countless advanced commands. If you’re comfortable with delving into manual pages, check out the extended macro engine user guide and reference manual.

Smart macros history and credit

Smart macros have an interesting history, starting out as Karel Tuček’s UHK firmware fork on GitHub.

Karel wanted special firmware features, and he originally (ab)used the text macro actions of Agent by making the firmware interpret the lines starting with the $ character as special commands. He’s essentially implemented a command interpreter in the UHK firmware that allowed for his advanced use cases.

I saw his efforts early on, and I was impressed, but I considered his work quite niche and wasn’t too interested. (In retrospect, I can see that his advanced commands are used and loved by many.)

Then it struck me that smart macros could enable the configuration of many UHK and module features without developing Agent, which is a huge win, as adding new features both to Agent and the firmware takes a ton of work. Exposing new features only via the macro engine of the firmware is so much easier. 

I came up with the idea of macro events and making smart macros a first-class citizen in Agent, then implemented the smart macro sidebar. Karel has implemented the acceleration driver of the modules, macro events, and, nowadays, pretty much everything that has to be done with firmware logic. His work is hard to overstate.

As an interesting trivia, the macro command editor of Agent might feel familiar. This is because we use Monaco editor, which also powers Visual Studio Code. In a way, Agent became an integrated development environment, supporting a special keyboard language whose interpreter runs in the UHK firmware.

The future of smart macros

I eventually want to expose basic smart macro settings, such as module settings or the LED fade timeout, not only via the smart macro sidebar but dedicated Agent widgets for better usability.

Nonetheless, we’ll keep and extend the currently available smart macro commands and settings because they allow for advanced configuration scenarios.

I plan to gradually move the extended macro commands from the current markdown macro documentation into the smart macro sidebar of Agent to make them easier to digest and not hide them behind the set "macroEngine.extendedCommands 1" command.

Closing words

To this day, we’ve released 60 Agent versions and 66 firmware versions, and we’re still going strong. I’m excited about our progress and grateful to our wonderful customers for their support. We keep moving forward because of you.

Thank you for reading this update! As usual, we plan to publish a manufacturing update around the end of the month. Stay safe!