t02lc

Tutorial 2 (LiquidCrystal Library): User Input

This tutoral will show how to read and process input from the user.

Theory

This is how m2tklib works:

1. Detect a user input and convert the input into an internal m2tklib "event". This step depends on the hardware.
2. Process the "event". This is independent from the hardware
3. Display the result (see previous Tutorial)

All three steps are handled by "callback" procedures.

1. Event Source: Translate Hardware events into m2tklib "events". Within the Arduino Environment this is usually m2_es_arduino (Others are m2_es_arduino_rotary_encoder or m2_es_arduino_serial).
2. Event Handler: The event handler defines which and how events are handled. Bigger event handlers like the m2_eh_6bs can handle many events (hardware buttons) but also need more memory than small event handlers like the m2_eh_2bs which supports two buttons. In principle all event handlers can be used with all input fields. But if there is only a very limited number of hardware buttons, than it might be less comfortable for the user to enter data. On the other hand, sometimes it is required to build really small devices with only a view number of buttons.
3. Graphics Handler: The graphics handler allows m2tklib to operate independently from the underlaying output device. For each supported output device, there is at least one graphics handler. Additionally the graphics handler defines the style how the user input fields (elements) are displayed. For the LiquidCrystal Library there is currently only one handler: m2_gh_lc (see complete listhere).

Example

The example uses the two button handler m2_eh_2bd:

M2tk m2(&el_num, m2_es_arduino, m2_eh_2bd, m2_gh_lc);

The setup part connects the pins of the Arduino hardware with the events:

  m2.setPin(M2_KEY_SELECT, 4);
  m2.setPin(M2_KEY_NEXT, 3);
  m2.setPin(M2_KEY_PREV, 5);
  m2.setPin(M2_KEY_EXIT, 2);  

This is the complete example (U32Plain). The user can enter an unsigned 32bit variable (M2_U32NUM-Field).

#include <LiquidCrystal.h>
#include "M2tk.h"
#include "m2ghlc.h"

LiquidCrystal lcd(12, 11, 5, 4, 3, 2);

uint8_t uiKeySelectPin = 10;
uint8_t uiKeyNextPin = 9;

uint32_t number = 1234;

M2_U32NUM(el_num, "a1c4", &number);
M2tk m2(&el_num, m2_es_arduino, m2_eh_2bs, m2_gh_lc);

void setup() {
  m2_SetLiquidCrystal(&lcd, 16, 2);
  m2.setPin(M2_KEY_SELECT, uiKeySelectPin);
  m2.setPin(M2_KEY_NEXT, uiKeyNextPin);
}

void loop() {
  m2.checkKey();
  m2.checkKey();
  if ( m2.handleKey() )
    m2.draw();
  m2.checkKey();
}

There are two more procedures in the main loop:

• m2.checkKey(): Debounce and detect hardware buttons. Translate hardware events into internal events and put them into an event queue. checkKey() should be called as often as possible.
• m2.handleKey(): This procedure will process one event from the queue. A non-zero will be returned if a refresh of the display is required. The first call to this procedure will return a non-zero value.

Conclusion

• Proper setup of m2tklib requires three callback procedures:
  1. Event Source: Translates hardware events (button press) to internal events. This is always m2_es_arduino for the Arduino Envornment.
  2. Event Handler: Execute the event. Use m2_eh_2bs if there are two buttons connected to the Arduino Board.
  3. Graphics Handler: Depends on the output device. Use m2_gh_lc for the LiquidCrystal library.
• Calls to m2.checkKey() will read and translate hardware events.
• Calls to m2.handleKey() will modify the content of the menu.

Links

• Previous Tutorial: Tutorial 1: Hello World
• Next Tutorial: Tutorial 3: User Interface Design
• Wiki Start Page