comment much of the default sketch

Model01-Firmware.ino

@@ -7,26 +7,68 @@
 #endif
 
 
+/** 
+ * These #include directives pull in the Kaleidoscope firmware core, 
+ * as well as the Kaleidoscope plugins we use in the Model 01's firmware
+ */
+
+
+// The Kaleidoscope core
 #include "Kaleidoscope.h"
 
+// Support for keys that move the mouse
 #include "Kaleidoscope-MouseKeys.h"
+
+// Support for macros
 #include "Kaleidoscope-Macros.h"
 
-
+// Support for controlling the keyboard's LEDs
 #include "Kaleidoscope-LEDControl.h"
 
+// Support for "Numlock" mode, which is mostly just the Numlock specific LED mode
 #include "Kaleidoscope-Numlock.h"
+
+// Support for an "LED off mode"
 #include "LED-Off.h"
+
+// Support for the "Boot greeting" effect, which pulses the 'LED' button for 10s on boot
 #include "Kaleidoscope-LEDEffect-BootGreeting.h"
+
+// Support for LED modes that set all LEDs to a single color
 #include "Kaleidoscope-LEDEffect-SolidColor.h"
+
+// Support for an LED mode that makes all the LEDs 'breathe' 
 #include "Kaleidoscope-LEDEffect-Breathe.h"
+
+// Support for an LED mode that makes a red pixel chase a blue pixel across the keyboard
 #include "Kaleidoscope-LEDEffect-Chase.h"
+
+// Support for LED modes that pulse the keyboard's LED in a rainbow pattern
 #include "Kaleidoscope-LEDEffect-Rainbow.h"
+
+// Support for an LED mode that lights up the keys as you press them
 #include "Kaleidoscope-LED-Stalker.h"
+
+// Support for an LED mode that prints the keys you press in letters 4px high 
 #include "Kaleidoscope-LED-AlphaSquare.h"
+
+// Support for Keyboardio's internal keyboard testing mode
 #include "Kaleidoscope-Model01-TestMode.h"
 
 
+/** This 'enum' is a list of all the macros used by the Model 01's firmware
+  * The names aren't particularly important. What is important is that each 
+  * is unique.
+  *
+  * These are the names of your macros. They'll be used in two places.
+  * The first is in your keymap definitions. There, you'll use the syntax
+  * `M(MACRO_NAME)` to mark a specific keymap position as triggering `MACRO_NAME`
+  *
+  * The second usage is in the 'switch' statement in the `macroAction` function.
+  * That switch statment is where the firmware dispatches a macro to the function  
+  * handling that macro
+  */ 
+
 enum { MACRO_VERSION_INFO,
        MACRO_ANY
      };
