How can I type accented characters with my UHK?

How can I type accented characters with my UHK?

We get this question from time to time, and the answer is not so obvious as one might think. I'm about to explain it in depth, but first I'll give you the 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 a 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 which 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 of the screen of the American, the German and the 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 now a unicode number is expected. At this point, enter "2764" followed by Enter and ❤ will magically get inserted. Linux Alt codes are the most powerful and most 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. Merely 375 different characters can be included this way.
  • 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 very handy, since they're saved to the on-board memory of your UHK, and always availblable 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 laborous, 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, eronomic, 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 semicolon. Users should actually understand how things work when it comes to this topic.

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.

By |2018-10-30T19:43:14+00:002018-06-23 23:55|agent, howto, tech talk|28 Comments
Increase your productivity by never leaving the home row. Improve your posture by typing on two, separate keyboard halves. Remap keys in any way you want. Experience how a keyboard can be different, yet familiar.


  1. Jimmy June 24, 2018 at 12:09 pm - Reply

    If I understand this correctly you are saying this isn't possible yet? I first tried to bind the Ö character to ; as per your tooltip but that does just output ; . So basically we should just build macro's but they aren't supported yet. I like the macro idea so I hope it gets implemented soon. because now the keyboard is kinda working half for me ( I have too google the accented characters about 200 times a day)

    • László Monda June 24, 2018 at 2:09 pm - Reply

      How exactly did you enter accented characters so far with your other keyboards?

      • Jimmy June 24, 2018 at 2:12 pm - Reply

        I used azerty layout. They are on the keyboard itself (usually using alt gr + key)

        • László Monda June 24, 2018 at 2:33 pm - Reply

          Then why aren't you doing the same on your UHK? AltGr is just right Alt.

  2. Walther June 24, 2018 at 2:04 pm - Reply

    For completeness, you missed the best way of typing special characters on linux: AltGr+DeadKeys:
    RightAlt + ' and then e becomes: é
    RightAlt + = and then e becomes €
    Of course this is limited to the character that are built up of two other characters, but I find this the most intuitive way.

    • László Monda June 24, 2018 at 3:37 pm - Reply

      Thanks for mentioning! Dead keys are very handy, and they're more intuitive to invoke than Alt codes, but they're dependent on the actual OS keymap.

      • Tor July 12, 2018 at 11:55 pm - Reply

        I've been rather happy with the ISO UHK, and using the left control as the compose key (also Linux). The dead key layouts I've tried don't mandate a chorded key to activate, so I find myself missing characters or getting one wrong character in place of two that way. This seems to be three keystrokes instead of the two key chord and a keystroke in your method, so it doesn't matter much.

        I did have to get used to the ISO shift being something other than shift for times when I just needed a command. For touch typing I never used that part of shift in the first place, so that was perfectly fine for me.

  3. Jimmy June 24, 2018 at 3:19 pm - Reply

    As you can see in this image , the azerty layout has the accented keys on the keyboard itself. For the UHK I switched to the qwerty layout, I assume my problem isn't related to the usage of the UHK but to the qwerty layout.

    • László Monda June 24, 2018 at 3:29 pm - Reply

      Yes, your problem is clearly related to the QWERTY OS layout. You will be able use accented characters with your UHK just as with your other keyboards when using the AZERTY OS layout.

      Did you actually read this article? I'm asking because because I'm trying super hard to help people like you and spent hours writing this article, but according to your follow-ups you didn't even read it.

      • Jimmy June 24, 2018 at 4:15 pm - Reply

        I have read the article and most things in it are clear to me. I also understood from it that we are basically waiting for the macro functionality to have an easy way to rebind it with the unicode setup ( I am using Linux).

        I apologize for asking this question the wrong way. I assumed at first the problem was related to the UHK but now I realize it was because I selected the keyboard layout wrong. I have now switched to a keyboard layout that supports all the characters I need an is still qwerty. I never even knew this was a thing, because I typed azerty all my life.

        I am happy with my UHK now and thank you for the article explaining it in detail.
        Keep up the good work!

        • László Monda June 24, 2018 at 4:22 pm - Reply

          Thank you for the clarification! We'll do our best to implement macro support soon. We're glad you're happy with your UHK!

    • Loïc Lacombe July 26, 2018 at 7:14 am - Reply

      I am a french azerty user too and I solved all my UHK issues with the qwerty-fr keyboard layout ( It is basically a qwerty layout but with our beloved french Alt-Gr layer to make all french special characters available.The layout is meant to be quite intuitive once you have grasped its phylosophy.

      • Jimmy October 9, 2018 at 12:58 pm - Reply

        I haved used the layout you suggested now for a few months, this is a very good solution and I love it. Thanks

  4. srm September 11, 2018 at 1:11 pm - Reply


    This keyboard is close to the perfection for me.
    But, not be able to setup a full-set like Bepo is really a deception for me.
    Maybe you can add solution for guys like me, even a very hacky solution, for example a solution to allow me upload differents exact per-key mappings for my needs and then allow me to customize every key to setup a Bepo

    • László Monda September 11, 2018 at 10:15 pm - Reply

      Hi there! I assume Agent issue 617 would solve this problem for you, right? We'll make it happen, but no ETA yet.

      • Tor September 11, 2018 at 10:29 pm - Reply

        For right now, the workaround is to steal the Fn layer (or whichever one you use least) to use for shifted characters. Caps lock, if it changes things oddly, can be done as a separate keymap. It occurs to me that you can probably make another keymap to replace the layer you steal.

        This layer workaround does behave a little oddly in terms of trying to use the mouse with shift and certain key combinations are order-sensitive when they should be, but for the most part it works quite well.

  5. Yasukawa October 8, 2018 at 1:29 am - Reply

    I want to set key by Usage ID.Because Japanese Key mapped UsageID 88h ~ 8Ah.

    • László Monda October 10, 2018 at 5:41 pm - Reply

      The next Agent release will contain international scancodes. You will be able to select them in the "International" section of the scancode selector. The scancode names themselves will be general, and won't be very descriptive, such as "International 1" or "Language 2", but there won't be many of them, so it'll be easy to find the one you're looking for by experimenting a bit. There's no solid ETA on the upcoming Agent release. Please keep checking the page. The new release will be the one after 1.2.11.

      • Yasukawa October 12, 2018 at 12:15 pm - Reply


  6. Holger November 15, 2018 at 2:50 pm - Reply

    This is so heartbreaking xD I searched the universe and back for the perfect keyboard.
    Mechanical, Ergonomic, DE Layout…I just can't tick all the boxes this is so frustrating…why did I have to be born a german -.-

    • László Monda November 15, 2018 at 6:03 pm - Reply

      We'll eventually provide German keycaps, but no ETA yet. In the meantime, blank may fit your needs, and it should keep away all the people who can't touch type. :)

      • Holger November 16, 2018 at 7:47 am - Reply

        hmmm…2019? If it is 2019 I guess I wait…I have too many cooperative cooding sessions at my desk xD

      • Tor November 16, 2018 at 8:26 am - Reply

        If getting close will do, WASD Keyboards will do fully custom printed keycap sets, and have told me they can handle the UHK layout, except some substitution will have to be made for space and backspace. For those keys you'll have to either use the not-quite-matching original UHK keys (what I plan to do when I get around to actually getting a set printed myself), or you can see what options they do have.

    • Philipp December 14, 2018 at 11:51 am - Reply

      Hi Holger, I had similar problems and even had to dig into QMK-coding in order to be able to type proberly (my own christmas gift to myelf will tell whether I was successful). The way I understand it the UHK will work out of the box, only the keycaps might be off.
      As a fellow german programmer you should definitely check out the NEO-2 layout on Just use it in your free time for checking emails in the evening and within a month you will be able to type as fast as with QWERTZ, but with way more pleasure while programming as you never have to leave the home row again for brackets or numbers.

  7. Holger November 16, 2018 at 8:43 am - Reply

    I'm still new in the Mechanical keyboard comunity. I thought the main problem would be handling the QWERTZ layout because it's so different from the QWERTY.
    Keys like {[]} that I use most often as a programmer are all on the number keys.
    I also thought I should learn the normal ISO layout because {[]} is easier to access in QWERTY layout and QWERTY is not as big a change as DEVORAK would be.
    QWERTY in general has so much more support in terms of mechanical keyboards…

    • Tor November 16, 2018 at 11:22 pm - Reply

      With keyboards, there are two completely separate issues with layouts. What I understand now to be the significant one is what the computer shows for a given typed key. The only difference between the various country specific ISO layouts is the keycap printing. They all send the same scancode for the same physical key, and the computer is set to the relevant country code to make the keyboard legend match what shows up on the computer. If you tell the computer the UHK is a German layout keyboard, it will act like one, regardless of the legends.

      What the UHK programming does (and is still a WIP), is to allow you to send different scancodes for a given key so you can plug a UHK into a computer expecting one keycap printing, and have it act as if it is a different keyboard, for example, being able to plug the UHK into a computer expecting a UK English ISO keyboard, and have it send the scancodes so it acts like a German layout keyboard.

      For your own keyboard, if you touch type, the labels on the keycaps probably don't matter much, and it should be plug and play on your computer. Just tell your computer the keyboard is your German layout, if it doesn't automatically assume so. If you want a German printed keycap set right away, there are some potential options listed above and linked in recent blog posts.

      • Holger November 17, 2018 at 5:40 am - Reply

        Really?!?!?! That Sounds perfect! I was a little confused because I wasn't sure that I that would be the case. So if don't modify anything it will work out of the box with PC or mac and as soon as there are German key caps I can just switch them…now that solves it ^^ thanks

        • Jan Christoph December 15, 2018 at 12:58 pm - Reply

          Yes, it works that way. I'm also German and use it the same way.

          My main OS layout is Colemak and my main UHK layout is QWERTY. German characters I type with the Linux compose key (AltGr + " + a → ä). If I want to type German characters without the compose key I change my OS to QWERTZ layout, UHK layout stays on QWERTY all the time. BTW, for Windows I use a little tool called WinCompose ( that emulates Linux' compose key functionality so that I don't have to adapt to the OS I'm using.

          The UHK layout comes in handy when I use it with my phone. I set the UHK layout to Colemak which is more convenient than switching Android to Colemak.

          .. and I can reassure you that the UHK is the perfect keyboard :-D

Leave A Comment

Ultimate Hacking Keyboard


On Your Ultimate Hacking Keyboard