Keyrah V3

Keyrah V3

Overview

Keyrah V3 is the revised version of our popular Keyrah interface. Keyrah V3 allows you to connect the keyboards of classic computer systems like the Commodore 64 or the Amiga 1200 to modern computers (e.g. PC, Mac, or the Raspberry Pi) via USB. It also supports digital joysticks and analog paddles of such classic systems, which will be converted to standard HID game controllers. Supported systems with this model are:

• Commodore C64 (all models)
• Commodore SX-64
• Commodore VIC-20 (VC20)
• Commodore C16
• Commodore C128D
• Amiga 1200
• Amiga 600
• Amiga 500
• Amiga 4000/CDTV
• Atari ST (8-pin connector only)
• PC XT / PC AT (PS/2)

The following systems can be made compatible by mounting additional connectors on the circuit board, or using adapters:

• Commodore C128
• Commodore C116
• Commodore Plus/4
• Commodore PET (8296) (Adapter Schematics)
• Commodore CBM2 (B-Series) (Adapter Schematics)
• Amiga 2000/3000 (with PS2 adapter)

Keyrah V3's switch allows you to switch between the standard and a keymap geared towards emulation. It looks and feels like the original power switch of the Commodore 64, adding a third switch position that allows you to send an ACPI signal to shut down/power up your computer. To avoid triggering the shutdown procedure by accident, this third position is not locked, so the switch will always flip back from it if not held in place. For further safety, the ACPI signal is only sent to the computer after being held in this position for five seconds.

Manual

• The Short Manual that is included in the Package (german and english)
• Full User Manual (english)

Support

• english support forum
• german support forum

Making a custom keymap (Example)

The following was derived from this forum thread and may serve as an example on how to produce a custom/alternative keymap.

Generally please refer to chapter 3.7 (and following) of the above manual. In particular make sure you understand the layout of the binary data, which is described in 3.7.1 (four blocks of data, each containing 3 keymap layers). The Keymaps contain a binary array (8 bytes per row), the content is described in 3.7.2 and following, the values are the USB HID keycodes.

In this this case we want to change the "ALT" key into the "Option" key used by macOS, in the keymap used for the C64 keyboard.

• Pick the 4 cbm keymaps, and merge them into one file in the following order (see 3.7.1): cbm_us.bin, cbm_us_emu.bin, cbm_de.bin, cbm_de_emu.bin. If you insert 1kiB of zeros instead of one of those files, that particular configuration will remain unchanged.
  • On Windows use something like copy cbm_us.bin /b + cbm_us_emu.bin /b + cbm_de.bin /b + cbm_de_emu.bin /b keyrah_custom.bin /b
  • On Linux or macOS use something like cat cbm_us.bin cbm_us_emu.bin cbm_de.bin cbm_de_emu.bin >> keyrah_custom.bin
• The tables in 3.7.1 show the basic layout of the resulting file
• Find the key you want to remap in the table for your keyboard in 3.7.2 (CBM is row 7, column 5)
  • It helps a lot if the hex editor you are using allows to configure how many bytes per line it shows - set that to 8, so each row in the hex editor will show one row of the matrix. It will look similar to the following:

0000:0000 | 2A 28 4F 51  3A 3C 3E 40 | *(OQ:<>@
0000:0008 | 20 1A 04 E1  1D 16 08 21 |  ..á...!
0000:0010 | 22 15 07 1B  06 09 17 23 | "......#
0000:0018 | 24 1C 0A 19  05 0B 18 25 | $......%
0000:0020 | 26 0C 0D 11  10 0E 12 27 | &......'
0000:0028 | 2E 13 0F 36  37 2F 31 2D | ...67/1-
0000:0030 | 35 33 30 38  E5 34 4E 4A | 5308å4NJ
0000:0038 | 1E 29 E0 2B  2C E2 14 1F | .)à+,â..
0000:0040 | 2A 28 35 33  3A 3B 3C 41 | *(53:;<A
0000:0048 | 51 13 0F 36  37 2F 2D 52 | Q..67/-R
0000:0050 | 50 34 30 38  29 31 2E 4F | P408)1.O
0000:0058 | 1E 2B E0 00  2C E2 14 1F | .+à.,â..
0000:0060 | E6 62 63 47  51 50 4F 52 | æbcGQPOR
0000:0068 | 29 57 56 5B  58 5E 61 4D | )WV[X^aM
0000:0070 | 53 60 5D 59  5A 5C 5F 2B | S`]YZ\_+
0000:0078 | 00 00 00 00  00 00 00 00 | ........
0000:0080 | 00 00 00 00  00 00 00 00 | ........

• Calculate the offset into the keymap file (again look at 3.7.1). eg (start of cbm_us_emu.bin) + 8 * 7 (row) + 5 (column) = 61. When looking at the dump above, at this offset you will find the hex value 0xE2 - which is "left alt", which is what we want to change to "LeftGUI", ie 0xE3.

• Change the value to whatever you like (use USB HID specs, the "Option" key would be "LeftGUI" with value 0xE3)
• Repeat the above for any other keys you want to change

• Convert the resulting binary file to a uf2 file using mkkeymap and flash it (keep the button on the board pressed while plugging in the USB cable, keyrah will register a mass storage device. Drop the .uf2 file into that). mkkeymap will take care of adding the "tags" mentioned in the manual.

• If something goes wrong, flash the reset.uf2 file (that will basically delete all custom mapping data)

After you have flashed the keymap, please keep in mind that the system/keyboard jumpers have no effect when a custom mapping was flashed - perhaps attach a note to your keyrah so you do not forget this. You can flash the mentioned reset.uf2 file to revert those changes.

• The mkkeymap tool (contains source code and Windows executable)
• The default keymaps that can be used as a template. Each binary file corresponds to one of the "blocks" mentioned in chapter 3.7.1 of the manual
• hut1_12v2.pdf contains the keycodes, in particular "Keyboard/Keypad Page (0x07)"

• last not least, the resulting binary of the above example is here

Shop

• Individual Computers' Shop (selected Products)

Resellers

Please shop locally. Our partners are listed in alphabetical order.

• Alinea Computer (Germany)
• Amiga Kit (UK, US)
• F.H.U.EDEN Komputery (Poland)
• GGS Data (Sweden)
• Protovision (Germany) (Retro Products only)
• Relec Software & Hardware (Switzerland)