Gravity: I2C RGB LED Button Module Wiki - DFRobot

1. Introduction

This is an I2C button module with RGB LED. The module not only supports reading button status like conventional ones, but also can control RGB LED color and switch on/off the light independently, which could create more visual and interactive experiences for your projects. For example, if the system prompts users to press a button, then the corresponding RGB LED shows a blinking green light; when users pressed the button, the light turns red.
This module has onboard 3bit DIP switch for setting 8 different I2C addresses, which means up to 8 such button modules can be cascaded together without occupying additional ports.

2. Features

3. Applications

4. Pinout

Pin Full Name Description
D SDA I2C Data Line
C SCL I2C Clock Line
+ VCC Positive Power Supply (DC 3.3V~5V)
- GND Negative Power Supply
INT Interrupt External Interrupt

5. Specification

6. Dimensions

7. Tutorial

7.1 Tutorial for Ardunio UNO Mainboard

This tutorial shows how to use the button module on Ardunio UNO mainboards.

7.1.1 Hardware Requirements

7.1.2 Software Requirements

7.1.3 Read Button Status

First, set the I2C address of the button module by toggling the 3-bit DIP switch A2, A1 and A0 with tweezers.

Note: The default I2C address of the button is 0x2A. The DIP switch can be set according to the address table at the bottom of the module as shown in the figure below.

Hardware Connection
Set I2C address and then connect the button module to the I2C interface of the UNO mainboard.

Sample Code
This sample shows how to read button status and prompt users to press and release button through the light.

#include <DFRobot_RGBButton.h>
DFRobot_RGBButton RGBButton(&Wire, /*I2CAddr*/ 0x2A);//set I2C address of the button module
void setup(void)
{
  Serial.begin(115200);
  while( ! RGBButton.begin() ){        //init
    Serial.println("Communication with device failed, please check connection!!!");
    delay(3000);
  }
  Serial.println("Begin ok!\n");
}
uint8_t flag = 0;
void loop()
{
  if( RGBButton.getButtonStatus() ) {
    flag = 1;
    RGBButton.setRGBColor(RGBButton.eRed);   // LED shows red light when the button is pressed
    delay(50);
  } else if( 1 == flag ) {
    flag = 0;
    RGBButton.setRGBColor(RGBButton.eBlack);   // LED goes out when the button is released
  }
}

Result
After uploading the codes, the button RGB LED shows red when the button is pressed and goes out when released.

7.1.4 Control RGB LED Color

In this sample, the hardware connection remains, and we will learn how to use the RGB LED of the button module as it can be controlled independently. Let's start with controlling LED color.

Sample Code
This sample implemented the rich color changes of RGB LED.

#include <DFRobot_RGBButton.h>
DFRobot_RGBButton RGBButton(&Wire, /*I2CAddr*/ 0x2A);

void setup(void)
{ Serial.begin(115200);
  while( ! RGBButton.begin() ){
    Serial.println("Communication with device failed, please check connection!");
    delay(3000);
  }
  Serial.println("Begin ok!\n");
  RGBButton.setRGBColor(RGBButton.eRed);       // display conventional colors
  delay(1000);
  RGBButton.setRGBColor(RGBButton.eOrange);
  delay(1000);
  RGBButton.setRGBColor(RGBButton.eYellow);
  delay(1000);
  RGBButton.setRGBColor(RGBButton.eGreen);
  delay(1000);
  RGBButton.setRGBColor(RGBButton.eCyan);
  delay(1000);
  RGBButton.setRGBColor(RGBButton.eBlue);
  delay(1000);
  RGBButton.setRGBColor(RGBButton.ePurple);
  delay(1000);
  RGBButton.setRGBColor(RGBButton.eWhite);
  delay(1000);
  RGBButton.setRGBColor(RGBButton.eBlack);
  delay(1000);
}
uint8_t rValue, gValue, bValue;

void loop()
{   rValue = random(0,255);          // random display colors
    gValue = random(0,255);
    bValue = random(0,255);
    RGBButton.setRGBColor(/*r=*/rValue, /*g=*/gValue, /*b=*/bValue);
    delay(1000);
}

Result
After uploading the codes, RGB LED will change color at one-second intervals, displaying 9 conventional colors first and then displaying random colors.

7.1.5 Control RGB LED Brightness

In this sample, we will learn how to control the brightness of RGB LED and the hardware connection remains. The LED color is set to blue so that we can focus on brightness changes.

Sample Code
This sample shows obvious brightness changes of RGB LED.

#include <DFRobot_RGBButton.h>
DFRobot_RGBButton RGBButton(&Wire, /*I2CAddr*/ 0x2A);

void setup(void)
{ 
  Serial.begin(115200);
  while( ! RGBButton.begin() )
  {
    Serial.println("Communication with device failed, please check connection!");
    delay(3000);
  }
  Serial.println("Begin ok!\n");
  RGBButton.setRGBColor(/*r=*/0, /*g=*/0, /*b=*/0);
}

