Shopping Cart 0 items
log in register
Today's Deals Forum Desktop Site
All Categories
Featured
Brands
Development
Sensors
Tools
Miscellaneous
Components
E-Textiles
Robotics
Wireless & IoT
Audio

SparkFun Qwiic Button Hookup Guide

≡ Pages
Contributors: El Duderino
Favorited Favorite 0

Qwiic Button 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 library is to search for SparkFun Qwiic Button in the Arduino Library Manager tool. You can also manually install the Qwiic Button Library from the GitHub Repository or you can download it by clicking the button below.

Download the SparkFun Qwiic Button Library (ZIP)

Library Functions

Here is a list of the functions of the library with some quick descriptions of what they do. The examples cover most of the functions so we recommend going through them first.

Device Status

  • begin(uint8_t address = DEFAULT_ADDRESS, TwoWire &wirePort = Wire);- Sets device I2C address to a user-specified address, over whatever port the user specifies.
  • isConnected();- Returns true if the button will acknowledge over I2C, false otherwise.
  • uint8_t deviceID();- Return the 8-bit device ID of the attached device.
  • checkDeviceID();- Returns true if the device ID matches that of either the button or the switch
  • uint8_t getDeviceType();- Returns 1 if a button is attached, 2 if a switch is attached. Returns 0 if there is no device attached.
  • uint16_t getFirmwareVersion();- Returns the firmware version of the attached device as a 16-bit integer. The leftmost (high) byte is the major revision. The rightmost (low) byte is the minor version number. (Ex. 0x0202 is v2.02)
  • setI2Caddress(uint8_t address);- Configures the attached device to attach to the I2C bus using the specified address.
  • uint8_t getI2Caddress();- Returns the I2C address of the device.
Note: The "setI2Caddress();" function will not work if any of the I2C address jumpers are closed. Assuming the code 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 and the last part of this function won't be able to connect to the button for the firmware printout and future I2C address changes.

Button Status/Configuration

  • isPressed();- Returns 1 if the button is pressed, and 0 otherwise.
  • hasBeenClicked();- Returns 1 if the button was clicked, and 0 otherwise.
  • uint8_t setDebounceTime(uint16_t time);- Sets the time that the button waits for the mechanical contacts to settle (in ms) and checks if the register was set properly. Returns 0 on success, 1 on register I2C write fail, and 2 if the value didn't get written into the register properly.
  • uint16_t getDebounceTime();- Returns the value set to wait for the button's the mechanical contacts to settle, (in ms).
Note: You may notice there are two button status functions listed: isPressed(); and hasBeenClicked();. The isPressed(); function returns true while the button is pressed/held down and false when the button is unpressed/released. The hasBeenClicked(); function will only return true when the button is pressed and then released.

Interrupt Status/Configuration

  • uint8_t enablePressedInterrupt();- Configure the interrupt pin to go LOW while the button is pressed (held down).
  • uint8_t disablePressedInterrupt();- Sets the interrupt to no longer trigger while the button is pressed.
  • uint8_t enableClickedInterrupt();- Configure the interrupt pin to go LOW when the button is clicked.
  • uint8_t disableClickedInterrupt();- Configures the interrupt pin to no longer go low when the button is clicked.
  • uint8_t clearEventBits();- Sets "isPressed", "hasBeenClicked", and "eventAvailable" to zero.
  • uint8_t resetInterruptConfig();- Resets all interrupt configuration settings back to defaults.

FIFO Queue

  • isPressedQueueFull();- Checks the queue of button press timestamps and returns true if full, false otherwise.
  • isPressedQueueEmpty();- Opposite of the above function. Checks if the timestamp queue is empty.
  • unsigned long timeSinceLastPress();- Returns the time (in ms) since the last button press.
  • unsigned long timeSinceFirstPress();- Returns time (in ms) since the first button press.
  • popPressedQueue();- Returns the oldest value in the Pressed Queue (ms since first button press), and then removes it.
  • isClickedQueueFull();- Checks the queue of button click timestamps and returns true if full, false otherwise.
  • isClickedQueueEmpty();- Opposite of the above function. Checks if the timestamp queue is empty.
  • unsigned long timeSinceLastClick();- Returns the time (in ms) since the last button click.
  • unsigned long timeSinceFirstClick();- Returns the time (in ms) since the first button click.
  • popClickedQueue();- Returns the oldest value in the Clicked Queue (ms since first button click), and then removes it.

Button LED Configuration

  • LEDoff();- Turn the button LED off.
  • LEDon(uint8_t brightness = 255);- Turn the button LED on and set the brightness.
  • LEDconfig(uint8_t brightness, uint16_t cycleTime, uint16_t offTime, uint8_t granularity = 1);- Configures the button LED.
    • Brightness: Stores the brightness of the LED. Accepts values between 0 and 255.
    • cycleTime: Total pulse cycle time (in ms). Does not include off time.
    • offTime: Off time between pulses (in ms). Default is 500 ms.
    • granularity: Amount of steps it takes to get to the set brightness level.

Internal I2C Abstraction

Advanced Functions! This list of functions is for reading/writing to one or more registers. They are beyond the scope of this tutorial and are included primarily for users to implement in custom code.
  • uint8_t readSingleRegister(Qwiic_Button_Register reg); - Reads a single 8-bit register.
  • uint16_t readDoubleRegister(Qwiic_Button_Register reg); - Reads a 16-bit register (little endian).
  • unsigned long readQuadRegister(Qwiic_Button_Register reg); - Reads a 32-bit register (little endian).
  • writeSingleRegister(Qwiic_Button_Register reg, uint8_t data); - Attempts to write data into a single 8-bit register. Does not check to make sure it was written successfully. Returns 0 if there was no error on I2C transmission, and 1 otherwise.
  • writeDoubleRegister(Qwiic_Button_Register reg, uint16_t data); - Attempts to write data into a double (two 8-bit) registers. Does not check to make sure it was written successfully. Returns 0 if there was no error on I2C transmission, and 1 otherwise.
  • uint8_t writeSingleRegisterWithReadback(Qwiic_Button_Register reg, uint8_t data); - Writes data into a single 8-bit register, and checks to make sure the data was written successfully. Returns 0 on no error, 1 on I2C write fail, and 2 if the register doesn't read back the same value that was written.
  • uint16_t writeDoubleRegisterWithReadback(Qwiic_Button_Register reg, uint16_t data); - Writes data into a double (two 8-bit) registers, and checks to make sure the data was written successfully. Returns 0 on no error, 1 on I2C write fail, and 2 if the register doesn't read back the same value that was written.
View as a single page Next Page →
Arduino Examples
← Previous Page
Hardware Assembly