Input devices

Detailed Description

The routines gain access to the input devices of eWicht as simple bit values.

For a correct reading of the input values an internal state machine handles debouncing and counting.

Todo:: Place a graphic here for showing the buttons.

Files

file input.c

Button routines for input status of eWicht.

file input.h

Input module defines and global function prototypes for eWicht.

Defines

#define BTN_COUNT   0x09

The count of buttons.

#define ENC_ENDSTOP_MASK   0x01

Flag for configuring the state machine (SM) of the rotary encoder button.

#define ENC_TURBO_MASK   0x02

Flag for configuring the state machine (SM) of the rotary encoder button.

#define ENC_NOCHANGE_MASK   0x04

Flag for configuring the state machine (SM) of the rotary encoder button.

#define BTN_LONG_PUSH_TIME   (100u)

This value is used to measure the first push time (unit is the cycle call time of the InputMain routine) of a button after a reset of the appropriate state machine and the first push.

#define BTN_DOUBLE_PUSH_TIME   (60u)

A button state machine waits between to single pushes until this time is elapsed (unit is the cycle call time of the InputMain routine).

Enumerations

enum eButtonID {
  PWR_BTN = 0, SEL_BTN, ACC_BTN, FL_BTN,
  F1_BTN, F2_BTN, F3_BTN, F4_BTN,
  ENC_BTN, ALL_BTN
}

IDs for accessing the buttons. More...

Functions

void InputInit (void)

Initializes the input module.

void InputMain (void)

The input state machines are feeded, handled and checked.

void InputButtonReset (eButtonID eBtn)

The state machine of the given button will be reseted or all if ALL_BTN is the parameter.

void InputResetPowerButton (void)

The power button state machine is something special and can be reset by this function.

void InputResetButtonPush (eButtonID eBtn)

This function can be used to reset single push events in the state machine.

BOOL bInputButtonPushedOnce (eButtonID eBtn)

The application can ask the input module for a given button if there was a single push since the last call of InputButtonReset.

BOOL bInputButtonPushedTwice (eButtonID eBtn)

The application can ask the input module for a given button if there was a double push since the last call of InputButtonReset or InputInit.

BOOL bInputButtonPushedLong (eButtonID eBtn)

The application can ask the input module for a given button if there was a long push since the last call of InputButtonReset or InputInit.

BOOL bInputButtonPushed (eButtonID eBtn)

This function combines the functions bInputButtonPushedLong, bInputButtonPushedOnce and bInputButtonPushedTwice.

SHORT s16InputEncoderGetValue (void)

This function returns the actual value of rotary encoder state machine.

void InputEncoderInit (SHORT s16Val, SHORT s16Min, SHORT s16Max, BYTE u8Flags)

This function initializes the rotary encoder.

BOOL bInputEncoderValueChanged (void)

This function returns TRUE if the value of rotary encoder state machine has changed after the last call of s16InputEncoderGetValue.

void InputEncoderSetValue (short s16NewVal, BOOL bRemember)

The function sets the internal encoder value to the given value.

void InputForceChangedEncoderValue (void)

After calling this function the function bInputEncoderValueChanged delivers a TRUE when calling after this function call.

BOOL InputEncoderGetDirection (void)

This function delivers the current or last rotary direction of the encoder button.

BYTE u8InputButtonQuickPushed (void)

The function delivers the ID of any pushed quick button (F1-F4).

BOOL bInputButtonPressed (eButtonID eBtn)

The function checks whether the requested button is currently pressed or released.

BOOL IsEncoderTurning (void)

The function checks whether the input encoder is turning.

void InputInterruptHandler (void)

This function handles the periodic requested interrupts.

Define Documentation

#define BTN_DOUBLE_PUSH_TIME (60u)

A button state machine waits between to single pushes until this time is elapsed (unit is the cycle call time of the InputMain routine).

If the time is shorter the SM sets a flag for a double push requestable by bInputButtonPushedTwice.

Definition at line 78 of file input.h.

#define BTN_LONG_PUSH_TIME (100u)

This value is used to measure the first push time (unit is the cycle call time of the InputMain routine) of a button after a reset of the appropriate state machine and the first push.

If this time has elapsed, a flag for a long push is set and can requested by bInputButtonPushedLong.

Definition at line 71 of file input.h.

#define ENC_ENDSTOP_MASK 0x01

Flag for configuring the state machine (SM) of the rotary encoder button.

In case the SM detects an over- or underflow it stops the decrement or increment if the ENDSTOP flag is set. If the flag is not set, the encoder value rolls over from maximum to minimum (in case of overflow) or from minimum to maximum (in case of underflow).

