From 4517ff7c0e1c828d0a57ee177d4325610c914405 Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Thu, 5 Nov 2020 16:12:46 -0800 Subject: [PATCH] Add a first version of a Kaleidoscope testing DSL. The goal is to make it easy for folks to write tests without knowing C++ Signed-off-by: Jesse Vincent --- .gitignore | 1 + testing/bin/ktest-to-cxx | 362 +++++++++++++++ testing/makefiles/testcase.mk | 17 + tests/examples/basic-generated/sketch.ino | 537 ++++++++++++++++++++++ tests/examples/basic-generated/test.ktest | 28 ++ 5 files changed, 945 insertions(+) create mode 100644 testing/bin/ktest-to-cxx create mode 100644 tests/examples/basic-generated/sketch.ino create mode 100644 tests/examples/basic-generated/test.ktest diff --git a/.gitignore b/.gitignore index 710ed307..c6c002f6 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ /docs/api /_build/ /results/ +generated-testcase.cpp diff --git a/testing/bin/ktest-to-cxx b/testing/bin/ktest-to-cxx new file mode 100644 index 00000000..50b64adf --- /dev/null +++ b/testing/bin/ktest-to-cxx @@ -0,0 +1,362 @@ +#!/usr/bin/perl + +use warnings; +use strict; +use Getopt::Long; +use File::Spec; + +my $text_filename = ""; +my $cxx_filename = ""; +my $verbose; +my $cxx_output = ""; +my $depth = 0; +my $reports_expected = 0; +my @script_lines; +my $named_switches = {}; + +GetOptions( + "cxx=s" => \$cxx_filename, # string + "ktest=s" => \$text_filename, + "verbose" => \$verbose + ) # flag + or die("Error in command line arguments\n"); + +my $test; + +if ( -f $text_filename ) { + load_from_text(); +} +else { + die "Couldn't find $text_filename"; +} + +generate_test_file(); + +open(my $outfile, ">", $cxx_filename) || die "Can't open output file $!"; +print $outfile $cxx_output; +close ($outfile); + +exit(0); + + + + +sub load_from_text { + my @content = (); + open( my $text_fh, "<", $text_filename ) or die "Can't open file $!"; + my $line_num = 0; + for my $line (<$text_fh>) { + my ( $key, $content, $comment, $error, $type ); + $line_num++; + chomp $line; + + $line =~ s/^\s+//; + + if ( $line eq '' ) { + next; + } + if ( $line =~ /^(.*?)\s*#\s+(.*)$/ ) { + $line = $1; + $comment = $2; + } + + if ( $line =~ /^(.*?)\s+(.*)\s*$/ ) { + $type = lc $1; + $content = $2; + } + else { + $error = "Couldn't parse line"; + } + + my $dispatcher = { + version => sub { + my $version = shift; + if ($version != 1) { + die "This parser only supports v1"; + } + return undef; + }, + type => sub { + my $type = shift; + $type =~ s/\s//g; + $test->{type} = $type; + return undef; + }, + name => sub { + my $name = shift; + $name =~ s/\s//g; + $test->{name} = $name; + return undef; + }, + + keyswitch => sub { + my $content = shift; + if ( $content =~ /^(.*)\s+(\d+)\s+(\d+)$/ ) { + my $switch = $1; + my $row = $2; + my $col = $3; + if ( exists $named_switches->{$switch} ) { + die "Attempted to redefine '$switch' on line $line_num"; + } + else { + $named_switches->{$switch} = [ $row, $col ]; + } + return undef; + } + }, + press => sub { + my $content = shift; + unless ( defined $named_switches->{$content} ) { + die "Attempt to press undefined switch $content on line $line_num"; + } + return { switch => $content }; + }, + release => sub { + my $content = shift; + unless ( defined $named_switches->{$content} ) { + die +"Attempt to press undefined switch $content on line $line_num"; + } + return { switch => $content }; + }, + expect => sub { + my $content = shift; + if ( $content =~ /^keyboard-report\s+(.*)$/ ) { + my $report_data = $1; + my @keys = split( /,?\s+/, $report_data ); + if ( $#keys == 0 && $keys[0] =~ /^empty$/i ) { + @keys = (); + } + return { + report_type => 'keyboard', + keys => [@keys] + }; + } + else { + die "Don't know how parse $content at line $line_num"; + } + }, + run => sub { + my $content = shift; + if ( $content =~ /^(\d+)\s+(\w+)$/ ) { + my $count = $1; + my $unit = $2; + if ( $unit =~ /cycle/ ) { + return { cycles => $count }; + } + elsif ( $unit =~ /milli|ms/ ) { + return { millis => $count }; + } + else { die "Line $line_num: failed to parse a 'run' clause: $content"; } + } + else { die "Line $line_num: failed to parse a 'run' clause: $content"; } + + }, + + }; + + my $data; + if ( $type && exists $dispatcher->{$type} ) { + $data = $dispatcher->{$type}->($content); + # an empty return means "don't put it in the script + if (!$data) { + next; + } + } + + push @content, + { + action => $type, + content => $content, + comment => $comment, + data => $data, + line_num => $line_num + }; + + } + close ($text_fh); + @script_lines = @content; +} + + +sub generate_test_file { + +my $preface = <rel2abs( $text_filename ) ]} + +SETUP_GOOGLETEST(); + +namespace kaleidoscope { +namespace testing { +namespace { + +class KeyboardReports : public VirtualDeviceTest {}; +EOF + +for my $line (split/\n/,$preface) { + cxx($line); +} + + cxx( "TEST_F(" . $test->{type} . "," . $test->{name} . ") {" ); + indent(); + generate_key_addrs(); + + generate_script( ); + + outdent(); + cxx("} // TEST_F"); + +my $postscript = <{$key}->[0] . ", " + . $named_switches->{$key}->[1] + . "};" ); + + } + +} + +sub generate_script { + cxx_section("Test script"); + $reports_expected = 0; + for my $entry (@script_lines) { + + if ($entry->{comment} && (! $entry->{action} ) ) { + cxx_comment($entry->{comment}); + } elsif (my $action = $entry->{action} ) { + + if ( $action eq 'press' ) { generate_press( $entry ) } + elsif ( $action eq 'release' ) { generate_release( $entry ); } + elsif ( $action eq 'run' ) { generate_run( $entry ) } + elsif ( $action eq 'expect' ) { generate_expect_report( $entry ); } + else { + die "$action unknown on line $entry->{line_num}"; + } + } + } + if ($reports_expected) { + generate_check_expected_reports(); + } +} + +sub generate_run { + my $action = shift; + if ( $action->{'comment'} ) { + cxx_comment( $action->{'comment'} ); + } + if ( $action->{data}->{'cycles'} ) { + cxx( 'sim_.RunCycles(' . $action->{data}->{'cycles'} . ');' ); + } + elsif ( $action->{data}->{'millis'} ) { + cxx( 'sim_.RunForMillis(' . $action->{data}->{'millis'} . ');' ); + } +} + +sub generate_press { + my $e = shift; + + # TODO handle multuple presses + cxx( "PressKey(key_addr_" . $e->{data}->{switch} . ");" , $e->{comment}); +} + +sub generate_release { + my $e = shift; + + # TODO handle multiple releases + cxx( "ReleaseKey(key_addr_" . $e->{data}->{switch} . ");" , $e->{comment}); +} + +sub generate_expect_report { + my $report = shift; + $reports_expected++; + my $codes = join( + ", ", + ( + ref( $report->{data}->{keys} ) + ? @{ $report->{data}->{keys} } + : ( $report->{data}->{keys} ) + ) + ); + cxx( "ExpectReport(Keycodes{$codes}, \"" . $report->{comment} . "\");" ); + cxx(""); +} + +sub generate_check_expected_reports { + cxx(""); + cxx(""); + cxx("CHECK_EXPECTED_REPORTS();"); + cxx(""); +} + +sub indent { + $depth += 2; +} + +sub outdent { + $depth -= 2; + if ( $depth < 0 ) { + die "Tried to outdent beyond 0"; + } +} + +sub cxx_section { + my $line = shift; + cxx(''); + cxx(''); + cxx_comment($line); + cxx_comment( "=" x length($line) ); + cxx(''); + cxx(''); +} + +sub cxx_comment { + my $line = shift; + cxx( "// " . $line ); +} + +sub cxx { + my $line = shift; + my $comment = shift || ''; + $cxx_output .= " " x $depth; + $cxx_output .= $line; + $cxx_output .= $comment if ($comment); + $cxx_output .= "\n"; + if ($verbose) { + debug("$line"); + } +} + +sub debug { + my $msg = shift; + print STDERR ( " " x $depth ) . $msg . "\n"; +} diff --git a/testing/makefiles/testcase.mk b/testing/makefiles/testcase.mk index 89bb90eb..a47c1b91 100644 --- a/testing/makefiles/testcase.mk +++ b/testing/makefiles/testcase.mk @@ -13,6 +13,12 @@ BIN_FILE=$(subst .ino,,$(SKETCH_FILE)) LIB_FILE=${BIN_FILE}-latest.a TEST_FILES=$(wildcard $(SRC_DIR)/*.cpp) + +# If we have a ktest file, we want to turn it into a generated testcase +ifneq (,$(wildcard test.ktest)) +TEST_FILES += $(SRC_DIR)/generated-testcase.cpp +endif + TEST_OBJS=$(patsubst $(SRC_DIR)/%.cpp,${OBJ_DIR}/%.o,$(TEST_FILES)) ifndef BOARD_HARDWARE_PATH @@ -55,6 +61,17 @@ compile-sketch: -lpthread \ -lm + +# If we have a test.ktest file, it should be processed into a c++ testcase +${SRC_DIR}/generated-testcase.cpp: test.ktest +ifneq (,$(wildcard test.ktest)) + @echo "Compiling ktest script into ${SRC_DIR}/generated-testcase.cpp" + install -d "${SRC_DIR}" + perl ${top_dir}/testing/bin/ktest-to-cxx \ + --ktest=test.ktest \ + --cxx=${SRC_DIR}/generated-testcase.cpp +endif + ${OBJ_DIR}/%.o: ${SRC_DIR}/%.cpp @echo "compile $@" install -d "${OBJ_DIR}" diff --git a/tests/examples/basic-generated/sketch.ino b/tests/examples/basic-generated/sketch.ino new file mode 100644 index 00000000..c35a7555 --- /dev/null +++ b/tests/examples/basic-generated/sketch.ino @@ -0,0 +1,537 @@ +// -*- mode: c++ -*- +// Copyright 2016 Keyboardio, inc. +// See "LICENSE" for license details + +#ifndef BUILD_INFORMATION +#define BUILD_INFORMATION "locally built" +#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 storing the keymap in EEPROM +#include "Kaleidoscope-EEPROM-Settings.h" +#include "Kaleidoscope-EEPROM-Keymap.h" + +// Support for communicating with the host via a simple Serial protocol +#include "Kaleidoscope-FocusSerial.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 "Numpad" mode, which is mostly just the Numpad specific LED mode +#include "Kaleidoscope-NumPad.h" + +// Support for the "Boot greeting" effect, which pulses the 'LED' button for 10s +// when the keyboard is connected to a computer (or that computer is powered on) +#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 an LED mode that lets one configure per-layer color maps +#include "Kaleidoscope-Colormap.h" + +// Support for Keyboardio's internal keyboard testing mode +#include "Kaleidoscope-HardwareTestMode.h" + +// Support for host power management (suspend & wakeup) +#include "Kaleidoscope-HostPowerManagement.h" + +// Support for magic combos (key chords that trigger an action) +#include "Kaleidoscope-MagicCombo.h" + +// Support for USB quirks, like changing the key state report protocol +#include "Kaleidoscope-USB-Quirks.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 statement actually runs the code associated with a macro when + * a macro key is pressed. + */ + +enum { MACRO_VERSION_INFO, + MACRO_ANY + }; + + + +/** The Model 01's key layouts are defined as 'keymaps'. By default, there are three + * keymaps: The standard QWERTY keymap, the "Function layer" keymap and the "Numpad" + * keymap. + * + * Each keymap is defined as a list using the 'KEYMAP_STACKED' macro, built + * of first the left hand's layout, followed by the right hand's layout. + * + * Keymaps typically consist mostly of `Key_` definitions. There are many, many keys + * defined as part of the USB HID Keyboard specification. You can find the names + * (if not yet the explanations) for all the standard `Key_` defintions offered by + * Kaleidoscope in these files: + * https://github.com/keyboardio/Kaleidoscope/blob/master/src/key_defs_keyboard.h + * https://github.com/keyboardio/Kaleidoscope/blob/master/src/key_defs_consumerctl.h + * https://github.com/keyboardio/Kaleidoscope/blob/master/src/key_defs_sysctl.h + * https://github.com/keyboardio/Kaleidoscope/blob/master/src/key_defs_keymaps.h + * + * Additional things that should be documented here include + * using ___ to let keypresses fall through to the previously active layer + * using XXX to mark a keyswitch as 'blocked' on this layer + * using ShiftToLayer() and LockLayer() keys to change the active keymap. + * keeping NUM and FN consistent and accessible on all layers + * + * The PROG key is special, since it is how you indicate to the board that you + * want to flash the firmware. However, it can be remapped to a regular key. + * When the keyboard boots, it first looks to see whether the PROG key is held + * down; if it is, it simply awaits further flashing instructions. If it is + * not, it continues loading the rest of the firmware and the keyboard + * functions normally, with whatever binding you have set to PROG. More detail + * here: https://community.keyboard.io/t/how-the-prog-key-gets-you-into-the-bootloader/506/8 + * + * The "keymaps" data structure is a list of the keymaps compiled into the firmware. + * The order of keymaps in the list is important, as the ShiftToLayer(#) and LockLayer(#) + * macros switch to key layers based on this list. + * + * + + * A key defined as 'ShiftToLayer(FUNCTION)' will switch to FUNCTION while held. + * Similarly, a key defined as 'LockLayer(NUMPAD)' will switch to NUMPAD when tapped. + */ + +/** + * Layers are "0-indexed" -- That is the first one is layer 0. The second one is layer 1. + * The third one is layer 2. + * This 'enum' lets us use names like QWERTY, FUNCTION, and NUMPAD in place of + * the numbers 0, 1 and 2. + * + */ + +enum { PRIMARY, NUMPAD, FUNCTION }; // layers + + +/** + * To change your keyboard's layout from QWERTY to DVORAK or COLEMAK, comment out the line + * + * #define PRIMARY_KEYMAP_QWERTY + * + * by changing it to + * + * // #define PRIMARY_KEYMAP_QWERTY + * + * Then uncomment the line corresponding to the layout you want to use. + * + */ + +#define PRIMARY_KEYMAP_QWERTY +// #define PRIMARY_KEYMAP_COLEMAK +// #define PRIMARY_KEYMAP_DVORAK +// #define PRIMARY_KEYMAP_CUSTOM + + + +/* This comment temporarily turns off astyle's indent enforcement + * so we can make the keymaps actually resemble the physical key layout better + */ +// *INDENT-OFF* + +KEYMAPS( + +#if defined (PRIMARY_KEYMAP_QWERTY) + [PRIMARY] = KEYMAP_STACKED + (___, Key_1, Key_2, Key_3, Key_4, Key_5, Key_LEDEffectNext, + Key_Backtick, Key_Q, Key_W, Key_E, Key_R, Key_T, Key_Tab, + Key_PageUp, Key_A, Key_S, Key_D, Key_F, Key_G, + Key_PageDown, Key_Z, Key_X, Key_C, Key_V, Key_B, Key_Escape, + Key_LeftControl, Key_Backspace, Key_LeftGui, Key_LeftShift, + ShiftToLayer(FUNCTION), + + M(MACRO_ANY), Key_6, Key_7, Key_8, Key_9, Key_0, LockLayer(NUMPAD), + Key_Enter, Key_Y, Key_U, Key_I, Key_O, Key_P, Key_Equals, + Key_H, Key_J, Key_K, Key_L, Key_Semicolon, Key_Quote, + Key_RightAlt, Key_N, Key_M, Key_Comma, Key_Period, Key_Slash, Key_Minus, + Key_RightShift, Key_LeftAlt, Key_Spacebar, Key_RightControl, + ShiftToLayer(FUNCTION)), + +#elif defined (PRIMARY_KEYMAP_DVORAK) + + [PRIMARY] = KEYMAP_STACKED + (___, Key_1, Key_2, Key_3, Key_4, Key_5, Key_LEDEffectNext, + Key_Backtick, Key_Quote, Key_Comma, Key_Period, Key_P, Key_Y, Key_Tab, + Key_PageUp, Key_A, Key_O, Key_E, Key_U, Key_I, + Key_PageDown, Key_Semicolon, Key_Q, Key_J, Key_K, Key_X, Key_Escape, + Key_LeftControl, Key_Backspace, Key_LeftGui, Key_LeftShift, + ShiftToLayer(FUNCTION), + + M(MACRO_ANY), Key_6, Key_7, Key_8, Key_9, Key_0, LockLayer(NUMPAD), + Key_Enter, Key_F, Key_G, Key_C, Key_R, Key_L, Key_Slash, + Key_D, Key_H, Key_T, Key_N, Key_S, Key_Minus, + Key_RightAlt, Key_B, Key_M, Key_W, Key_V, Key_Z, Key_Equals, + Key_RightShift, Key_LeftAlt, Key_Spacebar, Key_RightControl, + ShiftToLayer(FUNCTION)), + +#elif defined (PRIMARY_KEYMAP_COLEMAK) + + [PRIMARY] = KEYMAP_STACKED + (___, Key_1, Key_2, Key_3, Key_4, Key_5, Key_LEDEffectNext, + Key_Backtick, Key_Q, Key_W, Key_F, Key_P, Key_G, Key_Tab, + Key_PageUp, Key_A, Key_R, Key_S, Key_T, Key_D, + Key_PageDown, Key_Z, Key_X, Key_C, Key_V, Key_B, Key_Escape, + Key_LeftControl, Key_Backspace, Key_LeftGui, Key_LeftShift, + ShiftToLayer(FUNCTION), + + M(MACRO_ANY), Key_6, Key_7, Key_8, Key_9, Key_0, LockLayer(NUMPAD), + Key_Enter, Key_J, Key_L, Key_U, Key_Y, Key_Semicolon, Key_Equals, + Key_H, Key_N, Key_E, Key_I, Key_O, Key_Quote, + Key_RightAlt, Key_K, Key_M, Key_Comma, Key_Period, Key_Slash, Key_Minus, + Key_RightShift, Key_LeftAlt, Key_Spacebar, Key_RightControl, + ShiftToLayer(FUNCTION)), + +#elif defined (PRIMARY_KEYMAP_CUSTOM) + // Edit this keymap to make a custom layout + [PRIMARY] = KEYMAP_STACKED + (___, Key_1, Key_2, Key_3, Key_4, Key_5, Key_LEDEffectNext, + Key_Backtick, Key_Q, Key_W, Key_E, Key_R, Key_T, Key_Tab, + Key_PageUp, Key_A, Key_S, Key_D, Key_F, Key_G, + Key_PageDown, Key_Z, Key_X, Key_C, Key_V, Key_B, Key_Escape, + Key_LeftControl, Key_Backspace, Key_LeftGui, Key_LeftShift, + ShiftToLayer(FUNCTION), + + M(MACRO_ANY), Key_6, Key_7, Key_8, Key_9, Key_0, LockLayer(NUMPAD), + Key_Enter, Key_Y, Key_U, Key_I, Key_O, Key_P, Key_Equals, + Key_H, Key_J, Key_K, Key_L, Key_Semicolon, Key_Quote, + Key_RightAlt, Key_N, Key_M, Key_Comma, Key_Period, Key_Slash, Key_Minus, + Key_RightShift, Key_LeftAlt, Key_Spacebar, Key_RightControl, + ShiftToLayer(FUNCTION)), + +#else + +#error "No default keymap defined. You should make sure that you have a line like '#define PRIMARY_KEYMAP_QWERTY' in your sketch" + +#endif + + + + [NUMPAD] = KEYMAP_STACKED + (___, ___, ___, ___, ___, ___, ___, + ___, ___, ___, ___, ___, ___, ___, + ___, ___, ___, ___, ___, ___, + ___, ___, ___, ___, ___, ___, ___, + ___, ___, ___, ___, + ___, + + M(MACRO_VERSION_INFO), ___, Key_7, Key_8, Key_9, Key_KeypadSubtract, ___, + ___, ___, Key_4, Key_5, Key_6, Key_KeypadAdd, ___, + ___, Key_1, Key_2, Key_3, Key_Equals, ___, + ___, ___, Key_0, Key_Period, Key_KeypadMultiply, Key_KeypadDivide, Key_Enter, + ___, ___, ___, ___, + ___), + + [FUNCTION] = KEYMAP_STACKED + (___, Key_F1, Key_F2, Key_F3, Key_F4, Key_F5, Key_CapsLock, + Key_Tab, ___, Key_mouseUp, ___, Key_mouseBtnR, Key_mouseWarpEnd, Key_mouseWarpNE, + Key_Home, Key_mouseL, Key_mouseDn, Key_mouseR, Key_mouseBtnL, Key_mouseWarpNW, + Key_End, Key_PrintScreen, Key_Insert, ___, Key_mouseBtnM, Key_mouseWarpSW, Key_mouseWarpSE, + ___, Key_Delete, ___, ___, + ___, + + Consumer_ScanPreviousTrack, Key_F6, Key_F7, Key_F8, Key_F9, Key_F10, Key_F11, + Consumer_PlaySlashPause, Consumer_ScanNextTrack, Key_LeftCurlyBracket, Key_RightCurlyBracket, Key_LeftBracket, Key_RightBracket, Key_F12, + Key_LeftArrow, Key_DownArrow, Key_UpArrow, Key_RightArrow, ___, ___, + Key_PcApplication, Consumer_Mute, Consumer_VolumeDecrement, Consumer_VolumeIncrement, ___, Key_Backslash, Key_Pipe, + ___, ___, Key_Enter, ___, + ___) +) // KEYMAPS( + +/* Re-enable astyle's indent enforcement */ +// *INDENT-ON* + +/** 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 ")); + Macros.type(PSTR(BUILD_INFORMATION)); + } +} + +/** 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; + bool toggledOn = false; + if (keyToggledOn(keyState)) { + lastKey.setKeyCode(Key_A.getKeyCode() + (uint8_t)(millis() % 36)); + toggledOn = true; + } + + if (keyIsPressed(keyState)) + Kaleidoscope.hid().keyboard().pressKey(lastKey, toggledOn); +} + + +/** 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) { + + case MACRO_VERSION_INFO: + versionInfoMacro(keyState); + break; + + case MACRO_ANY: + anyKeyMacro(keyState); + break; + } + return MACRO_NONE; +} + + + +// These 'solid' color effect definitions define a rainbow of +// LED color modes calibrated to draw 500mA or less on the +// Keyboardio Model 01. + +static constexpr uint8_t solid_red_level = 160; +static kaleidoscope::plugin::LEDSolidColor solidRed(solid_red_level, 0, 0); +static kaleidoscope::plugin::LEDSolidColor solidOrange(140, 70, 0); +static kaleidoscope::plugin::LEDSolidColor solidYellow(130, 100, 0); +static kaleidoscope::plugin::LEDSolidColor solidGreen(0, 160, 0); +static kaleidoscope::plugin::LEDSolidColor solidBlue(0, 70, 130); +static kaleidoscope::plugin::LEDSolidColor solidIndigo(0, 0, 170); +static kaleidoscope::plugin::LEDSolidColor solidViolet(130, 0, 120); + +/** toggleLedsOnSuspendResume toggles the LEDs off when the host goes to sleep, + * and turns them back on when it wakes up. + */ +void toggleLedsOnSuspendResume(kaleidoscope::plugin::HostPowerManagement::Event event) { + switch (event) { + case kaleidoscope::plugin::HostPowerManagement::Suspend: + LEDControl.disable(); + break; + case kaleidoscope::plugin::HostPowerManagement::Resume: + LEDControl.enable(); + break; + case kaleidoscope::plugin::HostPowerManagement::Sleep: + break; + } +} + +/** hostPowerManagementEventHandler dispatches power management events (suspend, + * resume, and sleep) to other functions that perform action based on these + * events. + */ +void hostPowerManagementEventHandler(kaleidoscope::plugin::HostPowerManagement::Event event) { + toggleLedsOnSuspendResume(event); +} + +/** A tiny wrapper, to be used by MagicCombo. + * This simply toggles the keyboard protocol via USBQuirks, and wraps it within + * a function with an unused argument, to match what MagicCombo expects. + */ +static void toggleKeyboardProtocol(uint8_t combo_index) { + USBQuirks.toggleKeyboardProtocol(); +} + +/** Magic combo list, a list of key combo and action pairs the firmware should + * recognise. + */ +USE_MAGIC_COMBOS({.action = toggleKeyboardProtocol, + // Left Fn + Esc + Shift + .keys = { R3C6, R2C6, R3C7 } + }); + +// First, 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_INIT_PLUGINS( + // The EEPROMSettings & EEPROMKeymap plugins make it possible to have an + // editable keymap in EEPROM. + EEPROMSettings, + EEPROMKeymap, + + // Focus allows bi-directional communication with the host, and is the + // interface through which the keymap in EEPROM can be edited. + Focus, + + // FocusSettingsCommand adds a few Focus commands, intended to aid in + // changing some settings of the keyboard, such as the default layer (via the + // `settings.defaultLayer` command) + FocusSettingsCommand, + + // FocusEEPROMCommand adds a set of Focus commands, which are very helpful in + // both debugging, and in backing up one's EEPROM contents. + FocusEEPROMCommand, + + // The boot greeting effect pulses the LED button for 10 seconds after the + // keyboard is first connected + BootGreetingEffect, + + // The hardware test mode, which can be invoked by tapping Prog, LED and the + // left Fn button at the same time. + HardwareTestMode, + + // 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 Colormap effect makes it possible to set up per-layer colormaps + ColormapEffect, + + // The numpad plugin is responsible for lighting up the 'numpad' mode + // with a custom LED effect + NumPad, + + // The macros plugin adds support for macros + Macros, + + // The MouseKeys plugin lets you add keys to your keymap which move the mouse. + MouseKeys, + + // The HostPowerManagement plugin allows us to turn LEDs off when then host + // goes to sleep, and resume them when it wakes up. + HostPowerManagement, + + // The MagicCombo plugin lets you use key combinations to trigger custom + // actions - a bit like Macros, but triggered by pressing multiple keys at the + // same time. + MagicCombo, + + // The USBQuirks plugin lets you do some things with USB that we aren't + // comfortable - or able - to do automatically, but can be useful + // nevertheless. Such as toggling the key report protocol between Boot (used + // by BIOSes) and Report (NKRO). + USBQuirks +); + +/** The 'setup' function is one of the two standard Arduino sketch functions. + * It's called when your keyboard first powers up. This is where you set up + * Kaleidoscope and any plugins. + */ +void setup() { + // First, call Kaleidoscope's internal setup function + Kaleidoscope.setup(); + + // While we hope to improve this in the future, the NumPad plugin + // needs to be explicitly told which keymap layer is your numpad layer + NumPad.numPadLayer = NUMPAD; + + // We configure the AlphaSquare effect to use RED letters + AlphaSquare.color = CRGB(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/blob/master/doc/plugin/LED-Stalker.md + 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(); + + // To make the keymap editable without flashing new firmware, we store + // additional layers in EEPROM. For now, we reserve space for five layers. If + // one wants to use these layers, just set the default layer to one in EEPROM, + // by using the `settings.defaultLayer` Focus command, or by using the + // `keymap.onlyCustom` command to use EEPROM layers only. + EEPROMKeymap.setup(5); + + // We need to tell the Colormap plugin how many layers we want to have custom + // maps for. To make things simple, we set it to five layers, which is how + // many editable layers we have (see above). + ColormapEffect.max_layers(5); +} + +/** 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(); +} diff --git a/tests/examples/basic-generated/test.ktest b/tests/examples/basic-generated/test.ktest new file mode 100644 index 00000000..e2968c8f --- /dev/null +++ b/tests/examples/basic-generated/test.ktest @@ -0,0 +1,28 @@ +VERSION 1 +TYPE KeyboardReports +NAME Keys Active When pressed + +# Comment lines end up as comments in the generated source +KEYSWITCH switchA 2 1 +KEYSWITCH switchS 2 2 + +PRESS switchA +RUN 1 cycles +EXPECT keyboard-report Key_A # Key A should be pressed + +RELEASE switchA +RUN 1 cycle +EXPECT keyboard-report empty # No keys should be pressed + + +PRESS switchA +PRESS switchS +RUN 1 ms +EXPECT keyboard-report Key_A # TODO modflag rollover prevention inapropriately sends two reports here. It's not harmful, but is annoying +EXPECT keyboard-report Key_A, Key_S # A and S should be pressed + +RELEASE switchA +RELEASE switchS +RUN 1 cycle +EXPECT keyboard-report empty # No keys should be pressed +