@@ -92,6 +134,12 @@ const Key keymaps[][ROWS][COLS] PROGMEM = {
 
 #define NUMPAD_KEYMAP_ID 2
 
+
+/** versionInfoMacro handles the 'firmware version info' macro
+ *  When a key bound to the macro is pressed, this macro
+ *  prints out the firmware build information as virtual keystrokes
+ */
+
 static void versionInfoMacro(uint8_t keyState) {
   if (keyToggledOn(keyState)) {
     Macros.type(PSTR("Keyboardio Model 01 - Kaleidoscope "));
@@ -99,6 +147,14 @@ static void versionInfoMacro(uint8_t keyState) {
   }
 }
 
+/** anyKeyMacro is used to provide the functionality of the 'Any' key. 
+ *
+ * When the 'any key' macro is toggled on, a random alphanumeric key is
+ * selected. While the key is held, the function generates a synthetic
+ * keypress event repeating that randomly selected key. 
+ *
+ */
+
 static void anyKeyMacro(uint8_t keyState) {
   static Key lastKey;
   if (keyToggledOn(keyState))
@@ -109,6 +165,18 @@ static void anyKeyMacro(uint8_t keyState) {
 }
 
 
+/** macroAction dispatches keymap events that are tied to a macro 
+    to that macro. It takes two uint8_t parameters. 
+
+    The first is the macro being called (the entry in the 'enum' earlier in this file).
+    The second is the state of the keyswitch. You can use the keyswitch state to figure out
+    if the key has just been toggled on, is currently pressed or if it's just been released.
+   
+    The 'switch' statement should have a 'case' for each entry of the macro enum.
+    Each 'case' statement should call out to a function to handle the macro in question. 
+
+ */
+
 const macro_t *macroAction(uint8_t macroIndex, uint8_t keyState) {
   switch (macroIndex) {
 
@@ -125,6 +193,10 @@ const macro_t *macroAction(uint8_t macroIndex, uint8_t keyState) {
 
 
 
+// These 'solid' color effect definitions define a rainbow of 
+// LED color modes calibrated to draw 500mA or less on the 
+// Keyboardio Model 01.
+
 
 static kaleidoscope::LEDSolidColor solidRed(160, 0, 0);
 static kaleidoscope::LEDSolidColor solidOrange(140, 70, 0);
@@ -136,31 +208,96 @@ static kaleidoscope::LEDSolidColor solidViolet(130, 0, 120);
 
 
 
+/** The 'setup' function is one of the two standard Arduino sketch functions. 
+  * It's called when your keyboard boots up. This is where you set up Kaleidoscope
+  * and any plugins.
+  */
 
 void setup() {
+  // First, call Kaleidoscope's internal setup function
   Kaleidoscope.setup();
+
+  // Next, tell Kaleidoscope which plugins you want to use. 
+  // The order can be important. For example, LED effects are 
+  // added in the order they're listed here.
   Kaleidoscope.use(
+    // The boot greeting effect pulses the LED button for 10 seconds after the keyboard boots up
     &BootGreetingEffect,
+
+    // The hardware test mode, which can be invoked by tapping Prog, LED and the left Fn button at the same time.
     &TestMode,
-    &LEDControl, &LEDOff,
+
-    &LEDRainbowEffect, &LEDRainbowWaveEffect, &LEDChaseEffect,
+    // LEDControl provides support for other LED modes
+    &LEDControl, 
+
+    // We start with the LED effect that turns off all the LEDs. 
+    &LEDOff,
+   
+    // The rainbow effect changes the color of all of the keyboard's keys at the same time
+    // running through all the colors of the rainbow.
+    &LEDRainbowEffect, 
+
+    // The rainbow wave effect lights up your keyboard with all the colors of a rainbow
+    // and slowly moves the rainbow across your keyboard
+    &LEDRainbowWaveEffect,
+
+    // The chase effect follows the adventure of a blue pixel which chases a red pixel across
+    // your keyboard. Spoiler: the blue pixel never catches the red pixel
+    &LEDChaseEffect,
+    
+    // These static effects turn your keyboard's LEDs a variety of colors
     &solidRed, &solidOrange, &solidYellow, &solidGreen, &solidBlue, &solidIndigo, &solidViolet,
+
+    // The breathe effect slowly pulses all of the LEDs on your keyboard
     &LEDBreatheEffect,
+
+    // The AlphaSquare effect prints each character you type, using your 
+    // keyboard's LEDs as a display
     &AlphaSquareEffect,
+
+    // The stalker effect lights up the keys you've pressed recently
     &StalkerEffect,
+
+    // The numlock plugin is responsible for lighting up the 'numpad' mode
+    // with a custom LED effect
     &NumLock,
+
+    // The macros plugin adds support for macros
     &Macros,
+
+    // The MouseKeys plugin lets you add keys to your keymap which move the mouse.
     &MouseKeys,
     NULL);
 
+  // While we hope to improve this in the future, the NumLock plugin
+  // needs to be explicitly told which keymap layer is your numpad layer
   NumLock.numPadLayer = NUMPAD_KEYMAP_ID;
+
+  // We configure the AlphaSquare effect to use RED letters
   AlphaSquare.color = { 255, 0, 0 };
+
+  // We set the brightness of the rainbow effects to 150 (on a scale of 0-255)
+  // This draws more than 500mA, but looks much nicer than a dimmer effect
   LEDRainbowEffect.brightness(150);
   LEDRainbowWaveEffect.brightness(150);
+
+  // The LED Stalker mode has a few effects. The one we like is
+  // called 'BlazingTrail'. For details on other options, 
+  // see https://github.com/keyboardio/Kaleidoscope-LED-Stalker
   StalkerEffect.variant = STALKER(BlazingTrail);
+
+  // We want to make sure that the firmware starts with LED effects off
+  // This avoids over-taxing devices that don't have a lot of power to share
+  // with USB devices
   LEDOff.activate();
 }
 
+/** loop is the second of the standard Arduino sketch functions. 
+  * As you might expect, it runs in a loop, never exiting.
+  *
+  * For Kaleidoscope-based keyboard firmware, you usually just want to 
+  * call Kaleidoscope.loop(); and not do anything custom here.
+  */
 
 void loop() {
   Kaleidoscope.loop();