README.org

   1 * Atreus Keyboard
   2
   3 The [[http://ergodox.org][Ergodox]] keyboard is an absolutely fantastic design; I use it every
   4 day at my office. However, I like to work away from the office
   5 frequently, and I thought I might try my hand at designing something a
   6 little more portable. The great thing about assembling my Ergodox is
   7 that it taught me there's really nothing magical about it; it's just a
   8 piece of circuitry with a bunch of switches read by a microcontroller
   9 that speaks the USB HID interface.
  10
  11 The Atreus is meant to be complementary to the Ergodox as something
  12 smaller, cheaper, and more travel-friendly. The case measures 25x11cm
  13 and lacks even a number row, relying heavily upon the fn key. There is
  14 no PCB in this design, requiring [[http://wiki.geekhack.org/index.php?title=Hard-Wiring_How-To][a manual matrix wiring approach]].
  15 However, given that there are only 4 rows and 11 columns, this isn't
  16 as daunting as it could be.
  17
  18 I've seen a number of existing DIY 40% keyboard designs, but most of
  19 them stagger the rows, which I find very annoying now that I've gotten
  20 used to the columnar layout of the Ergodox. In addition, many of the
  21 designs I've seen waste a lot of room on the space bar, failing to
  22 take into account the fact that the thumb is the strongest and most
  23 versatile of the fingers. This design avoids both these problems while
  24 taking a more couch-friendly single-piece approach.
  25
  26 [[atreus.jpg]]
  27
  28 Having so few keys, this board is pretty idiosyncratic. It works very
  29 well for the kind of work that I do, but it probably wouldn't be a
  30 good fit for you if you do a lot of numerical data entry or make heavy
  31 use of function keys, arrows, or home/end. If you primarily use
  32 programs with good key rebinding functionality, you're probably in
  33 good shape. For instance, =enter= is in a bit of an awkward position,
  34 but many programs treat =control-m= as the same.
  35
  36 ** Layout
  37
  38 Only a handful of punctuation marks (and no digits) are available
  39 unshifted, and all the modifiers are on the bottom row:
  40
  41  :    '     ,     .     p     y       ||       f     g     c     r    l
  42  :    a     o     e     u     i       ||       d     h     t     n    s
  43  :    ;     q     j     k     x       ||       b     m     w     v    z
  44  :   esc   tab  super shift bksp ctrl || alt space  fn     -     /  enter
  45
  46 The numbers and most of the punctuation are on the fn layer with a
  47 numpad-style arrangement under the right hand:
  48
  49  :    !     @     {     }     |       ||     pgup    7     8     9    *
  50  :    #     $     (     )     `       ||     pgdn    4     5     6    +
  51  :    %     ^     [     ]     ~       ||       \     1     2     3    ?
  52  :  reset paste                       ||     hwdv          .     0    =
  53
  54 An alternate layout has the numbers in a more traditional row across the top:
  55
  56  :    1     2     3     4    5        ||       6     7     8     9    0
  57  :    -     +     (     )    =        ||       .     [     ]     {    }
  58  :    !     @     #     $    %        ||       ^     &     *     ~    ?
  59  :  reset paste              `        ||     hwdv        pgup  pgdn   \
  60
  61 I type in Dvorak but prefer to do the remapping in software rather
  62 than hardware so I don't have to change layouts when I switch to my
  63 laptop's internal keyboard. However, the =hwdv= key switches it to
  64 hardware dvorak mode, which is useful for attaching to computers that
  65 may not have software dvorak set up. The =paste= key sends
  66 shift+insert, while the =reset= button activates the bootloader,
  67 allowing easy reprogramming without opening the case.
  68
  69 This is all a matter of firmware though; the layout is easy to change
  70 after the fact.
  71
  72 ** Parts
  73
  74 *** Switches
  75
  76 This layout has five modifiers and 37 non-modifiers.
  77
  78 I strongly prefer the feel and sound of tactile [[http://mechanicalkeyboards.com/shop/index.php?l=product_detail&p=651][Cherry MX blue]]
  79 switches for typing. However, I like having linear switches on the
  80 modifier keys (ctrl, alt, super, shift, and fn). [[http://mechanicalkeyboards.com/shop/index.php?l=product_detail&p=102][Cherry MX red switches]]
  81 are nice and light but are expensive and difficult to
  82 find. [[http://mechanicalkeyboards.com/shop/index.php?l=product_detail&p=103][Cherry MX black switches]] are cheaper and easier to source, but
  83 may be too heavy, especially for keys under pinky fingers.
  84
  85 One trick is take the springs from some of your blue switches and
  86 trade them with the springs from your black switches. The blacks then
  87 become the equivalent of reds, and the blues become MX green switches,
  88 which are a heavier variant of blues. These are typically used for
  89 space bars on boards that otherwise use blues. They could be suitable
  90 for non-modifier thumb keys like backspace, space, and enter. However,
  91 the recommended layout above has all its modifiers under the thumbs,
  92 so this is not an issue.
  93
  94 *** Diodes
  95
  96 In order to avoid ghosting, each switch needs a [[https://www.radioshack.com/product/index.jsp?productId=2062587][1N4148 diode]].
  97
  98 *** Microcontroller
  99
 100 An [[http://www.digikey.com/product-search/en/programmers-development-systems/evaluation-boards-embedded-mcu-dsp/2621773?k=arduino%20micro][Arduino Micro]] or [[http://www.pjrc.com/teensy/index.html][Teensy 2]] is recommended. Be sure to get one
 101 without headers so it will fit in between the bottom layer and the plate.
 102
 103 *** Keycaps
 104
 105 This [[http://keyshop.pimpmykeyboard.com/product/dsa-pbt-blank-sets][DSA-shaped base set]] (spherical indentations on the key, same
 106 profile for each row) from Signature Plastics has 52 1x keys plus a
 107 few extras we won't use. There are two "deep dish" keys in that set
 108 which you can place under your index fingers on the home row to help
 109 guide your hands to the right spot without looking. However, you only
 110 get a single 1.5x keycap, and the middle two thumb keys both use them,
 111 so you might want to pick up an extra. (You can buy a single DSA 1.5x
 112 keycap from [[http://www.keycapsdirect.com/key-capsinventory.php][Signature Plastics]].)
 113
 114 If you want labels on your keycaps, you can get a full labelled
 115 standard 104-key set from [[http://elitekeyboards.com/products.php?sub=access#cherrymxkeys][Elite Keyboards]] as well. However, the
 116 modifiers in that set are larger than what the Atreus uses, so you'll
 117 have to place some mis-labelled caps on the bottom row.
 118
 119 ** Case
 120
 121 Layered laser-cut acrylic; see [[file:case.svg][case.svg]].
 122
 123 [[layers.jpg][layers.jpg]]
 124
 125 The first two shapes in the case file are the top and bottom covers;
 126 these should be cut on 3mm acrylic (black in the photo). The third is
 127 the spacer that goes under the fourth, which is the plate on which the
 128 switches are mounted. These should be cut in 6mm, especially the
 129 spacer, which needs to be at least as thick as the micro USB cable you
 130 connect to the microcontroller. The switch plate could be thinner,
 131 but not under 3mm.
 132
 133 On a 100W Epilog laser, the 3mm layers cut in about a minute and a
 134 half. I did a run with 6mm acrylic of the other layers which took
 135 nearly 6 minutes.
 136
 137 ** Firmware
 138
 139 My [[https://github.com/technomancy/tmk_keyboard/tree/atreus][fork of the tmk firmware]] has support for the Atreus layout.  You
 140 should be able to cd into the =keyboard/atreus= directory and run
 141 =make KEYMAP\=atreus= (or whichever variant you want) to produce a
 142 qwerty =atreus.hex= file. You will probably want to create your own
 143 layout once you've gotten a chance to try it and see what works for
 144 you. Use the =.hex= file with the [[http://www.pjrc.com/teensy/loader.html][teensy loader]] or Arduino tools to
 145 upload to the microcontroller.
 146
 147 Once the firmware is loaded and the keyboard is assembled, pressing
 148 the onboard reset button to update new versions of the firmware is
 149 pretty cumbersome; instead use the "reset" button on the lower left
 150 of the layout which has the same effect.
 151
 152 I'm working on an experimental Forth-based firmware in the [[https://github.com/technomancy/orestes][Orestes]]
 153 project, but that project is still in its infancy at the time of this
 154 writing.
 155
 156 ** Bill of Materials
 157
 158 - 50 MX Blue switches: $29.00 (mechanicalkeyboards.com)
 159 - 50 diodes: $3.45 (radio shack, should be able to buy in-person)
 160 - Base blank DSA keycap set: $18.00 (signatureplastics.com)
 161 - Teensy 2: $16 (pjrc.com or mechanicalkeyboards.com)
 162 - Acrylic materials: $11
 163 - Acrylic laser cutting: 7.5 at $3/min (varies by thickness of acrylic)
 164
 165 - Labelled 104 keycap set: $20.00 (optional, replaces DSA set above)
 166 - 5 MX Black switches: $8.50 (optional)
 167 - 5 MX Red switches: $10.00 (optional)
 168 - additional 1.5x DSA keycap: $1 (optional)
 169
 170 =(+ 29 3.45 18 16 11 (* 3 7.5))= $99.95 plus tax/shipping
 171
 172 - mechanicalkeyboards.com: free shipping in the US
 173 - Signature Plastics (keycaps) US shipping: $8.00
 174 - PJRC (teensy) shipping: $3.03
 175
 176 *** Cost-saving Options
 177
 178 There are a few ways to lower the cost further.  Using [[http://mechanicalkeyboards.com/shop/index.php?l=product_detail&p=482][Matias]] key
 179 switches could save you a fair bit if you go in on a 90-pack with
 180 someone else, but they're a little harder to find keycaps for; the MX
 181 caps won't work on them. Using wood for the case will reduce both the
 182 materials cost as well as the amount of time needed to cut the case.
 183
 184 Replacing the colored acrylic with transparent might also save a few
 185 dollars. You could also use thinner acrylic for the switch plate too;
 186 I cut mine in 4.5mm. A thinner spacer is inadvisable; even with 6mm
 187 it's pretty tight.
 188
 189 Another common trick is scavenging keycaps and switches from used
 190 keyboards; something with Cherry or Alps switches should work. This
 191 can be time-consuming though.
 192
 193 *** Other Tools
 194
 195 You'll need a soldering iron, solder, a glue gun, a multimeter, wire,
 196 wire strippers, and a USB mini cable. You'll also need seven M3
 197 machine screws with nuts; the length of the screws depends on the
 198 thickness of the acrylic you use. You can add rubber feet to thet
 199 bottom to prevent the board from sliding around when placed on a desk.
 200
 201 ** Assembly
 202
 203 Once you have all the parts, the first thing to do is glue the
 204 switches to the switch plate since there's no PCB to hold them in
 205 place. Be aware that the screw holes unfortunately are not
 206 symmetrical, so before inserting the switches it's important to ensure
 207 that the plate is right-side-up. Use a drop of hot glue on the top and
 208 bottom of each switch to affix it in place.
 209
 210 [[wires.jpg]]
 211
 212 Once the switches are in place, the matrix must be created. I
 213 recommend getting red wire for the (postitive) rows and black for the
 214 (negative) columns. The rows need eight wires with the insulation
 215 exposed at intervals matching the spacing of the switches; see the
 216 above photo for details. You could also just use many short stripped
 217 segments of wire instead of a contiguous piece.
 218
 219 [[thumb-diagram.jpg]]
 220
 221 Most of the row wires will need four segments of insulation, but
 222 you'll need two with five for the rows with the inner thumb
 223 keys. Physically the inner thumb keys look like two additional
 224 columns, but logically they are treated as if they're in the same
 225 column with the left one in row 3 and the right one in row 4.
 226
 227 [[matrix.jpg]]
 228
 229 The exposed sections of row wire should be connected to the higher of
 230 the pins on the switch using a diode. Be aware that diodes are
 231 directional! The band around the diode should point to the top of the
 232 board. Take care with the upper row that you don't let the wire go too
 233 close to the top edge of the board; avoid getting in the way of the
 234 spacer layer. Once the rows are wired, the remaining (negative) pin of
 235 each switch should be wired into the negative pin of the switch above
 236 and below it with black wire. This should be slightly easier since no
 237 diode is necessary. The photo above shows the completed matrix for one
 238 side. Test each row and column as you go with a multimeter. You should
 239 be able to get continuity from row to column when the corresponding
 240 switch is activated.
 241
 242 After the matrix has been wired on both sides, the next step is to
 243 connect the microcontroller. The TMK firmware has the rows in pins D0,
 244 D1, D2, and D3 of the microcontroller. You'll need to connect the rows
 245 from both the left and right sides into the proper pin. There are more
 246 columns than rows, so I used ribbon cable to bring the column
 247 connections back to the microcontroller from the outside in. The
 248 columns go to pins F0, F1, E6, C7, C6, B6, D4, B1, B0, B5, and
 249 B4. It's important to realize that when you flip over the board
 250 in order to solder it, you have to flip over the schematic in your
 251 mind too. If you count your columns from the left, you'll get them
 252 backwards. (Which I actually did for the first half.)
 253
 254 [[controller.jpg]]
 255
 256 Once you've wired one side of the microcontroller in, it would be a
 257 good time to test it. You'll need to compile and upload as per the
 258 "Firmware" section above. At this point you should be reading real
 259 keycodes from the half of the keyboard that you've wired. Once you've
 260 confirmed that's working, continue with the other half. Then screw the
 261 other layers in place and you're all set!
 262
 263 ** Inspiration
 264
 265 These fine projects all provided inspiration for various aspects of
 266 the Atreus, as well as the folks on the =#geekhack= freenode channel.
 267
 268 - [[http://ergodox.org][Ergodox]]
 269 - [[http://deskthority.net/workshop-f7/onehand-20-keyboard-t6617.html][OneHand]]
 270 - [[http://blog.fsck.com/2013/12/better-and-better-keyboards.html][keyboard.io]]
 271 - [[http://geekhack.org/index.php?topic=48718][ErgoT]]
 272
 273 ** Builds
 274
 275 If you've built an Atreus, please let us know (pull request or
 276 otherwise) and get your name and link added here:
 277
 278 - [[http://technomancy.us/173][Phil Hagelberg]]
 279 - [[http://blog.tarn-vedra.de/2014/04/reproducing-keyboard-science_1707.html][Moritz Ulrich]]
 280 - [[http://geekhack.org/index.php?topic=57007.0][Constantine]]
 281
 282 ** License
 283
 284 Copyright © 2014 Phil Hagelberg
 285
 286 Released under the [[https://www.gnu.org/licenses/gpl.html][GNU GPL version 3]]