/* (C) 2005 by Richard West (rw88@cornell.edu)
 * Published: 25 Feb 2005
 * Updated:   12 Jan 2006
 * Published under GNU General Public License - http://www.linux.org/info/gnu.html
 *
 * Keypad Header File
 *
 * Hardware setup notes:
 *      Keypad connected to Portx.0-7 (see note 2)
 *      LCD connected to Portx.0-7 (see note 3)
 *
 * Important notes:
 *      1) In order for the keypad library to compile, one of the following
 *      compiler directives must be invoked before including the keypad.h
 *      library: "#define KEYPAD_TELPAD", "#define KEYPAD_HEXPAD", or
 *      "#define KEYPAD_KEYBOARD".  If none of these directives are used, a user
 *      specified keysymbol_table and keycode_table must be provided prior to
 *      including keypad.h.  An appropriate KEY_TABLE_LENGTH must be defined (ex.
 *      "#define KEY_TABLE_LENGTH 16").
 *
 *      2) A port must be specified for the keypad.  Before including keypad.h,
 *      invoke the compiler directive "#define KEYPAD_USEPORTx" where x={A,B,C,D}
 *      depending which port you wish to use.  Failure to do so will cause the keypad
 *      scanning to fail.  Note: this won't generate a compile-time error.
 *
 *      3) In order to use any of the keypad display functions, invoke the compiler
 *      directive "#define KEYPAD_USEDISPLAY" prior to "#include keypad.h".  If this
 *      compiler directive is absent, none of the keypad display functions will be
 *      compiled.  This is a memory-saving option.  A port must be specified for the
 *      LCD.  Before including keypad.h, invoke the compiler directive "#define DISPLAY_USEPORTx"
 *      where x={A,B,C,D} depending which port you wish to use.  The port must be
 *      different from the keypad port.  Note: this won't generate a compile-time error.
 */

#ifndef _KEYPAD_H_
#define _KEYPAD_H_
// Mega32 compiler directive
#include <Mega32.h>

#ifdef KEYPAD_USEDISPLAY
// keypad display states
#define KEYPAD_NODISPLAY 0x00
#define KEYPAD_MASKDISPLAY 0x01
#define KEYPAD_ECHODISPLAY 0x02
#endif

// "public" keypad runtime global variables
unsigned char keystring_ready;
unsigned char keystring[17];

// "public" function prototypes
void keypad_map_keysymbol(unsigned char old_keysymbol, unsigned char new_keysymbol);
/* function: replaces old_keysymbol in keysymbol_table with new_keysymbol
 * use for: modifying entries in the keysymbol_table for specific keypad buttons
 */

void keypad_define_terminator(unsigned char keysymbol);
/* function: modifies an entry in the keysymbol_table to be the terminator ('\0')
 * use for: defining a terminator
 * note: a terminator must be defined for keypad_get_string() to work.  A terminator
 * is defined for KEYPAD_KEYBOARD, so defining additional terminators is optional.
 */

void keypad_ignore_keysymbol(unsigned char keysymbol);
/* function: modifies an entry in the keysymbol_table to be ignored (0xFF)
 * use for: defining keypad buttons/keycodes to be ignored
 * note: useful for defining "shift" of "function" buttons
 */

// only compile if using display
#ifdef KEYPAD_USEDISPLAY
void keypad_set_display(unsigned char display);
/* function: sets display mode for the keypad (none, mask ('*'), or echo)
 * use for: specifying type of display to use for keypad entry
 * note: maybe used multiple times to switch between display modes
 */

void keypad_gotoxy(unsigned char x, unsigned char y);
/* function: sets keypad cursor
 * use for: specifies starting location for keypad entry display
 * note: keypad automatically increments the cursor with each displayed character
 * so use only prior to releasing the keypad
 */
#endif

void keypad_get_string(void);
/* function: scans and debounces the keypad
 * use for: reading string from keypad as part of a timer isr
 * note: runs as a state machine; completion indicated by keystring_ready == 0x01;
 * keystring contains the user's input
 */

void keypad_release(void);
/* function: resets keypad state machine
 * use for: resetting the keypad once the keystring has been interpreted by
 * calling program
 * note: the state machine will only work once if not reset
 */

#include "keypad.c"
#endif