Repetitive strain injury + MacOs + Generic Keyboard ( tips + mapping )

8 min readDec 22, 2017

How to map generic usb keyboard on MacOs ?

Hello ladies and gentlemen,
as every user of Apple computers (MacBook) or keyboards (wireless or wired magic keyboard), i have been aiming several troubles while using Apple wired / wireless keyboard after several months.

This issue is not mechanical or functional — it is called “RSI — Repetitive Strain Injury”. What is RSI ? Let’s take a look at Wikipedia :

A repetitive strain injury (RSI) is an “injury to the musculoskeletal and nervous systems that may be caused by repetitive tasks, forceful exertions, vibrations, mechanical compression, or sustained or awkward positions”. — Wikipedia.org

So, let’s keep it simple, this injury is caused by non-ergonomic workflow, work enviroment or device — in my (our) case keyboard. Pain started to be more and more intensive and my efficiency while coding has been lowered to watching youtube videos every 30 minutes.

What are symtoms of RSI ?

“Some examples of symptoms experienced by patients with RSI are aching, pulsing pain, tingling and extremity weakness, initially presenting with intermittent discomfort and then, with a higher degree of frequency.” — Wikipedia.org

Again wikipedia saved us and now we know if we are facing this awesome injury caused by non-ergonomic anything. Best solution is new keyboard ( or / and mouse). I had awesome lovely backlighted mechanical keyboard HyperX FPS Alloy Red — I loved this keyboard until i sold linux beast desktop, and started using Mac-only.

Troubles with Generic USB Keyboard

Ok, what’s basic difference in keyboard layout of Apple keyboard and Generic USB Keyboard which is working on Windows and /usually / same for linux.

This issues in keymap are usually problem for people which are using non-english layout — as me, because i started coding with Slovak keymap 10 years ago, it’s much more comfortable to use Alt for special characters than type on English layout and being forced to switch language everytime when i gonna reply to customer’s e-mail or write some texts on web in Slovak ( we have some cool chars like Ň,Č,Ž,Ď,Á,É,Í,Ó,Ä,Ô.. ) gramatically correct.

Comparation of layout Apple keyboards, Generic USB keyboard

First main difference is that

Modifier keys on Generic USB Keyboard are

Control, Windows ( Super ), Alt, Space, Alt, Windows ( Super ), Menu, Control

Modifier keys on Apple Keyboard are

Control, Alt, Command ( Super ), Space, Command ( Super ),Alt

If you want to know how to change them, and how to remap your keyboard and solve issues, continue reading or just scroll down down down :)

Apple wireless keyboard — English UK (ANSI)

Apple wireless keyboard — English UK (ISO)

And for comparation i also going to show you Slovak layout, so in case you have same problems you will know what to do after reading this ;)

Apple wireless keyboard —Slovak SK (ANSI)

Apple wireless keyboard — Slovak SK (ISO)

As you see on Slovak ISO layout, there is backslash and pipe key left of the y key. This is my issue — pipe and backslash i use a lot when coding,especially when you are writing namespaces in php or escaping chars.

Reallity of physical keyboard is, that ISO keyboard usually don’t have backslash left of Y key. So this key is missing if you are planning to use it on mac.

3 Things to look for before buying new keyboard

Check layout of modifier keys, lot of keyboards have layout like this :

Control, Super, Alt, Space, Alt, Fn / usually for backlight contol /,Menu, Control

So first thing have been — keyboard with layout

Control, Super, Alt, Space, Alt, Super, Menu, Control.

2. Ergonomical shape — To prevent RSI you need ergonomic keyboard or at least right height, so your wrists will not suffer.

3. Size — Size matters, for ergonomic workflow you need right size of keyboard, mouse pad and mouse, distance from LCD Screen(s), height of LCD(S), angle while typing, chair, position, and habits — you can google a lot about this topic.

How to setup Generic USB keyboard on MacOs

Requirements

Mac
Generic USB Keyboard
Application for creating custom keymaps Ukelele ( Download here )

Preparation

After installation of Ukelele, and copying resources to disk .Let’s start with modificators setup.

So we want our keyboard layout closest to Mac/Book/ keyboard, because this way we dont’t have to switch our brain to “oh it’s macbook so don’t forget it’s different”

Go to Apple icon on top-bar, click on “System preferences…”
Click on “Keyboard”

3. Click on button “Modifier keys”

4. Choose USB KEYBOARD or simply other option than internal if you are using macbook, if not, until you have connected your apple keyboard there will be just one option.

5. Set modifiers like this, or change it by you if you preffer different setup.

6. Abraka dabra ! This is done.

7. (Optional) physically replace keycap / plastic piece which you press — key / — switch Windows (Super) key with Alt

So as you can notice from settings, windows key is command, alt is option, and ctrl is control.

Layout customization and editing with Ukelele

So best workflow is to set keyboard layout you want to modify as active :

Select your base keyboard “language” which we gonna fix or modify

In case you don’t have this icon in bar, just go to System preferences > Keyboard > Tab “Input Sources” and check “Show Input menu in menu bar”

Now open Ukelele, and close blank keyboard
And click “File > New From Current Input Source“

You will see window like this :

In my case it’s “Slovak copy” in your case it will be your lang. + “ copy”

Right click on item and select “Set Keyboard Name and Script” :

Set Name of your layout, and Script i chosen “Unicode”. It’s smart to use different name on your layout than original one.

Unicode — You really should use this in almost all cases.

After few experiments and tests i ended up like this :D

So your input sources will after playing around don’t look like this :)))

Now double click our item.
Go to View > Keyboard Type > Choose “ USB pro Keyboard”
Don’t forget to set right Coding, if you are from USA / CA and keyboard is for your market, it’s higher chance you will have ANSI, if you are from Europe you will have ISO, and if you are from Asia you will have JIS.
Also check type of your keyboard while it’s configured by MacOs Keyboard Assistent ( you can always change this by clicking “Change Keyboard Type..” in Keyboard settings ):

But of course, problem with your mapping could be because of wrong “keyboard manufacture” as i had experience with some +- 50€ ( approx. 59USD ) keyboards — manufactor decided to use magic method for ctrl and alt modifier keys, it worked only with driver deployed with keyboard, and while trying to map it on linux with several utilities — output keycode been eq. to SHIFT
You will see something like this

Now in case we have key which is giving different output than predicted one, simply press it — if you see change of color for that key, it means keycode is right,

as i tried key under escape — when keyboard is set as ANSI have been “50” and ISO as “10” and because my keyboard is ISO — with ANSI there have been no mapping for it.

If there is no key color change on press, there is high chance you have bad type — Try to change ANSI to ISO or vice-versa

If our key press is registered — let’s edit it’s value.