Definition at line 52 of file input.h.

#define ENC_NOCHANGE_MASK 0x04

Flag for configuring the state machine (SM) of the rotary encoder button.

In case the flag is set a bInputEncoderValueChanged() call returns FALSE afterwards.

Definition at line 64 of file input.h.

#define ENC_TURBO_MASK 0x02

Flag for configuring the state machine (SM) of the rotary encoder button.

When given then the turbo encoder is enabled. That flag should be used when the encoder is configured for a great value space.

Definition at line 58 of file input.h.

Enumeration Type Documentation

enum eButtonID

IDs for accessing the buttons.

Enumerator:

PWR_BTN	ID for the Power button.
SEL_BTN	ID for the Select button.
ACC_BTN	ID for the Accessory button.
FL_BTN	ID for the FL button.
F1_BTN	ID for the F1 button (Quick ID 0).
F2_BTN	ID for the F2 button (Quick ID 1).
F3_BTN	ID for the F3 button (Quick ID 2).
F4_BTN	ID for the F4 button (Quick ID 3).
ENC_BTN	ID for the rotary encoder button.
ALL_BTN	Special ID to access all buttons.

Definition at line 88 of file input.h.

Function Documentation

BOOL bInputButtonPressed ( eButtonID eBtn )

The function checks whether the requested button is currently pressed or released.

The request is done independently of the button state machine due the direct button value access.

Precondition:: The input devices must be initialized by a InputInit call.

Return values:

	TRUE	The requested button is currently pressed.
	FALSE	The requested button is currently released.

Definition at line 401 of file input.c.

BOOL bInputButtonPushed ( eButtonID eBtn )

This function combines the functions bInputButtonPushedLong, bInputButtonPushedOnce and bInputButtonPushedTwice.

The caller can test for a push button event if the detailed source is not important.

Precondition:: The input devices must be initialized by a InputInit call or the asked button state machine must reseted with InputButtonReset at least once.

Parameters:

eBtn

The button state machine which should be checked for any push. The value ALL_BTN checks if any of the buttons was pushed.

Return values:

	TRUE	There was a push since the last InputButtonReset.
	FALSE	There was no push since the last InputButtonReset.

Remarks:: None

Definition at line 414 of file input.c.

BOOL bInputButtonPushedLong ( eButtonID eBtn )

The application can ask the input module for a given button if there was a long push since the last call of InputButtonReset or InputInit.

A long push is detected if a button was pushed at least BTN_LONG_PUSH_TIME ms.

Precondition:: The input devices must be initialized by a InputInit call or the asked button state machine must reseted with InputButtonReset at least once.

Parameters:

eBtn

The button state machine which should be checked for the long push. The return value for ALL_BTN is meaningless and the behaviour is undefined.

Return values:

	TRUE	There was a long push since the last InputButtonReset.
	FALSE	There was no long push since the last InputButtonReset.

Remarks:: None

Definition at line 334 of file input.c.

BOOL bInputButtonPushedOnce ( eButtonID eBtn )

The application can ask the input module for a given button if there was a single push since the last call of InputButtonReset.

A single push is detected if a button was pushed at least 8 ms and released afterwards.

Precondition:: The input devices must be initialized by a InputInit call or the asked button state machine must reseted with InputButtonReset at least once.

Parameters:

eBtn

The button state machine which should be checked for the single push. The return value for ALL_BTN is meaningless and the behaviour is undefined.

Return values:

	TRUE	There was a single push since the last InputButtonReset.
	FALSE	There was no single push since the last InputButtonReset.

Remarks:: None

Definition at line 287 of file input.c.

BOOL bInputButtonPushedTwice ( eButtonID eBtn )

The application can ask the input module for a given button if there was a double push since the last call of InputButtonReset or InputInit.

A double push is detected if the state machine has seen two single pushes inbetween a time of BTN_DOUBLE_PUSH_TIME ms.

Precondition:: The input devices must be initialized by a InputInit call or the asked button state machine must reseted with InputButtonReset at least once.

Parameters:

eBtn

The button state machine which should be checked for the double push. The return value for ALL_BTN is meaningless and the behaviour is undefined.

Return values:

	TRUE	There was a double push since the last InputButtonReset.
	FALSE	There was no double push since the last InputButtonReset.

Remarks:: None

Definition at line 319 of file input.c.

BOOL bInputEncoderValueChanged ( void )

This function returns TRUE if the value of rotary encoder state machine has changed after the last call of s16InputEncoderGetValue.

