# Raspberry Pi GPIOzero

1. [Materials needed](#materials-needed)
2. [GPIO pinout](#gpio_pinout)
3. [Analog vs. Digital](#analog-vs-digital)
4. [Blink](#blink)
5. [LED PWM](#led-pwm)
6. [Button](#button)
7. [Combining everything](#combining-everything)

Your Raspberry Pi is more than just a small computer, it is a hardware prototyping tool! The RPi has **bi-directional I/O pins**, which you can use to drive LEDs, spin motors, or read button presses. To drive the RPi's I/O lines requires a bit or programming. You can use a [variety of programing languages](http://elinux.org/RPi_GPIO_Code_Samples), but we decided to use a really solid, easy tools for driving I/O: **Python**.

### Materials needed

* Raspberry Pi 3 B
* [Breadboard](https://www.sparkfun.com/products/12002?_ga=1.251311686.1915117394.1476705504)
* [Jumper Wires(M/F)](https://www.sparkfun.com/products/12794)
* [Momentary Pushbutton Switch](https://www.sparkfun.com/products/9190?_ga=1.213562324.1915117394.1476705504)
* [Resistors](https://www.sparkfun.com/products/11507?_ga=1.213562324.1915117394.1476705504)
* [2 LEDs](https://www.sparkfun.com/products/9590?_ga=1.213548756.1915117394.1476705504)

###  GPIO Pinout

Raspberry has its GPIO over a standard male header on the board. From the first models to the latest, the header has expanded from 26 pins to 40 pins while maintaining the original pinout.

<p align="center">
<img src="../img/rpi_old_new_pin.jpg" alt="rpi" width="500">
</p>

There are (at least) two, different numbering schemes you may encounter when referencing **Pi pin numbers**:

1. **Broadcom (SoC) chip-specific** pin numbers.
2. **P1 physical** pin numbers.

You can use either number-system, but when you are programming how to use the pins, it requires that you declare which scheme you are using at the very beginning of your program. We will see this later.

The next table shows all 40 pins on the P1 header, including any particular function they may have, and their dual numbers:

<p align="center">
<img src="../img/header_pinout.jpg" alt="pin" width="500">
</p>

In the next table, we show another numbering system along with the ones we showed above: **Pi pin header numbers and element14 given names, wiringPi numbers, Python numbers, and related silkscreen on the wedge**. The Broadcom pin numbers in the table are related to RPi Model 2 and later only.

<p align="center">
<img src="../img/Pi_pin_header_numbers.png" alt="pin" width="500">
</p>

This table shows that the RPi not only gives you access to the bi-directional I/O pins, but also [Serial (UART)](https://learn.sparkfun.com/tutorials/serial-communication), [I2C](https://learn.sparkfun.com/tutorials/i2c), [SPI](https://learn.sparkfun.com/tutorials/serial-peripheral-interface-spi), and even some Pulse width modulation ([PWM](https://learn.sparkfun.com/tutorials/pulse-width-modulation) — “analog output”).  

There is a useful online guide for finding the assignment and numbering of each pin, along with other guides, that you may find useful at: [pinout.xyz](pinout.xyz)

##### Analog vs. Digital

Before starting with our practise, we will revise the difference between **analog** and **digital** signals. Both are used to transmit information, usually through **electric signals**. In both these technologies, the information, such as any audio or video, is transformed into electric signals. The **difference between analog and digital**:

* In **analog technology**, information is translated into electric pulses of varying amplitude.

* In **digital technology**, translation of information is into binary format (zero or one) where each bit is representative of two distinct amplitudes.

<img src="../img/analog_digital.png" alt="pin" style="width: 300px;"/>

##### Comparison chart

||Analog	|Digital|
|:------|:-------|:-------|
|**Signal**| Analog signal is a continuous signal which represents physical measurements.|	Digital signals are discrete time signals generated by digital modulation.|
|**Waves**|	Denoted by sine waves.|	Denoted by square waves.|
|**Representation**| Uses continuous range of values to represent information.|	Uses discrete or discontinuous values to represent information.|
|**Example**|	Human voice in air, analog electronic devices.|	Computers, CDs, DVDs, and other digital electronic devices.|
|**Technology**| Analog technology records waveforms as they are.|	Samples analog waveforms into a limited set of numbers and records them.|
|**Data transmissions**|Subjected to deterioration by noise during transmission and write/read cycle.|Can be noise-immune without deterioration during transmission and write/read cycle.|
|**Response to Noise**|	More likely to get affected reducing accuracy|	Less affected since noise response are analog in nature|
|**Flexibility**|	Analog hardware is not flexible.|Digital hardware is flexible in implementation.|
|**Uses**|Can be used in analog devices only. Best suited for audio and video transmission.|	Best suited for Computing and digital electronics.|
|**Applications**|Thermometer|PCs, PDAs|
|**Bandwidth**|	Analog signal processing can be done in real time and consumes less bandwidth.|	There is no guarantee that digital signal processing can be done in real time and consumes more bandwidth to carry out the same information.|
|**Memory**| Stored in the form of wave signal.|Stored in the form of binary bit.|
|**Power**|	Analog instrument draws large power.|	Digital instrument drawS only negligible power.|
|**Cost**|Low cost and portable.|	Cost is high and not easily portable.|
|**Impedance**|	Low	|High order of 100 megaohm|
|**Errors**|Analog instruments usually have a scale which is cramped at lower end and give considerable observational errors.|	Digital instruments are free from observational errors like parallax and approximation errors.|

### Blink
We will start with a very easy example, the classic "Blink" example, later we will do the same with our Arduino and see the differences.

##### Hardware Setup
We start assembling the circuit as shown in the diagram below.

![Wiring](../img/raspi-blink-wiring.png)

##### Code
For the code we are going to use the [GPIOzero](https://gpiozero.readthedocs.io/en/stable/) library which is a  on the GPIO library (https://sourceforge.net/p/raspberry-gpio-python/wiki/Home/).

1. From your laptop's terminal connect to the RPi
2. Create a folder called "code" and inside it a file called "blinker.py":
```bash
$ mkdir code
$ cd code
$ nano blinker.py
```
Note: you may not need to create a new folder everytime for the script. I.e. once you have created the folder code, you can create the scripts within the folder with nano <script name>. The command nano in this case is to open the nano editor.

3. Copy and paste this code:
```python
#!/usr/bin/env python

from gpiozero import LED
from time import sleep

led = LED(17)

while True:
    led.on()
    sleep(1)
    led.off()
    sleep(1)

```

4. Save and exit

5. Run this script with the command:
```bash
sudo python ./blinker.py
```
6. To stop the script from running press CTRL+C

7. To make the script an executable run:
```bash
$ sudo chmod u+x blinker.py
```
Now you can execute it with just this command:
```bash
$ ./blinker.py
```
8. Yay! The LED is blinking!

##### Understanding the "Blink" example

```python
#!/usr/bin/env python
```
This line is used to tell which interpreter (in our case Python) to use when the file is made into an executable.



When we use Python to control our GPIO pins, we always need to import the corresponding Python module, which goes at the top of the script:
```python
import gpiozero as gpio
```
Here, we are giving a shorter name to the module “GPIOzero”, in order to call the module through our script. This line is fundamental for every script requiring GPIO functions. If you want to import only certain classes from GPIOzero you could also sepcify the components. As an example, let's say if you are interested in only the LED:
```python
from gpiozero import LED
```
Or if want to use the Button and LED class.
```python
from gpiozero import LED, Button
```
And if we are just importing the function sleep from the [time library](https://www.tutorialspoint.com/python/time_sleep.htm), we will later use it to make the LED blink.
```python
from time import sleep
```

In the next line:
```python
led = LED(17)
```
Here we are creating a variable called `led` and we are initialising it with an object of the class [LED](https://gpiozero.readthedocs.io/en/stable/api_output.html#led). On object of the class LED to be initialised takes as a parameter the pin number to which the LED is connected to, in our case the pin number is 17 (GPIO17, not physical pin number 17).
**Note:** GPIOzero uses ONLY Broadcom (BCM) pin numbering, instead of physical pin numbering and it is not configurable, so when referring to pins in one of your scripts always use this numbering:  

![Broadcom](../img/broadcom_pin_layout.svg)



```python
while True:
```
Here we are are basically asking to Python to loop forever. In fact the `while` statements loops through its code until the initial condition becomes false, in our case never.



```python
led.on()
sleep(1)
led.off()
sleep(1)
```
Here we are using two methods of the class [LED](https://gpiozero.readthedocs.io/en/stable/api_output.html#led) pf GPIOzero. `on()` switches the device on and `off` turns it off. We are calling the two functions with a 1 second interval, in fact the function `sleep` suspends execution for the given number of seconds.

### LED PWM
Use the same layout for the electronics as before.

##### What is 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 (3.3 Volts for RPi and 5 Volts for Arduino) 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 the pulse width. To get varying analog values, you change, or modulate, that pulse width. If you repeat this on-off pattern fast enough with an LED for example, the result is as if the signal is a steady voltage between 0 and 5v controlling the brightness of the LED.

For more information check out [this link](https://learn.sparkfun.com/tutorials/pulse-width-modulation).

##### Code
Repeat the same steps of "Blink" to upload the code below, this time call the file *led-pwm.py* and save it in the *code* folder that we have previously created. It's up to you to make the code executable or not.
```python
#!/usr/bin/env python

from gpiozero import PWMLED
from time import sleep

led = PWMLED(17)

while True:
    led.value = 0  # off
    sleep(1)
    led.value = 0.5  # half brightness
    sleep(1)
    led.value = 1  # full brightness
    sleep(1)
```

##### Understanding "LED PWM" code

The main difference here is that we are using the [class PWMLED](https://gpiozero.readthedocs.io/en/stable/api_output.html#gpiozero.PWMLED) instead of the class LED. The PWMLED class has an extra parameter that we can tweak which is `value`. `value` indicates the duty cycle of this PWM device. 0.0 is off, 1.0 is fully on. Values in between may be specified for varying levels of power in the device.

### Button

##### Hardware Setup
We start assembling the circuit as shown in the diagram below.

![Wiring](../img/button-wiring.png)

##### Code
Repeat the same steps of "Blink" to upload the code below, this time call the file *button.py* and save it in the *code* folder that we have previously created. It's up to you to make the code executable or not.

```python
#!/usr/bin/env python

from gpiozero import Button

button = Button(2)
buttonWasPressed = False # 1st flag
buttonWasReleased = False # 2nd flag

while True:
    if button.is_pressed:
        buttonWasReleased = False
        if not buttonWasPressed:
            print("Button is pressed")
            buttonWasPressed = True
    else:
        buttonWasPressed = False
        if not buttonWasReleased:
            print("Button is released")
            buttonWasReleased = True
```

##### Understanding "Button" code
Here we are using the [class Button](https://gpiozero.readthedocs.io/en/stable/api_input.html#button) from GPIOzero. This class has many functions and parameter, so make sure you check out the reference. Here we are using the `is_pressed` property of the class. `is_pressed` returns True if the device is currently active and False otherwise.

In this example, we also introduce the concept of flags. Flags are a way to help us keep track of the binary state of a particular thing by storing them as boolean variables (1/0 or True/False). In this case, we need to keep track of the binary state of whether the button is was pressed, and the binary state of whether the button was released.  

> **Note** that we need to keep track of the _actions_ that occured, not the state of the button itself as this is already monitored `is_pressed` property of the `Button()` class.

In the code above, we use these flags to prevent the repetition of a print statement. i.e. If we did not have them, then the _"Button is released"_ statement would print repetitively until the button was pressed, and vice versa.

Flags allow us to ensure the print statement is only _printed_ on the first iteration of the loop. Every iteration thereafter will skip the print statement. This occurs until there is a change in the `is_pressed` property, at which point the respective flag is reset to `False`.


### Combining Everything

Now we challenge you to combine all the previous three scripts to create one. Make the script in order that:
* when the button is pressed one of the two leds fades to 25% of its brightness and the other one blinks once
* when the button is released the pwmled goes back to 100% brightness.

##### Hardware Setup
We start assembling the circuit as shown in the diagram below.

![Wiring](../img/practise_1.png)

##### Code Tips
Use the `when_pressed` and `when_released` properties of the [Button class](https://gpiozero.readthedocs.io/en/stable/api_input.html#button).
[Here](https://gpiozero.readthedocs.io/en/stable/recipes.html#button-controlled-led) you can find the code to control one LED with the button.

###### Acknowledgement:
<small>Based on the GPIOzero library [notes](https://gpiozero.readthedocs.io/en/stable/index.html) and [this reference](http://www.diffen.com/difference/Analog_vs_Digital) and [this intro](https://learn.sparkfun.com/tutorials/raspberry-gpio). </small>