uint8_t rValue = 0, gValue = 0, bValue;

void loop()
{
  for(uint8_t t=0;t<255;t++)
  { 
    RGBButton.setRGBColor(/*r=*/rValue, /*g=*/gValue, /*b=*/t);
    delay(10); 
  }
  for(uint8_t i=255;i>0;i--) 
  { 
    RGBButton.setRGBColor(/*r=*/rValue, /*g=*/gValue, /*b=*/i);
    delay(10); 
  }
}

Result
After uploading the codes, RGB LED shows blue light, and repeatedly changes from dim to bright and back to dim.

7.1.6 Control Breathing Light

We learned how to read button status and control RGB LED in previous samples. And we combine the two in this one. The hardware connection remains.

Sample Code

#include <DFRobot_RGBButton.h>
DFRobot_RGBButton RGBButton(&Wire, /*I2CAddr*/ 0x2A);//set I2C address of the button module

void setup() {
   Serial.begin(115200);
   while( ! RGBButton.begin() ){       //init
   Serial.println("Communication with device failed, please check connection!");
   delay(3000);
  }
  Serial.println("Begin ok!\n");
}

int t = 0;   // basic variation factor of RGB values
uint8_t rValue = 0, gValue = 0, bValue = 0;

void loop() {
 if( RGBButton.getButtonStatus() ) {
    RGBButton.setRGBColor(RGBButton.eRed);
    delay(100);
  } else {
    rValue = (abs(sin(3.14 * t / 180))) * 255;
    gValue = (abs(sin(3.14 * (t + 60) / 180))) * 255;
    bValue = (abs(sin(3.14 * (t + 120) / 180))) * 255;
    t += 1;
    RGBButton.setRGBColor(/*r=*/rValue, /*g=*/gValue, /*b=*/bValue);//set pulse width value of red, green and blue LEDs
    delay(100);
  }
}

Result
After uploading the codes, RGB LED presents a breathing lighting effect; it turns red when the button is pressed and back to the color of the breathing light when released.

7.1.7 Interrupt Function

The button module can send interrupt commands to the main controller via INT pin when used as an I2C slave, which better reflects the interactivity it brings. In this sample, we will learn the interrupt communication mode of the button module.

Hardware Connection
Interrupt 0 of the UNO mainboard is used in this sample. Connect the INT pin of the button module to the digital pin 2 of the UNO board, the LED to digital pin 8, and the button to the I2C interface.

Sample Code
This sample shows how to use INT pin of the button module.

#include <DFRobot_RGBButton.h>
DFRobot_RGBButton RGBButton(&Wire, /*I2CAddr*/ 0x2A);

 int LEDPin = 8;
volatile uint8_t flag = 0, temp = 0;
void interrupt()
{   if(3 != flag){
    temp = flag;
    flag = 3;
  }else{
    flag = temp;
    temp = 4; }}

void setup(void)
{    Serial.begin(115200);
    while( ! RGBButton.begin() ){
    Serial.println("Communication with device failed, please check connection!");
    delay(3000);    }
    Serial.println("Begin ok!\n");
    attachInterrupt(/*Interrupt No*/0, interrupt, CHANGE);   // Open the external interrupt 0, connect INT to the digital pin of the main control: 
    RGBButton.setRGBColor(RGBButton.eGreen);
    pinMode(LEDPin, OUTPUT);   }

void loop()
{   if (3 == flag) {   // When the button is pressed, an interrupt occurs, set RGB LED to blue
      RGBButton.setRGBColor(RGBButton.eBlue);
      digitalWrite(LEDPin,HIGH);  }
  if (4 == temp) {   // When the button is released, an interrupt occurs, change back to the color before it was pressed
      temp = 0;
      RGBButton.setRGBColor(RGBButton.eGreen);
      digitalWrite(LEDPin,LOW);  }
}

Result
After uploading the codes, the RGB LED on the button module turns on in green by default. When the button is pressed, it changes to blue and an interrupt occurs, and this time the external blue LED lights up. When the button released, the button RGB LED turns back to green, and the blue LED goes off.

7.1.8 Button Cascading

Designed with I2C, multiple modules are allowed to be cascaded without occupying additional ports. In this sample, six button modules will be cascaded and controlled independently without affecting each other.

Hardware Connection
Cascade 6 button modules, occupying only one I2C interface of the UNO mainboard.

Sample Code
6 button modules are cascaded, when button pressed, they show different colors. 

