jklof · OleUrgast · Feb 2, 2020 · Feb 2, 2020 · Feb 3, 2020 · Feb 5, 2020
diff --git a/README.md b/README.md
@@ -3,3 +3,94 @@ Arduino Amiga keyboard interface
 
 This is a bit of code that allows you to use Amiga hw keyboard as USB HID keyboard.
 Useful for projects such as replacing Amiga internals with Raspberry.
+
+---
+
+This is a fork of jklof/amigakb adjusted for Vampire V4-SA
+
+This should work with all Amiga keyboards that have their own controller (i.e. all keyboards except A600 and A1200):
+- A500
+- A1000 (early and later models)
+- A2000/A3000
+- A4000/CD32
+- CDTV
+
+The repository also contains [schematics and premade board files](boards) for building a "Pro Micro" based adapter that runs this code.
+3D printable cases for the boards can be found at https://www.thingiverse.com/thing:4593520
+
+### Changes to the original code:
+- Merged in changes from https://forum.arduino.cc/index.php?topic=139358.90
+- Changed Backslash, Hash and Help key mappings
+- Added reset handling for keyboards without reset line
+- Made use of the caps lock special handling (for compensating differences between Amiga and USB keyboard protocols)
+  configurable via a jumper (V4 expects key events differently than usual for USB keyboards)
+  This can be switched with a jumper between pin 2 and ground.
+- replaced digitalRead() with direct register usage to meet timing requirements for early A1000 keyboards
+- changed handshake to work with early A1000 keyboards
+- send data via USB during handshake pulse, in order to not miss next key event
+- Added option to use a switch between pin 4 and ground to select an alternative keymap in order to make codes of keys available that do not exist on the amiga keyboard (currently only used for providing F11 and F12 (which are used by V4SA to toggle options) on F1 and F2)
+
+
+### Uploading the precompiled hex file to the microcontroller
+To ease the installation process I've uploaded a precompiled build: [amigakb.hex](amigakb.hex)
+This file can be uploaded to the microcontroller using AVRDUDE: https://www.nongnu.org/avrdude/
+
+#### Linux
+
+Most distributions likely have an AVRDUDE package, for example on Ubuntu it can be installed using:
+```
+sudo apt-get install avrdude
+```
+When you plug in a "fresh" pro-micro the built-in CDC serial port will be recognized as a tty.
+Here is an example output of `dmesg` when the microcontroller gets connected:
+```
+usb 1-9: new full-speed USB device number 110 using xhci_hcd
+usb 1-9: New USB device found, idVendor=2341, idProduct=0036, bcdDevice= 0.01
+usb 1-9: New USB device strings: Mfr=2, Product=1, SerialNumber=0
+usb 1-9: Product: Arduino Leonardo
+usb 1-9: Manufacturer: Arduino LLC
+cdc_acm 1-9:1.0: ttyACM0: USB ACM device
+```
+Here the name of the serial port is `ttyACM0`.
+This port can be used to program the microcontroller with the downloaded hex file:
+```
+sudo avrdude -v -patmega32u4 -cavr109 -P/dev/ttyACM0 -b57600 -D -Uflash:w:amigakb.hex:i
+```
+#### Windows
+
+You can download a Windows version of AVRDUDE from https://github.com/mariusgreuel/avrdude/releases.
+
+Extract the AVRDUDE package and place the [amigakb.hex](amigakb.hex) file right next to the extracted files. Start a Windows Command Prompt in the same directory (for example by typing `cmd.exe` in the explorer address bar).
+
+When you plug in a "fresh" pro-micro the built in CDC serial port will be recognized as a new COM port.
+
+In this example the device manager has an entry called `USB Serial Device (COM5)`.
+
+This port can be used to program the microcontroller with the downloaded hex file.
+In the Windows Command Prompt type:
+```
+avrdude.exe -v -patmega32u4 -cavr109 -v -PCOM5 -b57600 -D -Uflash:w:amigakb.hex:i
+```
+
+### Building for V4-SA:
+- Use Arduino IDE v1.6.5-r5 (needed for the changes below - the last version before a refactoring of the USB stack).
+  Note that if you have used a newer version, such as 1.8.x, it might prevent the 1.6.5 version from working due to it using
+  incompatible compiler switches or adding incompatible packages.  If you get a linker error mentioning LTO (Link Time Optimisation)
+  it will certainly be caused by this.  To resolve the issue, on Windows, search in your c:\Users\<UserName>\AppData directory
+  for a directory called "Arduino15" and delete it.  There will probably be one in AppData\Local and one in AppData\Roaming.
+  You might have to repeat this process to switch back to the newer Arduino IDE version.  On MacOS the directory can be found in
+  ~/Library/Arduino15 and on Linux it is in ~/.arduino15.
+- When installing the Pro Micro board add-on for Arduino IDE, do *not* use the automated installation method or it will recreate
+  the Arduino15 directory and result in a non working build (as it installs the add-on for the latest 1.8.x version of the Arduino
+  IDE).  Instead, download and install the board add-on manually, as described on the Sparkfun website at
+  https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide/installing-windows under the section entitled "Installing the
+  .brd Files Manually".  This is an older version of the add-on designed for older versions of the Arduino IDE
+- Apply the change from https://github.com/tkoecker/Arduino/commit/e6783cb5e4b7e1dc8abc4932b3e3543ad793c6ff.patch to
+  get an USB core that uses low-speed USB, with only one boot protocol keyboard HID device.  Experience has shown that some versions
+  of patch do not work properly (at least on Windows), so look out for error messages such as "Hunk #X FAILED at XXX." or you'll
+  be building an unpatched USB stack and will wonder why it doesn't work on the Vampire!
+
+### TODO:
+- Add reset handling for A500 keyboard (i.e. keyboard with reset line) (optional as the current reset handling also is sufficient for A500 keyboards)
+- Fix mapping of numpad '(' and ')' keys (Amiga keycodes 0x5a, and 0x5b) (these seem currently not to be available on V4)
+- A500 keyboard: make LEDs controllable via USB (i.e. switch drive led on/off, switch power led bright/dim)
diff --git a/amigakb.hex b/amigakb.hex
@@ -0,0 +1,290 @@
+:100000000C942F010C9457010C9457010C94570138
+:100010000C9457010C9457010C9457010C94570100
+:100020000C9457010C9457010C94F0070C94D306D0
+:100030000C9457010C9457010C9457010C945701E0
+:100040000C9457010C9457010C9457010C945701D0
+:100050000C9457010C9457010C9457010C945F02B7
+:100060000C9457010C9457010C9457010C945701B0
+:100070000C9457010C9457010C9457010C945701A0
+:100080000C9457010C9457010C9457010C94570190
+:100090000C9457010C9457010C9457010C94570180
+:1000A0000C9457010C9457010C9457016D03700385
+:1000B0005F0363036903910391039103740378035E
+:1000C0007C038203860391038C0300000002000975
+:1000D0000F0000030401000C0000000000000000FD
+:1000E00000000000000000000408020110408040F1
+:1000F000102040804080080204018040201002014E
+:10010000108010204040040404040403040502028B
+:1001100002020403020202020606060606060404A0
+:1001200002020204000000002300260029002C0027
+:100130002F0000000000250028002B002E003100B9
+:1001400000000000240027002A002D0030000000DD
+:100150000000000000002A2B280000000000000022
+:1001600000000000000000000000000000002C9EC5
+:10017000B4A0A1A2A434A6A7A5AE362D3738271E59
+:100180001F20212223242526B333B62EB7B89F84FF
+:1001900085868788898A8B8C8D8E8F909192939497
+:1001A00095969798999A9B9C9D2F3130A3AD3504D5
+:1001B00005060708090A0B0C0D0E0F101112131477
+:1001C00015161718191A1B1C1DAFB1B0B50009047C
+:1001D00000000103010100092101010001222D009D
+:1001E0000705810308000A05010906A10105071991
+:1001F000E029E71500250175019508810295017533
+:10020000088103950675081500256505071900295D
+:10021000658100C000C112011001000000084123E7
+:1002200036800001010200011201100100000008E7
+:100230004123368000010102000141726475696E3C
+:100240006F204C4C430041726475696E6F204C65A1
+:100250006F6E6172646F0004030904005705112476
+:100260001FBECFEFDAE0DEBFCDBF12E0A0E0B1E00D
+:10027000EEEFF0E102C005900D92A830B107D9F77A
+:1002800022E0A8E0B2E001C01D92AB32B207E1F774
+:1002900012E0CEE5D2E004C02297FE010E94790868
+:1002A000CC35D107C9F70E942B040C947D080C941F
+:1002B0000000FC0181E080831182128262E082E012
+:1002C0000E94920362E084E00E94920362E088E070
+:1002D0000E94920362E089E00E94920362E08AE059
+:1002E0000E94920361E087E00E94920361E086E051
+:1002F0000E94920385E192E00C948E04FF920F938A
+:100300001F93CF93DF93EC01F3B0F4FAFF24F0F8DE
+:100310008881F816F1F0F882F1101EC09A819830A9
+:10032000C0F483B182958695877041E08427282F99
+:10033000217030E0E92FF0E0EE5FFE4F008002C058
+:10034000220F331F0A94E2F78981282B29839F5FAC
+:100350009A830FEF1FEF13C081E0F812FACF8A8162
+:100360008830B8F3098110E01A82198261E089E0CF
+:100370000E94920360E089E00E94CB03FB82C801E7
+:10038000DF91CF911F910F91FF90089588E092E047
+:100390000E94590161E087E00C94CB03EF92FF9239
+:1003A0001F93CF93DF931F92CDB7DEB77B016F3FD3
+:1003B0008FEF780709F464C0693F710591F06E3FD3
+:1003C0007105C9F460E885E192E00E94940463E855
+:1003D00085E192E00E94940467E885E192E00E9442
+:1003E000940485E192E00F90DF91CF911F91FF90EF
+:1003F000EF900C944A05162F1F7784E00E940104A9
+:100400001837F0F5412F50E021E030E0892B11F052
+:1004100020E030E088E7829FF001839FF00D1124F7
+:10042000E40FF51FE65FFE4F6081662349F1613CF2
+:10043000D9F482E069830E9401046981892BA1F4C7
+:1004400061EC85E192E00E94940484E690E00E94D1
+:10045000F40261EC85E192E00F90DF91CF911F9162
+:10046000FF90EF900C940205E7FCF4CF85E192E059
+:100470000F90DF91CF911F91FF90EF900C94940417
+:100480000F90DF91CF911F91FF90EF90089588E03A
+:1004900092E00E947E01BC0188E092E00E94CE01C1
+:1004A00080910B02882351F084E690E00E94F402D0
+:1004B00062E089E00E94920310920B0208951F925D
+:1004C0000F920FB60F9211242F933F938F939F9308
+:1004D000AF93BF9380910D0290910E02A0910F02F5
+:1004E000B091100230910C0223E0230F2D3720F43D
+:1004F0000196A11DB11D05C026E8230F0296A11D7E
+:10050000B11D20930C0280930D0290930E02A093D4
+:100510000F02B09310028091110290911202A091EB
+:100520001302B09114020196A11DB11D8093110216
+:1005300090931202A0931302B0931402BF91AF9153
+:100540009F918F913F912F910F900FBE0F901F9011
+:1005500018953FB7F8948091110290911202A091E2
+:100560001302B091140226B5A89B05C02F3F19F0C5
+:100570000196A11DB11D3FBF6627782F892F9A2FA5
+:10058000620F711D811D911D42E0660F771F881F4C
+:10059000991F4A95D1F70895CF92DF92EF92FF927B
+:1005A000CF93DF936B017C010E94A902EB01C11480
+:1005B000D104E104F10489F00E944E080E94A902CE
+:1005C0006C1B7D0B683E734090F381E0C81AD10824
+:1005D000E108F108C851DC4FEACFDF91CF91FF90DD
+:1005E000EF90DF90CF9008958230910538F0880F1A
+:1005F000991F880F991F05970197F1F7089578942F
+:1006000084B5826084BD84B5816084BD85B5826017
+:1006100085BD85B5816085BDEEE6F0E080818160B5
+:100620008083E1E8F0E010828081826080838081B5
+:1006300081608083E0E8F0E0808181608083E1E98F
+:10064000F0E0808182608083808181608083E0E946
+:10065000F0E0808181608083E1ECF0E08081846063
+:100660008083808182608083808181608083E3ECED
+:10067000F0E0808181608083E0ECF0E08081826046
+:100680008083E2ECF0E0808181608083EAE7F0E043
+:1006900080818460808380818260808380818160AA
+:1006A0008083808180688083089590E0FC01319789
+:1006B000EF30F105B0F5EA5AFF4F0C9477088091BE
+:1006C00080008F7703C0809180008F7D80938000B1
+:1006D000089580918000877FF9CF84B58F7702C01D
+:1006E00084B58F7D84BD0895809190008F7707C079
+:1006F000809190008F7D03C080919000877F8093D0
+:10070000900008958091C0008F7703C08091C00051
+:100710008F7D8093C00008958091C200877F809371
+:10072000C2000895CF93DF9390E0FC01E851FF4FA2
+:100730002491FC01EA5FFE4F8491882349F190E007
+:10074000880F991FFC01E05CFE4FA591B4918E5C6F
+:100750009E4FFC01C591D4919FB7611108C0F894D8
+:100760008C91209582238C93888182230AC06230E9
+:1007700051F4F8948C91322F309583238C93888197
+:10078000822B888304C0F8948C91822B8C939FBF1A
+:10079000DF91CF9108950F931F93CF93DF931F9213
+:1007A000CDB7DEB7282F30E0F901E653FF4F849133
+:1007B000F901E851FF4F1491F901EA5FFE4F0491EE
+:1007C0000023C9F0882321F069830E9455036981C1
+:1007D000E02FF0E0EE0FFF1FEE5CFE4FA591B4910D
+:1007E0009FB7F8948C91611103C01095812301C0CB
+:1007F000812B8C939FBF0F90DF91CF911F910F9111
+:100800000895CF93DF93282F30E0F901E653FF4F8F
+:100810008491F901E851FF4FD491F901EA5FFE4F4D
+:10082000C491CC2391F081110E945503EC2FF0E08C
+:10083000EE0FFF1FEC5DFE4FA591B4912C912D237F
+:1008400081E090E021F480E002C080E090E0DF9160
+:10085000CF91089508950E94FF020E942A0482E227
+:1008600092E00E942F080E94C601C0E0D0E00E94E2
+:1008700047022097E1F30E940000F9CFFF920F9307
+:100880001F93CF93DF93EC01F62EE881F98104806A
+:10089000F581E02D09958C01E881F9810680F781C9
+:1008A000E02D6F2DCE010995C8019927DF91CF91D9
+:1008B0001F910F91FF900895FC0120812F5F2083ED
+:1008C00049E150E06EEC71E080E80C9492064DE254
+:1008D00050E067EE71E080E80C94920681E40C949D
+:1008E000F705FC0191818081813A31F481E09130FA
+:1008F00091F0933089F411C0813271F49B3021F46E
+:1009000082818093010105C09A3031F48281809305
+:10091000000181E00895089580E00895089548E079
+:1009200050E082E00C946E04CF93DF93DC016838D2
+:1009300018F0E8E7E60F25C0E62FF0E067FF11C0EA
+:10094000E058F10981E090E001C0880FEA95EAF7EC
+:1009500014969C911497982B14969C931497E0E00E
+:1009600010C0E25BFE4FE491EE2309F440C0E7FFC4
+:1009700008C014968C911497826014968C931497E7
+:10098000EF7716968C9116978E1741F117968C91EA
+:1009900017978E1719F118968C9118978E17F1F0FA
+:1009A00019968C9119978E17C9F01A968C911A97EF
+:1009B0008E17A1F01B968C911B978E1779F080E013
+:1009C00090E0ED01C80FD91F2E81211102C0EE83E6
+:1009D00005C0019686309105A1F709C0BD016C5F85
+:1009E0007F4FCD010E948F0481E090E008C081E03C
+:1009F00090E013969C938E93129780E090E0DF91A5
+:100A0000CF910895683818F0E8E7E60F25C0E62F83
+:100A1000F0E067FF12C0E058F10921E030E001C0CA
+:100A2000220FEA95EAF72095DC0114963C91149781
+:100A3000322314963C93E0E00FC0E25BFE4FE4915A
+:100A4000EE2329F1E7FF08C0DC0114962C911497DE
+:100A50002D7F14962C93EF7720E030E0EE2351F0B9
+:100A6000DC01A20FB31F16964C9116974E1302C0CD
+:100A700016961C922F5F3F4F2630310579F7BC0147
+:100A80006C5F7F4F0E948F0481E090E0089580E0CA
+:100A900090E00895FC011682178210861186128656
+:100AA00013861482BC016C5F7F4F0C948F041092EC
+:100AB000210210921802109217028EEF91E090938B
+:100AC0001602809315020895409126025091270244
+:100AD000209124023091250242175307B4F49091DB
+:100AE000E8009570E1F39091E80092FD19C08093C1
+:100AF000F100809126029091270201968770992734
+:100B0000892B19F48EEF8093E80080912602909152
+:100B100027020196909327028093260281E0089590
+:100B200080E00895CF92DF92FF920F931F93CF93AF
+:100B3000DF931F92CDB7DEB7082F162F862F880FB1
+:100B40008E5F99830E94640583E00E946405F02E05
+:100B5000C02E9981D92E8C2D8F19811778F4F6012A
+:100B600084910E946405082F80E00E946405802320
+:100B7000FFEFCF1ADF0A8111EECF01C081E00F90A5
+:100B8000DF91CF911F910F91FF90DF90CF9008954B
+:100B9000615030F02091F100FC0120830196F8CFE4
+:100BA000289884E68093290208952FB7FC012083BA
+:100BB000F89467706093E9000895CF93DF931F92D4
+:100BC000CDB7DEB7682FCE0101960E94D505909172
+:100BD000E800892F807295FF04C09091F20080E4B4
+:100BE000891B99819FBF0F90DF91CF9108956F92DC
+:100BF0007F928F929F92AF92BF92CF92DF92EF92AD
+:100C0000FF920F931F93CF93DF931F92CDB7DEB761
+:100C1000782E7B01C42EB52E80912802882369F09E
+:100C2000042F152F8AEFD82E872D8072982E9AE3E5
+:100C3000A92E872D8074882E11C08FEF9FEF57C08B
+:100C4000872D0E94DD05682E81110CC0DA94A9F36E
+:100C500061E070E080E090E00E94CC020115110597
+:100C600079F73BC0282F30E0021713070CF4602EF1
+:100C7000672DCE0101960E94D5058091E80085FF81
+:100C800029C0262D30E0021B130B992039F06A94FD
+:100C90008FEF6816B1F01092F100F9CFF701862DB1
+:100CA00077FE07C0815058F094919093F1003196EF
+:100CB000F9CF815020F091919093F100FACFE20E9C
+:100CC000F31E8091E80085FF0FC00115110511F496
+:100CD00081100AC089818FBFC1CF5D9884E680935F
+:100CE0002A028C2D9B2D03C0A092E800F3CF0F9019
+:100CF000DF91CF911F910F91FF90EF90DF90CF90F8
+:100D0000BF90AF909F908F907F906F9008951092BA
+:100D1000E9001092270210922602909325028093F8
+:100D200024020895CF92DF92FF920F931F93CF93E7
+:100D3000DF9300D0CDB7DEB7F82E8A016B01011525
+:100D40001105B1F0F601F7FE02C0849101C0808167
+:100D500049835A830E94640501501109FFEFCF1A9D
+:100D6000DF0A49815A818111EACF8FEF9FEF01C0DD
+:100D7000CA010F900F90DF91CF911F910F91FF90BB
+:100D8000DF90CF900895CF93DF931F92CDB7DEB75A
+:100D90001982CE0101960E945C04898190E00F9037
+:100DA000DF91CF9108951F920F920FB60F921124E9
+:100DB000EF92FF920F931F932F933F934F935F9365
+:100DC0006F937F938F939F93AF93BF93EF93FF9313
+:100DD000CF93DF93CDB7DEB76297DEBFCDBF109262
+:100DE000E9008091E80083FFDEC068E0CE010A964A
+:100DF0000E94C80582EF8093E8009A8597FF05C09E
+:100E00008091E80080FFFCCF03C08EEF8093E80064
+:100E1000892F807609F0B3C08B85811105C01092AF
+:100E2000F1001092F100B8C0282F2D7F213009F475
+:100E3000B3C0853049F48091E80080FFFCCF8C85F9
+:100E400080688093E300A8C0863009F076C02D85C5
+:100E5000E888F988223071F580E090E02A8B0E94C2
+:100E600087060E94C30699E08E010F5F1F4FF801AD
+:100E7000392F11923A95E9F799832A892A8391E0CB
+:100E80009E8390E8988792E399872091260230917B
+:100E90002702275F3F4F3C832B838D83C7010E942E
+:100EA000870649E050E0B80180E00E9492060E9467
+:100EB000C30672C0C7012A8B0E9487062A89223284
+:100EC00041F482E290E00E946704892B09F064C03B
+:100ED00067C0213069F488899989089711F42093B3
+:100EE000230280912302811118C068E272E01AC0C7
+:100EF000233009F055C08C85882391F0823021F48D
+:100F000060E186E492E006C0813009F049C06BE000
+:100F10008AE392E00E9492053DC066E172E002C061
+:100F200067E572E06115710509F43AC0FB0144916F
+:100F300050E080E80E9492062FC0873089F1883007
+:100F400021F481E08093F10027C0893029F5937066
+:100F500039F581E08093E9008093EB00E5E1F2E070
+:100F6000E491E093EC0086E38093ED008EE78093BC
+:100F7000EA001092EA008C85809328020DC08889CF
+:100F800099890E9487068E8581110AC0CE010A9632
+:100F90000E947104882321F08EEF8093E80003C043
+:100FA00081E28093EB0062960FB6F894DEBF0FBE2D
+:100FB000CDBFDF91CF91FF91EF91BF91AF919F9105
+:100FC0008F917F916F915F914F913F912F911F91E1
+:100FD0000F91FF90EF900F900FBE0F901F901895FC
+:100FE0001F920F920FB60F9211248F939F938091AF
+:100FF000E1001092E10083FF0FC01092E90091E040
+:101000009093EB001092EC0092E39093ED0010921D
+:10101000280298E09093F00082FF1AC080912A0283
+:10102000882339F080912A02815080932A028823F4
+:1010300069F080912902882359F08091290281501A
+:1010400080932902811104C0289A02C05D9AF1CFD1
+:101050009F918F910F900FBE0F901F901895109237
+:10106000280281E08093D70080EA8093D80082E153
+:1010700089BD09B400FEFDCF61E070E080E090E042
+:101080000E94CC0280E98093D8008CE08093E2003B
+:1010900084E08093E000559A209A08950895CF92B5
+:1010A000DF92EF92FF920F931F93CF93DF936C0128
+:1010B0007A01EB01E60EF71E00E010E0CE15DF0529
+:1010C00061F06991D601ED91FC910190F081E02DE4
+:1010D000C6010995080F191FF1CFC801DF91CF9103
+:1010E0001F910F91FF90EF90DF90CF900895EE0F3A
+:0E10F000FF1F0590F491E02D0994F894FFCFB6
+:1010FE0001010605040302010007BD313233343508
+:10110E0036373839302D3D5C00EA71776572747967
+:10111E0075696F705B5D00E1E2E361736466676839
+:10112E006A6B6C3B27BA00E4E5E6EC7A786376628C
+:10113E006E6D2C2E2F00EBE7E8E920B2B3E0B0B1D4
+:10114E00D4000000DE00DAD9D7D8C2C3C4C5C6C7E2
+:10115E00C8C9CACBDBCFDCDDDFD38185C1808286F7
+:10116E008387000000000000000000000000000067
+:10117E000000BD313233343536373839302D3D5CD1
+:10118E0000EA71776572747975696F705B5D00E165
+:10119E00E2E36173646667686A6B6C3B27BA00E4CE
+:1011AE00E5E6EC7A786376626E6D2C2E2F00EBE717
+:1011BE00E8E920B2B3E0B0B1D4000000DE00DAD925
+:1011CE00D7D8CCCDC4C5C6C7C8C9CACBDBCFDCDD2A
+:1011DE00DFD38185C18082868387000000000000F6
+:1011EE0000000000000000000000000000003E04AF
+:0811FE004F08940402054A05A4
+:00000001FF