Qwiic Keypad Hookup Guide a learn.sparkfun.com tutorial

Available online at: http://sfe.io/t271

Contents

Introduction

Keypads are very handy input devices, but who wants to tie up 7 GPIO pins, wire up a handful of pull-up resistors, and write firmware that wastes valuable processing time scanning the keys for inputs? Let’s make the development process easier! The SparkFun Qwiic Keypad comes fully assembled and uses the simple Qwiic interface. No soldering, no voltage translation, no figuring out which I2C pin is SDA or SCL, just plug and go!

SparkFun Qwiic Keypad - 12 Button

SparkFun Qwiic Keypad - 12 Button

COM-15290
$11.50
11

The Qwiic Keypad reads and stores the last 15 button presses in a First-In, First-Out (FIFO) stack, so you don’t need to constantly poll the keypad from your microcontroller. This information, then, is accessible through the Qwiic interface. Qwiic Keypad even has a software configurable I2C address so you can have multiple I2C devices on the same bus.

Required Materials

The SparkFun Qwiic Keypad does need a few additional items for you to get started; a Qwiic enabled microcontroller and a Qwiic cable. You may already have a few of these items, so feel free to modify your cart based on your needs.

SparkFun Qwiic Cable Kit

SparkFun Qwiic Cable Kit

KIT-15081
$8.95
20
SparkFun RedBoard Qwiic

SparkFun RedBoard Qwiic

DEV-15123
$21.50
19
SparkFun RedBoard Turbo - SAMD21 Development Board

SparkFun RedBoard Turbo - SAMD21 Development Board

DEV-14812
$19.95
8

SparkFun Thing Plus - ESP32 WROOM

WRL-14689
7 Retired

Suggested Reading

If you're unfamiliar with jumper pads or I2C be sure to checkout some of these foundational tutorials.

Logic Levels

Learn the difference between 3.3V and 5V devices and logic levels.

I2C

An introduction to I2C, one of the main embedded communications protocols in use today.

How to Work with Jumper Pads and PCB Traces

Handling PCB jumper pads and traces is an essential skill. Learn how to cut a PCB trace, add a solder jumper between pads to reroute connections, and repair a trace with the green wire method if a trace is damaged.

RedBoard Qwiic Hookup Guide

This tutorial covers the basic functionality of the RedBoard Qwiic. This tutorial also covers how to get started blinking an LED and using the Qwiic system.
Note: For a greater understanding of how the firmware works to multiplex the keys, check out these tutorials.

Button Pad Hookup Guide

An introduction to matrix scanning, using the SparkFun 4x4 Button Pad.

Multiplexer Breakout Hookup Guide

How to use the 74HC4051 multiplexer breakout to drive eight LEDs, read eight button inputs, or monitor eight potentiometers.

Arduino Kepad Tutorials
Arduino Keypad Library
Arduino Keypad Tutorial

Qwiic Connect System

The Qwiic Keypad utilizes the Qwiic connect system. We recommend familiarizing yourself with the Logic Levels and I2C tutorials (above) before using it. Click on the banner above to learn more about our Qwiic products.

Hardware Overview

Keypad

This is a basic 12 button keypad that has been designed for easy user input and functionality. The buttons are set up in a matrix format. This allows the ATtiny84 to scan the 7 output pins to see which of the 12 buttons are being pressed.

Annotated image of buttons

Each of the keypad's 12 buttons has been labeled 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, *, and # and has been formatted to into the same layout as a telephone keypad. Each keypress resistance ranges between 10 - 150Ω.

Power LED

There is a power status LED to help make sure that your Qwiic Keypad is getting power. You can power the board either through the polarized Qwiic connector system or the breakout pins (PWR and GND) provided. The Qwiic system is meant to run on 3.3V, be sure that you are NOT using another voltage when using the Qwiic system. Qwiic Keypad is very low power and uses less than 4mA at 3.3V.

Annotated image of Power LED

ATtiny84

