updating documentation :)

(and a few minor changes)

readme.md

@@ -20,51 +20,199 @@ the fact that Markdown doesn't have any way (that I know of) to rewrite the
 URLs as would be required.
 
 
+## Features (on the ErgoDox)
+* 6KRO
+* Teensy 2.0, MCP23018 I/O expander
+* ~167 Hz scan rate (last time I measured it) (most of which is spent
+  communicating via I²C)
+* firmware level layers
+
+
 ## About this Project
 
-This project is definitely in beta, but I'll do my best to keep the 'master'
-branch working.  Please see the source (and especially the accompanying '.md'
-files) for documentation.  And [references.md] (references.md) contains lots of
-good links, along with descriptions.
+This project is still definitely a work in progress, but it's getting towards
+something I'll be happy with when the keyboard finally goes into group buy.
+The 'master' branch should always contain the most recent "stable" release of
+the code.  The 'dev' branch may have new things, but it may also have
+expiremental or not yet fixed things.  Code on the 'master' branch should also
+tend to be more thoroughly tested.  Please see the source (and especially the
+accompanying '.md' files) for documentation.  And [references.md]
+(references.md) contains lots of good links, along with descriptions.
 
 If you're just trying to compile, jump to the bottom of the file and read the
 [Dependencies] (#dependencies-for-building-from-source) section.  Once that's
-taken care of, navigate to the [src] (src) directory, compile using Make, and
-fire up your teensy loader to transfer the '.hex' file.  Just to be safe, you
-should also check the '.eep' file.  If it's larger than 0 bytes, you need to
-load it too.
-
-If you're looking to hack on the source, or just feel like reading it, you
-probably don't need much direction for a small project like this.  I'll try to
-write more later (for people who are new to AVR programming, like I was when I
-started this project), but for now:
-* [src/lib] (src/lib) is for generally useful stuff.  The TWI and USB libraries
-  are in there, along with the file containing basic key press and release
-  functions.
-* [src/keyboard] (src/keyboard) is for keyboard specific stuff.  All the chip
-  initialization code is there, along with the layout files, the software
-  matrix to hardware matrix mapping, and hardware specific documentation.
-* [src/main.c] (src/main.c) ties it all together.
+taken care of, navigate to the [src] (src) directory (*not* the toplevel
+directory), compile using Make, and fire up your teensy loader to transfer the
+'.hex' file.  Just to be safe, you should also check the '.eep' file.  If it's
+larger than 0 bytes, you need to load it too.
 
 Open issues, feature requests, and such are tracked [on github]
 (/benblazak/ergodox-firmware/issues).
 
 
-## Notes
+## About this Project (more technical)
+
+If you're looking to hack on the source, or just feel like reading it:
+
+* The [makefile] (./makefile) and [build-scripts] (./build-scripts) folder in
+  the toplevel directory are for building the collection of files that are
+  posted on the [downloads]
+  (https://github.com/benblazak/ergodox-firmware/downloads) page.  They are not
+  guaranteed to work on non-Unix systems, and may be more hackish than the
+  stuff in [src] (./src).  They help me out though.
+* [src/lib] (src/lib) is for generally useful stuff relating to the firmware.
+  [src/lib-other] (src/lib-other) is for generally useful stuff that I didn't
+  write myself.  The TWI and USB libraries are in there, along with the files
+  containing key press and release functions.
+* [src/keyboard] (src/keyboard) is for keyboard specific stuff.  All the chip
+  initialization code is there, along with the layout files, the software
+  matrix to hardware matrix mapping, and hardware specific documentation.
+* [src/main.c] (src/main.c) ties it all together, and provides a few higher
+  level functions that are useful in the key press and release functions.
+
+
+A few concepts that might be different:
+
+* The layer stack
+
+  When activated, layers are pushed onto the top of a stack.  When deactivated,
+  layers are popped out from wherever they are in the stack.  Layers may be
+  active in the stack more than once.  When a keypress occures, the top layer
+  is used to determine what actions to take.
+
+* Keypresses are functions
+
+  Each time a key is pressed, the "press" function assigned to that key on the
+  current layer is called.  When the key is released, the "release" function
+  (from the same layer the key was on when it was pressed) is called.  These
+  functions may do pretty much anything - from sending multiple different
+  keypresses to the host, to changing the firmware state in some way, to
+  activating a new layer.  They may also be "transparent", i.e. execute the
+  function assigned to the key on the layer one down from the top layer
+  (allowing for layers that are effectively "masks" over whatever layer was
+  active before them).
+
+
+
+## HowTo
+
+These instructions (or notes, rather) are meant for people who's googling
+skills and patience are directly proportional to the amount of C programming
+they don't already know :) .  I've done my best to organize and comment things
+though, so I hope that just about anyone who manages to find their way all the
+way here will be able to figure out a good deal from context.
+
+
+### Change the Direction of the Diodes
+
+That is, how to change whether the rows or the columns are being driven.  This can be done for each side of the keyboard separately.
+
+* See [src/keyboard/ergodox/options.h] (src/keyboard/ergodox/options.h)
+
+
+### Create a New Keymap
+
+* Files to reference:
+    * Keycode macros: see the file
+      [src/lib/usb/usage-page/keyboard--short-names.h]
+      (src/lib/usb/usage-page/keyboard--short-names.h).
+        * See [keyboard.h] (src/lib/usb/usage-page/keyboard.h) for the actual
+          values, with references to the specification.
+    * Keyboard functions: see all files in the folder
+      [src/lib/key-functions/public] (src/lib/key-functions/public).
+    * Template layout files: see the QWERTY keymap source files in the folder
+      [src/keyboard/ergodox/layout] (src/keyboard/ergodox/layout)
+        * Currently [qwerty-kinesis-mod.c]
+          (src/keyboard/ergodox/layout/qwerty-kinesis-mod.c) and
+          [qwerty-kinesis-mod.h]
+          (src/keyboard/ergodox/layout/qwerty-kinesis-mod.h)).
+        * You'll probably want to make a copy of each to use as a template.
+
+* You will need to set the `LAYOUT` variable in [src/makefile-options]
+  (src/makefile-options) to the base name of your new layout files before you
+  recompile.  ('.h' files may be called what you wish, but '.c' files must all
+  have the same prefix (i.e. "base name") or they won't be compiled).
+
+* Among other things, the '.h' layout file defines the macros that control the
+  meaning of each of the LEDs on the keyboard (capslock, etc.).  They may be
+  changed freely (or removed, to disable that LED).
+
+* The '.c' layout file defines the values (keycode|value, press function,
+  release function) assigned to each key, for each layer.
+    * If a "press" function is set to NULL for a given layer, nothing will be
+      called when the key is pressed on that layer.  Likewise for "release"
+      functions.  If both are set to `NULL`, nothing will happen when the key
+      is pressed in either event, so it doesn't matter what the keycode|value
+      is for that layer - but you should probably pick something like `0` and
+      stick to it, just for clarity.
+    * The default number of layers is 10 (defined in
+      [default--matrix-control.h]
+      (src/keyboard/ergodox/layout/default--matrix-control.h) - you can
+      override it in the layout's '.h' file, if you like).  You don't have to
+      define all of them in the '.c' layout file, just the ones you want (C
+      sets the uninitialized portions of the matrices to 0).
+    * Make sure that in layer-0 **nothing is transparent** (see [About this
+      Project (more technical)] (#about-this-project-more-technical).  Behavior
+      is undefined if this occurs (off the top of my head, it'll probably cause
+      an infinite loop - and you'll have to reset your keyboard (unplug it and
+      plug it in again)).
+    * Be careful how you assign things.  Pay **close attention** to the
+      possible combinations of keypresses that could occur.  It's perfectly
+      possible, for example, to make a layout that can shift to layer 2 (or
+      some layer that doesn't even exist) and can't shift back, or that fails
+      to tell the host when keys are released.  It's fairly unlikely that
+      anything bad will happen if you mess up (though you could theoretically
+      generate a sequence of keypresses that accidentally do very bad things on
+      your machine), but it's important to have the possibility in mind.
+      Please consider yourself warned :) .
+
+
+### Add Code for a Different Type of Keyboard
+
+* All the function prototypes and macro definitions required by the rest of the
+  code should be in the following files (using the ergodox code as an example):
+    * [controller.h] (src/keyboard/ergodox/controller.h)
+    * [layout.h] (src/keyboard/ergodox/layout.h) (which in the ergodox code
+      only exists to include 
+      [layout/default--led-control.h]
+      (src/keyboard/ergodox/layout/default--led-control.h) and
+      [layout/default--matrix-control.h]
+      (src/keyboard/ergodox/layout/default--matrix-control.h))
+    * [matrix.h] (src/keyboard/ergodox/matrix.h)
+
+* (In broad terms, you'll need to define functions that initialize and update
+  the matrix, LED control macros, macros defining matrix dimensions, and
+  keycode | key-lookup macros (or functions).)
+
+* You will need to set the `KEYBOARD` variable in [src/makefile-options]
+  (src/makefile-options) to the name of your new keyboard folder before you
+  recompile.  You may also wish to change some of the other options in that
+  file.
+
+* The '.h' files listed above *must* exist, with those names, in the toplevel
+  of your keyboard's directory (e.g. in `src/keyboard/new-keyboard-name`).
+  They may include other '.h' files if you wish to put various definitions or
+  prototypes in other places.  They will be included (with the help of some
+  handy macros) in the corresponding files in [src/keyboard] (src/keyboard),
+  which are in turn the files included by "main" and the keyboard functions.
+
+* If you change the way things are included, be careful for circular includes.
+  "main", the keyboard functions, and the keyboard code all need various
+  parts of each other.
+
+* Make sure to keep your eye on the `SRC` variable in [src/makefile]
+  (src/makefile), to make sure all your '.c' files are getting compiled.
 
-### Features as of 2012-04-11 : first major release on branch 'main'
-* 6KRO
-* Teensy 2.0, MCP23018 I/O expander
-* ~167 Hz scan rate (most of which is spent communicating via I²C)
-* firmware level layers
 
 
 ## Dependencies (for building from source)
 
 * See the PJRC [Getting Started] (http://pjrc.com/teensy/first_use.html) page
-  for instructions on how to set up an AVR programming environment.  This
-  project uses C (not Arduino), and Make.  I'm compiling with GNU tools under
-  Ubuntu, but other environments (especially [WinAVR]
+  for instructions on how to set up an AVR programming environment (be sure to
+  click through all the subsections (in the navigation bar on the left), as
+  there is essential information in each one).  This project uses C (not
+  Arduino), and Make.  I'm compiling with GNU tools under OS X, but other
+  environments (especially Linux, appropriately set up, or [WinAVR]
   (http://winavr.sourceforge.net/) under Windows) should work too.
 
 * I also assume that you are using [git] (http://git-scm.com/) (for `make

references.md

@@ -257,7 +257,7 @@
 
 * [LUFA (2012) (Lightweight USB Framework for AVRs)]
   (http://www.fourwalledcubicle.com/LUFA.php)  
-  Very well known USB library for AVRs.  And it looks like it be really good
+  Very well known USB library for AVRs.  And it looks like it'd be really good
   too, but the documentation is hard to get into, and the examples don't seem
   to have enough explanation for me, since I don't have any background in what
   USB is doing in the first place.

src/keyboard/ergodox/layout.md

@@ -2,18 +2,6 @@
 
 Different layouts are included by modifying a variable in the makefile.
 
-To write a new one:
-* Create new layout files under [layout] (layout) (see [qwerty.h]
-  (layout/qwerty.h) and [qwerty.c] (layout/qwerty.c)).
-* Use `0` for no-operation (unused) keys, and `NULL` for no-operation (unused)
-  functions.
-* See [matrix/mapping.h] (matrix/mapping.h) for how the key matrix maps to
-  hardware.
-* See [keyboard-usage-page--short-names.h]
-  (../../lib/_usb/keyboard-usage-page--short-names.h) for available keycodes.
-* See [key-functions.c] (../../lib/key-functions.c) for what functions keys
-  can call.
-
 
 ## notes
 

src/keyboard/ergodox/layout/dvorak-kinesis-mod.c

@@ -1,6 +1,5 @@
 /* ----------------------------------------------------------------------------
- * ergoDOX layout : QWERTY (modified from the Kinesis layout)
- * TODO: rewrite for new kbfun's
+ * ergoDOX layout : Dvorak (modified from the Kinesis layout)
  * ----------------------------------------------------------------------------
  * Copyright (c) 2012 Ben Blazak <[email protected]>
  * Released under The MIT License (MIT) (see "license.md")

src/keyboard/ergodox/layout/qwerty-kinesis-mod.c

@@ -1,6 +1,5 @@
 /* ----------------------------------------------------------------------------
  * ergoDOX layout : QWERTY (modified from the Kinesis layout)
- * TODO: rewrite for new kbfun's
  * ----------------------------------------------------------------------------
  * Copyright (c) 2012 Ben Blazak <[email protected]>
  * Released under The MIT License (MIT) (see "license.md")

src/main.h

@@ -12,7 +12,6 @@
 
 	#include <stdbool.h>
 	#include <stdint.h>
-	#include "./lib/key-functions/public.h"
 	#include "./keyboard/matrix.h"
 
 	// --------------------------------------------------------------------