======PROJECT======
PROJECT: Colored LED Research (clr2)

=====Objective=====
A mild throwback to the ledX projects, where we find ourselves once again playing with an LED, only an LED of MANY colours: the RGB LED!

We will be integrating buttons and a switch to allow finer, manual control over the individual red, green, blue values of the LED.
=====Abstraction=====
{{page>haas:fall2020:common:projects:abstraction&noheader}}

=====Locational Awareness=====
{{page>haas:fall2020:common:projects:location&noheader}}

=====Reading=====
In "The C Book", please read through Chapter 8.

Review needed concepts in [[https://www.tutorialspoint.com/cprogramming/|this tutorial]] and also [[https://www.cprogramming.com/tutorial/c-tutorial.html?inl=hp|this one]]

ALSO: read through Chapter 5 in the [[https://lab46.g7n.org/downloads/tutorial.pdf|FreeNove Tutorial]]

AND: the wiringPi API on [[http://wiringpi.com/reference/software-pwm-library/|Sofware PWM functionality]]

=====Background=====
For this project, you will be working with a C program using the wiringPi library on the Raspberry Pi, wiring up a circuit containing an RGB LED to your breadboard and witnessing your ability to access and control it in varying states of on and off (more than just simply "ON" and "OFF") via a software-based Pulse Width Modulation (PWM) scheme.

With the help of buttons and a switch, we will be able to allow the user to manually adjust the individual red, green, and blue values of the RGB LED,
=====Loops=====
{{page>haas:fall2020:common:projects:loops&noheader}}

=====Input and Output via the GPIO pins on the pi=====
One of the intended uses of the Raspberry Pi and other small, single board computers is as an interface tool to peripherals in projects, personal and industrial.

The pi has a set of **General Purpose Input Output** (GPIO) pins intended for precisely this purpose:

{{ :haas:fall2020:common:projects:gpio-pinout-diagram-2.png |}}

Please note the orientation of the pi (ethernet/USB at bottom) to calibrate yourself to the location of pin 1 and all subsequent pins, along with their identified function (ie top left pin, pin 1, provides a constant 3.3v DC power)

We can also get a live update on the state of each pin on our pi itself, using the '**gpio readall**' command at our pi prompt:

<cli>
yourpi:~/src/desig/clr1$ gpio readall
 +-----+-----+---------+------+---+---Pi 4B--+---+------+---------+-----+-----+
 | BCM | wPi |   Name  | Mode | V | Physical | V | Mode | Name    | wPi | BCM |
 +-----+-----+---------+------+---+----++----+---+------+---------+-----+-----+
 |     |     |    3.3v |      |   |  1 || 2  |   |      | 5v      |     |     |
 |   2 |   8 |   SDA.1 | ALT0 | 1 |  3 || 4  |   |      | 5v      |     |     |
 |   3 |   9 |   SCL.1 | ALT0 | 1 |  5 || 6  |   |      | 0v      |     |     |
 |   4 |   7 | GPIO. 7 |   IN | 0 |  7 || 8  | 1 | ALT5 | TxD     | 15  | 14  |
 |     |     |      0v |      |   |  9 || 10 | 1 | ALT5 | RxD     | 16  | 15  |
 |  17 |   0 | GPIO. 0 |   IN | 0 | 11 || 12 | 0 | IN   | GPIO. 1 | 1   | 18  |
 |  27 |   2 | GPIO. 2 |   IN | 0 | 13 || 14 |   |      | 0v      |     |     |
 |  22 |   3 | GPIO. 3 |   IN | 0 | 15 || 16 | 0 | IN   | GPIO. 4 | 4   | 23  |
 |     |     |    3.3v |      |   | 17 || 18 | 0 | IN   | GPIO. 5 | 5   | 24  |
 |  10 |  12 |    MOSI |   IN | 0 | 19 || 20 |   |      | 0v      |     |     |
 |   9 |  13 |    MISO |   IN | 0 | 21 || 22 | 0 | IN   | GPIO. 6 | 6   | 25  |
 |  11 |  14 |    SCLK |   IN | 0 | 23 || 24 | 1 | IN   | CE0     | 10  | 8   |
 |     |     |      0v |      |   | 25 || 26 | 1 | IN   | CE1     | 11  | 7   |
 |   0 |  30 |   SDA.0 |   IN | 1 | 27 || 28 | 1 | IN   | SCL.0   | 31  | 1   |
 |   5 |  21 | GPIO.21 |   IN | 1 | 29 || 30 |   |      | 0v      |     |     |
 |   6 |  22 | GPIO.22 |   IN | 1 | 31 || 32 | 0 | IN   | GPIO.26 | 26  | 12  |
 |  13 |  23 | GPIO.23 |   IN | 0 | 33 || 34 |   |      | 0v      |     |     |
 |  19 |  24 | GPIO.24 |   IN | 0 | 35 || 36 | 0 | IN   | GPIO.27 | 27  | 16  |
 |  26 |  25 | GPIO.25 |   IN | 0 | 37 || 38 | 0 | IN   | GPIO.28 | 28  | 20  |
 |     |     |      0v |      |   | 39 || 40 | 0 | IN   | GPIO.29 | 29  | 21  |
 +-----+-----+---------+------+---+----++----+---+------+---------+-----+-----+
 | BCM | wPi |   Name  | Mode | V | Physical | V | Mode | Name    | wPi | BCM |
 +-----+-----+---------+------+---+---Pi 4B--+---+------+---------+-----+-----+
</cli>

Yes, it may be packed with information, but it is an informative, technical reference.

Why is this so layered and directed, you may ask? Well, it is a matter of competing standards (approaches to identification of each pin, based on particular reference points).

For example, the "Physical" columns (dead center) in the center conform to the image diagram I posted above of the 40 pins (where pin 1 is the top-left).

The "BCM" columns (far left and far right) refer to the hardware identifications for each pin by the manufacturer. You might notice that BCM pin 17 (physical pin 11) corresponds to wPi pin 0.

And the "wPi" columns (second from left, and second from right), correspond to the pin identifications as use by the wiringPi library, which we are using here.

Additionally, we see "Mode" and "V" columns; mode informs us of the operating mode of that pin at present configuration (IN means it is configured for INPUT, OUT means it is configured for OUTPUT). V implies voltage on the pin (0 means no voltage, 1 means there is voltage present at time of checking). For this project, we will be configuring a specific pin to OUTPUT mode, and modulating it between a state of ON (1) and OFF (0).

So, in exploring the use of the table: if we wanted to hook a component up to wiringPi pin #0, that corresponds to manufacturer (BCM) pin 17, which is physical pin 11.

You will want to verify placement before supplying power, that is why we are taking things slow, and providing you opportunities to confirm (by posting pictures in the discord channel) before proceeding.

It may seem a bit bewildering or overwhelming at first, but like anything, time and exposure will ensure it becomes increasingly second nature.

====Grabbing project resources (on lab46)====
I have prepared a **grabit** for resources related to this project. To obtain:

<cli>
lab46:~/src/desig$ grabit desig clr2
make: Entering directory '/var/public/SEMESTER/desig/clr2'
'/var/public/SEMESTER/desig/clr2/Makefile' -> '/home/user/src/desig/clr2/Makefile'
'/var/public/SEMESTER/desig/clr2/clr2.c' -> '/home/user/src/desig/clr2/clr2.c'
make: Leaving directory '/var/public/SEMESTER/desig/clr2'
lab46:~/src/desig$ 
</cli>

At which point you can change into the newly created and populated **clr2/** directory.

====Getting project resources from lab46 to your pi====
Okay, you've snagged the project files on lab46. Now, how to get them to your pi?

The same way you've been juggling project files already, by using your mercurial repository!

Using the **hg** tool, be sure to **add**, **commit**, and **push** successfully on lab46.

Then, over on your pi, use **hg** to **pull** and **update** the new changes into place. Then you can proceed.

=====Wiring up our circuit=====
Please reference the [[https://lab46.g7n.org/downloads/tutorial.pdf|FreeNove Tutorial]], Chapter 5, Project 5.1 for the parts and circuit diagram. 

The RGB LED circuit for this project remains identical to that of clr0 and clr1. New will be the buttons and switch circuits that are added.

You will want to add THREE button circuits, each connected to a unique GPIO. You can utilize the plastic button caps to help identify which button is which. Each button will be directly responsible for adjusting the current level of colour intensity (ie pressing the button intended to adjust the red component of the RGB LED will adjust the red value).

You will also want to utilize a switch, which looks like this:

{{ :haas:fall2020:common:projects:switch.png |}}

Your kit should have come with two of them, you will need ONE.

The switch circuit will involve hooking up 3.3v to the center pin, putting a 1k resistor between the pin of the switch and the 3.3v source coming from the pi. And ONE of the other pins should then go through a 10k resistor into a GPIO pin on the pi (set to INPUT mode, just like the buttons).

This switch is going to control the DIRECTION of change- one way, it will be INCREASING in value. The other, it will be DECREASING.

So, your ultimate circuit will have FOUR independent inputs- red control, green control, and blue control (all buttons), and then the DIRECTION switch (increase/decrease). FOUR GPIOs in INPUT mode are needed.

====Final result====
Once all connected, your circuit should allow for directional, per-colour adjustment of each of the three colours. Here's an animated gif of one such circuit in action:

{{ :haas:fall2020:common:projects:clr2_working_example.gif |}}
=====Program=====
Your program to implement for this project involves using the wired up RGB LED, the three buttons, and the switch, to do the following:

  * switch control direction of adjustment (increasing in value or decreasing in value)
  * each button allows you to adjust the value of a particular colour component of the RGB LED. It is recommended that you use the button caps of the respective colour (put the red cap on the red adjustment button, for instance)
  * display the current RGB values on the RGB LED.
  * please have some sort of minimal delay in your program... no shorter than 100mS
=====Compiling=====
Since the grabit brought in a Makefile, you can compile your code simply by typing: **make**

Any compiler errors will go into a text file called **errors**

To do a full cleaning, run: **make clean** then **make** (or **make debug**)

If you'd like to see compiler messages as you compile, run: **make debug**

When done and ready to submit, on lab46: **make submit**

=====Strategy=====
In general, you will want your completed program to perform in the manner described as follows (in English-like pseudocode):

<code>
LOOP TO KEEP PROGRAM GOING

        IF SWITCH IS IN POSITION 1:
                DIR <- +10
        ELSE
                DIR <- -10
        END IF

        IF RED BUTTON IS PRESSED:
                REDCOLOR <- REDCOLOR + DIR
        END IF

        IF GREEN BUTTON IS PRESSED:
                GREENCOLOR <- GREENCOLOR + DIR
        END IF

        IF BLUE BUTTON IS PRESSED:
                BLUECOLOR <- BLUECOLOR + DIR
        END IF

        SETRED(REDCOLOR)
        SETGREEN(GREENCOLOR)
        SETBLUE(BLUECOLOR)

        DELAY

END LOOP
</code>
=====Submission=====
To successfully complete this project, the following criteria must be met:

  * Code must compile cleanly (no notes, warnings, nor errors)
  * Output must be correct, and match the form given in the sample output above.
  * Code must be nicely and consistently indented
  * Code must be well commented
  * Do NOT double space your code. Group like statements together.
  * Output Formatting (including spacing) of program must conform to the provided output (see above).
  * Track/version the source code in a repository
  * Submit a copy of your source code to me using the **submit** tool.
  * Post required images and obtain needed confirmation to proceed from me on class channel on discord.

To submit this program to me using the **submit** tool, run the following command at your lab46 prompt:

<cli>
lab46:~/src/desig/clr2$ submit desig clr2 clr2.c
Submitting desig project "clr2":
    -> clr2.c(OK)

SUCCESSFULLY SUBMITTED
</cli>

You should get some sort of confirmation indicating successful submission if all went according to plan. If not, check for typos and or locational mismatches.

What I'll be looking for:

<code>
91:clr2:final tally of results (91/91)
*:clr2:post picture of unpowered layout to #desig and get approval [13/13]
*:clr2:post picture to #desig by Sunday before deadline [13/13]
*:clr2:post picture of powered layout to #desig [13/13] 
*:clr2:grabit on the code on lab46 by Sunday before deadline [13/13]
*:clr2:clr2.c code adequately modified per project requirements [26/26]
*:clr2:updated code is pushed to lab46 repository [13/13]
</code>

Additionally:
  * Solutions not abiding by spirit of project will be subject to a 25% overall deduction
  * Solutions not utilizing descriptive why and how comments will be subject to a 25% overall deduction
  * Solutions not utilizing indentation to promote scope and clarity will be subject to a 25% overall deduction
  * Solutions not organized and easy to read are subject to a 25% overall deduction