Add guide for lacquering.

[atreides.git] / README.org

* Atreus Keyboard

The Atreus is a mechanical keyboard designed primarily to match the
shape of human hands and to be as portable as possible. The case
measures 26x12cm and lacks even a number row, relying heavily upon the
=fn= key. There is a circuit board for this design, but it's also
possible to [[http://wiki.geekhack.org/index.php?title=Hard-Wiring_How-To][manually wire the matrix]].

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 [[http://ergodox.org][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]]

See [[./changelog.md][the changelog]] for the various revisions made to the design since
its initial release.

** Kits

You can buy [[http://atreus.technomancy.us][Atreus kits]] that have all the parts you need along with
detailed assembly instructions from http://atreus.technomancy.us. If
you'd rather round up all the parts yourself, that's possible too
since the design is completely open source; see the bill of materials
below.

** Layout

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

 :    q     w     e     r     t       ||       y     u     i     o    p
 :    a     s     d     f     g       ||       h     j     k     l    ;
 :    z     x     c     v     b       ||       n     m     ,     .    /
 :   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:

 :    !    @     up     {    }        ||     pgup    7     8     9    *
 :    #  left   down  right  $        ||     pgdn    4     5     6    +
 :    [    ]      (     )    &        ||       `     1     2     3    \
 :   L2  insert super shift bksp ctrl || alt space   fn    .     0    =

The =L2= key switches it to the function layer, and tapping =L0= here
brings it back to the first layer.

 :  insert home    ↑    end  pgup     ||       ↑     F7    F8    F9   F10
 :    del   ←      ↓     →   pgdn     ||       ↓     F4    F5    F6   F11
 :                           reset    ||             F1    F2    F3   F12
 :              super shift bksp ctrl || alt space   L0             

The [[https://atreus.technomancy.us/tmk][firmware]] includes a number of other options, including
colemak, dvorak, and "software dvorak" which sends keycodes assuming
the OS will perform the translation into dvorak. Adding new layouts or
changing existing ones is easy.

** Parts

*** Switches

This layout has five modifiers and 37 non-modifiers.

I strongly prefer the feel and sound of tactile [[https://deskthority.net/wiki/Matias_switch#Click][Matias Clicky]]
switches for typing. However, I like having [[https://deskthority.net/wiki/Matias_switch#Linear][Matias Linear
switches]] switches on the modifier keys (ctrl, alt, super, shift, and
fn) because the tactile effect has no benefit for keys that are held
down, and giving a different response helps you learn the layout more
quickly.

For users that need to operate in sound-sensitive environments like
open offices or libraries,
[[http://deskthority.net/wiki/Matias_switch#Quiet_click][Matias Quiet
Click]] switches are a popular choice since they still offer tactility
without the noise. Other users prefer switches in the
[[http://deskthority.net/wiki/Cherry_MX][Cherry MX]] family, which use
different keycaps and switch plates but still work fine.

*** Diodes

In order to avoid ghosting, each switch needs a diode. The [[https://www.radioshack.com/product/index.jsp?productId=2062587][1N4148]] is a
readily-available choice, but nearly any signal diode would work.

*** Microcontroller

The circuit board design uses a [[http://www.pololu.com/product/3101][Pololu A-star micro]]. Hand-wired boards
can also use a [[http://www.pjrc.com/teensy/index.html][Teensy 2]] or [[http://arduino.cc/en/Main/ArduinoBoardMicro][Arduino Pro Micro]].

Be sure to get a microcontroller without headers so it will fit in
between the bottom layer and the plate. USB micro is preferred over
USB mini for this reason as well.

*** Keycaps

Caps for Matias switches are included in the official kits. Sculpted
caps are also available [[http://matias.ca/order/#keycaps][from Matias]] or by harvesting from old Alps
keyboards. It's recommended that you use unlabeled keys, because due
to the different sizes and orientations of certain keys (backspace,
shift, enter, etc) many of the labels will be incorrect if present.

Cherry switches have more options. This
[[http://keyshop.pimpmykeyboard.com/products/full-keysets/dsa-blank-sets-1][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.

** Circuit Board

The =atreus.rkt= program calculates switch and diode positions based
on row/column counts, spacing, and rotation factors, and emits a
=atreus.kicad_pcb= file. The board outline and traces are done by hand
and are stored in the =header.rktd= and =traces.rktd= files
respectively. The =atreus.kicad_pcb= file can be imported into [[http://kicad-pcb.org][Kicad]]
which can export Gerber files suitable for fabrication. A copy of the
Kicad PCB file is included in the repository if you don't want to
recompile it using Racket. Recompiling is only required if you want to
make changes to the procedurally-generated portions of the board.

Unfortunately most PCB fabricators require a minimum order of 10 or
so, making this impractical for one-offs. The PCB is not required, so
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.

** Case

Layered laser-cut wood or acrylic. The [[http://geekhack.org/index.php?topic%3D54759.msg1304117#msg1304117][mark II case]] (EPS files in the
=case/= directory) features 8 screw holes and a kind of "stair step"
design around the top and bottom of the key clusters; mark I is
pictured below.

The =3mm-alps-all.eps= file contains the top plate, bottom plate, and
switch plate for Matias switches. =3mm.eps= contains the files for
Cherry boards. These pieces can all be cut on 3mm acrylic or wood. The
=spacer.eps= file should be cut on something thicker; between 4.5mm
and 6mm is recommended. The spacer needs to be at least as thick as
the connector of the USB cable you're using.

There is also a programmatically-implemented version of the case
written in OpenSCAD; it is more flexible (you can tweak the number of
rows/cols, etc and recompile) but it doesn't match the canonical case
exactly; in particular the screw holes are placed differently.

The original case (=case-mk-i.svg=) design is also included; it is
slightly less wide and has a minor asymmetry with the screws on the
bottom side.

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.

Wood cases should be finished with sandpaper and finishing oil/wax or
with [[https://atreus.technomancy.us/lacquer.pdf][lacquer]] which
takes longer but feels nicer.

** Firmware

The [[https://atreus.technomancy.us/tmk][TMK firmware]] is
recommended. You should be able to change into the =keyboard/atreus=
directory and run =make KEYMAP=qwerty= (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. See the readme for instructions of how to upload
it to the keyboard's controller.

There is also the older [[https://github.com/technomancy/atreus-firmware][atreus-firmware]] custom codebase which works
but has fewer features. It is recommended mostly for learning purposes
since the code is much simpler and easier to understand than TMK.

** Bill of Materials

Using Cherry switches is cheapest unless you can find cheap Alps-mount keycaps:

- 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: $23.00 (signatureplastics.com)
- Teensy 2: $16, $3 shipping (pjrc.com)
- Case materials: ~$16, varies by source
- Case laser cutting: 7.5 minutes on a 100W Epilog laser; varies by source
- USB micro cable: $5, various sources

Recommended but optional:

- 5 MX Red or MX Black switches: $8.50 - $10.00
- additional 1.5x DSA keycap: $1 plus $8 shipping

The base keycap set only has one 1.5x key, which is used for the inner
thumb keys. You can use a 1x key for one of them, but it looks kind of
tacky, so I recommend getting a second 1.5x keycap separately.

*** Other Tools

You'll need a soldering iron, solder, and a wire cutter. A multimeter
can come in handy for testing the connections but is optional. You'll
also need eight 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. You'll also need sandpaper and lacquer for the
wooden case.

If you are building a hand-wired board you will also need a glue gun,
hookup wire, and wire strippers.

** Assembly

See the [[https://atreus.technomancy.us/assembly.pdf][assembly instructions]] PDF.

Hand-wired boards will want the [[https://atreus.technomancy.us/assembly-hand-wired.pdf][previous edition of the assembly instructions]].

The LaTeX source to the assembly instructions is in the =assembly= directory.

** 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 add your name to [[https://github.com/technomancy/atreus/wiki/BuildLogs][the build logs wiki]].

There's also a [[https://atreus.technomancy.us/list][mailing list]] for people who have built or ordered an
Atreus or are interested in doing so.

** Orestes

A new [[https://www.flickr.com/photos/technomancy/14654421878][experimental build]] uses the [[http://pjrc.com/store/teensy31.html][Teensy 3]] microcontroller and
ARM [[https://github.com/technomancy/orestes/tree/teensy3][Forth-based]] firmware, but this is not yet suitable for general-purpose use.

** License

Copyright © 2014-2016 Phil Hagelberg and contributors

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