converter/adb_usb/README.md

   1 ADB to USB keyboard converter
   2 =============================
   3 This firmware converts Apple ADB keyboard/mouse protocol to USB, you can use it to plug old ADB keyboard/mouse into modern computer. It works on prebuilt TMK ADB-USB Converter or generic dev board with USB AVR MCU(ATMega32U4/2) like Teensy2.0.
   4
   5 Discuss about this here: http://geekhack.org/showwiki.php?title=Island:14290
   6
   7 Prebuilt TMK ADB-USB converter is available here: https://geekhack.org/index.php?topic=72052.0
   8
   9
  10
  11 README FIRST
  12 ------------
  13 https://github.com/tmk/tmk_keyboard
  14 https://github.com/tmk/tmk_keyboard/tree/master/converter/adb_usb
  15
  16 Also check these when you are in trouble.
  17
  18 https://github.com/tmk/tmk_keyboard/wiki
  19 https://github.com/tmk/tmk_keyboard/issues
  20
  21
  22 Wiring
  23 ------
  24 If you build this yourself you have to solder some wires.
  25 Connect ADB pins to controller just by 3 lines(Vcc, GND, Data) at least. By default Data line uses port PD0.
  26 This is not needed but you can connect PSW to PD1 optionally.
  27
  28 ADB female socket from the front:
  29
  30       ,--_--.
  31      / o4 3o \      1: DATA
  32     | o2   1o |     2: PSW(Power SW)
  33      -  ===  -      3: VCC
  34       `-___-'       4: GND
  35
  36 This converter uses AVR's internal pull-up, but it seems to be too weak, in particular when you want to use a long or coiled cable. The external pull-up resistor(1K-10K Ohm) on Data is strongly recommended.(It is almost must!)
  37 https://github.com/tmk/tmk_keyboard/wiki/FAQ#pull-up-resistor
  38
  39 Pull-up resister:
  40
  41     Keyboard       AVR MCU
  42                    ,------.
  43     5V------+------|VCC   |
  44             |      |      |
  45            [R]     |      |
  46             |      |      |
  47     DATA----+------|PD0   |
  48                    |      |
  49     GND------------|GND   |
  50                    `------'
  51     R: 1K Ohm resistor
  52
  53
  54 Define following macros for ADB connection in config.h if you use other than port PD0.
  55
  56     ADB_PORT, ADB_PIN, ADB_DDR, ADB_DATA_BIT
  57
  58
  59 Build firmware and Program microcontroller
  60 ------------------------------------------
  61 See [doc/build.md](../../tmk_core/doc/build.md).
  62
  63 To build firmware and program TMK ADB-USB Converter run these commands:
  64
  65     $ make -f Makefile clean
  66     $ make -f Makefile [KEYMAP=yourname]
  67     $ make -f Makefile [KEYMAP=yourname] dfu
  68
  69 You can select keymap name with optional `KEYMAP=` ('plain' is default name). Push button on the converter before running `dfu` target.
  70
  71 Use **Makefile.rev1** for old TMK Converter rev.1 and Teensy2.0 instead of **Makefile**.
  72
  73
  74
  75 Keymap
  76 ------
  77 You can change keymap by editing code of unimap_plain.c directly, or copy it to your own keymap file like unimap_yourname.c and edit the file.
  78 How to define the keymap is probably obvious. You can find key symbols in common/keycode.h. And see [doc/keymap.md](../../tmk_core/doc/keymap.md) for more detail.
  79
  80
  81 Magic command
  82 -------------
  83 To get help message in hid_listen press `h` holding Magic key. Magic key is `Power key`.
  84
  85 https://github.com/tmk/tmk_keyboard/wiki#debug
  86
  87
  88 Locking CapsLock
  89 ----------------
  90 Many of old ADB keyboards have mechanical push-lock switch for Capslock key and this converter supports the locking Capslock key by default. Use keycode `LCAP` instead of `CAPS` in your keymap in short. See README in top directory for more detail.
  91 https://github.com/tmk/tmk_keyboard/blob/master/README.md#mechanical-locking-support
  92
  93 If you want to remap Capslock key you will have to remove locking pin or just replace with normal momentary switch. Some keyboards like Apple Adujstable keyboard use firmware-base locking with momentary switch for Capslock and remapping it won't be useful in most cases.
  94
  95
  96 Notes for keyboard
  97 ------------------
  98 Not-extended ADB keyboards have no discrimination between right modifier and left one,
  99 you will always see left control even if you press right control key.
 100 Apple Extended Keyboard and Apple Extended Keyboard II can discriminate both side
 101 modifiers except for GUI key(Windows/Command).
 102
 103 And most of ADB keyboards have no diodes in its matrix so they are not NKRO unfortunately,
 104 though ADB protocol itself supports it. See tmk_core/protocol/adb.c for more info.
 105
 106
 107 Notes for mouse
 108 ---------------
 109 ADB mouse support was added by @mek-apelsin on Apr,2015.
 110 https://github.com/tmk/tmk_keyboard/pull/207
 111
 112 All one-button mouses should be supported.
 113
 114 As of 2019 June, the converter can handle multi-button mice and trackball up to eight buttons if the pointing device supports Apple Extended Mouse protocol. But some devices use their own specific protocol unfortunately and they will work as one-button mouse unless device specific code is added.
 115
 116 Kensington Turbo Mouse 5(#64210) is supported now.
 117 https://github.com/tmk/tmk_keyboard/issues/274#issuecomment-504726633
 118
 119 EOF