Precondition:: The rotary encoder must be initialized by a InputEncoderInit call.

Return values:

	TRUE	The value has changed.
	FALSE	The value has not changed.

Remarks:: The function also returns TRUE after a initialization with a call of InputEncoderInit (if ENC_NOCHANGE_MASK is not set) or InputEncoderSetValue.

Definition at line 521 of file input.c.

void InputButtonReset ( eButtonID eBtn )

The state machine of the given button will be reseted or all if ALL_BTN is the parameter.

The state machine processes basic inputs like short single pushes (requestable with bInputButtonPushedOnce), single long pushes (requestable with bInputButtonPushedLong) and double short pushes (requestable with bInputButtonPushedTwice). To reset this occured button events the application must call this function.

Precondition:: The input devices must be initialized by a InputInit call.

Parameters:

eBtn

The button state machine which should be reset.

Returns:: None

Remarks:: None

Definition at line 268 of file input.c.

BOOL InputEncoderGetDirection ( void )

This function delivers the current or last rotary direction of the encoder button.

Precondition:: The rotary encoder must be initialized by a InputEncoderInit call.

Return values:

	TRUE	The current (or last) rotary direction of the encoder button is right.
	FALSE	The current (or last) rotary direction of the encoder button is left.

Definition at line 555 of file input.c.

void InputEncoderInit	(	SHORT	s16Val,
		SHORT	s16Min,
		SHORT	s16Max,
		BYTE	u8Flags
	)

This function initializes the rotary encoder.

The state machine of the rotary encoder can be configured in some flags, value range and the start value as well.

Precondition:: The input devices must be initialized by a InputInit call.

Parameters:

	s16Val	Thats the initial start value of the rotary encoder. If the user do not move the encoder after the initialization a call of s16InputEncoderGetValue would return this value.
	s16Min	The minimum value of the encoder. The state machine checks for this value to prevent an underflow.
	s16Max	The maximum value of the encoder. The state machine checks for this value to prevent an overflow.
	u8Flags	Some flags which configure the behaviour on over- and underflow situations. See ENC_ENDSTOP_MASK, ENC_NOCHANGE_MASK and ENC_TURBO_MASK for details.

Definition at line 437 of file input.c.

void InputEncoderSetValue	(	short	s16NewVal,
		BOOL	bRemember
	)

The function sets the internal encoder value to the given value.

Precondition:: The rotary encoder must be initialized by a InputEncoderInit call.

Parameters:

	s16NewVal	The new value for the encoder.
	bRemember	If TRUE the function bInputEncoderValueChanged delivers a TRUE when calling after this function call.

Definition at line 497 of file input.c.

void InputForceChangedEncoderValue ( void )

After calling this function the function bInputEncoderValueChanged delivers a TRUE when calling after this function call.

Precondition:: The rotary encoder must be initialized by a InputEncoderInit call.

Definition at line 541 of file input.c.

void InputInit ( void )

Initializes the input module.

The modules includes the buttons and their state machines.

Precondition:: None.

Returns:: None

Remarks:: None

Definition at line 71 of file input.c.

void InputInterruptHandler ( void )

This function handles the periodic requested interrupts.

The routine processes the rotary encoder state machines.

Definition at line 641 of file input.c.

void InputMain ( void )

The input state machines are feeded, handled and checked.

The application must call this routine periodically (cycle must be 10 ms).

Precondition:: The input devices are initialized by a InputInit call.

Returns:: None

Remarks:: None

Definition at line 110 of file input.c.

void InputResetButtonPush ( eButtonID eBtn )

This function can be used to reset single push events in the state machine.

Other events like long and double pushes are not affected. If the application also waits for this events it should use InputButtonReset rather than this function to prevent missing them.

Parameters:

eBtn

The button state machine which single push flag should be reset. The return value for ALL_BTN is meaningless and the behaviour not defined.

Returns:: None

Remarks:: None

Definition at line 302 of file input.c.

void InputResetPowerButton ( void )

The power button state machine is something special and can be reset by this function.

The power button is not only used for normal application. The input module has a special state machine for this button to react on long pushes. After a long push was noticed by the state machine and processed by the application it should acknowledged and reseted by call of InputResetPowerButton. In fact the power button has two state machines. The first one is handled like the other push buttons and can be reset due a call of InputButtonReset. The second one handles only single long pushes which are used by eWicht to handle power on and off. This SM is divorced from the first SM to prevent missing long pushes. Single and double pushes are not affected.

Precondition:: The input devices must be initialized by a InputInit call.

Returns:: None

