mostly aesthetic updates

firmware/keyboard/ergodox/controller.c

@@ -12,7 +12,7 @@
 #include <stdint.h>
 #include "./controller/mcp23018.h"
 #include "./controller/teensy-2-0.h"
-#include "../../keyboard.h"
+#include "../../../firmware/keyboard.h"
 
 // ----------------------------------------------------------------------------
 

firmware/keyboard/ergodox/led.c

@@ -14,7 +14,7 @@
 #include <stdint.h>
 #include <avr/io.h>
 #include <util/delay.h>
-#include "../../keyboard.h"
+#include "../../../firmware/keyboard.h"
 
 // ----------------------------------------------------------------------------
 

firmware/lib/eeprom.h

@@ -33,6 +33,12 @@
 
 // ----------------------------------------------------------------------------
 
+#ifndef OPT__EEPROM_MACRO__EEPROM_SIZE
+    #error "OPT__EEPROM_MACRO__EEPROM_SIZE not defined"
+#endif
+
+// ----------------------------------------------------------------------------
+
 uint8_t eeprom__read  (uint8_t * from);
 uint8_t eeprom__write (uint8_t * to, uint8_t data);
 uint8_t eeprom__copy  (uint8_t * to, uint8_t * from, uint8_t length);
@@ -49,6 +55,21 @@ uint8_t eeprom__copy  (uint8_t * to, uint8_t * from, uint8_t length);
 // ============================================================================
 
 
+// ----------------------------------------------------------------------------
+// macros ---------------------------------------------------------------------
+// ----------------------------------------------------------------------------
+
+// === OPT__EEPROM_MACRO__EEPROM_SIZE ===
+/**                           macros/OPT__EEPROM_MACRO__EEPROM_SIZE/description
+ * The total size (in bytes) of the EEPROM memory to be allocated by the
+ * implementing file
+ */
+
+
+// ----------------------------------------------------------------------------
+// functions ------------------------------------------------------------------
+// ----------------------------------------------------------------------------
+
 // === eeprom__read() ===
 /**                                          functions/eeprom__read/description
  * Read and return the data at `address` in the EEPROM memory space

firmware/lib/layout/eeprom-macro.h

@@ -77,6 +77,7 @@ void    eeprom_macro__clear_all     (void);
 
 // ----------------------------------------------------------------------------
 // types ----------------------------------------------------------------------
+// ----------------------------------------------------------------------------
 
 // === eeprom_macro__uid_t ===
 /**                                       types/eeprom_macro__uid_t/description
@@ -106,6 +107,7 @@ void    eeprom_macro__clear_all     (void);
 
 // ----------------------------------------------------------------------------
 // functions ------------------------------------------------------------------
+// ----------------------------------------------------------------------------
 
 // === eeprom_macro__init ===
 /**                                    functions/eeprom_macro__init/description

firmware/lib/layout/eeprom-macro/atmega32u4.c

@@ -29,18 +29,13 @@
 
 // ----------------------------------------------------------------------------
 
-// TODO: consider moving this, and all similar things in other files, into the
-// '.h' files instead (and *always* including the '.h' files in implementing
-// '.c' files)
-#ifndef OPT__EEPROM_MACRO__EEPROM_SIZE
-    #error "OPT__EEPROM_MACRO__EEPROM_SIZE not defined"
-#endif
 /**                           macros/OPT__EEPROM_MACRO__EEPROM_SIZE/description
- * The total size (in bytes) of the EEPROM memory to be allocated by this file
- *
- * Notes:
+ * Implementation notes:
  * - The ATMega32U4 has 1024 bytes of internal EEPROM total
  */
+#if OPT__EEPROM_MACRO__EEPROM_SIZE > 1024
+    #error "OPT__EEPROM_MACRO__EEPROM_SIZE must be <= 1024"
+#endif
 
 // ----------------------------------------------------------------------------
 

firmware/lib/twi.h

