Keyboard

Remap the right Shift key and/or the 🠝 (Up arrow) key

A common request is to remap the right Shift key and/or the 🠝 (Up arrow) key.

You can remap either key to the other, or apply both mappings to swap the two keys.

This does not change the special functions for either key - Fn+🠝 (Up arrow) still produces Page Up, and Fn+right Shift still presses Fn Tg.

1. Get purism_ectool:

   1. Download purism_ectool from firmware tools, and save it in your Downloads folder.

   2. Open a terminal.

   3. Change to Downloads and prepare the tool: cd ~/Downloads && gunzip purism_ectool.gz && chmod a+x purism_ectool

2. Optionally, remap the right Shift key to produce 🠝 (Up arrow):

   1. Invoke purism_ectool: sudo ./purism_ectool keymap 0 6 0 0x175

   2. sudo may prompt for your password. If so, type your password and press ⮠ Enter. Nothing is shown on the screen while typing (not even dots), for security reasons.

3. Optionally, remap the 🠝 (Up arrow) key to produce right Shift:

   1. Invoke purism_ectool: sudo ./purism_ectool keymap 0 2 1 0x59

Remap any keys

Librem EC supports remapping the keyboard keys. You can change the key codes produced by each physical key.

To change a physical keys key code:

1. Identify the key layer:

   • The key layer is 0 for the key’s normal function (without Fn), or 1 for the key’s special function (with Fn).

   • Some keys do not have a special function by default, such as most letter keys.

   • In that case, both the normal and special function produce the same key code.

   • You can change the key’s code for each layer if you want to reassign both.

2. Identify the key’s physical position:

   • The physical position is the key’s location in the key matrix.

   • Look at the key matrix below and find the output and input numbers corresponding to that key.

3. Choose a new key code:

   • Review the scan code values and find the numeric value of the desired key code.

   • The numbers are in hexadecimal and start with 0x.

   • For keys that combine other values with |, add the two values.

   • For example, K_UP is KF_EO | 0x75, which results in 0x0175.

4. Get purism_ectool:

   1. Download purism_ectool from firmware tools, and save it in your Downloads folder.

   2. Open a terminal.

   3. Change to Downloads and prepare the tool: cd ~/Downloads && gunzip purism_ectool.gz && chmod a+x purism_ectool

5. Remap key(s):

   1. Invoke purism_ectool: sudo ./purism_ectool keymap <layer> <output> <input> <keycode>

   2. For example: sudo ./purism_ectool keymap 0 2 1 0x59

   3. sudo may prompt for your password. If so, type your password and press ⮠ Enter. Nothing is shown on the screen while typing (not even dots), for security reasons.

   4. Repeat for each key that you want to remap.

Reset the key map

You can reset the key map to the factory defaults.

1. Shut down the computer (if turned on):

   • If the key map prevents you from shutting down the computer, you can plug in a USB keyboard temporarily.

   • If this is also not available, you can hold the ⏻ (Power) key for 4 seconds to force the system off, but this will lose all unsaved work.

2. Unplug the AC adapter, if plugged in.

3. Wait 10 seconds.

4. Hold down Fn+Esc.

   • Hold down the keys with Fn and Esc printed on them, even if you remapped those functions.

5. Press the ⏻ (Power) button to turn on the system.

6. When the power LED lights, release all three keys.

The key map is now reset to the default. This also resets the EC’s other settings, including the battery charge thresholds.

Librem 14 key matrix

	Input 0	Input 1	Input 2	Input 3	Input 4	Input 5	Input 6	Input 7
Output 0	___	K_RIGHT	___	K_PRINT_SCREEN	K_DEL	___	___	___
Output 1	K_QUOTE	K_ENTER	___	___	K_EQUALS	K_BKSP	K_BRACE_CLOSE	K_BACKSLASH
Output 2	K_SLASH	K_UP	K_MINUS	K_F12	K_0	K_P	K_BRACE_OPEN	K_SEMICOLON
Output 3	___	K_LEFT_CTRL	___	___	K_RIGHT_CTRL	___	___	___
Output 4	___	___	K_F8	K_F9	___	___	___	K_LEFT
Output 5	K_COMMA	___	K_F7	K_F6	K_F5	K_8	K_I	K_K
Output 6	K_RIGHT_SHIFT	K_LEFT_SHIFT	___	___	___	___	___	___
Output 7	K_PERIOD	K_DOWN	___	K_F11	K_F10	K_9	K_O	K_L
Output 8	K_M	K_N	K_H	K_Y	K_6	K_7	K_U	K_J
Output 9	K_V	K_B	K_G	K_T	K_5	K_4	K_R	K_F
Output 10	K_X	K_Z	K_F2	K_F1	K_ESC	K_2	K_W	K_S
Output 11	K_C	K_SPACE	K_F3	K_F4	K_CAPS	K_3	K_E	K_D
Output 12	K_RIGHT_ALT	K_LEFT_ALT	___	___	___	___	___	___
Output 13	___	___	KT_FN	K_TAB	K_TICK	K_1	K_Q	K_A
Output 14	___	K_LEFT_SUPER	___	___	___	___	___	___
Output 15	___	___	___	___	___	___	___	___