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 [[https://geekhack.org/index.php?topic=22780.0][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 Matias]] or by harvesting from old Alps
 100 keyboards. It's recommended that you use unlabeled keys, because due
 101 to the different sizes and orientations of certain keys (backspace,
 102 shift, enter, etc) many of the labels will be incorrect if present.
 103
 104 Cherry switches have more options. This
 105 [[http://pimpmykeyboard.com/dsa-pbt-abs-blank-keycap-sets/][DSA-shaped base set]] (spherical indentations on the key, same profile for each
 106 row) from Signature Plastics has 52 1x keys plus a few extras we won't
 107 use. There are two "deep dish" keys in that set which you can place
 108 under your index fingers on the home row to help guide your hands to
 109 the right spot without looking. However, you only get a single 1.5x
 110 keycap, and the middle two thumb keys both use them, so you might want
 111 to pick up an extra.
 112
 113 ** Circuit Board
 114
 115 The =atreus.rkt= program calculates switch and diode positions based
 116 on row/column counts, spacing, and rotation factors, and emits a
 117 =atreus.kicad_pcb= file. The board outline and traces are done by hand
 118 and are stored in the =header.rktd= and =traces.rktd= files
 119 respectively. The =atreus.kicad_pcb= file can be imported into [[http://kicad-pcb.org][Kicad]]
 120 which can export Gerber files suitable for fabrication. A copy of the
 121 Kicad PCB file is included in the repository if you don't want to
 122 recompile it using Racket. Recompiling is only required if you want to
 123 make changes to the procedurally-generated portions of the board.
 124
 125 Unfortunately most PCB fabricators require a minimum order of 10 or
 126 so, making this impractical for one-offs. The PCB is not required, so
 127 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.
 128
 129 ** Case
 130
 131 Layered laser-cut wood or acrylic. The [[http://geekhack.org/index.php?topic%3D54759.msg1304117#msg1304117][mark II case]] (EPS files in the
 132 =case/= directory) features 8 screw holes and a kind of "stair step"
 133 design around the top and bottom of the key clusters; mark I is
 134 pictured below.
 135
 136 The =3mm-alps-all.eps= file contains the top plate, bottom plate, and
 137 switch plate for Matias switches. =3mm.eps= contains the files for
 138 Cherry boards. These pieces can all be cut on 3mm acrylic or wood. The
 139 =spacer.eps= file should be cut on something thicker; between 4.5mm
 140 and 6mm is recommended. The spacer needs to be at least as thick as
 141 the connector of the USB cable you're using.
 142
 143 There is also a programmatically-implemented version of the case
 144 written in OpenSCAD; it is more flexible (you can tweak the number of
 145 rows/cols, etc and recompile) but it doesn't match the canonical case
 146 exactly; in particular the screw holes are placed differently.
 147
 148 The original case (=case-mk-i.svg=) design is also included; it is
 149 slightly less wide and has a minor asymmetry with the screws on the
 150 bottom side.
 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 finishing oil/wax or
 157 with [[https://atreus.technomancy.us/lacquer.pdf][lacquer]] which
 158 takes longer but feels nicer.
 159
 160 ** Firmware
 161
 162 The [[https://atreus.technomancy.us/tmk][TMK firmware]] is
 163 recommended. You should be able to change into the =keyboard/atreus=
 164 directory and run =make KEYMAP=qwerty= (or whichever variant you want)
 165 to produce a qwerty =atreus.hex= file. You will probably want to
 166 create your own layout once you've gotten a chance to try it and see
 167 what works for you. See the readme for instructions of how to upload
 168 it to the keyboard's controller.
 169
 170 There is also the older [[https://github.com/technomancy/atreus-firmware][atreus-firmware]] custom codebase which works
 171 but has fewer features. It is recommended mostly for learning purposes
 172 since the code is much simpler and easier to understand than TMK.
 173
 174 ** Bill of Materials
 175
 176 If you don't want to get [[https://atreus.technomancy.us][the kit]] you can source parts yourself. (You
 177 can also order a partial kit if you want to customize some of the
 178 parts.) Using Cherry switches is cheapest unless you can find cheap
 179 Alps-mount keycaps:
 180
 181 - 50 Matias or Cherry switches from mechanicalkeyboards.com
 182 - 50 diodes from radio shack, ebay, or whatever
 183 - 40 1x, 2 1.5x Keycaps from signatureplastics.com OR full keycap set from matias.ca
 184 - A-star micro from pololu.com
 185 - Case materials from various sources
 186 - Case laser cutting: 7.5 minutes on a 100W Epilog laser; varies by source
 187 - USB micro cable, get anywhere
 188
 189 Recommended but optional:
 190
 191 - 5 linear Matias or Cherry switches
 192
 193 The base keycap set from Signature Plastics only has one 1.5x key,
 194 which is used for the inner thumb keys. You can use a 1x key for one
 195 of them, but it looks kind of tacky, so I recommend getting a second
 196 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 lacquer for the
 206 wooden case.
 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 [[https://atreus.technomancy.us/assembly.pdf][assembly instructions]] PDF.
 214
 215 Hand-wired boards will want the [[https://atreus.technomancy.us/assembly-hand-wired.pdf][previous edition of the assembly instructions]].
 216
 217 The LaTeX source to the assembly instructions is in the =assembly= directory.
 218
 219 ** Inspiration
 220
 221 These fine projects all provided inspiration for various aspects of
 222 the Atreus, as well as the folks on the =#geekhack= freenode channel.
 223
 224 - [[https://geekhack.org/index.php?topic=22780.0][Ergodox]]
 225 - [[http://deskthority.net/workshop-f7/onehand-20-keyboard-t6617.html][OneHand]]
 226 - [[http://blog.fsck.com/2013/12/better-and-better-keyboards.html][keyboard.io]]
 227 - [[http://geekhack.org/index.php?topic=48718][ErgoT]]
 228
 229 ** Builds
 230
 231 If you've built an Atreus, please add your name to [[https://github.com/technomancy/atreus/wiki/BuildLogs][the build logs wiki]].
 232
 233 There's also a [[https://atreus.technomancy.us/list][mailing list]] for people who have built or ordered an
 234 Atreus or are interested in doing so.
 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-2016 Phil Hagelberg and contributors
 244
 245 Released under the [[https://www.gnu.org/licenses/gpl.html][GNU GPL version 3]]