@@ -24,6 +24,12 @@
 
 // ----------------------------------------------------------------------------
 
+#ifndef OPT__TWI__FREQUENCY
+    #error "OPT__TWI__FREQUENCY not defined"
+#endif
+
+// ----------------------------------------------------------------------------
+
 void    twi__init  (void);
 uint8_t twi__start (void);
 void    twi__stop  (void);
@@ -35,3 +41,71 @@ uint8_t twi__read  (uint8_t * data);
 // ----------------------------------------------------------------------------
 #endif  // ERGODOX_FIRMWARE__FIRMWARE__LIB__TWI__H
 
+
+
+// ============================================================================
+// === documentation ==========================================================
+// ============================================================================
+
+
+// ----------------------------------------------------------------------------
+// macros ---------------------------------------------------------------------
+// ----------------------------------------------------------------------------
+
+// === OPT__TWI__FREQUENCY ===
+/**                                      macros/OPT__TWI__FREQUENCY/description
+ * The TWI Frequency, in Hz.
+ */
+
+
+// ----------------------------------------------------------------------------
+// functions ------------------------------------------------------------------
+// ----------------------------------------------------------------------------
+
+// === twi__init() ===
+/**                                             functions/twi__init/description
+ * Initialize TWI
+ *
+ * Notes:
+ * - Should be called exactly once during keyboard startup
+ */
+
+// === twi__start() ===
+/**                                            functions/twi__start/description
+ * Send a TWI Start signal
+ *
+ * Returns:
+ * - success: `0`
+ * - failure: The TWI status code
+ */
+
+// === twi__stop() ===
+/**                                             functions/twi__stop/description
+ * Send a TWI Stop signal
+ */
+
+// === twi__send() ===
+/**                                             functions/twi__send/description
+ * Send `data` (which may actually be an instruction or a device or register
+ * address) over the bus
+ *
+ * Arguments:
+ * - `data`: The data to send
+ *
+ * Returns:
+ * - success: `0`
+ * - failure: The TWI status code
+ */
+
+// === twi__read() ===
+/**                                             functions/twi__read/description
+ * Read incoming data
+ *
+ * Arguments:
+ * - `data`: A pointer to the location to read data to
+ *
+ * Returns:
+ * - success: `0`
+ * - failure: The TWI status code
+ */
+

firmware/lib/twi/atmega32u4.c

@@ -28,13 +28,11 @@
 
 // ----------------------------------------------------------------------------
 
-#ifndef OPT__TWI__FREQUENCY
-    #error "OPT__TWI__FREQUENCY not defined"
+#if OPT__TWI__FREQUENCY > 400000
+    #error "OPT__TWI__FREQUENCY must be <= 400000"
 #endif
 /**                                      macros/OPT__TWI__FREQUENCY/description
- * The TWI Frequency, in Hz.
- *
- * Notes:
+ * Implementation notes:
  * - The max speed for the ATmega32U4 is 400kHz (datasheet sec. 20.1)
  * - The max speed for the MCP23017 is 1.7MHz (datasheet pg. 1)
  * - The max speed for the MCP23018 is 3.4MHz (datasheet pg. 1)

firmware/main.c

@@ -23,9 +23,6 @@
 
 // ----------------------------------------------------------------------------
 
-#ifndef OPT__DEBOUNCE_TIME
-    #error "OPT__DEBOUNCE_TIME not defined"
-#endif
 /**                                       macros/OPT__DEBOUNCE_TIME/description
  * The minimum amount of time to wait between two scans of a key, in
  * milliseconds
@@ -33,6 +30,9 @@
  * Notes:
  * - Cherry MX bounce time <= 5ms (at 16 in/sec actuation speed) (spec)
  */
+#ifndef OPT__DEBOUNCE_TIME
+    #error "OPT__DEBOUNCE_TIME not defined"
+#endif
 
 // ----------------------------------------------------------------------------