TL;DR: Update to the newest Agent and set the backlighting of keys to your heart's desire!
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.
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:
Update 2023-08-19: Now the "LED settings" page contains the "LED fade timeout" setting, so you don't have to use smart macros to use it.
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.
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.
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.
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!
Once in a while, we get emails asking how to use macros on the UHK, so let's see how.
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.
Some of you asked how to mount your UHK to your armchair or custom-made accessories, so let us provide a drawing of the back of the UHK. The drawing features the 8 bronze inserts that allow for mounting.
Click on the image for its higher resolution version, or download the drawing in PDF or DXF format.
People ask from time to time whether we provide a numeric keypad. The answer is no, but one can create a virtual numpad very easily in Agent, the configurator application of the UHK.
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 this didn't stop our awesome customers from making / 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, and make 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 you're willing to spend more on a robust case, then Cole Chamberlain's case should be a great option which he made from a Pelican 1085 hard shell case. Check out the relevant Twitter conversation.
Although we did our best to make Agent as intuitive as possible, we get questions from time to time. By far, the most usual question is how to exchange the keys of the bottom row.
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!
We get this question from time to time, and the answer is not as obvious as one might think. I'm about to explain it in-depth, but first, I'll give you a short answer in case you're in a hurry. Please consider the relevant tooltip of Agent:
Hopefully, this explains what to do. You're welcome to suggest better phrasing in the comments, but this is the short and sweet version. And now on to the more detailed explanation.
Characters vs Scancodes
The most important thing to understand is that USB keyboards (the UHK included) do not send characters to your computer. No, Sir. They send scancodes. When you press a key, a scancode of 1 to 255 gets sent to the computer. It's not a character but a number!
Now think about this: There are 255 different scancodes that must be mapped to more than 100,000 characters that are used on planet Earth! How so? This is how:
Your operating system translates scancodes to characters based on your actual operating system keyboard layout.
Let me give you an example to make you realize the crucial role of your OS layout. Let's say that an American, a German, and a Russian user purchase USB keyboards of the same physical layout. Now let's take the semicolon key according to the American layout. On all three keyboards, when pressing this key, the scancode 51 gets sent to the computer, yet, the character ";", "ö", and "ж" appear on the screen of the American, German, and Russian users, respectively, merely because they use different OS keymaps.
When it comes to mapping scancodes to characters, the situation is actually slightly more nuanced because modifiers also affect the mapped characters. For example, on the US layout, Shift + 4 produces "$", and on the Hungarian layout, AltGr + U produces "€", but this doesn't alter the nature of the beast.
Alt codes
There's a mechanism called "Alt codes", which allows users to produce various accented characters in a way that is (mostly) independent of the current OS keymap.
On Linux, press Shift+Ctrl+U, which prefixes your cursor with an "u", indicating that a Unicode number is now expected. At this point, enter "2764" followed by Enter, and ❤ will magically get inserted. Linux Alt codes are the most powerful and standard, given that they're backed by Unicode numbers.
On Windows, first, you have to have Num Lock enabled. Then, hold an Alt key and press a Windows-specific numeric code, and finally release the Alt key, at which point the relevant character will be included. 375 different characters can be included this way, but there is a way to unlock additional Alt codes to be able to access otherwise non-typeable Unicode characters
On Macintosh, there's also a similar mechanism that is better called Accent Codes. Let's say you want to put an accent to the "o" letter. You press Option+E, then press "o," which results in "ó". The set of characters that can be produced this way is similarly limited as on Windows, although in true Mac fashion, the implementation is much more intuitive.
Alt codes provide a way to output various characters in a way that is mostly independent of the current OS keymap, but they're OS-specific, and they don't work in every environment. For example, let's say that your hard drive is encrypted, and you have to type a password before the OS boots up. Depending on your OS, Alt codes may not be available at this point. On Linux, they also can't be used in terminals outside of the X server, so you can't rely on them in every environment.
Alt codes on the UHK
Given that Alt codes are sequences of keystrokes, they're ideally suited to be assigned to keys using UHK macros. For example, you can bind the Alt code of "é" to Mod+e. UHK macros are very handy since they're saved to the on-board memory of your UHK and always available without running special software once you set them up via Agent. I'm about to elaborate on implementing Alt codes on your UHK.
The macro editor of Agent is very intuitive to use, and based on the above, one should be able to create macros that implement Alt codes. There are some gotchas, though.
First up, Alt codes are OS-specific which will pose a problem if you use multiple OSes. If so, you'll have to create all your Alt code macros for every OS you use, and then create OS-specific keymaps in Agent and bind the macros of the respective OSes. This is clearly laborious, but there's no way around it. We won't implement USB fingerprinting in the UHK firmware to detect OSes because it's fundamentally unreliable.
The second gotcha is that you won't be able to compose Alt codes with modifiers. Imagine holding Shift, then typing Alt code key sequences, then releasing Shift. Modifiers clearly mess with Alt codes.
Third, some Alt codes are dependent on the state of your OS. You have to have NumLock enabled for Windows Alt codes, and Mac accent codes are dependent on the OS keymap in use.
Accented characters in Agent
Some of you were wondering why Agent doesn't offer or display accented characters. This is one of those features that seem like a no-brainer from a user perspective, but in practice, it's not only incredibly hard to implement but cannot be implemented properly. Let me tell you why.
In order for Agent to expose accented characters, it must be aware of the current OS keymap. Being a cross-platform application, it'd have to query the actual keymap on Linux, Mac, and Windows. A quick search reveals ways to query this information (often rather obscure ways) via OS-specific APIs, but I have found no way to query the actual mappings between scancodes and characters, which is critical.
Without the exact per-key mappings, Agent would have to have a database of every single OS-specific layout, such as "French (Bepo, ergonomic, Dvorak way, Latin-9 only)" or "Russian (Ukraine, standard RSTU)". We could extract such a database from the relevant Linux packages, but these layout names are not standardized, so they're inconsistent across OSes, and the mappings surely differ in some ways.
The bottom line is that it'd take huge resources to implement the above, and we'd end up with a half-assed implementation, given that a perfect implementation is practically infeasible. Even if we were able to implement this perfectly, I don't think it would be a good idea. I can foresee users complaining that they set up the é key in Agent, then plugged their UHK into another machine (featuring a different OS keymap), and the é key suddenly became a semicolon. Users should actually understand how things work when it comes to this topic.
Scancodes vs Characters in the UHK
When remapping UHK keys, you should keep in mind that:
Agent accepts characters:
In regular actions, Agent implicitly translates characters to scancodes according to the en-US mapping (and also back whenever it needs to show the corresponding label). (So the saved configuration contains scancodes.)
In macros (the Text and Command action), Agent just leaves characters for the firmware to interpret. (So the saved configuration contains characters.)
Internally, the UHK works with the macro Text and Command actions as with regular text (i.e., characters).
However, the UHK always produces scancodes.
For regular actions, the configuration already contains scancodes, so the UHK just sends them to the computer.
If the UHK produces scancodes based on macro text (i.e., based on characters), the UHK translates them back to scancodes according to en-US mapping.
The OS transforms scancodes (received from the UHK) back to characters according to its current language keymap.
That's it, folks! If you're still reading, then you're truly one of the brave few. Any questions, feel free to shoot them in the comments.
Custom scancodes
You can specify custom scancodes on the UHK. See how.