With the pre-installed firmware, the ATtiny84 acts as an intermediary (microcontroller) multiplexing the buttons for inputs. This allows the Qwiic Keypad to store the button presses in the FIFO stack to be read over I2C. Although the ATtiny84 has a wide voltage range, since this is a Qwiic product, users should power the board with the labeled 3.3V.

Annotated image of ATtiny84

First-In, First-Out (FIFO) Stack

In the firmware, the FIFO stack stores the most recent 15 button inputs. Once the stack is full, any previous inputs are overwritten. The FIFO stack is manually incremented using the FIFO Command register. If there are no more values stored in the FIFO stack, the output will be 0x00 or Null.

demonstration of a FIFO
Demonstration of the FIFO: (1) Filling the FIFO stack with inputs, (2) overwriting old inputs, and (3) incrementing & reading the FIFO.

Note: Technically, the FIFO stack is actually a circular buffer that tracks the beginning and end index of the stack.

The condition for a FIFO incrementation is a request event (register is read) after the updateFIFO register has already been set to 0x01.

Order of operations for FIFO incrementation:
  1. Input: Set updateFIFO register to 0x01.
  2. Firmware: Wait for request event.
  3. Input: Create a request event (read a register).
  4. Firmware:
    1. Set updateFIFO register to 0x00.
    2. Increment new index for the FIFO buffer.
    3. Determines the "next button" value.
    4. Calculates time since the "next button" was pressed.
    5. Updates register with new values (for the "next button" and time since the "next button" was pressed).
  5. Input: Wait for next updateFIFO command.

Qwiic and I2C

I2C Address

In the firmware, the Qwiic Keypad’s I2C address is configurable so you can add a bunch of them to the same bus without collision issues.

Factory Default I2C Slave Address: 0x4B

I2C Registers

Address Description
0x00 Default I2C Slave Address (Stored in EEPROM)
0x01 - 0x02 Firmware Version (MSB First)
0x03 Oldest Button Press (aka First-Out from FIFO stack)
0x04 - 0x05 Time in ms since the button was pressed (MSB First, 16-bit = Max Value of 65,535 ms).
0x06 FIFO Increment Command: Set bit 0 to increment FIFO.
0x07 Current/Set I2C Slave Address (Write). Stored in EEPROM.

Connections

The simplest way to use the Qwiic Keypad is through the Qwiic connect system. The connectors are polarized for the I2C connection and power. (*They are tied to their corresponding breakout pins.)

Annotated image of  Qwiic connectors
Qwiic connectors.

However, the board also provides six labeled breakout pins. You can connect these lines to the I2C bus of your microcontroller and power pins (3.3V and GND), if it doesn't have a Qwiic connector. The interrupt and reset pins are also broken out to use for triggered events.

Annotated image of  I2C connections
I2C Connections- The pins are tied to the Qwiic connectors.

Interrupt Pin

The interrupt pin (active low) is used to indicate that there are available entries in the FIFO stack. Effectively, if it is tied to an interrupt on your microcontroller and you are using it to increment the FIFO stack, then it will get triggered every time a button is pressed. The INT pin is pulled up with a 4.7kΩ resistor and will be low if there are entries. The INT pin will return high once the FIFO has been cleared.

Annotated image of interrupt pin

Reset Pin

Reset pin tied to the reset pin on the ATtiny. When pulled low, this will effectively reset the Qwiic Keypad and restart the device, loading the I2C address that was stored in EEPROM. It is mostly, broken out for reprogramming the ATtiny84.

Annotated image of reset pin

Jumpers

There are jumpers on the board allowing the user to select between different I2C addresses as well as to remove the pull up resistors from the I2C pins, if needed.

I2C Address

Bridging the I2C address jumper changes the slave address from the value stored in EEPROM to the I2C Jumper Default (or alternate): 0x4A.

Annotated image of I2C address jumper

I2C Pull-Up

Cutting the I2C jumper will remove the 2.2kΩ pull-up resistors from the I2C bus. If you have many devices on your I2C bus you may want to remove these jumpers. Not sure how to cut a jumper? Read here!

