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/download][firmware]] includes a number of other options, including
  57 colemak and dvorak. [[https://atreus.technomancy.us/qmk][Customizing your layout]] is easy to do with the QMK configurator interface.
  58
  59 ** Parts
  60
  61 *** Switches
  62
  63 This layout has five modifiers and 37 non-modifiers.
  64
  65 I strongly prefer the feel and sound of tactile [[https://deskthority.net/wiki/Matias_switch#Click][Matias Clicky]]
  66 switches for typing. However, I like having [[https://deskthority.net/wiki/Matias_switch#Linear][Matias Linear
  67 switches]] switches on the modifier keys (ctrl, alt, super, shift, and
  68 fn) because the tactile effect has no benefit for keys that are held
  69 down, and giving a different response helps you learn the layout more
  70 quickly.
  71
  72 For users that need to operate in sound-sensitive environments like
  73 open offices or libraries,
  74 [[http://deskthority.net/wiki/Matias_switch#Quiet_click][Matias Quiet
  75 Click]] switches are a popular choice since they still offer tactility
  76 without the noise. Other users prefer switches in the
  77 [[http://deskthority.net/wiki/Cherry_MX][Cherry MX]] family, which use
  78 different keycaps and switch plates but still work fine.
  79
  80 *** Diodes
  81
  82 In order to avoid ghosting, each switch needs a diode. The [[https://www.radioshack.com/product/index.jsp?productId=2062587][1N4148]] is a
  83 readily-available choice, but nearly any signal diode would work.
  84
  85 *** Microcontroller
  86
  87 The circuit board design uses a [[http://www.pololu.com/product/3101][Pololu A-star micro]]. Hand-wired boards
  88 can also use a [[http://arduino.cc/en/Main/ArduinoBoardMicro][Arduino Pro Micro]].
  89
  90 Be sure to get a microcontroller without headers so it will fit in
  91 between the bottom layer and the plate. USB micro is preferred over
  92 USB mini for this reason as well.
  93
  94 *** Keycaps
  95
  96 Caps for Matias switches are included in the official kits. Sculpted
  97 caps are also available [[http://matias.ca/order/#keycaps][from Matias]] or by harvesting from old Alps
  98 keyboards. It's recommended that you use unlabeled keys, because due
  99 to the different sizes and orientations of certain keys (backspace,
 100 shift, enter, etc) many of the labels will be incorrect if present.
 101
 102 Cherry switches have more options. This
 103 [[http://pimpmykeyboard.com/dsa-pbt-abs-blank-keycap-sets/][DSA-shaped base set]] (spherical indentations on the key, same profile for each
 104 row) from Signature Plastics has 52 1x keys plus a few extras we won't
 105 use. There are two "deep dish" keys in that set which you can place
 106 under your index fingers on the home row to help guide your hands to
 107 the right spot without looking. However, you only get a single 1.5x
 108 keycap, and the middle two thumb keys both use them, so you might want
 109 to pick up an extra.
 110
 111 ** Circuit Board
 112
 113 The =atreus.rkt= program calculates switch and diode positions based
 114 on row/column counts, spacing, and rotation factors, and emits a
 115 =atreus.kicad_pcb= file. The board outline and traces are done by hand
 116 and are stored in the =header.rktd= and =traces.rktd= files
 117 respectively. The =atreus.kicad_pcb= file can be imported into [[http://kicad-pcb.org][Kicad]]
 118 which can export Gerber files suitable for fabrication. A copy of the
 119 Kicad PCB file is included in the repository if you don't want to
 120 recompile it using Racket. Recompiling is only required if you want to
 121 make changes to the procedurally-generated portions of the board.
 122
 123 Unfortunately most PCB fabricators require a minimum order of 10 or
 124 so, making this impractical for one-offs. The PCB is not required, so
 125 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.
 126
 127 ** Case
 128
 129 Layered laser-cut wood or acrylic. The [[http://geekhack.org/index.php?topic%3D54759.msg1304117#msg1304117][mark II case]] (EPS files in the
 130 =case/= directory) features 8 screw holes and a kind of "stair step"
 131 design around the top and bottom of the key clusters; mark I has
 132 straight lines.
 133
 134 The files =alps-top-plate-3mm.eps=, =alps-switch-plate-3mm.eps=, and
 135 =bottom-plate-3mm.eps= are to be cut in 3mm acrylic or wood. The
 136 =spacer.eps= file can be cut on something thicker; between 4.5mm and
 137 6mm is recommended. Alternatively you can cut it in 3mm twice. The
 138 spacer needs to be at least as thick as the connector of the USB cable
 139 you're using. If you are using Cherry switches, you should use
 140 =cherry-3mm.eps= for the top, switch, and bottom plates instead, but
 141 the spacer is the same.
 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 lacquer, shellac, or polyurethane.
 157
 158 ** Firmware
 159
 160 The [[https://qmk.fm][QMK firmware]] is
 161 recommended. [[https://atreus.technomancy.us/download][Standard
 162 layouts]] are available precompiled, or you can
 163 [[https://atreus.technomancy.us/qmk][design your own]] in the
 164 configurator.
 165
 166 There is also the older
 167 [[https://github.com/technomancy/atreus-firmware][atreus-firmware]]
 168 custom codebase which works but has fewer features. It is recommended
 169 mostly for learning purposes since the code is much simpler and easier
 170 to understand than QMK. Previously TMK was the recommended choice for
 171 firmware, but QMK has much better documentation and ease of use and is
 172 now recommended.
 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 An [[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 really suitable for general-purpose use; it's more of a curiosity.
 240
 241 ** License
 242
 243 Copyright © 2014-2018 Phil Hagelberg and contributors
 244
 245 Released under the [[https://www.gnu.org/licenses/gpl.html][GNU GPL version 3]]