Agent and the UHK firmware have been getting increasingly powerful, but we haven't done a good job showcasing these capabilities. Luckily, John came to the rescue and created an excellent YouTube tutorial featuring the following points:

• 00:00 What are smart macros?
• 01:02 Dual function backtick
• 02:58 Special macros for initialization and keymap changes
• 03:55 OS-specific settings by keymap
• 04:47 Capslock shift
• 05:38 Record macro and playback to avoid tedious repetition
• 06:31 Reassign keymap during alt-tab to close apps with one hand
• 07:52 Function keys EVERYWHERE
• 09:04 Delete line and easy-to-use macro wizard form
• 09:24 Mouse jiggler to avoid screen timeouts
• 10:48 Gaming macro shift walk tap or hold
• 11:25 One shot modifier for fluid typing
• 11:58 Creating your macros, community support, and GPT4

John has also made these macros available on a dedicated GitHub page, so you can easily copy-paste them into Agent.

Speaking of Agent, we've been adding some new features worth mentioning, especially in the context of smart macros. See the following screenshot.

As you can see, we've added syntax highlighting and autocomplete. Autocomplete is thoroughly implemented, using the actual grammar and a generic parser. As such, its completions should be close to 100% contextually accurate. It's also worth mentioning that Agent pulls the grammar of the exact firmware revision actually used.

Agent also displays the error of a macro I intentionally made when saving the configuration. Clicking on the error makes the cursor jump to the relevant position of the affected macro. Thanks to these improvements, writing your macros is easier than ever.

Smart macros are a big deal because they enable features traditionally only possible with QMK and ZMK in a highly integrated manner without installing a toolchain. If you want to learn more about smart macros, the following resources should be useful:

• smart macro user guide - a light introduction to basic concepts, including many examples
• smart macro reference manual - an exhaustive (although dry and formal) list of all commands
• The forum's "my configuration" and "configuration question" categories contain many examples and are the place to share your ideas and get help with their implementation.
• Agent has an integrated, interactive smart macro reference that mostly describes configuration commands. See the "smart macro reference" tab on the right side of the previous screenshot. This side pane will eventually include all the smart macro documentation.

Finally, I want to share two recent UHK reviews. The first was made by John, and in his true style, he's done a deep dive featuring Riser, the palm rests, the modules, the keycaps and switches, and many layout-related and smart macro-related topics, even gaming.

Evan has also made a UHK review, largely featuring the ergonomic benefits and accessories of the UHK, especially the modules.

That's it for now! I hope you found this update useful. Talk to you later!

The UHK 60 v2 has been supporting functional backlighting from the get-go, which is loosely speaking per-key backlighting, but functional backlighting colors are tied to the configuration of keys, so it hasn't been possible to set colors independently of key mappings until now.

Let's see how to use Agent's new and shiny (pun clearly intended) per-key backlighting feature.

First, update to the newest Agent and let it update your firmware.

Next up, navigate to the new "LED settings" page.

In the "Functional backlighting colors" section, you can adjust the eight functional backlighting colors if you want to stick to functional backlighting.

The newly added "LED fade timeout" option disables the LEDs after the specified idle interval. (This option has been available as a smart macro variable).

If you want to finally switch to per-key backlighting, choose the "Per-key backlighting" option in the "Backlighting mode" section of the page and check out one of your keymaps.

As you can see, there's a color palette on the top of the page, and by default, all keys are white. Now let's pick a color and start painting.

When hitting the "Save to keyboard" button, the colors will be updated on your UHK. Key colors are saved per keymap and per layer.

You can easily add new colors, adjust existing colors, and remove any colors. Just hover over the palette, and read the instructions in the tooltips.

When the paint mode is inactive (none of the colors are checked), you can drag key colors to the palette to overwrite existing palette colors or add new colors.

Talk to you later!

First up, add the Shift layer to your keymap:

On the Shift layer, map the 1 key to Ctrl+C:

The modifier layer (in this example, the Shift layer) automatically becomes active when you press the relevant modifier key. If a key on the modifier layer is unmapped, the UHK will fall back to the base layer and compose its mapping with the modifier.

You're probably already done, but there's one more thing. By default, modifier layers can be activated by both left and right modifiers. If you want to use only the left or right modifier to activate a modifier layer, you can change the modifier layer triggers via smart macros:

You're done!

Some of you want your UHK to automatically turn off its LEDs after some idle time, which can be configured by setting the leds.fadeTimeout smart macro variable in the $onInit macro as follows.

You can learn more about smart macros.

We realize that this setting is not as accessible as it should be, and we'll make it easier to adjust it in later Agent versions.

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!

First up, the macro has to be created. You can see some default macros under the Macro section of the sidebar. You can add new macros with the plus button.

Second, you have to assign the macro. You can assign a macro to any key of any layer of any keymap. Let's say you want to assign the "Go to UHK site in browser" macro to the Q key of the Fn layer of the "QWERTY for PC" keymap. This way, the macro can be triggered via Fn+Q.

To assign the macro, simply go to the target keymap, choose the target layer, and click on the target key. Then the key action popover will appear. Click on the Macro tab, choose the desired macro, click on the "Remap key" button, and finally click on the "Save to keyboard" button that appears in the bottom right corner.

You've made it! Happy macroing!

Click on the image for its higher resolution version, or download the drawing in PDF or DXF format.

See additional CAD files at https://github.com/UltimateHackingKeyboard/cad

See the following screenshot. The numpad is mapped to the Fn layer, and its keys are laid out in a familiar fashion.

The big advantage of a virtual numpad is that one doesn't have to reach out all the way to the other side of the keyboard. This results in increased productivity, and the mouse is much closer, too. That is, if you even use a mouse after mastering the UHK mouse layer.

As a last word, make sure you have Num Lock enabled, otherwise your numpad keys will function according to their bottom function, like Home instead of 7 and such. You can map Num Lock to any key of your UHK.

We don't plan to offer a carrying case, but that hasn't stopped our awesome customers from making and buying some amazing cases for their UHKs. Let's see some of these cases!

UHK case

If you have a UHK without a UHK palm rest, then look no further than @contracode's case. Be sure to check out his tweet for instructions.

UHK + Palm Rest soft case

If you have a UHK with a palm rest, then Stephen Walsh's case is probably the best choice for you. See his tweet.

Since writing this article, @z0nelevel let us know that the UHK and the palm rest fits into many 13 inch notebook cases like this one:

UHK + Palm Rest hard case

If you have a UHK with a palm rest and are willing to spend more on a robust case, then Cole Chamberlain's case should be a great option, as he made it from a Pelican 1085 hard-shell case. Check out the relevant Twitter conversation.

Further cases

• https://twitter.com/ClemensScharti/status/1188505514289876992

We've never ceased to be amazed by the ingenuity of our customers. If you have further case ideas, feel free to post a comment about them!

Let's say you want to exchange Alt and Fn.

Now select the base layer of your default keymap in Agent. You should see something like this:

The important thing to understand is that each key has an associated action. Let's click on Alt.

A popover appears that contains the type and properties of the action. The Keypress tab is active, so this is a keypress action (type) featuring no scancode and the left Alt modifier (properties).

Now let's see the action of the Fn key by clicking on it.

Now the Layer tab is active, which means that it's a layer switch action that activates the Fn layer while holding this key.

You simply have to exchange the actions of the Alt and Fn keys by clicking on them and setting their action type and properties. Make sure to check the "Remap on all layers" checkbox for modifier keys before clicking on the "Remap key" button.

Lastly, click on the "Save to keyboard" button in the bottom right corner.

Last but not least, you can play with the web demo of Agent in the browser without installing it on your computer. Give it a try!

That's about it! Happy remapping!