#include <DFRobot_RGBButton.h>
DFRobot_RGBButton RGBButton1(&Wire, /*I2CAddr*/ 0x23);   // Button 1
DFRobot_RGBButton RGBButton2(&Wire, /*I2CAddr*/ 0x24);   // Button 2
DFRobot_RGBButton RGBButton3(&Wire, /*I2CAddr*/ 0x25);   // Button 3
DFRobot_RGBButton RGBButton4(&Wire, /*I2CAddr*/ 0x26);   // Button 4
DFRobot_RGBButton RGBButton5(&Wire, /*I2CAddr*/ 0x27);   // Button 5
DFRobot_RGBButton RGBButton6(&Wire, /*I2CAddr*/ 0x28);   // Button 6

void setup(void)
{ Serial.begin(115200);
  while( ! RGBButton1.begin() ){
  Serial.println("1");
  delay(3000);}
  while( ! RGBButton2.begin() ){
    Serial.println("2");
    delay(3000);
  }
  while( ! RGBButton3.begin() ){
    Serial.println("3");
    delay(3000);
  }
  while( ! RGBButton4.begin() ){
  Serial.println("4");
  delay(3000);}
  while( ! RGBButton5.begin() ){
    Serial.println("5");
    delay(3000);
  }
  while( ! RGBButton6.begin() ){
    Serial.println("6");
    delay(3000);
  }
  Serial.println("Begin ok!\n");
  RGBButton1.setRGBColor(RGBButton1.eWhite);
  RGBButton2.setRGBColor(RGBButton2.eWhite);
  RGBButton3.setRGBColor(RGBButton3.eWhite);
  RGBButton4.setRGBColor(RGBButton4.eWhite);
  RGBButton5.setRGBColor(RGBButton5.eWhite);
  RGBButton6.setRGBColor(RGBButton6.eWhite);
}

uint8_t flag1 = 0, flag2 = 0, flag3 = 0, flag4 = 0, flag5 = 0, flag6 = 0;

void loop()
{  if( RGBButton1.getButtonStatus() ) {   // Button 1, show red LED when pressed
    flag1 = 1;
    RGBButton1.setRGBColor(RGBButton1.eRed);
    delay(50);
  } else if( 1 == flag1 ) {
    flag1 = 0;
    RGBButton1.setRGBColor(RGBButton1.eWhite);
  }

  if( RGBButton2.getButtonStatus() ) {   // Button 2, show orange LED when pressed
    flag2 = 1;
    RGBButton2.setRGBColor(RGBButton2.eOrange);
    delay(50);
  } else if( 1 == flag2 ) {
    flag2 = 0;
    RGBButton2.setRGBColor(RGBButton2.eWhite);
  }

  if( RGBButton3.getButtonStatus() ) {   // Button 3, show yellow LED when pressed
    flag3 = 1;
    RGBButton3.setRGBColor(RGBButton3.eYellow);
    delay(50);
  } else if( 1 == flag3 ) {
    flag3 = 0;
    RGBButton3.setRGBColor(RGBButton3.eWhite);
  }
   if( RGBButton4.getButtonStatus() ) {   // Button 4, show green LED when pressed
    flag4 = 1;
    RGBButton4.setRGBColor(RGBButton4.eGreen);
    delay(50);
  } else if( 1 == flag4 ) {
    flag4 = 0;
    RGBButton4.setRGBColor(RGBButton4.eWhite);
  }

  if( RGBButton5.getButtonStatus() ) {   // Button 5, show blue LED when pressed
    flag5 = 1;
    RGBButton5.setRGBColor(RGBButton5.eBlue);
    delay(50);
  } else if( 1 == flag5 ) {
    flag5 = 0;
    RGBButton5.setRGBColor(RGBButton5.eWhite);
  }

  if( RGBButton6.getButtonStatus() ) {   // Button 6, show purple LED when pressed
    flag6 = 1;
    RGBButton6.setRGBColor(RGBButton6.ePurple);
    delay(50);
  } else if( 1 == flag6 ) {
    flag6 = 0;
    RGBButton6.setRGBColor(RGBButton6.eWhite);
  }
}

Result

6 button modules are cascaded, they all show white color by default. When a button is pressed, its corresponding RGB LED shows the color set in the program. For example, press the first button, and its button light turns red.

7.1.9 Point Counter

In this sample, we will make a point counter using an OLED display with I2C interface and two button modules. First download the library file U8g2 Library, and install the library in the Arduino IDE as the way shown above.

Hardware Requirements

Display link: https://www.dfrobot.com/product-1576.html

Hardware Connection
Connect the interrupt pins (INT) of the two button modules to the digital pins 2 and 3 of the UNO board, and the OLED display to another I2C interface on the UNO mainboard.

Sample Code
Press a button to add points and press another one to deduct points, and show points changes on the display.

#include <DFRobot_RGBButton.h>
#include <U8g2lib.h>

