[
  {
    "path": "README.md",
    "content": "# How to integrate a trackpoint in a mechanical keyboard\n\nThis is a summary of what I needed and learned while integrating a\ntrackpoint into my [custom built hand-wired split mechanical\nkeyboard][blackhawk]. It took quite a lot of research and planning, so I\nthought it would be helpful to others to create this guide.\n\n![final](images/collage-final.jpg)\n\nBefore starting this project, the main questions I had were:\n\n- How do I identify the pinout of my trackpoint?\n- What should I use for the trackpoint stem?\n- Will I need to ruin my keycaps to make space for the stem?\n- Can I use the same teensy to power both the keyboard and TP?\n- Can I use the TP and keyboard mousekeys concurrently?\n- Should I use busywait, interrupt or usart in TMK?\n- How do I build the reset circuit?\n- Will I have enough clearance inside the case?\n\nThere is a lot of useful information scattered around the deskthority\nand geekhack forums, and TMK issues, so I'm also including all the\n[pinouts][pinouts] I found during my travels, [datasheets][datasheets],\nand [TMK keyboard code tweaks](#tmk-firmware-changes-and-tweaks).\n(Unfortunately I didn't take note of where I found the above mentioned\nresources, so I can't give credit where it is due, for that I apologize.\nI'll try retrace my steps, but if you can let me know, I'd be most\nwelcome).\n\nThanks to hasu for his awesome TMK firmware, and the deskthority and\ngeekhack communities - if you have posted something to do with a\ntrackpoint, I've read it, and it most likely helped :)\n\nPull requests are welcome, especially new pinouts.\n\n## Table of contents\n\n- [Target audience](#target-audience)\n- [FAQ](#faq)\n    - [Q: What should I use for the trackpoint stem/stick?](#q-what-should-i-use-for-the-trackpoint-stem/stick)\n    - [Q: How do I identify the trackpoint pinout?](#q-how-do-i-identify-the-trackpoint-pinout)\n    - [Q: Should I use busywait, interrupt or usart in TMK?](#q-should-i-use-busywait-interrupt-or-usart-in-tmk)\n- [What you need](#what-you-need)\n- [Steps](#steps)\n    - [1. Solder leads to trackpoint](#1-solder-leads-to-trackpoint)\n    - [2. Create the reset circuit (RC)](#2-create-the-reset-circuit-rc)\n    - [3. Solder leads to reset circuit (RC)](#3-solder-leads-to-reset-circuit-rc)\n    - [4. Testing on a breadboard](#4-testing-on-a-breadboard)\n    - [5. Make trackpoint stem hole in case](#5-make-trackpoint-stem-hole-in-case)\n    - [6. Make space for trackpoint in keyboard](#6-make-space-for-trackpoint-in-keyboard)\n    - [7. Test trackpoint clearance and stem length, glue stem](#7-test-trackpoint-clearance-and-stem-length-glue-stem)\n    - [8. Solder reset circuit (RC) to teensy](#8-solder-reset-circuit-rc-to-teensy)\n    - [9. Finish up](#9-finish-up)\n    - [10. Update tmk_keyboard firmware and flash](#10-update-tmk_keyboard-firmware-and-flash)\n- [TMK firmware changes and tweaks](#tmk-firmware-changes-and-tweaks)\n\n## Target audience\n\nIt's hard to cover every use-case, keyboard and firmware so I'm limiting\nthis for folks who have a hand-wired mechanical keyboard that uses a\nteensy (2.0) with TMK_keyboard firmware, and who want to integrate a\ntrackpoint for just mouse movement (and take advantage of the keyboard\nfor mouse keys).\n\nThat said, the information here should still be useful for others.\n\n## FAQ\n\n### Q: What should I use for the trackpoint stem/stick?\n\n**A labret cheek piercing! (yes, I know, weird, but it's awesome!)**\n\n- Relatively cheap.\n- Super strong (surgical steel, titanium).\n- Really thin in diameter (16G is perfect for between keycaps).\n- They come in different lengths (8mm to 26mm).\n- They have a flat bottom (great for gluing to TP).\n- They have a screw on top ball, in different sizes.\n\nI ordered a few sets of different lengths and different diameters (I\nwasn't sure if 16G would be strong enough - it is), as well as different\nball sizes from ebay for relatively cheap.\n\nMy trackpoint pointer base sits flush under my 3mm switch plate, and\nwith a cherry MX switch having a height 10.2mm above the switch plate,\nand about 1-2mm PBT cherry keycap on top, the 14mm stem with 3mm ball is\nkind of perfect.\n\nFor extra friction on the ball, I used some sandpaper.\n\n![stem](images/stem.jpg)\n\n### Q: How do I identify the trackpoint pinout?\n\n**With some luck, or a multimeter and a steady hand.**\n(A scope would be better, but unfortunately I don't have one).\n\nIf you're lucky, someone has already identified the pinout of the\ntrackpoint you have (see [pinouts][pinouts]), or at least a similar one.\n\nIf not, you'll need to identify the pinout yourself, here are some tips:\n\n- The largest tracer is most likely GND.\n- The second largest tracer is most likely VCC.\n- Using a multimeter and the PTPM754 [datasheet][datasheets], test for\n  connectivity:\n\n```\nCLK (INT0)    - PTPM754 pin 24\nDATA (TXD/1)  - PTPM754 pin 2\nRST           - PTPM754 pin 5\nGND           - PTPM754 pin 8\nVCC           - PTPM754 pin 22\n```\n\n- Alternatively, if you have a scope and know what you're doing:\n\n```\nCLK  - should have a frequency reading\nDATA - should have a 5V reading\nRST  - should have a 0V reading\n```\n\n### Q: Should I use busywait, interrupt or usart in TMK?\n\nAs far as I know, USART is the recommended implementation, as it uses\nhardware for PS/2 signal receive.\n\nYou will need to use D2 (data) and D5 (clock) on the teensy though.\n\n## What you need\n\n- Keyboard with at least 6mm clearance between switch and base plates,\n  depending on the trackpoint module height.\n- TMK_keyboard firmware source code and development environment.\n- Teensy 2.0 (pins D2 and D5 available for USART).\n- Trackpoint module (salvaged from old thinkpad or new tp keyboard).\n- Veroboard (for reset circuit).\n- Reset circuit components (4.7k resistors x2, 100k resistor, 2.2uF capacitor).\n- Stem for trackpoint (labret cheek piercing 16G).\n- Double sided tape (for testing stem lengths before gluing).\n- Glue (stem to trackpoint, I used Loctite super glue-3)\n- Cutting knife (x-acto, nt-cutter, japanese knife, etc.).\n- Sandpaper (extra friction to stem ball, smooth veroboard cuts).\n- Thin wire (I used wire wrap 30 gauge).\n- Wire cutter and stripper.\n- PCB drill / thin rounded file (to make a 1.2mm hole).\n- Insulation tape (prevent shorts, protect trackpoint circuitry).\n- Soldering equipment.\n- Multi-meter.\n- Patience.\n\n- Bonus: extra teensy and breadboard for testing.\n\n## Steps\n\n### 1. Solder leads to trackpoint\n\n- What you need:\n\n    - Thin wire (I used wire wrap 30 guage wire)\n    - Wire cutter and stripper\n    - Soldering equipment\n    - Bonus: helping hand\n\n- Cut and strip 5 leads.\n- Clean and tin the trackpoint pads to be soldered.\n- Use a helping hand to hold the leads on the tinned pads, and heat the\n  stripped leads so they solder to the pad.\n\n### 2. Create the reset circuit (RC)\n\n- What you need:\n\n    - 4.7k resistors x2\n    - 100k resistor\n    - 2.2uF capacitor\n    - Veroboard\n    - Cutting knife (x-acto, nt-cutter, japanese knife, etc.)\n    - Sandpaper\n    - Soldering equipment\n    - Insulation tape\n\n- Cut a piece of veroboard (6x5 - the 5 is for rails)\n\n    - Using the cutting knife, perform 5-10 cuts on both sides.\n    - Using a little pressure, snap the board on the cut.\n    - Use sandpaper to smooth out the cut edges.\n\n![veroboard](images/veroboard.jpg)\n\n- Place the components on the veroboard, and solder\n\n    - Resistors\n\n        - Resistors don't have polarity, no need to worry.\n        - Bend component legs, insert into veroboard.\n        - On the back-side, slightly bend legs so components stay in position.\n        - Use insulation tape to hold resistors in position if needed.\n        - Snip legs (leaving about 3-5mm) and solder.\n        - Snip the protruding legs for extra clearance.\n\n    - Capacitor\n\n        - Capacitors have polarity, usually marked with a minus (negative).\n        - Positive leg must go in the VCC rail.\n        - Insert capacitor legs partially, so it can be bent off the\n          veroboard for clearance inside the keyboard case.\n        - On the back-side, bend legs slightly so it stays in position.\n        - Use insulation tape to hold capacitor in position.\n        - Snip legs and bend negative over to 100k resistor pad, and solder.\n        - Snip the protruding leg for extra clearance.\n\n![collage-reset](images/collage-reset.jpg)\n\n### 3. Solder leads to reset circuit (RC)\n\n- What you need:\n\n    - Thin wire (I used wire wrap 30 guage wire).\n    - Wire cutter and stripper.\n    - Soldering equipment.\n    - Bonus: helping hand.\n\n- Solder trackpoint leads to reset circuit.\n- Cut, strip and solder leads to reset circuit that will go to the teensy.\n\n![reset-underside](images/reset-underside.jpg)\n\n### 4. Testing on a breadboard\n\n- Insert teensy in breadboard.\n- Insert leads from RC into breadboard connected to teensy pins.\n- Update firmware to enable PS2 mouse and USART (see below).\n- Flash firmware to teensy, and test.\n\n![breadboard](images/breadboard.jpg)\n\n### 5. Make trackpoint stem hole in case\n\n- What you need:\n\n    - PCB drill / thin rounded file (to make a 1.2mm hole).\n\n- Decide where you want the trackpoint stem - I prefer using my middle\n  finger and have a row staggered keyboard, so I positioned it on the\n  cross section between U/I/K (QWERTY layout).\n\n- Locate position for trackpoint stem, and scratch or mark the space\n  available.\n\n- Remove the keycaps, make the hole (slowly and carefully), replace\n  keycaps.\n\n- Test stem diameter in hole. Should be rigid with a slight amount of\n  slack.\n\n![collage-hole](images/collage-hole.jpg)\n\n### 6. Make space for trackpoint in keyboard\n\n- What you need:\n\n    - Insulation tape.\n    - Wire cutter.\n\n- Add insulation tape to trackpoint to prevent shorts.\n- Rewire diodes / column wires if needed for trackpoint clearance.\n- Trim switch legs if needed for trackpoint clearance.\n- Relocate D2 and D5 pins if they are already being used.\n\n![collage-rewiring](images/collage-rewiring.jpg)\n\n### 7. Test trackpoint clearance and stem length, glue stem\n\n- What you need:\n\n    - Stem for trackpoint (labret cheek piercing 16G, different lengths).\n    - Double sided tape.\n    - Glue (loctite super glue-3).\n    - Sandpaper.\n\n- Remove red cap.\n- Stick a stem to trackpoint pointer base with double side tape.\n- Insert trackpoint with stem into hole.\n- Close case, flip keyboard, screw on stem ball, test.\n- Rinse and repeat for other stems until satisfied with length.\n\n- Remove double sided tape, glue stem.\n- Use sandpaper to roughen up the stem ball for added friction.\n\n### 8. Solder reset circuit (RC) to teensy\n\n- Solder leads to teensy:\n\n```\nVCC  -> teensy VCC\nGND  -> teensy GND\nCLK  -> teensy D5\nDATA -> teensy D2\n```\n\n![inside-side-view](images/inside-side-view.jpg)\n\n### 9. Finish up\n\n- Verify trackpoint is positioned squarely, and close case.\n- Screw on stem ball.\n\n![top-side-view](images/top-side-view.jpg)\n\n### 10. Update tmk_keyboard firmware and flash\n\n- What you need:\n\n    - TMK keyboard firmware and development environment.\n\n- Update firmware with PS2 mouse and USART support (see below).\n- Plug in keyboard, flash and test.\n\n## TMK firmware changes and tweaks\n\n- Configure PS2 mouse and USART support: [diff][tmk_usart]\n- Configure mousekeys: [keycodes][tmk_keycodes], [keymap][tmk_keymap]\n- Enable concurrent trackpoint movement and mousekeys: [diff][tmk_concurrent]\n- Trackpoint polling interval delay for dropped key strokes: [diff1][tmk_poll1], [diff2][tmk_poll2]\n- Todo: auto-enable mouse-layer on tp movement.\n\n\n[blackhawk]: http://www.alonswartz.org/keyboards/blackhawk/\n[pinouts]: ./pinouts/\n[datasheets]: ./datasheets/\n\n[tmk_usart]: https://github.com/alonswartz/tmk_keyboard/commit/f20a6f8fed823e5406f783b51db96c07ee14f079\n[tmk_keycodes]: https://github.com/alonswartz/tmk_keyboard/blob/blackhawk/tmk_core/doc/keycode.txt#L212\n[tmk_keymap]: https://github.com/alonswartz/tmk_keyboard/blob/1de1336fe06905893340df78ce43e9cafdbf32c9/keyboard/blackhawk/keymap_default.c#L23\n[tmk_concurrent]: https://github.com/alonswartz/tmk_keyboard/commit/e71670a120b0b0f746b13f593df0c988f03d277c\n[tmk_poll1]: https://github.com/alonswartz/tmk_keyboard/commit/a5c7dc87bb9f2872483f40482060a645e00e7557\n[tmk_poll2]: https://github.com/alonswartz/tmk_keyboard/commit/1de1336fe06905893340df78ce43e9cafdbf32c9\n\n"
  },
  {
    "path": "bin/toc.sh",
    "content": "#!/bin/bash -e\n\nfatal() { echo \"FATAL [$(basename $0)]: $@\" 1>&2; exit 1; }\n\nusage() {\ncat<<EOF\nSyntax: $(basename $0) file.md\nParse markdown and output table-of-contents\nEOF\nexit 1\n}\n\nsrc=$1\n[ -n \"$src\" ] || usage\n[ -e \"$src\" ] || fatal \"$src does not exist\"\n\ngrep \"^#\" $src | while read heading; do\n    indent=$(echo \"$heading\" | sed \"s/^\\#\\#\\(\\#*\\).*/\\1/\" | sed \"s/\\#/    /g\")\n    title=$(echo \"$heading\" | sed \"s/^\\#* //\")\n    link=$(echo \"$title\" | tr '[A-Z] ' '[a-z]-' | tr -d ':?,.()')\n    echo \"$indent- [$title](#$link)\"\ndone\n"
  },
  {
    "path": "pinouts/DSC_0534.txt",
    "content": "from top to bottom\n\n1\n2\n3\n4  DATA\n5  GND\n6  VCC\n7\n8  CLK\n9\n10\n"
  },
  {
    "path": "pinouts/r61.txt",
    "content": "1 DATA\n2 RST\n3 BTN1\n4 BTN2\n5 BTN3\n6 CLOCK\n7 GND\n8 VCC\n"
  },
  {
    "path": "pinouts/s73.txt",
    "content": "from right to left (top to bottom)\n\n1\n2\n3\n4  CLK (INT0 - 24)\n5  VCC (22)\n6  GND (8)\n7\n8  DATA (TXD/T1 - 2)\n9\n10 RST (5)\n"
  }
]