By dave | August 2, 2019

Menu control using a matrix keyboard

Using a matrix keyboard with TcMenu is straightforward, we use the IoAbstraction Keyboard Manager component to handle the keyboard, along with a custom listener for tcMenu that feeds the menu manager with appropriate events upon key presses. This library allows you to connect your keyboard either using Arduino pin, or any supported IoAbstraction such as the I2C PCF8574 or MCP23017.


Setting up the menu sketch for a Matrix Keyboard

Step 1 is to wire up your keyboard in accordance with the above linked keyboard manager page, I recommend at this point testing it through the packaged IoAbstraction example.

Step 2 is to add keyboard support to your sketch:

Include the required header

#include <tcMenuKeyboard.h>

Globally declare the variables

// Either manually declare a keyboard layout or use one of the standard ones.
MAKE_KEYBOARD_LAYOUT_3X4(keyboardLayout) 
// or MAKE_KEYBOARD_LAYOUT_4X4(keyboardLayout)

// Now declare the keyboard manager
MatrixKeyboardManager keyboard;

// Lastly, we declare the tcMenu keyboard listener, that listens to keypresses
// and performs the right actions in the menu. If this one doesn't do the right
// thing, you can write your own / extend this one. 
MenuEditingKeyListener menuKeyListener;

Then create a setupKeyboard function that will initialise the keyboard

void setupKeyboard() {
    // set up the pin mappings for the rows and columns.
    keyboardLayout.setRowPin(0, 22);
    keyboardLayout.setRowPin(1, 23);
    keyboardLayout.setRowPin(2, 24);
    keyboardLayout.setRowPin(3, 25);
    keyboardLayout.setColPin(0, 26);
    keyboardLayout.setColPin(1, 27);
    keyboardLayout.setColPin(2, 28);

    // initialise telling the library it's wired on Arduino pins, with given layout
    // and listener, you could change the IOdevice to an I2C one for example. 
    keyboard.initialise(ioUsingArduino(), &keyboardLayout, &menuKeyListener);
    // repeat the pressed key after 850ms every 350ms 
    keyboard.setRepeatKeyMillis(850, 350);    
}

Then at the end of setup, call the function you created above.

void setup() {
    // ... your other setup stuff ...
    
    setupKeyboard();        
}

That’s it, your menu will be controllable by the keyboard. We’ll now discuss how it works:

How key presses work when not editing

  • Holding down (long press) ‘#’ at any time will go back to the root menu.
  • When not editing pressing 1 thru 9 will make the menu item at that position active.
  • Pressing ‘*’ while not in edit mode will enter edit mode for the active item, if the item is a sub menu, the sub menu will be activated.
  • Pressing ‘*’ on an action item will trigger it.
  • If you have a 4x4 keyboard, then the A and B keys can be used to move up and down.

How key presses work when editing

  • For non-text fields: Pressing ‘*’ while in edit mode will leave edit mode
  • For text fields, Each key you press is added to the text field, like a regular editor.
  • For Enums, pressing 1 thru 9 on an enum selects the options in order as if it were 1 based.
  • For Booleans, pressing ‘*’ on a boolean toggles it’s state.

For entering numeric values

  • Editing a numeric field zeros the value, a new value is entered using 0-9 keys, starting with units, then tens and so on.
  • If the field supports negative values, press either ‘#’ or ‘-’ to negate the current value.
  • Number editor starts allowing editing of the whole number, pressing ‘’ to edit the fraction (if available), then pressing ‘’ to exit editing.
  • For IPAddress, Large numbers and time fields: as per integer editing, but ‘*’ moves between each part.

Back to tcMenu main page

Other pages within this category

comments powered by Disqus

This site uses cookies to analyse traffic, serve ads by Google AdSense (non-personalized in EEA/UK), and to record consent. We also embed Twitter, Youtube and Disqus content on some pages, these companies have their own privacy policies.

Our privacy policy applies to all pages on our site

Should you need further guidance on how to proceed: External link for information about cookie management.