key.h

Go to the documentation of this file.

#ifndef DRIVER_KEY_H
#define DRIVER_KEY_H
/**********************************************************************/
/*
 * Copyright (c) 2015, Jetro AS
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONRIBUTORS ``AS IS'' AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
 * OF SUCH DAMAGE.
 *
 * This file is part of the EVE platform.
 */

/**
 * \file
 * @brief Interface for Key driver in key.c.
 *
 * @author AMO, Jetro AS
 */ /******************************************************************/

#include <core/mwork.h>
#include <sys/process.h>
#include <sys/event-base.h>
#include <lib/assert.h>

/**
 * \defgroup key Keypad driver
 * \ingroup abstract
 * \{
 *
 * This driver supports key debounce functionality if KEY_ENABLED is set true.
 * The function KeyInterruptEnable() must be called to enables interrupts for all keys.
 *
 * The number of scanned keys is given by NUMBER_OF_KEYS.
 * Key debounce time is given by KEY_PRELL_TIME.
 * When debouncing the interval is given by SCAN_KEY_INTERVAL.
 * The keys are read by the inline function ReadKeyInput().
 *
 * The following events are sent:
 * - The event KEY_PRESSED with keynumber (indexed from 0)
 *   is sent when a key is detected pressed
 * - The event KEY_RELEASED with keynumber (indexed from 0)
 *   is sent when a key is detected released and a combi event has not been sent
 *   which involves this key.
 * - The event COMBI_KEY_RELEASED with keynumber (indexed from 0)
 *   is sent when a key is detected released and a combi event has been sent
 *   which involves this key, and COMBI_KEY_RELEASE_ENABLED = TRUE.
 *
 * It is possible to send a repeated event when a key has been pressed
 * for a given time. The event can be repeated at a given interval.
 * This functionality is enabled if REPEAT_KEY_ENABLED is set true:
 *   The number of repeated keys is given by NUMBER_OF_REPEAT_KEYS.
 *   Repeat function is configured in table "struct key_repeat_t ConfigKeyRepeat[]" in Board.c
 *   The following events are sent:
 *   - After key has been pressed in "Step1Time" time,
 *     the event KEY_REPEAT1 with keynumber (indexed from 0) is sent each "RepeatTime" time
 *   - The following function is enabled if REPEAT_KEY_STEP2_ENABLED is set true:
 *   - After key has been pressed in "Step2Time" time,
 *     the event KEY_REPEAT2 with keynumber (indexed from 0) is sent each "RepeatTime" time
 *
 * It is possible to send a event when a combination of one or more keys
 * have been pressed for a given time.
 * This functionality is enabled if COMBI_KEYS_ENABLED is set true:
 *   The number of combi keys groups is given by NUMBER_OF_COMBI_GROUPS.
 *   Combi function is configured in table "struct key_combi_t ConfigKeyCombi[]" in Board.c
 *   The following events are sent:
 *   - After given time the event COMBI_KEY_PRESSED with combi key group number (indexed from 0) is sent
 *
 * All events are sent to process defined by KEY_SIGNAL_RECEIVER
 ***********************************************************************/

/***********************************************************************
 * Global definitions
***********************************************************************/

/** @brief The structure defines key repeat parameters. */
struct key_repeat_t
{
  uint8_t  KeyIndex;            //!< Index 0-31 for actual repeat key
  uint16_t RepeatTime;          //!< Number of repeat scans (wanted repeat time in ms / SCAN_KEY_INTERVAL)
  uint16_t Step1Time;           //!< Number of step1 scans (wanted step1 time in ms / SCAN_KEY_INTERVAL), must be > RepeatTime
  uint16_t Step2Time;           //!< Number of step2 scans (wanted step2 time in ms / SCAN_KEY_INTERVAL), must be > Step1Time
};

/** @brief The structure defines combi key parameters.
 *  Note that it is possible to define individual debounce time for each group.
 *  Thus it is also the way to define an individual key with debouncing which
 *  differs from default KEY_PRELL_TIME : just define a "group of 1 key.
 */
struct key_combi_t
{
  uint32_t Keys;                //!< Bit positions = key number
  uint16_t Time;                //!< Number of debounce scans (wanted debounce time in ms / SCAN_KEY_INTERVAL)
};

/** @brief Event numbers being sent to the application process.
 *  Event's void *data field contains key number.
 */
enum key_events_t
{
  KEY_PRESSED = EVENT_BASE_KEY_START, //!< Key was pressed
  KEY_RELEASED,                       //!< Key was released
  KEY_REPEAT1,                        //!< Key press repeat after Step1Time
  KEY_REPEAT2,                        //!< Key press repeat after Step2Time
  COMBI_KEY_PRESSED,                  //!< Key combination was pressed
  COMBI_KEY_RELEASED,                 //!< Key combination was released
  EVENT_KEY__LAST                     //!< Gives the size of allocated event numbers
};
CTASSERT(EVENT_KEY__LAST <= EVENT_BASE_KEY_END + 1);


/**
  * \name Functions called from application programs
  * \{
  */

/**********************************************************************/
/**
 * @brief Start Keys scanning.
 *
 * Only used if KEYS_HAVE_NO_INTERRUPT = true
 ***********************************************************************/
extern void StartKeyScan(void);

/**********************************************************************/
/**
 * @brief This callback function must be called when a key interrupt is received
 * by the platform.
 *
 * Only used if KEYS_HAVE_NO_INTERRUPT == false
 ***********************************************************************/
extern void KeyInterruptCb(void);

