.. note::

    Hello, welcome to the SunFounder Raspberry Pi & Arduino & ESP32 Enthusiasts Community on Facebook! Dive deeper into Raspberry Pi, Arduino, and ESP32 with fellow enthusiasts.

    **Why Join?**

    - **Expert Support**: Solve post-sale issues and technical challenges with help from our community and team.
    - **Learn & Share**: Exchange tips and tutorials to enhance your skills.
    - **Exclusive Previews**: Get early access to new product announcements and sneak peeks.
    - **Special Discounts**: Enjoy exclusive discounts on our newest products.
    - **Festive Promotions and Giveaways**: Take part in giveaways and holiday promotions.

    👉 Ready to explore and create with us? Click [|link_sf_facebook|] and join today!

.. _1.1.2_rgb_c_pi5:

1.1.2 RGB LED
====================

Introduction
--------------

In this lesson, we will use it to control an RGB LED to flash various
kinds of colors.

Components
--------------

.. image:: img/list_rgb_led.png
    :align: center

Principle
--------------

**PWM**

Pulse Width Modulation, or PWM, is a technique for getting analog
results with digital means. Digital control is used to create a square
wave, a signal switched between on and off. This on-off pattern can
simulate voltages in between full on (5 Volts) and off (0 Volts) by
changing the portion of the time the signal spends on versus the time
that the signal spends off. The duration of \"on time\" is called pulse
width. To get varying analog values, you change, or modulate, that
width. If you repeat this on-off pattern fast enough with some device,
an LED for example, the result would be like this: the signal is a
steady voltage between 0 and 5v controlling the brightness of the LED.

**Duty Cycle**

A duty cycle is the percentage of one period in which a signal is
active. A period is the time it takes for a signal to complete an
on-and-off cycle. As a formula, a duty cycle may be expressed as:

.. image:: img/image56.png
   :width: 1.16667in
   :height: 0.36458in
   :align: center

Where **D** is the duty cycle, **T** is the time the signal is active,
and **P** is the total period of the signal. Thus, a 60% duty cycle
means the signal is on 60% of the time but off 40% of the time. The \"on
time\" for a 60% duty cycle could be a fraction of a second, a day, or
even a week, depending on the length of the period.

.. image:: img/image57.jpeg
   :width: 4.325in
   :height: 5.49167in
   :align: center

**RGB LED**

.. image:: img/rgb_led_sch.png
    :width: 500
    :align: center

The three primary colors of the RGB LED can be mixed into various colors
by brightness. The brightness of LED can be adjusted with PWM. Raspberry
Pi has only one channel for hardware PWM output, but it needs three
channels to control the RGB LED, which means it is difficult to control
the RGB LED with the hardware PWM of Raspberry Pi. Fortunately, the
softPwm library simulates PWM (softPwm) by programming. You only need to
include the header file softPwm.h (for C language users), and then call
the API it provides to easily control the RGB LED by multi-channel PWM
output, so as to display all kinds of color.

Schematic Diagram
-----------------------

After connecting the pins of R, G, and B to a current limiting resistor,
connect them to the GPIO17, GPIO18, and GPIO27 respectively. The longest
pin (GND) of the LED connects to the GND of the Raspberry Pi. When the
three pins are given different PWM values, the RGB LED will display
different colors.

============ ======== ======== ===
T-Board Name physical wiringPi BCM
GPIO17       Pin 11   0        17
GPIO18       Pin 12   1        18
GPIO27       Pin 13   2        27
============ ======== ======== ===

.. image:: img/rgb_led_schematic.png

Experimental Procedures
----------------------------

**Step 1:** Build the circuit.

.. image:: img/image61.png
   :width: 6.59097in
   :height: 4.29722in

**Step 2:** Go to the folder of the code.

.. raw:: html

   <run></run>

.. code-block::

    cd ~/davinci-kit-for-raspberry-pi/c/1.1.2/

**Step 3:** Compile the code.

.. raw:: html

   <run></run>

.. code-block::

    gcc 1.1.2_rgbLed.c -lwiringPi

