Link to new Atreus firmware; describe the difference to TMK.

[atreides.git] / README.org

* Atreus Keyboard

The [[http://ergodox.org][Ergodox]] keyboard is an absolutely fantastic design; I use it every
day at my office. However, I like to work away from the office
frequently, and I thought I might try my hand at designing something a
little more portable. The great thing about assembling my Ergodox is
that it taught me there's really nothing magical about it; it's just a
piece of circuitry with a bunch of switches read by a microcontroller
that speaks the USB HID interface.

The Atreus is meant to be complementary to the Ergodox as something
smaller, cheaper, and more travel-friendly. The case measures 25x11cm
and lacks even a number row, relying heavily upon the fn key. There is
no PCB in this design, requiring [[http://wiki.geekhack.org/index.php?title=Hard-Wiring_How-To][a manual matrix wiring approach]].
However, given that there are only 4 rows and 11 columns, this isn't
as daunting as it could be.

I've seen a number of existing DIY 40% keyboard designs, but most of
them stagger the rows, which I find very annoying now that I've gotten
used to the columnar layout of the Ergodox. In addition, many of the
designs I've seen waste a lot of room on the space bar, failing to
take into account the fact that the thumb is the strongest and most
versatile of the fingers. This design avoids both these problems while
taking a more couch-friendly single-piece approach.

[[./atreus.jpg]]

Having so few keys, this board is pretty idiosyncratic. It works very
well for the kind of work that I do, but it probably wouldn't be a
good fit for you if you do a lot of numerical data entry or make heavy
use of function keys, arrows, or home/end. If you primarily use
[[https://github.com/technomancy/dotfiles/commit/856a638350a26b0cdb0bcc82042ed77a3fa4bdea][programs with good key rebinding functionality]], you're probably in
good shape. For instance, =enter= and =tab= are in a bit of an awkward
position, but many programs treat =control-m= and =control-i= as
=enter= and =tab= respectively.

** Layout

Only a handful of punctuation marks (and no digits) are available
unshifted, and all the modifiers are on the bottom row:

 :    '     ,     .     p     y       ||       f     g     c     r    l
 :    a     o     e     u     i       ||       d     h     t     n    s
 :    ;     q     j     k     x       ||       b     m     w     v    z
 :   esc   tab  super shift bksp ctrl || alt space  fn     -     /  enter

The numbers and most of the punctuation are on the fn layer with a
numpad-style arrangement under the right hand:

 :    !     @     {     }     |       ||     pgup    7     8     9    *
 :    #     $     (     )     `       ||     pgdn    4     5     6    +
 :    %     ^     [     ]     ~       ||       \     1     2     3    ?
 :  reset paste                       ||     hwdv          .     0    =

An alternate layout has the numbers in a more traditional row across the top:

 :    1     2     3     4    5        ||       6     7     8     9    0
 :    -     +     (     )    =        ||       .     [     ]     {    }
 :    !     @     #     $    %        ||       ^     &     *     ~    ?
 :  reset paste              `        ||     hwdv        pgup  pgdn   \

I type in Dvorak but prefer to do the remapping in software rather
than hardware so I don't have to change layouts when I switch to my
laptop's internal keyboard. However, the =hwdv= key switches it to
hardware Dvorak mode, which is useful for attaching to computers that
may not have software Dvorak set up. The =paste= key sends
shift+insert, while the =reset= button activates the bootloader,
allowing easy reprogramming without opening the case.

This is all a matter of firmware though; the layout is easy to change
after the fact.

** Parts

*** Switches

This layout has five modifiers and 37 non-modifiers.

I strongly prefer the feel and sound of tactile [[http://mechanicalkeyboards.com/shop/index.php?l=product_detail&p=651][Cherry MX blue]]
switches for typing. However, I like having linear switches on the
modifier keys (ctrl, alt, super, shift, and fn). [[http://mechanicalkeyboards.com/shop/index.php?l=product_detail&p=102][Cherry MX red
switches]] are nice and light but are more expensive and difficult to
find. [[http://mechanicalkeyboards.com/shop/index.php?l=product_detail&p=103][Cherry MX black switches]] are cheaper and easier to source, but
may be too heavy if you modify the layout to include modifiers under
the pinkies.

*** Diodes

In order to avoid ghosting, each switch needs a [[https://www.radioshack.com/product/index.jsp?productId=2062587][1N4148 diode]].

*** Microcontroller

An [[http://www.digikey.com/product-search/en/programmers-development-systems/evaluation-boards-embedded-mcu-dsp/2621773?k=arduino%20micro][Arduino Micro]] or [[http://www.pjrc.com/teensy/index.html][Teensy 2]] is recommended. Be sure to get one
without headers so it will fit in between the bottom layer and the plate.

*** Keycaps

This [[http://keyshop.pimpmykeyboard.com/product/dsa-pbt-blank-sets][DSA-shaped base set]] (spherical indentations on the key, same
profile for each row) from Signature Plastics has 52 1x keys plus a
few extras we won't use. There are two "deep dish" keys in that set
which you can place under your index fingers on the home row to help
guide your hands to the right spot without looking. However, you only
get a single 1.5x keycap, and the middle two thumb keys both use them,
so you might want to pick up an extra. (You can buy a single DSA 1.5x
keycap from [[http://www.keycapsdirect.com/key-capsinventory.php][Signature Plastics]].)

** Case

Layered laser-cut wood or acrylic; see [[file:./case.svg][the =case.svg= file]].

TODO: mention the difference between mk. I and mk. II cases.

[[./layers.jpg]]

The first two shapes in the case file are the top and bottom covers;
these should be cut on 3mm acrylic (black in the photo). The third is
the spacer that goes under the fourth, which is the plate on which the
switches are mounted. These should be cut in 6mm, especially the
spacer, which needs to be at least as thick as the mini USB cable you
connect to the microcontroller. I recommend using a mini USB cable
with as thin a connector as you can find or sanding the connector
down to the required thickness. The switch plate could be thinner, but
not under 3mm.

On a 100W Epilog laser, the 3mm layers cut in about a minute and a
half. I did a run with 6mm acrylic of the other layers which took
nearly 6 minutes.

TODO: describe finishing process for wood.

** Firmware

The [[https://gitlab.com/technomancy/atreus-firmware/blob/master/readme.md][custom Atreus firmware]] is a small (~100 LOC) project which
implements matrix scanning and debouncing with user-customizeable
layers and macro functions. Another option is the much more complex
TMK firmware. My [[https://github.com/technomancy/tmk_keyboard/tree/atreus][fork of the tmk firmware]] has support for the Atreus
layout. You should be able to change into the =keyboard/atreus=
directory and run =make KEYMAP=atreus= (or whichever variant you want)
to produce a qwerty =atreus.hex= file. You will probably want to
create your own layout once you've gotten a chance to try it and see
what works for you.

In either case you would use the =.hex= file produced with the [[http://www.pjrc.com/teensy/loader.html][teensy
loader]] or Arduino tools to upload to the microcontroller.

Once the firmware is loaded and the keyboard is assembled, pressing
the onboard reset button to update new versions of the firmware is
pretty cumbersome; instead use the "reset" button on the lower left
of the layout which has the same effect.

** Bill of Materials

- 50 MX Blue switches: $29.00 (mechanicalkeyboards.com)
- 50 diodes: $3.45 (radio shack, should be able to buy in-person)
- Base blank DSA keycap set: $18.00 (signatureplastics.com)
- Teensy 2: $16 (pjrc.com or mechanicalkeyboards.com)
- Acrylic materials: $11
- Acrylic laser cutting: 7.5 at $3/min (varies by thickness of acrylic)

- 5 MX Black switches: $8.50 (optional)
- 5 MX Red switches: $10.00 (optional)
- additional 1.5x DSA keycap: $1 (optional)

=(+ 29 3.45 18 16 11 (* 3 10))= $99.95 plus tax/shipping

- mechanicalkeyboards.com: free shipping in the US
- Signature Plastics (keycaps) US shipping: $8.00
- PJRC (teensy) shipping: $3.03

*** Cost-saving Options

There are a few ways to lower the cost further.  Using [[http://mechanicalkeyboards.com/shop/index.php?l=product_detail&p=482][Matias]] key
switches could save you a fair bit if you go in on a 90-pack with
someone else, but they're a little harder to find keycaps for; the MX
caps won't work on them. Using wood for the case will reduce both the
materials cost as well as the amount of time needed to cut the case.

Replacing the colored acrylic with transparent might also save a few
dollars. You could also use thinner acrylic for the switch plate too;
I cut mine in 4.5mm. A thinner spacer is inadvisable; even with 6mm
it's pretty tight.

Another common trick is scavenging keycaps and switches from used
keyboards; something with Cherry or Alps switches should work. This
can be time-consuming though.

*** Other Tools

You'll need a soldering iron, solder, a glue gun, a multimeter, wire,
wire strippers, and a 5-pin USB Mini-B cable. You'll also need seven M3
machine screws with nuts; the length of the screws depends on the
thickness of the acrylic you use. You can add rubber feet to the
bottom to prevent the board from sliding around when placed on a desk.

** Assembly

Once you have all the parts, the first thing to do is glue the
switches to the switch plate since there's no PCB to hold them in
place. Be aware that the screw holes unfortunately are not
symmetrical, so before inserting the switches it's important to ensure
that the plate is right-side-up. Use a drop of hot glue on the top and
bottom of each switch to affix it in place.

TODO: document using the diode legs for the columns.

[[./wires.jpg]]

Once the switches are in place, the matrix must be created. I
recommend getting red wire for the (positive) rows and black for the
(negative) columns. The rows need eight wires with the insulation
exposed at intervals matching the spacing of the switches; see the
above photo for details. You could also just use many short stripped
segments of wire instead of a contiguous piece.

[[./thumb-diagram.png]]

Most of the row wires will need four segments of insulation, but
you'll need two with five for the rows with the inner thumb
keys. Physically the inner thumb keys look like two additional
columns, but logically they are treated as if they're both in column
number 6; the left key in row 3 and the right one in row 4.

[[./matrix.jpg]]

The exposed sections of row wire should be connected to the higher of
the pins on the switch using a diode. Be aware that diodes are
directional! The band around the diode should point to the top of the
board. Take care with the upper row that you don't let the wire go too
close to the top edge of the board; avoid getting in the way of the
spacer layer. Once the rows are wired, the remaining (negative) pin of
each switch should be wired into the negative pin of the switch above
and below it with black wire. This should be slightly easier since no
diode is necessary. The photo above shows the completed matrix for one
side. Test each row and column as you go with a multimeter. You should
be able to get continuity from row to column when the corresponding
switch is activated.

After the matrix has been wired on both sides, the next step is to
connect the microcontroller. Both the Atreus and TMK firmwares have
the rows in pins D0, D1, D2, and D3 of the microcontroller.

|------------+----+----+----+----|
| row number |  1 |  2 |  3 |  4 |
|------------+----+----+----+----|
| pin number | D0 | D1 | D2 | D3 |

You'll need to connect the rows from the right side to the left side,
which then should be wired to the proper pin. There are more
columns than rows, so I used ribbon cable to bring the column
connections back to the microcontroller from the outside in.

Depending on the firmware you want to use, you'll wire the columns
differently. The simpler Atreus firmware simply starts at B0 and goes
up to F4-6, while the more featureful TMK firmware jumps all over the
place.

Atreus:

|---------------+----+----+----+----+----+----+----+----+----+----+----|
| column number |  0 |  1 |  2 |  3 |  4 |  5 |  6 |  7 |  8 |  9 | 10 |
|---------------+----+----+----+----+----+----+----+----+----+----+----|
| pin number    | B0 | B1 | B2 | B3 | B4 | B5 | B6 | B7 | F4 | F5 | F6 |

TMK:

|---------------+----+----+----+----+----+----+----+----+----+----+----|
| column number |  1 |  2 |  3 |  4 |  5 |  6 |  7 |  8 |  9 | 10 | 11 |
|---------------+----+----+----+----+----+----+----+----+----+----+----|
| pin number    | F0 | F1 | E6 | C7 | C6 | B6 | D4 | B1 | B0 | B5 | B4 |

(It may be possible to adapt the TMK firmware to the consecutive pinout.)

It's important to realize that when you flip over the board
in order to solder it, you have to flip over the schematic in your
mind too. If you count your columns from the left, you'll get them
backwards. (Which I actually did for the first half.)

[[./controller.jpg]]

Once you've wired one side of the microcontroller in, it would be a
good time to test it. You'll need to compile and upload as per the
"Firmware" section above. At this point you should be reading real
keycodes from the half of the keyboard that you've wired. Once you've
confirmed that's working, continue with the other half. Then screw the
other layers in place and you're all set!

** Inspiration

These fine projects all provided inspiration for various aspects of
the Atreus, as well as the folks on the =#geekhack= freenode channel.

- [[http://ergodox.org][Ergodox]]
- [[http://deskthority.net/workshop-f7/onehand-20-keyboard-t6617.html][OneHand]]
- [[http://blog.fsck.com/2013/12/better-and-better-keyboards.html][keyboard.io]]
- [[http://geekhack.org/index.php?topic=48718][ErgoT]]

** Builds

If you've built an Atreus, please let us know (pull request or
otherwise) and get your name and link added here:

- [[http://technomancy.us/173][Phil Hagelberg]]
- [[http://blog.tarn-vedra.de/2014/04/reproducing-keyboard-science_1707.html][Moritz Ulrich]]
- [[http://geekhack.org/index.php?topic=57007.0][Constantine]]

** License

Copyright © 2014 Phil Hagelberg

Released under the [[https://www.gnu.org/licenses/gpl.html][GNU GPL version 3]]