diff --git a/qmk-guide/README.md b/qmk-guide/README.md new file mode 100644 index 0000000..14386a2 --- /dev/null +++ b/qmk-guide/README.md @@ -0,0 +1,245 @@ +# The EZ Way to QMK + +Do you love your Kinesis Advantage, but also love your Ergodox-EZ? Now you can +have the best of both worlds with your very own QMK running Dactyl! Feels like a +Kinesis, works like an Ergodox-EZ. + +I found this [Massdrop guide](massdrop-ergodox-build-guide.pdf) that shipped with their original +Ergodox to be very helpful. + +## Shopping List + +### Things you'll have to find yourself: + +* Case +* 70x Cherry MX compatible Switches +* 6x Cherry ML switches (optional) + + +### Things you can order from Digikey + +#### An aside on LEDs + +Before you place this order, you'll need to figure out what color you want your +LEDs to be, or if you even want LEDs at all. + +I had a terrible time figuring out how to figure out which resistor to use with +each LED. All I can attest to is that +[These Orange LEDs](http://www.maxkeyboard.com/max-keyboard-orange-3mm-flangeless-replacement-led-for-backlit-mechanical-keyboard-10-pcs.html) +work with +[These 220Ω resistors](http://www.digikey.com/scripts/DkSearch/dksus.dll?Detail&itemSeq=229354283&uq=636318134508631803) +or at least have yet to fail in my Dactyl. + +I was hoping that I could find these LEDs on Digikey for you, but they don't +have ones with the exact specs and I don't know if that breaks the compatibility +with the resistors I found. + +Here's +[the evil mad scientist's guide](http://www.evilmadscientist.com/2012/resistors-for-leds/) +to choosing resistors for LEDs, but every time I did the math, it didn't work +out. + +Seriously, find someone who knows more about this if you're making decisions +here. You're probably already more qualified than me, so open a PR and fix this +session. + +* 70x [1N4148 Diodes](http://www.digikey.com/scripts/DkSearch/dksus.dll?Detail&itemSeq=229354375&uq=636318149504319926) +* 2x [2.2kΩ Pull up Resistors](https://www.digikey.com/product-detail/en/CFR-25JB-52-2K2/2.2KQBK-ND/666) +* 2x [TRRS Jacks](http://www.digikey.com/scripts/DkSearch/dksus.dll?Detail&itemSeq=229354247&uq=636318148338283334) +* 1 [Teensy 2.0](https://www.digikey.com/product-detail/en/adafruit-industries-llc/199/1528-1993-ND/6827126) +* 1 [MCP23018 I/O Expander](https://www.digikey.com/product-detail/en/microchip-technology/MCP23018-E-SP/MCP23018-E-SP-ND/1999505) +* [28 Pin IC Socket](http://www.digikey.com/scripts/DkSearch/dksus.dll?Detail&itemSeq=229356912&uq=636318143621851738) + +If you want everything in this list from [Digikey](https://www.digikey.com), you +can upload [this cart](digikey-shopping-cart.csv). + +### Things From Amazon + +* 1x [MiniUSB Extender Cable](https://www.amazon.com/gp/product/B00B5HSA3Q) +* Solder/Electrical Tape/Twosided tape +* [30AWG wrapping wire](https://www.amazon.com/gp/product/B00GWFECWO) +* TRRS Cable [this one](https://www.amazon.com/Coiled-3-5mm-Jack-Audio-Cable/dp/B019TRW4HQ) + worked for me, but it's a matter of taste and how much distance you need. + +## Wiring up the Matrix + +The firmware you choose will determine the wiring of the keyboard. Since the +Ergodox-EZ isn't going anywhere **AND** has first class support in QMK by its +creator, it makes pretty good sense to wire it up the same way. + +Here's what the matrix code for the Ergodox-EZ in QMK looks like: + +```c +// matrix positions +{ // MCP23018 + { k00, k10, k20, k30, k40, KC_NO }, \ + { k01, k11, k21, k31, k41, k51 }, \ + { k02, k12, k22, k32, k42, k52 }, \ + { k03, k13, k23, k33, k43, k53 }, \ + { k04, k14, k24, k34, k44, k54 }, \ + { k05, k15, k25, k35, KC_NO, k55 }, \ + { k06, k16, KC_NO, k36, KC_NO, k56 }, \ + // Teensy + { k07, k17, KC_NO, k37, KC_NO, k57 }, \ + { k08, k18, k28, k38, KC_NO, k58 }, \ + { k09, k19, k29, k39, k49, k59 }, \ + { k0A, k1A, k2A, k3A, k4A, k5A }, \ + { k0B, k1B, k2B, k3B, k4B, k5B }, \ + { k0C, k1C, k2C, k3C, k4C, k5C }, \ + { k0D, k1D, k2D, k3D, k4D, KC_NO } \ +} +``` + +This is a software mapping of 14 rows, even though the physical layout will wind +up with 14 columns. Physically, it looks like this: + +![](dactyl-keymapping.png) + +Look at those colors, they'll be consistent throughout this documentation, +including the physical wire we wire it up with. + +### Rows + +You don't have to decide how to connect the rows to the Teensy or MCP yet. Just +worry about getting the matrix right. + +Wiring rows 0-4 is easy. With the 30AWG wire, I had to cut individual wire +segments from switch to switch. The thumb clusters are Row 5 on each side, so +the same approach will work, it just doesn't look like a row. + +Row 5 is the thumb cluster, so just wire them together and imagine they're in a +row instead of it being more like a circle. + +The rows are just wire. Individual segments connecting two switches. I used a +pair of pointy tweezers to put little hooks on the end of each segment. The idea +is to let the Solder do most of the work. If a day ever comes where you have to +desolder one of these, you'll be glad you didn't aggressively wrap it. + +### Columns + +The columns need to be wired with diodes. You can probably wire the entire +column with the diode stems, but I chose to add some wire segments so it would +look clearer for this guide. + +![](dactyl-left-wiring.jpg) + +The diodes need the black bar facing away from the key. The other guides +disagree, but they don't use QMK. + +To use wire segments here, I soldered the end of the diode with the black bar to +the wire first, then placed the other stem on the switch, positioned the diode +where I wanted it and then bet the diode stem into a hook around the switch +terminal. + +I also made a habit of keeping the trimmed diode stems to use as bridges if +needed later. + +**Note:** Column 6 only has one key at this point. + +### Ergodox Compatibility Inner Columns + +**This is an optional step, and can be done as a mod after you're done** so +there's no pressure to make this decision now. + +Ergodoxes have an additional three keys in columns 6 & 7. Do you want them on +your Dactyl? + +I own an Ergodox-EZ as well, and want to use the same keymap for both. So I +added the extra switches below the thumb clusters as Cherry ML switches. If you +don't care about a consistent experience between a Dactyl and Ergodox, or even +if you do, it's a matter of personal preference. + +Wherever you put them, they're wired into rows 0,1 and 3. Either way, you need +to wire columns 6 and 7 to the top inner most key in the thumb cluster, so +columns 6 & 7 are going to be live. + +If you go with MLs, you can put them wherever you want, but be careful measuring +where the holes go, you only get one shot. + +**TODO:** CherryML switch hole specs. + +## The Matrix Has You + +Actually, you have it! Congratulations on having gotten this far. + +## Wiring The Right Half + +### Wiring the Teensy + +We have to start off with the obligatory wiring diagram + +![](dactyl-circuit-diagram.png) + +Notice the row numbers are different from the other guides to match the QMK +key codes we're using. + +I started off by breadboarding this whole project, but I also burnt out the +teensy's bootloader. +[My misadventures wiring a Dactyl](http://joedevivo.com/2017/05/20/building-a-qmk-dactyl.html) +are a fun read if you feel like this is too hard. I've been there. + +Here's the pinout mappings for the rows and columns: + +| Row | Wire Color | Teensy Pin | +|---------|------------|------------| +| 0 | Yellow | PF0 | +| 1 | Orange | PF1 | +| 2 | Green | PF4 | +| 3 | Brown | PF5 | +| 4 | Blue | PF6 | +| 5 | Purple | PF7 | + + +| Column | Wire Color | Teensy Pin | +|--------|------------|------------| +| 7 | Red | PB0 | +| 8 | Yellow | PB1 | +| 9 | Orange | PB2 | +| A | Green | PB3 | +| B | Brown | PD2 | +| C | Blue | PD3 | +| D | Purple | PC6 | + +Wiring the teensy involves looping the 30AWG wire through the Teensy's pinouts, +I went through twice, and then dabbed a little solder. If you are ok with +possibly wasting a little wire, you can use longer wire to solder up the Teensy +and then breadboard with those wires. There's no room for pins in the case, so +this is the best way to test it out. + +Here's my breadboarded version, almost done. (missing the reset wire to the MCP +in this photo) + +![](dactyl-breadboard.jpg) + +Yours will look similar, but with the Teensy coming from off board with a bunch +of wires. You don't have to breadboard the columns and rows for the teensy, you +can test them by clipping them to the right spot on the matrix you built. + +Columns and rows run by the MCP (Greetings, program!) will be accessible via the +breadboard. + +Here's what that looks like wired in. + +![](dactyl-right-wiring.jpg) + +Fortunately, QMK *will* let you just run the right half, so you can check in at +this point and see how that all works, + +### The TRRS Jack + +In an effort to move some of the bulk away from the Teensy, I put the pull up +resistors as close to the jack as I could. + +![](dactyl-pull-up-resistors.jpg) + +I wired the two 2.2k resistors to the bottom two terminals on the TRRS jack, +then wired the SCL(PD0) and SDA(PD1) to the resistor leg going into the jack. +Then soldered the outside legs together and ran a wire from Vcc to those outside +legs, and from them to a third terminal on the TRRS jack. Now all you need is to +run GND to the fourth terminal. + +![](trrs-diagram.jpg) + +## Wiring The Left Half + +### Wiring the I/O Expander diff --git a/qmk-guide/dactyl-breadboard.jpg b/qmk-guide/dactyl-breadboard.jpg new file mode 100644 index 0000000..052ab69 Binary files /dev/null and b/qmk-guide/dactyl-breadboard.jpg differ diff --git a/qmk-guide/dactyl-circuit-diagram.png b/qmk-guide/dactyl-circuit-diagram.png new file mode 100644 index 0000000..b563a1c Binary files /dev/null and b/qmk-guide/dactyl-circuit-diagram.png differ diff --git a/qmk-guide/dactyl-keymapping.png b/qmk-guide/dactyl-keymapping.png new file mode 100644 index 0000000..cc0051e Binary files /dev/null and b/qmk-guide/dactyl-keymapping.png differ diff --git a/qmk-guide/dactyl-left-wiring.jpg b/qmk-guide/dactyl-left-wiring.jpg new file mode 100644 index 0000000..575a1f6 Binary files /dev/null and b/qmk-guide/dactyl-left-wiring.jpg differ diff --git a/qmk-guide/dactyl-pull-up-resistors.jpg b/qmk-guide/dactyl-pull-up-resistors.jpg new file mode 100644 index 0000000..aea79e7 Binary files /dev/null and b/qmk-guide/dactyl-pull-up-resistors.jpg differ diff --git a/qmk-guide/dactyl-right-wiring.jpg b/qmk-guide/dactyl-right-wiring.jpg new file mode 100644 index 0000000..b857268 Binary files /dev/null and b/qmk-guide/dactyl-right-wiring.jpg differ diff --git a/qmk-guide/digikey-shopping-cart.csv b/qmk-guide/digikey-shopping-cart.csv new file mode 100644 index 0000000..f358f37 --- /dev/null +++ b/qmk-guide/digikey-shopping-cart.csv @@ -0,0 +1,8 @@ +Index,Quantity,Part Number,Description,Customer Reference,Available Quantity,Backorder Quantity,Unit Price USD,Extended Price USD, +1,2,CP-43514-ND,CONN JACK 4COND 3.5MM R/A,,2,0,1.06000,2.12, +2,2,2.2KQBK-ND,RES 2.2K OHM 1/4W 5% AXIAL,,2,0,0.10000,0.20, +3,3,220QBK-ND,RES 220 OHM 1/4W 5% AXIAL,,3,0,0.10000,0.30, +4,1,1528-1993-ND,TEENSY (ATMEGA32U4 USB DEV BOARD,,1,0,19.94000,19.94, +5,100,1N4148FS-ND,DIODE GEN PURP 100V 200MA DO35,,100,0,0.03080,3.08, +6,10,ED3050-5-ND,CONN IC DIP SOCKET 28POS TIN,,10,0,0.31500,3.15, +7,1,MCP23018-E/SP-ND,IC I/O EXPANDER I2C 16B 28SDIP,,1,0,1.56000,1.56, diff --git a/qmk-guide/massdrop-ergodox-build-guide.pdf b/qmk-guide/massdrop-ergodox-build-guide.pdf new file mode 100644 index 0000000..dd1c0f1 Binary files /dev/null and b/qmk-guide/massdrop-ergodox-build-guide.pdf differ diff --git a/qmk-guide/trrs-diagram.jpg b/qmk-guide/trrs-diagram.jpg new file mode 100644 index 0000000..81d308b Binary files /dev/null and b/qmk-guide/trrs-diagram.jpg differ