.. note::

    When the instruction \"gcc\" is executed, if \"-o\" is not called, then the executable file is named \"a.out\".

**Step 4:** Run the executable file.

.. raw:: html

   <run></run>

.. code-block::

    sudo ./a.out


After the code runs, you will see that RGB displays red, green, blue,
yellow, pink, and cyan.

.. note::

    If it does not work after running, or there is an error prompt: \"wiringPi.h: No such file or directory\", please refer to :ref:`install_wiringpi_pi5`.

**Code**

.. code-block:: c

    #include <wiringPi.h>
    #include <softPwm.h>
    #include <stdio.h>
    #define uchar unsigned char
    #define LedPinRed    0
    #define LedPinGreen  1
    #define LedPinBlue   2

    void ledInit(void){
        softPwmCreate(LedPinRed,  0, 100);
        softPwmCreate(LedPinGreen,0, 100);
        softPwmCreate(LedPinBlue, 0, 100);
    }

    void ledColorSet(uchar r_val, uchar g_val, uchar b_val){
        softPwmWrite(LedPinRed,   r_val);
        softPwmWrite(LedPinGreen, g_val);
        softPwmWrite(LedPinBlue,  b_val);
    }

    int main(void){

        if(wiringPiSetup() == -1){ //when initialize wiring failed, printf messageto screen
            printf("setup wiringPi failed !");
            return 1;
        }

        ledInit();
        while(1){
            printf("Red\n");
            ledColorSet(0xff,0x00,0x00);   //red     
            delay(500);
            printf("Green\n");
            ledColorSet(0x00,0xff,0x00);   //green
            delay(500);
            printf("Blue\n");
            ledColorSet(0x00,0x00,0xff);   //blue
            delay(500);
            printf("Yellow\n");
            ledColorSet(0xff,0xff,0x00);   //yellow
            delay(500);
            printf("Purple\n");
            ledColorSet(0xff,0x00,0xff);   //purple
            delay(500);
            printf("Cyan\n");
            ledColorSet(0xc0,0xff,0x3e);   //cyan
            delay(500);
        }
        return 0;
    }

**Code Explanation**

.. code-block:: c

    #include <softPwm.h>

Library used for realizing the pwm function of the software.

.. code-block:: c

    void ledInit(void){
        softPwmCreate(LedPinRed,  0, 100);
        softPwmCreate(LedPinGreen,0, 100);
        softPwmCreate(LedPinBlue, 0, 100);
    }

The function is to use software to create a PWM pin, set its period
between 0x100us-100x100us.

The prototype of the function softPwmCreate(LedPinRed, 0, 100) is as
follows:

.. code-block:: c

    int softPwmCreate(int pin,int initialValue,int pwmRange);

* **Parameter pin:** Any GPIO pin of Raspberry Pi can be set as a PWM pin.
* **Parameter initialValue:** The initial pulse width is that initialValue times100us.
* **Parameter pwmRange:** the period of PWM is that pwmRange times100us.

.. code-block:: c

    void ledColorSet(uchar r_val, uchar g_val, uchar b_val){
        softPwmWrite(LedPinRed,   r_val);
        softPwmWrite(LedPinGreen, g_val);
        softPwmWrite(LedPinBlue,  b_val);
    }

This function is to set the colors of the LED. Using RGB, the formal
parameter **r_val** represents the luminance of the red one, **g_val**
of the green one, **b_val** of the blue one.

The prototype of the function softPwmWrite(LedPinBlue, b_val) is as
follows：

.. code-block:: c

    void softPwmWrite (int pin, int value) ;

* **Parameter pin:** Any GPIO pin of Raspberry Pi can be set as a PWM pin.
* **Parameter Value:** The pulse width of PWM is value times 100us. Note that value can only be less than pwmRange defined previously, if it is larger than pwmRange, the value will be given a fixed value, pwmRange.

.. code-block:: c

    ledColorSet(0xff,0x00,0x00);

Call the function defined before. Write 0xff into LedPinRed and 0x00
into LedPinGreen and LedPinBlue. Only the Red LED lights up after
running this code. If you want to light up LEDs in other colors, just
modify the parameters.