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  :    !    @     up     {    }        ||     pgup    7     8     9    *
  44  :    #  left   down  right  $        ||     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  :                             reset  ||             F1    F2    F3   F12
  54  :              super shift bksp ctrl || alt space   L0
  55
  56 The [[https://atreus.technomancy.us/tmk][firmware]] 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 [[https://deskthority.net/wiki/Matias_switch#Click][Matias Clicky]]
  68 switches for typing. However, I like having [[https://deskthority.net/wiki/Matias_switch#Linear][Matias Linear
  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,
  76 [[http://deskthority.net/wiki/Matias_switch#Quiet_click][Matias Quiet
  77 Click]] switches are a popular choice since they still offer tactility
  78 without the noise. Other users prefer switches in the
  79 [[http://deskthority.net/wiki/Cherry_MX][Cherry MX]] family, which use
  80 different keycaps and switch plates but still work fine.
  81
  82 *** Diodes
  83
  84 In order to avoid ghosting, each switch needs a diode. The [[https://www.radioshack.com/product/index.jsp?productId=2062587][1N4148]] is a
  85 readily-available choice, but nearly any signal diode would work.
  86
  87 *** Microcontroller
  88
  89 The circuit board design uses a [[http://www.pololu.com/product/3101][Pololu A-star micro]]. Hand-wired boards
  90 can also use a [[http://www.pjrc.com/teensy/index.html][Teensy 2]] or [[http://arduino.cc/en/Main/ArduinoBoardMicro][Arduino Pro Micro]].
  91
  92 Be sure to get a microcontroller without headers so it will fit in
  93 between the bottom layer and the plate. USB micro is preferred over
  94 USB mini for this reason as well.
  95
  96 *** Keycaps
  97
  98 Caps for Matias switches are included in the official kits. Sculpted
  99 caps are also available [[http://matias.ca/order/#keycaps][from
 100 Matias]] or by harvesting from old Alps keyboards. It's recommended
 101 that you use unlabeled keys, because due to the different sizes and
 102 orientations of certain keys (backspace, shift, enter, etc) the labels
 103 will be incorrect if present.
 104
 105 Cherry switches have more options. This
 106 [[http://keyshop.pimpmykeyboard.com/products/full-keysets/dsa-blank-sets-1][DSA-shaped
 107 base set]] (spherical indentations on the key, same profile for each
 108 row) from Signature Plastics has 52 1x keys plus a few extras we won't
 109 use. There are two "deep dish" keys in that set which you can place
 110 under your index fingers on the home row to help guide your hands to
 111 the right spot without looking. However, you only get a single 1.5x
 112 keycap, and the middle two thumb keys both use them, so you might want
 113 to pick up an extra.
 114
 115 ** Circuit Board
 116
 117 The =atreus.rkt= program calculates switch and diode positions based
 118 on row/column counts, spacing, and rotation factors, and emits a
 119 =atreus.kicad_pcb= file. The board outline and traces are done by hand
 120 and are stored in the =header.rktd= and =traces.rktd= files
 121 respectively. The =atreus.kicad_pcb= file can be imported into [[http://kicad-pcb.org][Kicad]]
 122 which can export Gerber files suitable for fabrication. A copy of the
 123 Kicad PCB file is included in the repository if you don't want to
 124 recompile it using Racket. Recompiling is only required if you want to
 125 make changes to the procedurally-generated portions of the board.
 126
 127 Unfortunately most PCB fabricators require a minimum order of 10 or
 128 so, making this impractical for one-offs. The PCB is not required, so
 129 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.
 130
 131 ** Case
 132
 133 Layered laser-cut wood or acrylic. The [[http://geekhack.org/index.php?topic%3D54759.msg1304117#msg1304117][mark II case]] (EPS files in the
 134 =case/= directory) features 8 screw holes and a kind of "stair step"
 135 design around the top and bottom of the key clusters; mark I is
 136 pictured below.
 137
 138 The =3mm-alps-all.eps= file contains the top plate, bottom plate, and
 139 switch plate for Matias switches. =3mm.eps= contains the files for
 140 Cherry boards. These pieces can all be cut on 3mm acrylic or wood. The
 141 =spacer.eps= file should be cut on something thicker; between 4.5mm
 142 and 6mm is recommended. The spacer needs to be at least as thick as
 143 the connector of the USB cable you're using.
 144
 145 There is also a programmatically-implemented version of the case
 146 written in OpenSCAD; it is more flexible (you can tweak the number of
 147 rows/cols, etc and recompile) but it doesn't match the canonical case
 148 exactly; in particular the screw holes are placed differently.
 149
 150 The original case (=case-mk-i.svg=) design is also included; it is
 151 slightly less wide and has a minor asymmetry with the screws on the
 152 bottom side.
 153
 154 On a 100W Epilog laser, the 3mm layers cut in about a minute and a
 155 half. I did a run with 6mm acrylic of the other layers which took
 156 nearly 6 minutes.
 157
 158 Wood cases should be finished with sandpaper and finishing oil/wax or
 159 with [[https://atreus.technomancy.us/lacquer.pdf][lacquer]] which
 160 takes longer but feels nicer.
 161
 162 ** Firmware
 163
 164 The [[https://atreus.technomancy.us/tmk][TMK firmware]] is
 165 recommended. You should be able to change into the =keyboard/atreus=
 166 directory and run =make KEYMAP=qwerty= (or whichever variant you want)
 167 to produce a qwerty =atreus.hex= file. You will probably want to
 168 create your own layout once you've gotten a chance to try it and see
 169 what works for you. See the readme for instructions of how to upload
 170 it to the keyboard's controller.
 171
 172 There is also the older
 173 [[https://github.com/technomancy/atreus-firmware][atreus-firmware]
 174 custom codebase which works but has fewer features. It is recommended
 175 mostly for learning purposes since the code is much simpler and easier
 176 to understand than TMK.
 177
 178 ** Bill of Materials
 179
 180 Using Cherry switches is cheapest unless you can find cheap Alps-mount keycaps:
 181
 182 - 50 MX Blue switches: $29.00 (mechanicalkeyboards.com)
 183 - 50 diodes: $3.45 (radio shack, should be able to buy in-person)
 184 - Base blank DSA keycap set: $23.00 (signatureplastics.com)
 185 - Teensy 2: $16, $3 shipping (pjrc.com)
 186 - Case materials: ~$16, varies by source
 187 - Case laser cutting: 7.5 minutes on a 100W Epilog laser; varies by source
 188 - USB micro cable: $5, various sources
 189
 190 Recommended but optional:
 191
 192 - 5 MX Red or MX Black switches: $8.50 - $10.00
 193 - additional 1.5x DSA keycap: $1 plus $8 shipping
 194
 195 The base keycap set only has one 1.5x key, which is used for the inner
 196 thumb keys. You can use a 1x key for one of them, but it looks kind of
 197 tacky, so I recommend getting a second 1.5x keycap separately.
 198
 199 *** Other Tools
 200
 201 You'll need a soldering iron, solder, and a wire cutter. A multimeter
 202 can come in handy for testing the connections but is optional. You'll
 203 also need eight M3 machine screws with nuts; the length of the screws
 204 depends on the thickness of the acrylic you use. You can add rubber
 205 feet to the bottom to prevent the board from sliding around when
 206 placed on a desk. You'll also need sandpaper and finishing oil for the
 207 wooden cases unless you have bought a kit.
 208
 209 If you are building a hand-wired board you will also need a glue gun,
 210 hookup wire, and wire strippers.
 211
 212 ** Assembly
 213
 214 See the [[https://atreus.technomancy.us/assembly.pdf][assembly instructions]] PDF.
 215
 216 Hand-wired boards will want the [[https://atreus.technomancy.us/assembly-hand-wired.pdf][previous edition of the assembly instructions]].
 217
 218 The LaTeX source to the assembly instructions is in the =assembly= directory.
 219
 220 ** Inspiration
 221
 222 These fine projects all provided inspiration for various aspects of
 223 the Atreus, as well as the folks on the =#geekhack= freenode channel.
 224
 225 - [[http://ergodox.org][Ergodox]]
 226 - [[http://deskthority.net/workshop-f7/onehand-20-keyboard-t6617.html][OneHand]]
 227 - [[http://blog.fsck.com/2013/12/better-and-better-keyboards.html][keyboard.io]]
 228 - [[http://geekhack.org/index.php?topic=48718][ErgoT]]
 229
 230 ** Builds
 231
 232 If you've built an Atreus, please add your name to [[https://github.com/technomancy/atreus/wiki/BuildLogs][the build logs wiki]].
 233
 234 There's also a [[https://atreus.technomancy.us/list][mailing list]] for people who have built or ordered an
 235 Atreus or are interested in doing so.
 236
 237 ** Orestes
 238
 239 A new [[https://www.flickr.com/photos/technomancy/14654421878][experimental build]] uses the [[http://pjrc.com/store/teensy31.html][Teensy 3]] microcontroller and
 240 ARM [[https://github.com/technomancy/orestes/tree/teensy3][Forth-based]] firmware, but this is not yet suitable for general-purpose use.
 241
 242 ** License
 243
 244 Copyright © 2014-2016 Phil Hagelberg and contributors
 245
 246 Released under the [[https://www.gnu.org/licenses/gpl.html][GNU GPL version 3]]