/**********************************************************************/
/**
 * @brief Sets key debounce time. Default time is KEY_PRELL_TIME.
 *
 * @param Time      New debounce time in ms
 ***********************************************************************/
extern void KeyDebounceTimeSet(uint16_t Time);

/**********************************************************************/
/**
 * @brief Returns status of debounced key.
 *
 * @param KeyIndex  key number from 0 to (NUMBER_OF_KEYS - 1)
 * @return          true if key pressed, else false
 ***********************************************************************/
bool KeyStatusGet(uint8_t KeyIndex);

/** \} */

/** \name Application' keypad configuration and supplied functions.
 *  \{
 *  The following is the keypad driver setup for application's board.h and
 *  board.c files.
 */

#ifdef KEY_DRIVER_DOXYGEN

#define KEY_ENABLED                     true/false //! Turn platform Keyboard support ON/OFF
#define KEYS_HAVE_NO_INTERRUPT          true/false //! If true, driver uses polling instead of IRQ
#define REPEAT_KEY_ENABLED              true/false //! Set to true to enable key repeat feature
#define REPEAT_KEY_STEP2_ENABLED        true/false //! Set to true to enable repeat step 2 (2nd timing between key presses)
#define COMBI_KEYS_ENABLED              true/false //! Set to true to enable combi keys (key groups)
#define COMBI_KEY_RELEASE_ENABLED       true/false //! Set to true to get events on combi keys release

#define NUMBER_OF_KEYS                  <N>         //! Total number of individual keys in the system (1-32)
#define NUMBER_OF_REPEAT_KEYS           <N>         //! Number of keys with repeating function (length of \ref ConfigKeyRepeat array)
#define NUMBER_OF_COMBI_GROUPS          <N>         //! Number of key groups with combi function (length of \ref ConfigKeyCombi array)

#define KEY_SIGNAL_RECEIVER             <struct process *p> //! Pointer to a Contiki process - key related events receiver
#define SCAN_KEY_INTERVAL               <T>                 //! Key polling interval in ms (for polling mode KEYS_HAVE_NO_INTERRUPT == true and for debouncing in all modes)
#define KEY_PRELL_TIME                  <T>                 //! Default key debouncing time in ms


/** @brief User defined array of \ref key_repeat_t structures defines key repeat parameters. */
struct key_repeat_t ConfigKeyRepeat[NUMBER_OF_REPEAT_KEYS];

/** @brief User defined array of \ref key_combi_t structures defines combi key groups parameters. */
struct key_combi_t ConfigKeyCombi[NUMBER_OF_COMBI_GROUPS];

#endif // KEY_DRIVER_DOXYGEN


/**********************************************************************/
/**
 * @brief Application supplied board-specific callback function for reading
 * key inputs.
 *
 * The driver calls this function in order to get current keys
 * status. It is an application responsibility to map actual internal GPIO or
 * GPIO extender port pins to an int32_t array of bits used as key status in
 * the driver.
 *
 * Example for 2 inverted keys (pressing connects to ground) supporting
 * press/release event generation:
 * \code
 * #define KEY0 0
 * #define KEY1 1
 * uint32_t LastReadKeyInput;
 * static __inline uint32_t ReadKeyInput(void)
 * {
 *   uint32_t KeyInput, KeyData;
 *   LastReadKeyInput = KeyInput = ~GpioPortGet(); // Pins are inverted!
 *   KeyData  = ((KeyInput >> KEY0_PIN_NUMBERn) & 1) << KEY0;
 *   KeyData |= ((KeyInput >> KEY1_PIN_NUMBERn) & 1) << KEY1;
 *   return KeyData;
 * }
 * \endcode
 *
 * @return          Keys bitmask. Each bit represents a key and settled if the
 *                  key is currently pressed, cleared if released.
 ***********************************************************************/
static __inline uint32_t ReadKeyInput(void);

/**********************************************************************/
/**
 * @brief Application supplied board-specific callback function to enable or
 * disable HW interrupts for all keys.
 *
 * This function must be called by application to enable interrupts in interrupt
 * mode (KEYS_HAVE_NO_INTERRUPT == false) before the driver starts to work.
 *
 * While working the driver uses the function. When a key is pressed/released,
 * the key interrupt will disable further key interrupts, and starts the key
 * debounce scheduler. The interrupts will be re-enabled again when the
 * scheduler is not active.
 *
 * Only used if KEYS_HAVE_NO_INTERRUPT = false.
 *
 * Example for 2 inverted keys (pressing connects to ground) supporting
 * press/release event generation:
 * \code
 * uint32_t LastReadKeyInput;
 * void KeyInterruptEnable(bool Enable)
 * {
 *   enum irq_mode_t NewMode;
 *   NewMode = (LastReadKeyInput & (1 << KEY0_PIN_NUMBERn)) ? IRQ_MODE_RISING : IRQ_MODE_FALLING;
 *   IrqEnableInternal(KEY0_PIN_NUMBERn, Enable ? NewMode : IRQ_MODE_DISABLED);
 *   NewMode = (LastReadKeyInput & (1 << KEY1_PIN_NUMBERn)) ? IRQ_MODE_RISING : IRQ_MODE_FALLING;
 *   IrqEnableInternal(KEY1_PIN_NUMBERn, Enable ? NewMode : IRQ_MODE_DISABLED);
 * }
 * \endcode
 *
 * @param Enable    true to enable interrupts, false to disable interrupts
 ***********************************************************************/
void KeyInterruptEnable(bool Enable);

/** \} */

/** \} key */

#endif //DRIVER_KEY_H