KoReader supports key mapping, i.e. associate different actions to physical buttons (for devices such as Kobo, PocketBook, etc.).

You need to create the file (if it doesn't already exist) koreader/settings/event_map.lua. There you can edit key bindings. For each button, an integer key is associated to an event. The format of the file is as follows:

return {
   [<Integer key for button A>] = "<Event X>",
   [<Integer key for button B>] = "<Event Y>",
   [<Integer key for button C>] = "<Event Z>",
   ...
}

Each vendor defines its own set of keys associated to the physical buttons. See vendor specific examples below.

A more generic way is to check the logs associated with pressing button events.

The keys for Kobo devices can be found in frontend/device/kobo/device.lua:

event_map = {
    [59] = "SleepCover",
    [90] = "LightButton",
    [102] = "Home",
    [116] = "Power",
    [193] = "RPgBack",
    [194] = "RPgFwd",
},

For instance:

• the key 102 corresponds to the Home button
• the key 193 corresponds to the Back button
• etc.

For PocketBook devices, the device keys used in frontend/device/pocketbook/device.lua are defined in ffi/inkview_h.lua (which can be found under the koreader/koreader-base project):

event_map = setmetatable({
    [-C.IV_KEY_HOME] = "Home",
    [-C.IV_KEY_MENU] = "Menu",
    [-C.IV_KEY_PREV] = "LPgBack",
    [-C.IV_KEY_NEXT] = "LPgFwd",
    [-C.IV_KEY_UP] = "Up",
    [-C.IV_KEY_DOWN] = "Down",
    [-C.IV_KEY_LEFT] = "Left",
    [-C.IV_KEY_RIGHT] = "Right",
    [-C.IV_KEY_OK] = "Press",
},

static const int IV_KEY_0 = 48;
static const int IV_KEY_1 = 49;
static const int IV_KEY_2 = 50;
static const int IV_KEY_3 = 51;
static const int IV_KEY_4 = 52;
static const int IV_KEY_5 = 53;
static const int IV_KEY_6 = 54;
static const int IV_KEY_7 = 55;
static const int IV_KEY_8 = 56;
static const int IV_KEY_9 = 57;
static const int IV_KEY_BACK = 27;
static const int IV_KEY_COVERCLOSE = 3;
static const int IV_KEY_COVEROPEN = 2;
static const int IV_KEY_DELETE = 8;
static const int IV_KEY_DOWN = 18;
static const int IV_KEY_HOME = 26;
static const int IV_KEY_KEYBOARDCLOSE = 16;
static const int IV_KEY_LANGUAGECHANGE = 15;
static const int IV_KEY_LEFT = 19;
static const int IV_KEY_MAX = 32;
static const int IV_KEY_MENU = 23;
static const int IV_KEY_MENU_POWER = 4;
static const int IV_KEY_MINUS = 21;
static const int IV_KEY_MUSIC = 30;
static const int IV_KEY_NEXT = 25;
static const int IV_KEY_NEXT2 = 29;
static const int IV_KEY_OK = 10;
static const int IV_KEY_PLUS = 22;
static const int IV_KEY_POWER = 1;
static const int IV_KEY_PREV = 24;
static const int IV_KEY_PREV2 = 28;
static const int IV_KEY_RIGHT = 20;
static const int IV_KEY_SHIFT = 14;
static const int IV_KEY_UP = 17;
static const int IV_KEY_ZOOMIN = 7;
static const int IV_KEY_ZOOMOUT = 6;

NOTE: the use of negated values when declaring the mapping (to avoid conflicts with the standard Linux keycodes).

1. Enable the verbose logs

• Check Settings > More tools > Developer options > Enable debug logging
• Check Settings > More tools > Developer options > Enable verbose debug logging

2. Press each button on your device
3. Open the koreader/crash.log file
4. Search for lines with the following pattern: DEBUG key event

For instance, pressing the Menu, Previous page, Next page and Home buttons on a PocketBook device generates the following lines in the log file:

...
11/16/24-11:12:45 DEBUG key event => code: 23 (Menu), value: 1, time: 1731751992.873064 
...
11/16/24-11:12:40 DEBUG key event => code: 24 (LPgBack), value: 1, time: 1731751987.199226 
...
11/16/24-11:12:41 DEBUG key event => code: 25 (LPgFwd), value: 1, time: 1731751988.055044 
...
11/16/24-11:12:53 DEBUG key event => code: 26 (Home), value: 1, time: 1731752000.164119 

A common use-case for changing key mapping is to invert the Next page and Previous page buttons.

Important note: recent versions of KoReader have a built-in feature for inverting page turn buttons (under Settings > Navigation > Physical buttons > Invert page turn buttons), so this key mapping trick is now obsolete.

For inverting page turn buttons, simply swap the keys associated with the "RPgBack" and "RPgFwd" events.

Kobo example:

return {
    [194] = "RPgBack",
    [193] = "RPgFwd",
}

More info on this can be found here.

One example is shown here, with example below:

return {
    [42] = "Back"
}

event_map.lua is limited to associating predefined actions with each button. It is however possible to create customized actions, but this requires patching the KoReader code. See this discussion for more details.