* 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.html][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.
+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 Ergodox. In addition, many of the
+used to the columnar layout of the [[https://geekhack.org/index.php?topic=22780.0][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]]
+[[./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.
+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 pgup pgdn enter
+ : esc tab super shift bksp ctrl || alt space fn - ' enter
-The numbers and most punctuation are on the fn layer:
+The numbers and most of the punctuation are on the fn layer with a
+numpad-style arrangement under the right hand:
- : 1 2 3 4 5 || 6 7 8 9 0
- : - + ( ) = || / [ ] { }
- : ! @ # $ % || ^ & * ~ ?
- : reset ` || hwdv _ | \
+ : ! @ 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 =
-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. The =hwdv= key does provide a hardware
-dvorak layer for using other peoples' computers though. This is all a
-matter of firmware though; the layout is easy to change after the
-fact.
+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
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 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, especially for keys under pinky fingers.
-
-One trick is take the springs from some of your blue switches and
-trade them with the springs from your black switches. The blacks then
-become the equivalent of reds, and the blues become MX green switches,
-which are a heavier variant of blues. These are typically used for
-space bars on boards that otherwise use blues. They could be suitable
-for non-modifier thumb keys like backspace, space, and enter.
+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 [[https://www.radioshack.com/product/index.jsp?productId=2062587][1N4148 diode]].
+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
-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.
+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
-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. It claims on that page to contain only one
-deep key, but my shipment contained two, which I put under the index
-finger keys to help guide your hands without looking. However, it only
-contained a single 1.5x keycap, and the middle two thumb keys both use
-them, so you might want to pick up an extra.
+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://pimpmykeyboard.com/dsa-pbt-abs-blank-keycap-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.
+
+** 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 acrylic; see [[file:case.svg][case.svg]].
+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.
-[[layers.jpg][layers.jpg]]
+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 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 micro USB cable you
-connect to the microcontroller. The switch plate could be thinner,
-but not under 3mm.
+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.
-** Firmware
+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.
-My [[https://github.com/technomancy/tmk_keyboard/tree/atreus][fork of the tmk firmware]] has support for the Atreus
-layout. Currently only supports software-dvorak--the default layer is
-all qwerty, but the punctuation keys send keycodes assuming that the
-qwerty->dvorak transformation will be applied to them, so they don't
-make sense otherwise.
+** Firmware
-You should be able to cd into the =keyboard/atreus= directory and run
-=make KEYMAP\=atreus= (or whichever variant you want) to produce a
-qwerty =atreus.hex= file. You might want to create your own layout
-once you've gotten a chance to try it and see what works for you. Use
-the =.hex= file with the [[http://www.pjrc.com/teensy/loader.html][teensy loader]] or Arduino tools to upload to the
-microcontroller.
+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.
-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.
+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
-- 50 MX Blue switches: $29.00 (mechanicalkeyboards.com)
-- 50 diodes: $3.45 (radio shack, should be able to buy in-person)
-- Base 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)
+If you don't want to get [[https://atreus.technomancy.us][the kit]] you can source parts yourself. (You
+can also order a partial kit if you want to customize some of the
+parts.) Using Cherry switches is cheapest unless you can find cheap
+Alps-mount keycaps:
+
+- 50 Matias or Cherry switches from mechanicalkeyboards.com
+- 50 diodes from radio shack, ebay, or whatever
+- 40 1x, 2 1.5x Keycaps from signatureplastics.com OR full keycap set from matias.ca
+- A-star micro from pololu.com
+- Case materials from various sources
+- Case laser cutting: 7.5 minutes on a 100W Epilog laser; varies by source
+- USB micro cable, get anywhere
-- 5 MX Black switches: $8.50 (optional)
-- 5 MX Red switches: $10.00 (optional)
-- additional 1.5x DSA keycap: $1 (optional)
+Recommended but optional:
-=(+ 29 3.45 18 16 11 (* 3 7.5))= $99.95 plus tax/shipping
+- 5 linear Matias or Cherry switches
-- mechanicalkeyboards.com: free shipping in the US
-- Signature Plastics (keycaps) US shipping: $8.00
-- PJRC (teensy) shipping: $3.03
+The base keycap set from Signature Plastics 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.
-*** Cost-saving Options
+*** Other Tools
-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.
+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.
-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.
+If you are building a hand-wired board you will also need a glue gun,
+hookup wire, and wire strippers.
-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.
+** Assembly
-*** Other Tools
+See the [[https://atreus.technomancy.us/assembly.pdf][assembly instructions]] PDF.
-You'll need a soldering iron, solder, a glue gun, a multimeter, wire,
-wire strippers, and a USB mini 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.
+Hand-wired boards will want the [[https://atreus.technomancy.us/assembly-hand-wired.pdf][previous edition of the assembly instructions]].
-** Assembly
+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.
+
+- [[https://geekhack.org/index.php?topic=22780.0][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
-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.
-
-[[wires.jpg]]
-
-Once the switches are in place, the matrix must be created. I
-recommend getting red wire for the rows and black for the 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. 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
-in the same column with the left one 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
-high; 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. Use
-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. The TMK firmware has the rows in pins D0,
-D1, D2, and D3 of the microcontroller. You'll need to connect the rows
-from both the left and right sides into 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. The
-columns go to pins F0, F1, E6, C7, C6, B6, D4, B1, B0, B5, and
-B4. 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!
+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 Phil Hagelberg
+Copyright © 2014-2016 Phil Hagelberg and contributors
Released under the [[https://www.gnu.org/licenses/gpl.html][GNU GPL version 3]]
projects / atreides.git / blobdiff