Hatari (esp. Mac) Keyboard Configuration

You may have discovered some difficulties using Hatari because the keyboard layout isn't the same as the real thing.  In particular you might need to type forward or backslash, or the underscore key, and these can be placed in the wrong location to the place you were expecting.  The problem I had was the underscore key couldn't be found anywhere which made typing any commands in SMS_QE (ql operating system?/basic) very difficult.

Here's an example keymap.txt file that helped me when my external microsoft USB keyboard was connected (as a US keyboard, with 'British' selected as the keyboard type (!!))..

# UNDERSCORE(dash) (s) or 12
45,12
# equals
61,13
# WORKS: THIS IS THE HASH. 'SDLK_BACKSLASH' (a) or 43
92,43
# The key to the left of number 1 // Some apps might benefit from mapping to 43 (key to the right of return) or to 96 (key to the left of Z)
# Many apps don't do anything with Atari key 96.
96,41
# Test atari key 96, Make the letter z do a 96:
122,96
# The programmers brackets (square and curly). Normal brackets are on shift 9 and 091,26
93,27
# DELETE (d) or 83
127,83
# Insert or 82
277,82
# Home
278,71
# End or ?temporary UNDO?
279,97

Unfortunately the macos seems to intercept the keys to the right of PrtScn/SysRq and is used to alter screen brightness.  Probably something in the System Preferences->Keyboard->Shortcuts->Display will let me fix that (F14 and F15 were mapped to Display/Increase display brightness).

If you don't like those keys doing what I've assigned them to do, then take a look at:

http://www.atarimuseum.com/computers/16bits/STINTERN.htm
or
http://retrospec.sgn.net/users/tomcat/miodrag/Atari_ST/Atari%20ST%20Internals.htm#KEYMAP
in particular the Keyboard Scancode Map.

Some things to note: An atari keyboard has hash to the right of the enter key, and there's an extra key between equals and backspace.  Worth looking at a photo.  Most applications don't use the UNDO key, but HELP is often mapped to something.

The numbers to the right of the comma are the ones that are in the picture, so eg; 30-33 correspond to ASDF.  So if you want to test eg; whether you've found the right key on your keyboard, change the second number to eg; 30 and then see whether pressing that key gets you an 'A' eg; in a 'create desktop icon' / 'install drive' dialog.  There are some characters that you can't use in a folder name that you might want to use when programming.. I haven't found a good 'keyboard test' program, but have used a couple of word processor / note taking accessories that have helped: EdHak's little brother 'Diary' by Craig Harvey.

Finding the meaning of the first number is more of a case of trial and error.  Some of the keys seem to be straightforward ascii, and come from the SDL library that was used to build Hatari.

For reference, this was with Hatari(en) version 1.9.0, ( running on Mac OS 10.11.6 ) which is a bit of an old one, as version 2.0.0 has been available since November 2016.

Hopefully this helps someone..

I've since then removed that US keyboard layout from my mac and re-identified the keyboard as the ISO/European one so have to repeat the process again.  This time round the MS keyboard has hash next to return and all the pictures on the keys do the correct thing on the mac.  So backslash is next to one shift key and forward slash is the one next to the other shift key (confused?)

I tried this again today and it seems to be using the keymap.txt I've shown above.  The only confusion was I thought I'd lost the hash (#) key, but instead shift 3.  So that still means the key to the left of 1 is generating the same scan as key to the left of enter.  2b and 29 in hex is 41 and 43.  So one of the lines:
92,43
96,41

needs changing.  I'll set 92 to A (30) and 96 to Z (44) temporarily... do hatari preferences, select the keymap.txt file again (no reboot)... and the key to the left of 1 is generating a z. but the hash key is still doing backtick.  And the key to the left of z is generating 'A'.. oops.

So 92 needs to be 41. (ie; make our key to the left of 1

and 96 needs to be 96. (ie; make the key to the left of z generate the key to the left of z)

And putting that in makes the key to the left of 1

And then at some point you think you're going mad... so I set key 45 (underscore) to key 43 (the one to the right of enter)
and then both keys generated a forward-slash. (ie; the one next to enter)..
So I checked the config again..
And remapped 35 to 43

Here's the finished config...
# UNDERSCORE(dash) (s) or 12
45,12
# equals
61,13
# to the left of enter(35)
35,43
# between enter and backspace or to the left of 1
92,41
# to the left of z
96,96

Good luck.

addendum: You might find this page useful, it relates SDL keywords to key numbers..
https://www.apt-browse.org/browse/debian/wheezy/main/i386/libsdl1.2-dev/1.2.15-5/file/usr/include/SDL/SDL_keysym.h and seems to map to what I just did...

 SDLK_MINUS  = 45,

 SDLK_EQUALS  = 61,

 SDLK_HASH  = 35,

 SDLK_BACKSLASH  = 92,

 SDLK_BACKQUOTE  = 96,

 SDLK_LEFTBRACKET = 91,
 SDLK_RIGHTBRACKET = 93,

 SDLK_DELETE  = 127,

 SDLK_INSERT  = 277,
 SDLK_HOME  = 278,
 SDLK_END  = 279,