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 [[https://github.com/technomancy/dotfiles/commit/856a638350a26b0cdb0bcc82042ed77a3fa4bdea][programs with good key rebinding functionality]], you're probably in
  33 good shape. For instance, =enter= and =tab= are in a bit of an awkward
  34 position, but many programs treat =control-m= and =control-i= as
  35 =enter= and =tab= respectively.
  36
  37 ** Layout
  38
  39 Only a handful of punctuation marks (and no digits) are available
  40 unshifted, and all the modifiers are on the bottom row:
  41
  42  :    '     ,     .     p     y       ||       f     g     c     r    l
  43  :    a     o     e     u     i       ||       d     h     t     n    s
  44  :    ;     q     j     k     x       ||       b     m     w     v    z
  45  :   esc   tab  super shift bksp ctrl || alt space  fn     -     /  enter
  46
  47 The numbers and most of the punctuation are on the fn layer with a
  48 numpad-style arrangement under the right hand:
  49
  50  :    !     @     {     }     |       ||     pgup    7     8     9    *
  51  :    #     $     (     )     `       ||     pgdn    4     5     6    +
  52  :    %     ^     [     ]     ~       ||       \     1     2     3    ?
  53  :  reset paste                       ||     hwdv          .     0    =
  54
  55 An alternate layout has the numbers in a more traditional row across the top:
  56
  57  :    1     2     3     4    5        ||       6     7     8     9    0
  58  :    -     +     (     )    =        ||       .     [     ]     {    }
  59  :    !     @     #     $    %        ||       ^     &     *     ~    ?
  60  :  reset paste              `        ||     hwdv        pgup  pgdn   \
  61
  62 I type in Dvorak but prefer to do the remapping in software rather
  63 than hardware so I don't have to change layouts when I switch to my
  64 laptop's internal keyboard. However, the =hwdv= key switches it to
  65 hardware Dvorak mode, which is useful for attaching to computers that
  66 may not have software Dvorak set up. The =paste= key sends
  67 shift+insert, while the =reset= button activates the bootloader,
  68 allowing easy reprogramming without opening the case.
  69
  70 This is all a matter of firmware though; the layout is easy to change
  71 after the fact.
  72
  73 ** Parts
  74
  75 *** Switches
  76
  77 This layout has five modifiers and 37 non-modifiers.
  78
  79 I strongly prefer the feel and sound of tactile [[http://mechanicalkeyboards.com/shop/index.php?l=product_detail&p=651][Cherry MX blue]]
  80 switches for typing. However, I like having linear [[http://mechanicalkeyboards.com/shop/index.php?l=product_detail&p=103][Cherry MX black
  81 switches]] switches on the modifier keys (ctrl, alt, super, shift, and
  82 fn) because the tactile effect has no benefit for keys that are held
  83 down, and giving a different response helps you learn the layout more
  84 quickly.
  85
  86 *** Diodes
  87
  88 In order to avoid ghosting, each switch needs a [[https://www.radioshack.com/product/index.jsp?productId=2062587][1N4148 diode]].
  89
  90 *** Microcontroller
  91
  92 A [[http://www.pjrc.com/teensy/index.html][Teensy 2]] is recommended. Be sure to get one without headers so it
  93 will fit in between the bottom layer and the plate.
  94
  95 *** Keycaps
  96
  97 This [[http://keyshop.pimpmykeyboard.com/product/dsa-pbt-blank-sets][DSA-shaped base set]] (spherical indentations on the key, same
  98 profile for each row) from Signature Plastics has 52 1x keys plus a
  99 few extras we won't use. There are two "deep dish" keys in that set
 100 which you can place under your index fingers on the home row to help
 101 guide your hands to the right spot without looking. However, you only
 102 get a single 1.5x keycap, and the middle two thumb keys both use them,
 103 so you might want to pick up an extra. (You can buy a single DSA 1.5x
 104 keycap from [[http://www.keycapsdirect.com/key-capsinventory.php][Signature Plastics]].)
 105
 106 ** Case
 107
 108 Layered laser-cut wood or acrylic. The original case (=case-mk-i.svg=)
 109 is slightly less wide and has a minor asymmetry with the screws on the
 110 bottom side. The [[http://geekhack.org/index.php?topic%3D54759.msg1304117#msg1304117][mark II case]] (in the `case` directory) is implemented
 111 programmatically in openscad, though dxf files are available as a
 112 convenience, which can be converted to SVG or EPS for laser cutting
 113 with Inkscape. Mark II features 8 screw holes and a kind of "stair
 114 step" design around the top and bottom of the key clusters; mark I is
 115 pictured below.
 116
 117 [[./layers.jpg]]
 118
 119 The bottom and top covers (black in the photo) should be cut in 3mm.
 120 The switch plate (frosted in the photo) can be cut in 4.5mm or
 121 3mm. The spacer should be cut in 6mm; it needs to be at least as
 122 thick as the mini USB cable you connect to the microcontroller. I
 123 recommend using a mini USB cable with as thin a connector as you can
 124 find or sanding the connector down to the required thickness.
 125
 126 TODO: describe finishing process for wood.
 127
 128 ** Firmware
 129
 130 The [[https://gitlab.com/technomancy/atreus-firmware/blob/master/readme.md][custom Atreus firmware]] is a small C project which
 131 implements matrix scanning and debouncing with user-customizeable
 132 layers and macro functions. Another option is the much more complex
 133 TMK firmware. My [[https://github.com/technomancy/tmk_keyboard/tree/atreus][fork of the tmk firmware]] has support for the Atreus
 134 layout. You should be able to change into the =keyboard/atreus=
 135 directory and run =make KEYMAP=atreus= (or whichever variant you want)
 136 to produce a qwerty =atreus.hex= file. You will probably want to
 137 create your own layout once you've gotten a chance to try it and see
 138 what works for you.
 139
 140 In either case you would use the =.hex= file produced with the [[http://www.pjrc.com/teensy/loader.html][teensy loader]] to upload to the microcontroller.
 141
 142 Once the firmware is loaded and the keyboard is assembled, pressing
 143 the onboard reset button to update new versions of the firmware is
 144 pretty cumbersome; instead use the "reset" button on the layout, which
 145 has the same effect.
 146
 147 ** Bill of Materials
 148
 149 - 50 MX Blue switches: $29.00 (mechanicalkeyboards.com)
 150 - 50 diodes: $3.45 (radio shack, should be able to buy in-person)
 151 - Base blank DSA keycap set: $21.00 (signatureplastics.com)
 152 - Teensy 2: $16 (pjrc.com)
 153 - Acrylic materials: ~$11, varies by source
 154 - Acrylic laser cutting: 7.5 minutes at $3/min (varies by thickness of acrylic)
 155
 156 - 5 MX Black switches: $8.50 (optional)
 157 - 5 MX Red switches: $10.00 (optional)
 158 - additional 1.5x DSA keycap: $1 (optional)
 159
 160 - mechanicalkeyboards.com: free shipping in the US
 161 - Signature Plastics (keycaps) US shipping: $8.00
 162 - PJRC (teensy) shipping: $3.03
 163
 164 I haven't found a way to add the 1.5x keycap to an order of the DSA
 165 base set, so you might be stuck paying Signature Plastics shipping
 166 twice.
 167
 168 *** Other Tools
 169
 170 You'll need a soldering iron, solder, a glue gun, a multimeter, hookup
 171 wire, wire strippers, and a USB Mini-B cable. You'll also need
 172 eight M3 machine screws with nuts; the length of the screws depends on
 173 the thickness of the acrylic you use. You can add rubber feet to the
 174 bottom to prevent the board from sliding around when placed on a desk.
 175
 176 ** Assembly
 177
 178 See the [[http://atreus.technomancy.us/assembly.pdf][assembly instructions]] PDF
 179
 180 ** Inspiration
 181
 182 These fine projects all provided inspiration for various aspects of
 183 the Atreus, as well as the folks on the =#geekhack= freenode channel.
 184
 185 - [[http://ergodox.org][Ergodox]]
 186 - [[http://deskthority.net/workshop-f7/onehand-20-keyboard-t6617.html][OneHand]]
 187 - [[http://blog.fsck.com/2013/12/better-and-better-keyboards.html][keyboard.io]]
 188 - [[http://geekhack.org/index.php?topic=48718][ErgoT]]
 189
 190 ** Builds
 191
 192 If you've built an Atreus, please let us know (pull request or
 193 otherwise) and get your name and link added here:
 194
 195 - [[http://technomancy.us/173][Phil Hagelberg]]
 196 - [[http://blog.tarn-vedra.de/2014/04/reproducing-keyboard-science_1707.html][Moritz Ulrich]]
 197 - [[http://geekhack.org/index.php?topic=57007.0][Constantine]]
 198 - [[http://blog.mattgauger.com/blog/2014/08/19/atreus-my-custom-keyboard/][Matt Gauger]]
 199
 200 ** Orestes
 201
 202 A new [[https://www.flickr.com/photos/technomancy/14654421878][experimental build]] uses the [[http://pjrc.com/store/teensy31.html][Teensy 3]] microcontroller and
 203 [[https://github.com/technomancy/orestes/tree/teensy3][Forth-based]] firmware, but this is not yet stable.
 204
 205 ** License
 206
 207 Copyright © 2014 Phil Hagelberg and contributors
 208
 209 Released under the [[https://www.gnu.org/licenses/gpl.html][GNU GPL version 3]]