Qwiic Keypad Hookup Guide

Pages
Favorited Favorite 0

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!

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.

  • Example1_ReadButton

    This example connects to the Qwiic Keypad using the default I2C address saved in the library. The sketch loops through reading the register for the button at the top of the FIFO stack and incrementing the FIFO. The example then prints out the value over the Serial Monitor. The * is represented by a space and the # is represented with a new line (or carriage return).

  • Example2_ReadWithTime

    This example operates exactly like the Example1_ReadButton, except the time since the button was pressed is outputted with the button that was pressed in the Serial Monitor. With a ~1 second delay between checks for button presses.

  • Example3_ChangeI2CAddress

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

    This example 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.

  • Example4_I2CScanner

    This example is from the I2C scanner example from the Arduino Playground webpage. The sketch 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.

  • Example5_InterruptRead

    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.

    This example operates exactly like the Example1_ReadButton, except that instead of constantly polling the keypad for button presses in the main loop, it responds to the interrupt (INT) pin. Utilizing an interrupt allows the MCU to execute a specific set of instructions (i.e. button read), outside of the main loop. For more details on interrupts, check out this tutorial on Processor Interrupts with Arduino .

  • Example6_Keycode

    This example is a use case example, in which the user must input the correct key code: 1, 2, 3, 4. The sketch also implements a timeout, so that the user must input the correct code within 30 seconds.