diff --git a/src/kaleidoscope/Hardware.h b/src/kaleidoscope/Hardware.h new file mode 100644 index 00000000..805730aa --- /dev/null +++ b/src/kaleidoscope/Hardware.h @@ -0,0 +1,268 @@ +/* -*- mode: c++ -*- + * Kaleidoscope-Hardware -- Kaleidoscope Hardware Base class + * Copyright (C) 2017, 2018 Keyboard.io, Inc + * + * This program is free software: you can redistribute it and/or modify it under + * the terms of the GNU General Public License as published by the Free Software + * Foundation, version 3. + * + * This program is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS + * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more + * details. + * + * You should have received a copy of the GNU General Public License along with + * this program. If not, see . + */ + +/** @file kaleidoscope/Hardware.h + * Base class for Kaleidoscope hardware libraries. + */ + +#pragma once + +#ifndef CRGB +#error cRGB and CRGB *must* be defined before including this header! +#endif + +/* All hardware libraries must define the following macros: + * HARDWARE_IMPLEMENTATION - the name of your public object conforming to + * the 'class Hardware' interface below. + * CRGB(r,g,b) - explained below + */ + +/** + * Forward declaration of the cRGB structure. + * + * The base class does not define the cRGB structure, that is left up to the + * individual Hardware libraries. We do a forward declaration here, because the + * base hardware has methods that depend on a cRGB structure. + * + * The structure will need to have at least three members: r, g, and b - + * compilation will fail otherwise. + * + * Despite its name, the members do not need to be in the order r g b -- most + * likely they will be in an order that is convenient for the hardware. So + * initializing a cRGB with a struct literal will give surprising results for any + * colors where r, g, and b do not have the same value. Each Hardware library + * defines a CRGB(r,g,b) macro which returns a literal cRGB with the given values. + */ +typedef struct cRGB cRGB; + +namespace kaleidoscope { +/** Kaleidoscope Hardware base class. + * Essential methods all hardware libraries must implement. + */ +class Hardware { + public: + /** + * @defgroup kaleidoscope_hardware_leds Kaleidoscope::Hardware/LEDs + * @{ + */ + /** + * Sync the LEDs with the underlying hardware. This should make sure that + * changes made before this call are reflected on the device. + */ + void syncLeds(void) {} + /** + * Set the color of a per-key LED at a given row and column. + * + * Setting the color does not need to take effect immediately, it can be + * delayed until @ref syncLeds is called. + * + * @param row is the logical row position of the key. + * @param col is the logical column position of the key. + * @param color is the color to set the LED to. + */ + void setCrgbAt(byte row, byte col, cRGB color) {} + /** + * Set the color of a per-key LED at a given LED index. + * + * Setting the color does not need to take effect immediately, it can be + * delayed until @ref syncLeds is called. + * + * @param i is the LED index to change the color of. + * @param color is the color to set it to. + */ + void setCrgbAt(uint8_t i, cRGB color) {} + /** + * Returns the color of the LED at a given index. + * + * @param i is the index of the LED to return the color of. + * + * @returns The color at the given position. + */ + cRGB getCrgbAt(uint8_t i) { + cRGB c = { + 0, 0, 0 + }; + return c; + } + /** + * Returns the index of the LED at a given row & column. + * + * @param row is the logical row position of the key. + * @param col is the logical column position of the key. + * + * @returns The index of the LED at the given position, or -1 if there are no + * LEDs there. + */ + int8_t getLedIndex(uint8_t row, byte col) { + return -1; + } + /** @} */ + + /** @defgroup kaleidoscope_hardware_matrix Kaleidoscope::Hardware/Matrix + * @{ + */ + /** + * Scan the keyboard matrix, and act on it. + */ + void scanMatrix(void) {} + /** + * Read the state of the keyboard matrix. + * + * Do whatever is necessary to read the current keyboard state - but without + * acting on it. + * + * This is primarily used by @ref scanMatrix, but may have other uses too. + */ + void readMatrix(void) {} + /** + * Act on the scanned keyboard matrix. + * + * Iterate through the scanned state (@see readMatrix), and act on any events. + */ + void actOnMatrixScan(void) {} + /** @} */ + + /** @defgroup kaleidoscope_hardware_masking Kaleidoscope::Hardware/Key masking + * + * Sometimes there are situations when one wants to ignore key events for a + * while, to mask them out. Masked keys will be ignored until they are + * released. + * + * This is implemented in the Hardware library because that knows best how + * to mask efficiently, as this requires a deeper knowledge of the hardware, + * which is all but hidden from the rest of the plugins. + * @{ + */ + /** + * Mask out a key. + * + * Masking a key out means that any other event than a release will be + * ignored until said release. + * + * @param row is the row the key is located at in the matrix. + * @param col is the column the key is located at in the matrix. + */ + void maskKey(byte row, byte col) {} + /** + * Unmask a key. + * + * Remove the mask - if any - for a given key. To be used when the mask + * needs to be removed without the key being released. + * + * @param row is the row the key is located at in the matrix. + * @param col is the column the key is located at in the matrix. + */ + void unMaskKey(byte row, byte col) {} + /** + * Check whether a key is masked or not. + * + * @param row is the row the key is located at in the matrix. + * @param col is the column the key is located at in the matrix. + * + * @returns true if the key is masked, false otherwise. + */ + bool isKeyMasked(byte row, byte col) { + return false; + } + /** @} */ + + /** @defgroup kaleidoscope_hardware_reattach Kaleidoscope::Hardware/Attach & Detach + * + * In situations where one wants to re-initialize the devices, perhaps to + * change settings inbetween, detaching from and then attaching back to the + * host is a desirable feature to have. Especially if this does not cut power, + * nor reboot the device. + * + * Because different hardware has different ways to accomplish this, the + * hardware plugin must provide these functions. Kaleidoscope will wrap them, + * so user code does not have to deal with KeyboardHardware. + * @{ + */ + /** + * Detach the device from the host. + * + * Must detach the device, without rebooting or cutting power. Only the end + * points should get detached, the device must remain powered on. + */ + void detachFromHost() {} + /** + * Attack the device to the host. + * + * Must restore the link detachFromHost severed. + */ + void attachToHost() {} + + /** @} */ + + /** + * @defgroup kaleidoscope_hardware_keyswitch_state Kaleidoscope::Hardware/Key-switch state + * + * These methods offer a way to peek at the key switch states, for those cases + * where we need to deal with the state closest to the hardware. Some methods + * offer a way to check if a key is pressed, others return the number of + * pressed keys. + * + * @{ + */ + /** + * Check if a key is pressed at a given position. + * + * @param row is the row the key is located at in the matrix. + * @param col is the column the key is located at in the matrix. + * + * @returns true if the key is pressed, false otherwise. + */ + bool isKeyswitchPressed(byte row, byte col) { + return false; + } + /** + * Check if a key is pressed at a given position. + * + * @param keyIndex is the key index, as calculated by `keyIndex`. + * + * @note Key indexes start at 1, not 0! + * + * @returns true if the key is pressed, false otherwise. + */ + bool isKeyswitchPressed(uint8_t keyIndex) { + return false; + } + /** + * Check the number of key switches currently pressed. + * + * @returns the number of keys pressed. + */ + uint8_t pressedKeyswitchCount() { + return 0; + } + + /** @} */ + + /** + * @defgroup kaleidoscope_hardware_misc Kaleidoscope::Hardware/Miscellaneous methods + * @{ + */ + /** + * Method to do any hardware-specific initialization. + * + * Called once when the device boots, this should initialize the device, and + * bring it up into a useful state. + */ + void setup() {} + /** @} */ +}; +} diff --git a/src/kaleidoscope/hardware/ATMegaKeyboard.h b/src/kaleidoscope/hardware/ATMegaKeyboard.h index ca73a12f..f44fafe7 100644 --- a/src/kaleidoscope/hardware/ATMegaKeyboard.h +++ b/src/kaleidoscope/hardware/ATMegaKeyboard.h @@ -39,6 +39,8 @@ struct cRGB { #endif +#include "kaleidoscope/Hardware.h" + #define ROW_PIN_LIST(...) __VA_ARGS__ #define COL_PIN_LIST(...) __VA_ARGS__ @@ -69,23 +71,13 @@ struct cRGB { namespace kaleidoscope { namespace hardware { -class ATMegaKeyboard { +class ATMegaKeyboard : public kaleidoscope::Hardware { public: ATMegaKeyboard(void) {} // these will be overridden by the subclass static uint8_t debounce; - void syncLeds(void) {} - void setCrgbAt(uint8_t row, byte col, cRGB color) {} - void setCrgbAt(int8_t i, cRGB crgb) {} - cRGB getCrgbAt(int8_t i) { - return CRGB(0, 0, 0); - } - int8_t getLedIndex(uint8_t row, byte col) { - return -1; - } - void setup(void); /** Detaching from / attaching to the host. diff --git a/src/kaleidoscope/hardware/ez/ErgoDox.h b/src/kaleidoscope/hardware/ez/ErgoDox.h index c7672ca7..000d537d 100644 --- a/src/kaleidoscope/hardware/ez/ErgoDox.h +++ b/src/kaleidoscope/hardware/ez/ErgoDox.h @@ -42,11 +42,13 @@ struct cRGB { #define CRGB(r,g,b) (cRGB){b, g, r} +#include "kaleidoscope/Hardware.h" + namespace kaleidoscope { namespace hardware { namespace ez { -class ErgoDox { +class ErgoDox : public kaleidoscope::Hardware { public: ErgoDox(void) {} @@ -54,16 +56,6 @@ class ErgoDox { static constexpr byte matrix_rows = 14; static constexpr int8_t led_count = 0; - void syncLeds(void) {} - void setCrgbAt(byte row, byte col, cRGB color) {} - void setCrgbAt(int8_t i, cRGB crgb) {} - cRGB getCrgbAt(int8_t i) { - return CRGB(0, 0, 0); - } - int8_t getLedIndex(byte row, byte col) { - return -1; - } - void scanMatrix(void); void readMatrix(void); void actOnMatrixScan(void); diff --git a/src/kaleidoscope/hardware/keyboardio/Model01.h b/src/kaleidoscope/hardware/keyboardio/Model01.h index c0fc0a6e..33dde527 100644 --- a/src/kaleidoscope/hardware/keyboardio/Model01.h +++ b/src/kaleidoscope/hardware/keyboardio/Model01.h @@ -29,11 +29,13 @@ #define CRGB(r,g,b) (cRGB){b, g, r} +#include "kaleidoscope/Hardware.h" + namespace kaleidoscope { namespace hardware { namespace keyboardio { -class Model01 { +class Model01 : public kaleidoscope::Hardware { public: Model01(void);