README.org

   1 * Atreus Keyboard
   2
   3 The Atreus is a mechanical keyboard designed primarily to match the
   4 shape of human hands and to be as portable as possible. The case
   5 measures 26x12cm and lacks even a number row, relying heavily upon the
   6 =fn= key. There is a circuit board for this design, but it's also
   7 possible to [[http://wiki.geekhack.org/index.php?title=Hard-Wiring_How-To][manually wire the matrix]].
   8
   9 I've seen a number of existing DIY 40% keyboard designs, but most of
  10 them stagger the rows, which I find very annoying now that I've gotten
  11 used to the columnar layout of the [[http://ergodox.org][Ergodox]]. In addition, many of the
  12 designs I've seen waste a lot of room on the space bar, failing to
  13 take into account the fact that the thumb is the strongest and most
  14 versatile of the fingers. This design avoids both these problems while
  15 taking a more couch-friendly single-piece approach.
  16
  17 [[./atreus.jpg]]
  18
  19 See [[./changelog.md][the changelog]] for the various revisions made to the design since
  20 its initial release.
  21
  22 ** Kits
  23
  24 You can buy [[http://atreus.technomancy.us][Atreus kits]] that have all the parts you need along with
  25 detailed assembly instructions from http://atreus.technomancy.us. If
  26 you'd rather round up all the parts yourself, that's possible too
  27 since the design is completely open source; see the bill of materials
  28 below.
  29
  30 ** Layout
  31
  32 Only a handful of punctuation marks (and no digits) are available
  33 unshifted, and all the modifiers are on the bottom row:
  34
  35  :    q     w     e     r     t       ||       y     u     i     o    p
  36  :    a     s     d     f     g       ||       h     j     k     l    ;
  37  :    z     x     c     v     b       ||       n     m     ,     .    /
  38  :   esc   tab  super shift bksp ctrl || alt space  fn     -     '  enter
  39
  40 The numbers and most of the punctuation are on the fn layer with a
  41 numpad-style arrangement under the right hand:
  42
  43  :    !     @     {     }     |       ||     pgup    7     8     9    *
  44  :    #     $     (     )     `       ||     pgdn    4     5     6    +
  45  :    %     ^     [     ]     ~       ||       \     1     2     3    ?
  46  :   L2  insert super shift bksp ctrl || alt space   fn    .     0    =
  47
  48 The =L2= key switches it to the function layer, and tapping =L0= here
  49 brings it back to the first layer.
  50
  51  :  insert home    ↑    end  pgup     ||       ↑     F7    F8    F9   F10
  52  :    del   ←      ↓     →   pgdn     ||       ↓     F4    F5    F6   F11
  53  :                                    ||             F1    F2    F3   F12
  54  :              super shift bksp ctrl || alt space   L0             reset
  55
  56 The [[https://github.com/technomancy/atreus-firmware][firmware project]] includes a number of other options, including
  57 colemak, dvorak, and "software dvorak" which sends keycodes assuming
  58 the OS will perform the translation into dvorak. Adding new layouts or
  59 changing existing ones is easy.
  60
  61 ** Parts
  62
  63 *** Switches
  64
  65 This layout has five modifiers and 37 non-modifiers.
  66
  67 I strongly prefer the feel and sound of tactile [[http://mechanicalkeyboards.com/shop/index.php?l=product_detail&p=651][Cherry MX blue]]
  68 switches for typing. However, I like having linear [[http://mechanicalkeyboards.com/shop/index.php?l=product_detail&p=103][Cherry MX black
  69 switches]] switches on the modifier keys (ctrl, alt, super, shift, and
  70 fn) because the tactile effect has no benefit for keys that are held
  71 down, and giving a different response helps you learn the layout more
  72 quickly.
  73
  74 For users that need to operate in sound-sensitive environments like
  75 open offices or libraries, [[http://deskthority.net/wiki/Cherry_MX_Clear][Cherry MX Clear]] switches are a popular
  76 choice since they still offer tactility withut the noise.
  77
  78 *** Diodes
  79
  80 In order to avoid ghosting, each switch needs a diode. The [[https://www.radioshack.com/product/index.jsp?productId=2062587][1N4148]] is a
  81 readily-available choice, but nearly any signal diode would work.
  82
  83 *** Microcontroller
  84
  85 The circuit board design uses a [[http://www.pololu.com/product/3101][Pololu A-star micro]]. Hand-wired boards
  86 can also use a [[http://www.pjrc.com/teensy/index.html][Teensy 2]] or [[http://arduino.cc/en/Main/ArduinoBoardMicro][Arduino Pro Micro]].
  87
  88 Be sure to get a microcontroller without headers so it will fit in
  89 between the bottom layer and the plate. USB micro is preferred over
  90 USB mini for this reason as well.
  91
  92 *** Keycaps
  93
  94 This [[http://keyshop.pimpmykeyboard.com/products/full-keysets/dsa-blank-sets-1][DSA-shaped base set]] (spherical indentations on the key, same
  95 profile for each row) from Signature Plastics has 52 1x keys plus a
  96 few extras we won't use. There are two "deep dish" keys in that set
  97 which you can place under your index fingers on the home row to help
  98 guide your hands to the right spot without looking. However, you only
  99 get a single 1.5x keycap, and the middle two thumb keys both use them,
 100 so you might want to pick up an extra.
 101
 102 Many keycap sets (not the one linked above) are "sculpted", meaning
 103 that keys that go in different rows have a different shape. While you
 104 can use these for an Atreus, it's unlikely you'll find a set with the
 105 correct number for each row, so it's more wasteful.
 106
 107 ** Circuit Board
 108
 109 The =atreus.rkt= program calculates switch and diode positions based
 110 on row/column counts, spacing, and rotation factors, and emits a
 111 =atreus.kicad_pcb= file. The board outline and traces are done by hand
 112 and are stored in the =header.rktd= and =traces.rktd= files
 113 respectively. The =atreus.kicad_pcb= file can be imported into [[http://kicad.org][Kicad]]
 114 which can export Gerber files suitable for fabrication. A copy of the
 115 Kicad PCB file is included in the repository if you don't want to
 116 recompile it using Racket. Recompiling is only required if you want to
 117 make changes to the procedurally-generated portions of the board.
 118
 119 Unfortunately most PCB fabricators require a minimum order of 10 or
 120 so, making this impractical for one-offs. The PCB is not required, so
 121 for one-off boards it's usually more sensible to stick with a [[http://atreus.technomancy.us/assembly-hand-wired.pdf][hand-wired build]] instead.
 122
 123 ** Case
 124
 125 Layered laser-cut wood or acrylic. The original case (=case-mk-i.svg=)
 126 is slightly less wide and has a minor asymmetry with the screws on the
 127 bottom side. The [[http://geekhack.org/index.php?topic%3D54759.msg1304117#msg1304117][mark II case]] (in the =case/dxf= directory) is
 128 available as a DFX file that you can convert to SVG or EPS for a laser
 129 cutter using Inkscape. Mark II features 8 screw holes and a kind of "stair
 130 step" design around the top and bottom of the key clusters; mark I is
 131 pictured below.
 132
 133 TODO: the logo is missing from some of the case files and needs to be added back in.
 134
 135 There is also a programmatically-implemented version of the case
 136 written in OpenSCAD; it is more flexible (you can tweak the number of
 137 rows/cols, etc and recompile) but it doesn't match the canonical case
 138 exactly; in particular the screw holes are placed differently.
 139
 140 [[./layers.jpg]]
 141
 142 The first two shapes in the case file are the top and bottom covers;
 143 these should be cut on 3mm acrylic (black in the photo). The third is
 144 the spacer that goes under the fourth, which is the plate on which the
 145 switches are mounted. These should be cut in 6mm, especially the
 146 spacer, which needs to be at least as thick as the mini USB cable you
 147 connect to the microcontroller. I recommend using a mini USB cable
 148 with as thin a connector as you can find or sanding the connector
 149 down to the required thickness. The switch plate could be thinner, but
 150 not under 3mm.
 151
 152 On a 100W Epilog laser, the 3mm layers cut in about a minute and a
 153 half. I did a run with 6mm acrylic of the other layers which took
 154 nearly 6 minutes.
 155
 156 Wood cases should be finished with sandpaper and finishding oil/wax.
 157
 158 ** Firmware
 159
 160 The [[https://github.com/technomancy/atreus-firmware/][custom Atreus firmware]] is a small C project which
 161 implements matrix scanning and debouncing with user-customizeable
 162 layers and macro functions. Another option is the much more complex
 163 TMK firmware. My [[https://github.com/technomancy/tmk_keyboard/tree/atreus][fork of the tmk firmware]] has support for the Atreus
 164 layout. You should be able to change into the =keyboard/atreus=
 165 directory and run =make KEYMAP=atreus= (or whichever variant you want)
 166 to produce a qwerty =atreus.hex= file. You will probably want to
 167 create your own layout once you've gotten a chance to try it and see
 168 what works for you.
 169
 170 In either case you would use the =.hex= file you just produced with
 171 =avrdude= or the [[http://www.pjrc.com/teensy/loader.html][teensy loader]] to upload to the microcontroller. =make
 172 upload= should do what you need.
 173
 174 Once the firmware is loaded and the keyboard is assembled, activating
 175 the hardware reset to upload new versions of the firmware is pretty
 176 cumbersome; instead use the "reset" button on the layout, which has
 177 the same effect.
 178
 179 ** Bill of Materials
 180
 181 - 50 MX Blue switches: $29.00 (mechanicalkeyboards.com)
 182 - 50 diodes: $3.45 (radio shack, should be able to buy in-person)
 183 - Base blank DSA keycap set: $23.00 (signatureplastics.com)
 184 - Teensy 2: $16, $3 shipping (pjrc.com)
 185 - Case materials: ~$16, varies by source
 186 - Case laser cutting: 7.5 minutes on a 100W Epilog laser; varies by source
 187 - USB micro cable: $5, various sources
 188
 189 Recommended but optional:
 190
 191 - 5 MX Red or MX Black switches: $8.50 - $10.00
 192 - additional 1.5x DSA keycap: $1 plus $8 shipping
 193
 194 The base keycap set only has one 1.5x key, which is used for the inner
 195 thumb keys. You can use a 1x key for one of them, but it looks kind of
 196 tacky, so I recommend getting a second 1.5x keycap separately.
 197
 198 *** Other Tools
 199
 200 You'll need a soldering iron, solder, and a wire cutter. A multimeter
 201 can come in handy for testing the connections but is optional. You'll
 202 also need eight M3 machine screws with nuts; the length of the screws
 203 depends on the thickness of the acrylic you use. You can add rubber
 204 feet to the bottom to prevent the board from sliding around when
 205 placed on a desk. You'll also need sandpaper and finishing oil for the
 206 wooden cases unless you have bought a kit.
 207
 208 If you are building a hand-wired board you will also need a glue gun,
 209 hookup wire, and wire strippers.
 210
 211 ** Assembly
 212
 213 See the [[http://atreus.technomancy.us/assembly.pdf][assembly instructions]] PDF.
 214
 215 Hand-wired boards will want the [[http://atreus.technomancy.us/assembly-hand-wired.pdf][previous edition of the assembly instructions]].
 216
 217 ** Inspiration
 218
 219 These fine projects all provided inspiration for various aspects of
 220 the Atreus, as well as the folks on the =#geekhack= freenode channel.
 221
 222 - [[http://ergodox.org][Ergodox]]
 223 - [[http://deskthority.net/workshop-f7/onehand-20-keyboard-t6617.html][OneHand]]
 224 - [[http://blog.fsck.com/2013/12/better-and-better-keyboards.html][keyboard.io]]
 225 - [[http://geekhack.org/index.php?topic=48718][ErgoT]]
 226
 227 ** Builds
 228
 229 If you've built an Atreus, please add your name to [[https://github.com/technomancy/atreus/wiki/BuildLogs][the build logs wiki]].
 230
 231 There's also a [[http://librelist.com/browser/atreus/][mailing list]] for people who have built or ordered an
 232 Atreus or are interested in doing so. To join, simply email
 233 =atreus@librelist.com= with a subject of "join" and reply to the
 234 confirmation.
 235
 236 ** Orestes
 237
 238 A new [[https://www.flickr.com/photos/technomancy/14654421878][experimental build]] uses the [[http://pjrc.com/store/teensy31.html][Teensy 3]] microcontroller and
 239 ARM [[https://github.com/technomancy/orestes/tree/teensy3][Forth-based]] firmware, but this is not yet suitable for general-purpose use.
 240
 241 ** License
 242
 243 Copyright © 2014 Phil Hagelberg and contributors
 244
 245 Released under the [[https://www.gnu.org/licenses/gpl.html][GNU GPL version 3]]