Annotated image of pullup jumper

Hardware Assembly

With the Qwiic connector system, assembling the hardware is simple. All you need to do is connect your Qwiic Keypad to Qwiic enabled microcontroller with a Qwiic cable. Otherwise, you can use the I2C pins, if you don't have a Qwiic connector on your microcontroller board. Just be aware of your input voltage and any logic level shifting you may need to do.

Example setup with RedBoard Qwiic

Example setup with RedBoard Qwiic.

Arduino Library

Note: This tutorial assumes you are familiar with Arduino products and you are using the latest stable version of the Arduino IDE on your desktop. If this is your first time using the Arduino IDE, please review our tutorial on installing the Arduino IDE. If you have not previously installed an Arduino library, please check out our installation guide.

The easiest way to install the Arduino library is by searching SparkFun Qwiic Keypad inside the Arduino library manager. To manually install, head on over to the GitHub repository or feel free to download the library here!

DOWNLOAD: SparkFun Qwiic Keypad Library (ZIP)

Library Functions

The Arduino library is commented and the functions should be self-explanatory. However, below is a detailed list of the available library functions.

.begin() or .begin(Wire, deviceAddress)
Creates a connection to an I2C device over the I2C bus using the default or specified I2C address.

Input: uint8_t deviceAddress
Unasssigned 8-bit integer for device address. If not defined, the library will use the default I2C address stored in the I2C library (0x4B).
Output: Boolean

True- Connected to I2C device.
False- No device found or connected.

.isConnected()
Tries to connect to the device at the I2C address stored in the library.

Output: Boolean

True- Connected to I2C device.
False- No device found or connected.

.getVersion()
Returns a string of the firmware version number.

Output: String AAA.BBB

AAA - Firmware Version (Major)
BBB - Firmware Version (Minor)

.setI2CAddress(newAddress)
Changes the I2C address to newAddress. Once changed, the new I2C address is saved in the EEPROM of the Qwiic Keypad. Reconnects to device using new I2C address. (The new address is printed out in the Serial Monitor.)

Input: uint8_t newAddress

Unasssigned 8-bit integer for device address.

Output: Serial

Address: 0x##, where 0x## is the new I2C address.
Address Change Failure- Error output if the the microcontroller wasn't able to change the I2C address.
ERROR: Address outside 8-119 range- Error output if the new I2C address is outside the available range.

Caution: Will not work if I2C address jumper is bridged. If the function is able to connect to the device, the library function may change the I2C address stored in EEPROM. However, by default the firmware will stay at the alternate I2C jumper address (0x4A) and the last part of this function won't be able to connect to the keypad for the firmware printout and future I2C address changes.

.getButton()
Returns the button at the top of the stack (aka the oldest button). In order to read this register for the first time, the FIFO needs to be incremented with the .updateFIFO() function first.

Output: byte

Value of the button.

.getTimeSincePressed()
This function reads the register that holds the time since the button (at the top of the FIFO stack) was pressed. In the firmware, the ATtiny85 actually responds to a request event (register read) and calculates the time since the button was pressed at that moment and updated the register. Like the .getButton() function, in order to use this function for the first time, the FIFO needs to be incremented with the .updateFIFO() function first.

Output: uint16_t

Unasssigned 16-bit integer [0 - 65,535] for time since button was pressed (in milliseconds).

Note: Since the time calculation occurs just before all the register values are updated and the time calculation only happens if there is a FIFO increment, the time calculation can only happen once during the first register read. Therefore, calling this function multiple times without a FIFO incrementation will report the same value, which corresponds to the time of the initial register read.

.updateFIFO()
Used to increment the FIFO stack- In the library, this function sets the updateFIFO register to 0x01. Once there is a request event (i.e .getButton() or .getTimeSincePressed()), the FIFO is incremented and the firmware clears the updateFIFO register back to 0x00.