DFRobot_RGBButton RGBButton_add(&Wire, /*I2CAddr*/ 0x23);
DFRobot_RGBButton RGBButton_sub(&Wire, /*I2CAddr*/ 0x24);
U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(/* rotation=*/U8G2_R0, /* reset=*/ U8X8_PIN_NONE);  
/* Interrupt flag */
volatile bool flag_add = false, flag_sub = false;
int add_num=0,sub_num=0,total=0;
/* External interrupt flag */
void interrupt_add()
{
  if(digitalRead(2)==HIGH){
    flag_add = true;
    add_num+=1;
  }else{
    flag_add = false;
  }
}
void interrupt_sub()
{
  if(digitalRead(3)==HIGH){
    flag_sub = true;
    sub_num+=1;
  }else{
    flag_sub = false;
  }
}
void setup(void)
{
  Serial.begin(115200);
  Wire.begin();

  u8g2.begin();
  u8g2.enableUTF8Print();
  u8g2.setFont(u8g2_font_t0_17b_tr  );
  Wire.setClock(100000);
  /**
   * @brief Init function
   * @return bool type, true if successful, false if error
   */
  while( ! RGBButton_add.begin() ){
    Serial.println("1!");
    delay(3000);
  }
  while( ! RGBButton_sub.begin() ){
    Serial.println("2!");
    delay(3000);
  }
  Serial.println("Begin ok!\n");
  attachInterrupt(/*Interrupt No*/0, interrupt_add, CHANGE);   // Open the external interrupt 0, connect INT to the digital pin of the main control:
  attachInterrupt(/*Interrupt No*/1, interrupt_sub, CHANGE);   // Open the external interrupt 0, connect INT to the digital pin of the main control:

}

void loop()
{

  Wire.setClock(100000);
  if(flag_add){
    RGBButton_add.setRGBColor(RGBButton_add.eRed);
  }else{
    RGBButton_add.setRGBColor(RGBButton_add.eBlue);
  }
  if(flag_sub){ 
    RGBButton_sub.setRGBColor(RGBButton_sub.eGreen);
  }else{
    RGBButton_sub.setRGBColor(RGBButton_sub.eBlue);
  }
  String str_add="ADD:"+String(add_num);
  String str_sub="DED:"+String(sub_num);
  String str_total="TOTAL:"+String(add_num-sub_num);
  u8g2.clearBuffer();          // clear the internal memory
  u8g2.setFont(u8g2_font_t0_17b_tr  );  // choose a suitable font
  u8g2.drawStr(0,10,str_add.c_str());  // write something to the internal memory
  u8g2.drawStr(0,30,str_sub.c_str());  // write something to the internal memory
  u8g2.drawStr(0,50,str_total.c_str());  // write something to the internal memory
  u8g2.sendBuffer();
}

Result

After uploading the codes, the two buttons light up blue. We can attach labels to them, the green for plus and red for minus. When pressed, the plus button lights up green and the minus button lights up red, and the points change can be clearly seen on the display.

8. API Function Library

  /**
   * @fn DFRobot_RGBButton
   * @brief Constructor
   * @param pWire - Wire object is defined in Wire.h, so just use &Wire and the methods in Wire can be pointed to and used
   * @param i2cAddr - RGBButton I2C address.
   * @return None
   */
  DFRobot_RGBButton(TwoWire *pWire=&Wire, uint8_t i2cAddr=RGBBUTTON_DEFAULT_I2C_ADDR);

  /**
   * @fn begin
   * @brief Init function
   * @return bool type, true if successful, false if error
   */
  bool begin(void);

  /**
   * @fn setRGBColor
   * @brief Set the basic seven colors, and white & black (white and black correspond to turning LED on and off respectively) or set the corresponding colors by setting RGB values
   * @param color - The corresponding values of the basic seven colors and white & black: 
   * @n  eRed, eOrange, eYellow, eGreen, eCyan, eBlue, ePurple, eWhite, eBlack
   * @param r - pulse width value of red LED
   * @param g - pulse width value of green LED
   * @param b - pulse width value of blue LED
   * @return None
   */
  void setRGBColor(eGeneralRGBValue_t color);
  void setRGBColor(uint8_t r, uint8_t g, uint8_t b);

  /**
   * @fn getButtonStatus
   * @brief Get button status
   * @return The current button status:
   * @retval   true - the button is pressed
   * @retval   false - the button is not pressed
   */
  bool getButtonStatus(void);

More Documents

DFR0991_STP 3D File.zip

DFR0991_2D_CAD.pdf

DFR0991_Circuit Schematics.pdf

FAQ

Q: Why does the button module sometimes not work after downloading the program?

A: First, check if the DIP switch address of the button module is set correctly; second, if you have changed the module I2C address during powering on, try powering down and reconnect.

Q: How many button modules can be cascaded?

A: Due to the limited communication distance of I2C, you can cascade up to 8 button modules by connecting them end to end or in the way of 1×3, etc.

For any questions, advice or cool ideas to share, please visit the DFRobot Forum.