X-Git-Url: https://git.armaanb.net/?a=blobdiff_plain;f=README.org;h=28a3a7b9680a0789a67b0f33b01305e331f27109;hb=c8a393a827bf661fd075d0a6fbff76183c934de3;hp=15c92d6d7fc61e0b6926823b96037088e64f863c;hpb=1bcc9b4556a30c1fd0539f37cb2c2be6ea551429;p=atreides.git diff --git a/README.org b/README.org index 15c92d6..28a3a7b 100644 --- a/README.org +++ b/README.org @@ -1,49 +1,60 @@ * 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 be 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. +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) available -unshifted, and all the modifiers are on the bottom row. +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 fn shift bksp ctrl || alt space enter super pgup pgdn + : 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: -The numbers and most punctuation are on the fn layer: + : ! @ 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 = - : 1 2 3 4 5 || 6 7 8 9 0 - : - + ( ) = || / [ ] { } - : ! @ # $ % || ^ & * ? ~ - : || ` _ \ +The =L2= key switches it to the function layer, and tapping =L0= here +brings it back to the first layer. -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. + : 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/download][firmware]] includes a number of other options, including +colemak and dvorak. [[https://atreus.technomancy.us/qmk][Customizing your layout]] is easy to do with the QMK configurator interface. ** Parts @@ -51,99 +62,184 @@ laptop's internal keyboard. This layout has five modifiers and 37 non-modifiers. -I strongly prefer the feel and sound of tactile [[http://www.digikey.com/product-detail/en/MX1A-E1NW/CH197-ND/20180][Cherry MX blue]] -switches for typing. However, I like having linear switches on the -modifier keys (ctrl, alt, super, shift, and fn). [[http://www.wasdkeyboards.com/index.php/products/keyboard-parts/cherry-mx-red-keyswitch-mx1a-l1nn-linear.html][Cherry MX red -switches]] are nice and light but are expensive and difficult to -find. [[http://www.digikey.com/product-detail/en/MX1A-11NW/CH160-ND/91134][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 [[http://www.digikey.com/product-detail/en/1N4148TR/1N4148FSTR-ND/458811][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. - -*** Keycaps +The circuit board design uses a [[http://www.pololu.com/product/3101][Pololu A-star micro]]. Hand-wired boards +can also use a [[http://arduino.cc/en/Main/ArduinoBoardMicro][Arduino Pro Micro]]. -This [[http://keyshop.pimpmykeyboard.com/product/dsa-pbt-blank-sets][DSA-shaped base set]] 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. +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. -*** Screws +*** Keycaps -Seven M3 machine screws and nuts hold the whole thing together. The -length of the screws depends on the thickness of the materials you use -for the case. +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]]. - -[[layers.jpg][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 micro USB cable you -connect to the microcontroller. +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 has +straight lines. + +The files =alps-top-plate-3mm.eps=, =alps-switch-plate-3mm.eps=, and +=bottom-plate-3mm.eps= are to be cut in 3mm acrylic or wood. The +=spacer.eps= file can be cut on something thicker; between 4.5mm and +6mm is recommended. Alternatively you can cut it in 3mm twice. The +spacer needs to be at least as thick as the connector of the USB cable +you're using. If you are using Cherry switches, you should use +=cherry-3mm.eps= for the top, switch, and bottom plates instead, but +the spacer is the same. + +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 lacquer, shellac, or polyurethane. + ** Firmware -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. +The [[https://qmk.fm][QMK firmware]] is +recommended. [[https://atreus.technomancy.us/download][Standard +layouts]] are available precompiled, or you can +[[https://atreus.technomancy.us/qmk][design your own]] in the +configurator. + +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 QMK. Previously TMK was the recommended choice for +firmware, but QMK has much better documentation and ease of use and is +now recommended. + +** Bill of Materials + +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 + +Recommended but optional: + +- 5 linear Matias or Cherry switches + +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. + +*** 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 -** Recommended Bill of Materials +These fine projects all provided inspiration for various aspects of +the Atreus, as well as the folks on the =#geekhack= freenode channel. -- 37 MX Blues @ $1.00 -- 5 MX Blacks @ 0.80 -- 42 diodes @ $0.052 -- Base keycap set: $18.00 -- Teensy 2: $16 OR Arduino Micro: $25 -- USB Mini cable: $1.94 -- Acrylic materials: $11 -- Acrylic laser cutting: 6 at $3/min (varies by thickness of acrylic) +- [[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]] -=(+ 37 (* 5 0.8) (* 42 0.052) 18 16 1.94 11 (* 3 7.5))= -> $112.62 plus tax/shipping +** Builds -- Digikey (switches, diodes, arduino?) US shipping: $5.32 -- Signature Plastics (keycaps) shipping: $8.00 -- PJRC (teensy) shipping: $3.03 +If you've built an Atreus, please add your name to [[https://github.com/technomancy/atreus/wiki/BuildLogs][the build logs wiki]]. -** Cost-saving Options +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. -There are a few ways to get the cost under $100. Using all black -switches brings it down, but I strongly recommend against this unless -you're already familiar with the feel of the various Cherry -switches. Using wood for the case will reduce both the materials cost -as well as the amount of time needed to cut the case. +** Orestes -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. +An [[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 really suitable for general-purpose use; it's more of a curiosity. ** License -Copyright © 2014 Phil Hagelberg +Copyright © 2014-2018 Phil Hagelberg and contributors Released under the [[https://www.gnu.org/licenses/gpl.html][GNU GPL version 3]]