Remapping the CBM Key for Mac

Caution: Non registered users only see threads and messages in the currently selected language, which is determined by their browser. Please create an account and log in to see all content by default. This is a limitation of the forum software.


Also users that are not logged in can not create new threads. This is a, unfortunately needed, counter measure against spam. Please create an account and log in to start new threads.

Don't Panic. Please wash hands.

    I would like to use my Keyrah & C64 keyboard on my Mac, however there doesn't seem to be a mapping for the command key in MacOS, meaning that most keyboard shortcuts are unavailable to me.


    I see from the manual that it is possible to add a custom keymap so I would like to remap the Commodore key to the cmd key press. I've looked through the manual and whilst there is instructions on how to flash the keyrah with a new keymap there isn't any detail on what a keymap file actually contains. Since I only want to remap a single key I was wondering if the default keymap file is available anywhere to download so that I could edit it?

    This is an interesting issue actually - i did not think about it at all before (yet it seems so obvious)...


    The Keymap just contains a binary array, the layout is in the manual, the values are the USB HID keycodes. However, to flash the keymap you'll have to convert it into uf2 format first. Somehow i forgot to write proper instructions and publish the little tool i made for this when Keyrah V3 was released...


    Anyway, i have attached the tool, and the default keymaps. In order to do what you want:


    - 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

    - now the tables in 3.7.1 tell you the basic layout of the resulting file

    - now find the key you want to remap in the table for your keyboard in 3.7.2 (CBM is row 11, column 5)

    - calculate the offset into the keymap file (again look at 3.7.1). eg for the US "emu" keymap would be 0x400 (start of cbm_us_emu.bin) + 8 * 11 (row) + 5 (column)

    - change the value to whatever you like (use USB HID specs)

    - repeat

    - convert the resulting binary file to a uf2 file using mkkeymap and flash it. mkkeymap will take care of adding the "tags" mentioned in the manual.

    - if you screw up, flash the reset.uf2 file (that will basically delete all custom mapping data)


    Keep in mind that the system/keyboard jumpers have no effect when a custom mapping was flashed


    Hope that helps :)


    I will use this thread to derive proper docs from it later, so don't hesitate to ask if you have further questions.


    (Also, please tell what information is missing for you in 3.7.x so i can add it. I thought all required info is there - but it surely is very condensed and technical, i admit :))

    Ok i forgot... since you are on a Mac, you'll have to produce the mkkeymap program yourself - you'll have to install the developer tools. then in the unpacked mkkeymap archive type "make", it should then compile the program. You can then use it within that directory by prefixing with ./

    OK so this is turning out to be a bit more complex than I had anticipated :D


    I have found a Stackoverflow page: https://stackoverflow.com/questions/48635385/hid-human-interface-device-send-keys-cmdspace that shows that the mac command key is actually the LeftGUI modifier. I have also found a document at https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf that indicates the hex value for the leftGUI is E3. So far so good.


    I've downloaded the keyrahv3_keymaps_230217.zip file and opened the cbm_us.bin in Visual Studio Code using the https://marketplace.visualstudio.com/items?itemName=ms-vscode.hexeditor hex editor extension

    I can see what looks to be a matrix and some of the actual ASCII characters are decoded. I tried to cross reference the matrix in the manual in section 3.7.2 with what I see in the bin file and they don't seem to match up. if I look at column 5 row 11 (the CBM key in 3.7.2) the value in the file is 00, which I assume is a zero value. Similarly in 3.7.2 is column 1 row 9 but in the output of the bin file it seems to be column 0 row 5.

    Where am I going wrong?

    First, i made a mistake above - the key at row 11, column 5 is the CBM key - but on a C16 keyboard (see the rightmost columns in that table). So you really want to change the key at row 7, column 5.


    That said, don't get misleaded by those ASCII chars - the USB HID codes are not ASCII at all :) To find the right byte to modify, it helps a lot if your hex editor allows you to show arbitrary number of bytes per line.... when i set mine to 8 (the maximum number of columns) then you can clearly see (and edit) the matrix, it looks like this (beginning of cbm_us.bin):



    So, the value you want to change is supposed to be at row 7, column 5 - meaning the offset in the file is (7*8) + 5 = 61 (hex 0x3d). If you look at the file now, at this offset you will find the hex value 0xe2 - which is "left alt", exactly whats expected :) And indeed, it should be changed to 0xe3 (the pdf you found is the same that i am looking at, so all good).

    I had to read over this a few times but I think I finally have it.


    It turned out that my editor was set to 18 bytes per row, so that meant that row 7, column 5 had a different value because there were more columns than were in the matrix in the manual. Once I set it to 8 everything lined up correctly. I also didn't realise for a while that the 0xe3 in your post was the same as E3 in the pdf (I'm not familiar with hex). I'm still not sure what the 'offset' in your post or the documentation refers to though but I'm not sure it matters now that I have identified the correct change to make! :)

    My next task is work out how to merge all the bin files in the correct order and create a .uf2 file. I'll do that in the next couple of days.

    Thank you for your help and patience so far Tobias

    For anyone who may find this topic later, to merge the files you can run the following command from a terminal:


    Code
    1. cat cbm_us.bin cbm_us_emu.bin cbm_de.bin cbm_de_emu.bin >> keyrah_custom.bin

    Sorry, I was just making a note as I went along. I flashed the Keyrah with the new file about 30 minutes ago file and it worked! I would upload it here for others to use but it seems like the .bin extension isn't allowed as an attachment.


    I'm a pretty tech savvy guy who works in IT but I would never have been able to do this just by referring to the manual, so thank you Tobias for your helpful explanations and quick replies.


    I do think the documentation needs re-working, it assumes a lot of knowledge that I really didn't have :) I also think providing a template composite .bin file that could be downloaded and edited would really help others, but perhaps you don't get that many mac users or people who need to remap the layout. You could even consider changing the mapping so that the CBM key is the left GUI modifier by default, it's also the Windows key!

    Quote

    I would upload it here for others to use but it seems like the .bin extension isn't allowed as an attachment.

    Just zip the file :)


    Quote

    You could even consider changing the mapping so that the CBM key is the left GUI modifier by default, it's also the Windows key!

    Then Windows people would be missing ALT, which is much more important (the Windows key is basically optional on windows).


    And yes, as said before, the docs surely need some rework - i'll make a wiki page from this thread or sth like that :)