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