Note: In the firmware, the FIFO isn't incremented until there is a request event (or register read). Therefore, you can't use this function multiple times without a request event, to scroll through the FIFO. Once the FIFO is incremented, the firmware clears the updateFIFO register back to 0x00.

Examples

There are six examples in the Qwiic Keypad Arduino Library to get you started with using Qwiic Keypad. These example files are named with self-explanatory titles, but in case you want more information, see the descriptions below.

Arduino Examples

Example 1: Read Button

The code for Example1_ReadButton connects to the Qwiic Keypad and prints out the value over the Serial Monitor. Below is a sample readout from the Serial Monitor using sequential button presses of: 1, 2, 3, 4, 5, 6, 7, 8, 9, *, 0, and #.

Serial Monitor readout for Example 1

Serial Monitor readout for Example 1.

Example 2: Read with Time

The code for Example2_ReadWithTime operates exactly like the Example1_ReadButton, except the time between since the last button press is printed. Below is a sample readout.

Serial Monitor readout for Example 2

Serial Monitor readout for Example 2.

Example 3: Change I2C Address

Caution: Will not work if I2C address jumper is bridged.

The code for Example3_ChangeI2CAddress connects to the Qwiic Keypad using the default I2C address set in the library and then prints out the I2C address and firmware version over the Serial Monitor. The sketch then, takes an input from the Serial Monitor to change the I2C address using a decimal value (DEC). Once the I2C address is changed, it is stored in the EEPROM of the Qwiic Keypad. After, the sketch connects to the keypad using the new I2C address and reads the registers for the firmware version again. The example then prints out those values over the Serial Monitor again. As shown in the sample readout below, the input value must between 8-119 (DEC) of unreserved I2C addresses.

Serial Monitor readout for Example 3

Serial Monitor readout for Example 3.

Example 4: I2C Scanner

The forth example, Example4_I2CScanner, scans for devices on the I2C bus and reports them on the Serial Monitor. This is useful for users who have forgotten the changed I2C address of their boards.

Serial Monitor readout for Example 4

Serial Monitor readout for Example 4.

Example 5: Read with Interrupt Pin

Note: This example is requires soldering. A wire must be soldered to the INT pin and connected to an interrupt pin on your microcontroller. As written, the example assumes you are using a Arduino UNO based board, like our RedBoard. The sketch designates Pin 2 as the interrupt pin.

The code for Example5_InterruptRead operates similar to Example1_ReadButton, except that instead of constantly polling the keypad for button presses in software, it responds to a hardware trigger on the interrupt (INT) pin. For more details on interrupts, check out this tutorial on Processor Interrupts with Arduino .

Serial Monitor readout for Example 5

Serial Monitor readout for Example 5.

Example 6: Key in Code

The last example, Example6_Keycode, is a use case example, in which the user must input the correct key code: 1, 2, 3, 4.

Serial Monitor readout for Example 6

Serial Monitor readout for Example 6.

Resources and Going Further

For more information, check out the resources below:

Need help getting started with Arduino and I2C? Check out these resources here:

Need some inspiration for your next project? Check out this Hotkey Project, similar to this blog post by ALEX THE GIANT from a few years ago.

Check out some of these other Qwiic product tutorials:

Qwiic UV Sensor (VEML6075) Hookup Guide

Learn how to connect your VEML6075 UV Sensor and figure out just when you should put some sunscreen on.

Qwiic MP3 Trigger Hookup Guide

Playing MP3s has never been easier.

SparkFun Qwiic Micro (SAMD21E) Hookup Guide

An introduction to the Qwiic Micro SAMD21E. Level up your Arduino-skills with the powerful SAMD21 ARM Cortex M0+ processor!

Hookup Guide for the Qwiic Motor Driver

Drive things "qwiic"-ly with the SparkFun Qwiic Motor Driver!

Or check out this blog post.

Enginursday: Keycode Security Starter, Part 2

March 5, 2020

learn.sparkfun.com | CC BY-SA 3.0 | SparkFun Electronics | Niwot, Colorado