From a10ddeaa50ef2263e532d1055745a693f77ad312 Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Mon, 2 Oct 2017 22:04:13 -0700 Subject: comment much of the default sketch --- Model01-Firmware.ino | 143 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 140 insertions(+), 3 deletions(-) (limited to 'Model01-Firmware.ino') diff --git a/Model01-Firmware.ino b/Model01-Firmware.ino index 20cede9..ff119cc 100644 --- a/Model01-Firmware.ino +++ b/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" -#include "Kaleidoscope-Macros.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(); -- cgit v1.2.3