Remarks:: None

Definition at line 310 of file input.c.

BOOL IsEncoderTurning ( void )

The function checks whether the input encoder is turning.

Precondition:: The input devices must be initialized by a InputInit call.

Return values:

	TRUE	The encoder button is turning.
	FALSE	The encoder button is not turning.

Definition at line 563 of file input.c.

SHORT s16InputEncoderGetValue ( void )

This function returns the actual value of rotary encoder state machine.

Precondition:: The rotary encoder must be initialized by a InputEncoderInit call.

Returns:: The current rotary encoder value. This value will be in the configured range.

Remarks:: None

Definition at line 477 of file input.c.

BYTE u8InputButtonQuickPushed ( void )

The function delivers the ID of any pushed quick button (F1-F4).

Precondition:: The input devices must be initialized by a InputInit call or the asked button state machine must reseted with InputButtonReset at least once.

Returns:: The ID of the quick button or 0xFF if non of the buttons was pushed for a long time.

Definition at line 356 of file input.c.


Files
file	input.c
	Button routines for input status of eWicht.
file	input.h
	Input module defines and global function prototypes for eWicht.
Defines
#define	BTN_COUNT 0x09
	The count of buttons.
#define	ENC_ENDSTOP_MASK 0x01
	Flag for configuring the state machine (SM) of the rotary encoder button.
#define	ENC_TURBO_MASK 0x02
	Flag for configuring the state machine (SM) of the rotary encoder button.
#define	ENC_NOCHANGE_MASK 0x04
	Flag for configuring the state machine (SM) of the rotary encoder button.
#define	BTN_LONG_PUSH_TIME (100u)
	This value is used to measure the first push time (unit is the cycle call time of the InputMain routine) of a button after a reset of the appropriate state machine and the first push.
#define	BTN_DOUBLE_PUSH_TIME (60u)
	A button state machine waits between to single pushes until this time is elapsed (unit is the cycle call time of the InputMain routine).
Enumerations
enum	eButtonID { PWR_BTN = 0, SEL_BTN, ACC_BTN, FL_BTN, F1_BTN, F2_BTN, F3_BTN, F4_BTN, ENC_BTN, ALL_BTN }
	IDs for accessing the buttons. More...
Functions
void	InputInit (void)
	Initializes the input module.
void	InputMain (void)
	The input state machines are feeded, handled and checked.
void	InputButtonReset (eButtonID eBtn)
	The state machine of the given button will be reseted or all if ALL_BTN is the parameter.
void	InputResetPowerButton (void)
	The power button state machine is something special and can be reset by this function.
void	InputResetButtonPush (eButtonID eBtn)
	This function can be used to reset single push events in the state machine.
BOOL	bInputButtonPushedOnce (eButtonID eBtn)
	The application can ask the input module for a given button if there was a single push since the last call of InputButtonReset.
BOOL	bInputButtonPushedTwice (eButtonID eBtn)
	The application can ask the input module for a given button if there was a double push since the last call of InputButtonReset or InputInit.
BOOL	bInputButtonPushedLong (eButtonID eBtn)
	The application can ask the input module for a given button if there was a long push since the last call of InputButtonReset or InputInit.
BOOL	bInputButtonPushed (eButtonID eBtn)
	This function combines the functions bInputButtonPushedLong, bInputButtonPushedOnce and bInputButtonPushedTwice.
SHORT	s16InputEncoderGetValue (void)
	This function returns the actual value of rotary encoder state machine.
void	InputEncoderInit (SHORT s16Val, SHORT s16Min, SHORT s16Max, BYTE u8Flags)
	This function initializes the rotary encoder.
BOOL	bInputEncoderValueChanged (void)
	This function returns TRUE if the value of rotary encoder state machine has changed after the last call of s16InputEncoderGetValue.
void	InputEncoderSetValue (short s16NewVal, BOOL bRemember)
	The function sets the internal encoder value to the given value.
void	InputForceChangedEncoderValue (void)
	After calling this function the function bInputEncoderValueChanged delivers a TRUE when calling after this function call.
BOOL	InputEncoderGetDirection (void)
	This function delivers the current or last rotary direction of the encoder button.
BYTE	u8InputButtonQuickPushed (void)
	The function delivers the ID of any pushed quick button (F1-F4).
BOOL	bInputButtonPressed (eButtonID eBtn)
	The function checks whether the requested button is currently pressed or released.
BOOL	IsEncoderTurning (void)
	The function checks whether the input encoder is turning.
void	InputInterruptHandler (void)
	This function handles the periodic requested interrupts.