L3_PythonGUIsAndHardware/L3_PythonGUIsAndHardware.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "4efaf6be",
   "metadata": {},
   "source": [
    "# `L3`: Lecture 3: Graphical User Interfaces & Raspberry Pi \n",
    "\n",
    "In the KT2505 course, we are going to work with the Raspberry Pi to set up a Portable Balance Lab (PBL). This lecture provides an introduction on the Raspberry Pi. Interfacing the sensory set-up with a (simple) interface will be helpfull during your measurements.The first section in this lecture provides an introduction on how to build a simple GUI with Python.\n",
    "\n",
    "\n",
    "__Outline:__\n",
    "  * [1. Graphical User Interface](#Ch1)\n",
    "      * [1.1 Guizero](#Ch11)\n",
    "      * [1.2 Create an interface](#Ch12)\n",
    "      * [1.3 Example: Temperature converter](#Ch13)\n",
    "      * [1.4 Pop-Ups](#Ch14)\n",
    "          * [1.4.1 Example: yes no question](#Ch141)\n",
    "          * [1.4.2 Example: 'Select file'- dialog box](#Ch142)\n",
    "          * [1.4.3 Test yourself example: 'Edit and save file'- dialog box](#Ch143)\n",
    "          * [1.4.4 Menus](#Ch144)      \n",
    "  * [2. What is the Raspberry Pi?](#Ch2)\n",
    "      * [2.1 What can you do with a Raspberry Pi? ](#Ch21)\n",
    "  * [3. Interfacing hardware](#Ch3)\n",
    "      * [3.1 GPIO Pin Connections](#Ch31)\n",
    "          * [3.1.1 Pin functions](#Ch311)\n",
    "          * [3.1.2 Serial Interface Pins](#Ch312)\n",
    "          * [3.1.3 Power Pins](#Ch313)\n",
    "          * [3.1.4 Hat Pins](#Ch314)\n",
    "          * [3.1.5 Breadboarding with Jumper Wires](#Ch315)\n",
    "      * [3.2 Digital Outputs](#Ch32)\n",
    "      * [3.3 Analog Outputs - Pulse Width Modulation](#Ch33)\n",
    "      * [3.4 Digital Inputs](#Ch34)\n",
    "      * [3.5 Analog Inputs](#Ch35)\n",
    "          * [3.5.1 Measuring resistance](#Ch351)\n",
    " "
   ]
  },
  {
   "attachments": {
    "image.png": {
     "image/png": "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"
    }
   },
   "cell_type": "markdown",
   "id": "f909d8fd",
   "metadata": {},
   "source": [
    "## 1. Graphical User Interface  <a class=\"anchor\" id=\"Ch1\"></a>\n",
    "\n",
    "In this lecture we are going to create graphical user interfaces (GUIs). These will come in use when setting up and running your experiments.\n",
    " \n",
    "### 1.1 Guizero <a class=\"anchor\" id=\"Ch11\"></a>\n",
    "\n",
    "There are many Python libraries for creating GUIs, but in this lecture we are going to work with `guizero`, which was specifically created for the Raspberry Pi.\n",
    "\n",
    "The guizero package is pre-installed on all Rapberry Pi's. However, if we want to use the same module on our own machine we need to install the module first.\n",
    " \n",
    "#### Windows\n",
    "\n",
    "1. Open a command prompt by clicking Start > Windows System > Command Prompt, or by typing 'command' into the start menu's search bar.\n",
    "\n",
    "2. Type this command and press enter:\n",
    "\n",
    "```bash\n",
    "    pip3 install guizero\n",
    "```\n",
    "\n",
    "\n",
    "#### Mac\n",
    "\n",
    "1. Open a terminal window by clicking Applications > Utilities > Terminal, or by typing 'terminal' into the desktop's search bar.\n",
    "2. Type this command and press enter:\n",
    "\n",
    "```bash\n",
    "    pip3 install guizero\n",
    "```\n",
    "\n",
    "#### Linux\n",
    "\n",
    "1. Open a terminal\n",
    "2. Install tkinter using your distribution's package manager, e.g. `sudo apt install python3-tk`\n",
    "3. Install guizero using pip by typing `pip3 install guizero` or `sudo pip3 install guizero` if you don't have superuser rights\n",
    " \n",
    " (Help: https://lawsie.github.io/guizero/)\n",
    " \n",
    "#### Raspberry Pi\n",
    " \n",
    " If you are working on the Raspberry Pi, make sure the package is up to date by updating it:\n",
    " \n",
    "1. Open the terminal on the Raspberry Pi. The terminal icon looks like: <img src=\"attachment:image.png\" alt=\"image\" style=\"width:50px;height:50px;\"> \n",
    "2. Run the following command:\n",
    "\n",
    "```bash\n",
    "    sudo pip3 install --upgrade guizero\n",
    "```\n",
    "    \n",
    "#### Troubleshooting\n",
    "\n",
    "* If 'command prompt' can not be found, try to find 'Anaconda prompt' and follow the steps\n",
    "\n",
    "* If 'pip3' does not work but results in error _'pip3 is not recognized as an internal or external command, operable program or batch file.'_ , try `pip install guizero`\n",
    "    \n",
    "### 1.2 Create an interface <a class=\"anchor\" id=\"Ch12\"></a>\n",
    "\n",
    "Let's run a first example with the `guizero` package:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7d07c5eb",
   "metadata": {},
   "outputs": [],
   "source": [
    "from guizero import App, Text\n",
    "\n",
    "app = App()\n",
    "Text(app, text=\"KT2505\")\n",
    "app.display()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3daab169",
   "metadata": {},
   "source": [
    "We import two things from the `guizero` library: `App` represents the application window and `Text` represents a text label that we are going to use to hold our 'KT2505' text. A new `App` is created and assigned to the variable `app`. We then make a `Text`, passing it `app` as its first parameter so that the text label will appear inside the application window. Finally, we call `app.display()` to make the window visible. You can just close the window by clicking on the _x_ in the top right, or stop the program."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "09766046",
   "metadata": {},
   "source": [
    "### 1.3 Example: Temperature converter <a class=\"anchor\" id=\"Ch13\"></a>\n",
    "\n",
    " To get started with guizero, you'll gradually build up an application that provides a GUI for temperature conversion. This application will use the `converter` module that we created in Lecture 2. The first step is to create the following interface, but it doesn't function yet:\n",
    "\n",
    "![image.png](images/temp_conv.png)\n",
    " "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2256d5c0",
   "metadata": {},
   "outputs": [],
   "source": [
    "# we need several things from guizero, so we import everything (*):\n",
    "from guizero import *\n",
    "\n",
    "app = App(title=\"Temp Converter\", layout=\"grid\", width=300, height=100)\n",
    "\n",
    "Text(app, text=\"degrees C\", grid=[0,0])\n",
    "degCfield = TextBox(app, grid=[1,0], width=\"fill\")  #\"fill\" enlarges the control to fill the cell\n",
    "\n",
    "Text(app, text=\"degrees F\", grid =[0,1])\n",
    "degFfield = Text(app, grid=[1,1])\n",
    "\n",
    "button = PushButton(app, text=\"Convert\", grid=[0,2])\n",
    "\n",
    "app.display()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bf031d68",
   "metadata": {},
   "source": [
    "After the import, we first create an `App`, like we did before but this time it has some additional parameters: a `title` which will appear in the window title area and the starting window size (`width` and `height`) in pixels.\n",
    "\n",
    "The other parameter (`layout ='grid'`) specifies that we are going to lay out the components in the window in a grid. This means that for each component we add to the screen, we will have to specify its grid position. You can see this in the first Text label (degrees C), which specifies a grid position of [0,0], which means top left.\n",
    "\n",
    "By using a grid layout we can line up the fields into columns and rows. Here, the grid layout has three rows and two colomns. The first row contains the label and the field to enter temperature, the second row has a label and a field to show the result in Fahrenheit, and the third row contains the button.\n",
    "\n",
    "The example above has a button, but the button doesn't do anything yet. To create a functioning interface, check out the following code:\n",
    "\n",
    "(this code uses the `converters.py` module that you created in the [previous lecture](../L2_PythonClassesAndWritingFiles/L2_PythonClassesAndWritingFiles.ipynb))\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7571f31a",
   "metadata": {},
   "outputs": [],
   "source": [
    "from guizero import *\n",
    "\n",
    "# now load the converter module from the previous lecture\n",
    "from converters import ScaleAndOffsetConverter\n",
    "\n",
    "c_to_f_conv = ScaleAndOffsetConverter('C','F',1.8,32)\n",
    "\n",
    "# We need a function that converts the input in C to the output in F. We use the module for this\n",
    "def convert():\n",
    "    c = float(degCfield.value)\n",
    "    degFfield.value = str(c_to_f_conv.convert(c))\n",
    "\n",
    "app = App(title=\"Temp Converter\", layout=\"grid\", width=300, height=100)\n",
    "Text(app, text=\"degrees C\", grid=[0,0])\n",
    "degCfield = TextBox(app, grid=[1,0], width=\"fill\") \n",
    "\n",
    "Text(app, text=\"degrees F\", grid=[0,1])\n",
    "degFfield = Text(app, grid=[1,1])\n",
    "\n",
    "# here we now need to add a command to convert the input. \n",
    "# This refers to the def specified above\n",
    "button = PushButton(app, text=\"Convert\", grid=[0,2], command=convert)\n",
    "\n",
    "app.display()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dcc14346",
   "metadata": {},
   "source": [
    "#### 1.3.1 Other GUI Widgets\n",
    "In the temperature converter we just used text fields and labels. There are of course many other controls you can use in your interface. All documentation on the controls can be found on the official [guizero website](https://lawsie.github.io/guizero/). \n",
    "To get you started, the following example contains many of the controls:\n",
    "\n",
    "![image.png](images/control_dump.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e6d3e920",
   "metadata": {},
   "outputs": [],
   "source": [
    "from guizero import *\n",
    "\n",
    "app = App(title=\"Control Dump\", layout=\"grid\", width=400, height=400)\n",
    "\n",
    "# Row 0\n",
    "Text(app, text=\"label\", grid=[0,0])\n",
    "TextBox(app, grid=[1,0])\n",
    "PushButton(app, text=\"Button\", grid=[2,0])\n",
    "\n",
    "# Row 1\n",
    "CheckBox(app, text=\"Checkbox\", grid=[0,1])\n",
    "ListBox(app, items=[\"Lab 1\", \"Lab 2\", \"Lab 3\"], grid=[1,1])\n",
    "Combo(app, options=[\"Lab 1\", \"Lab 2\", \"Lab 3\"], grid=[2,1])\n",
    "\n",
    "# Row 2\n",
    "ButtonGroup(app, options=[\"Neuro\",\"Sign\"], selected=\"Sign\", grid=[0,2])\n",
    "Slider(app, start=0, end=10, grid=[1,2])\n",
    "Picture(app, image=\"images/TU_delft-logo.jpg\", width=200, height=80, grid=[1,3])\n",
    "\n",
    "app.display()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4f61bfdc",
   "metadata": {},
   "source": [
    "### 1.4 Pop-Ups <a class=\"anchor\" id=\"Ch14\"></a>\n",
    "\n",
    "There will be situations where you'd like a pop-up for your program, for example to ask a question (save: yes or no?) or to select a file to open. There is a [big selection of pop-ups](https://lawsie.github.io/guizero/) that you can use from guizero. We have provided some usefull examples here. \n",
    "\n",
    "##### 1.4.1 Example: yes no question <a class=\"anchor\" id=\"Ch141\"></a>\n",
    "\n",
    "![image.png](images/yes_no.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ef210594",
   "metadata": {},
   "outputs": [],
   "source": [
    "from guizero import *\n",
    "\n",
    "def ask():\n",
    "    if yesno(\"Question\", \"Yes or No?\"):\n",
    "        info(\"Result\",\"You clicked Yes\")\n",
    "    else:\n",
    "        warn(\"Result\",\"You clicked no\") # the difference between 'info' and 'warn': warn shows a warning icon\n",
    "        \n",
    "app = App(title=\"Pop-Ups\", width=200, height=100)\n",
    "button = PushButton(app, text=\"Click me\", command=ask)\n",
    "app.display()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cc05fe9a",
   "metadata": {},
   "source": [
    "##### 1.4.2 Example: 'Select file'- dialog box  <a class=\"anchor\" id=\"Ch142\"></a>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e4be6b01",
   "metadata": {},
   "outputs": [],
   "source": [
    "from guizero import *\n",
    "\n",
    "def ask():\n",
    "    filename = select_file(title=\"Choose a text file\", filetypes=[[\"*.md\",\"*.txt\"]])\n",
    "    if not filename:\n",
    "        print(\"No file selected\")\n",
    "    else:\n",
    "        read_file(filename)\n",
    "        \n",
    "def read_file(filename):\n",
    "    f = open(filename)\n",
    "    text = f.read()\n",
    "    f.close()\n",
    "    text_area.value = text\n",
    "    \n",
    "app = App(width=600, height=200)\n",
    "text_area = TextBox(app, width=\"fill\", height=10, multiline=True, scrollbar=True)\n",
    "button = PushButton(app, text=\"Open\", command=ask)\n",
    "app.display()\n",
    "            "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dc215d19",
   "metadata": {},
   "source": [
    "##### 1.4.3 ❓ Test Yourself: 'Edit and save file'- dialog box  <a class=\"anchor\" id=\"Ch143\"></a>\n",
    "\n",
    "This app lets you open and read a text file. You can edit the text, however you can't save it yet. Try to add a save button to save the edits you make.\n",
    "\n",
    "1. Open file: `\"notes_experiments.txt\"`\n",
    "2. Make some changes to the file and save it again"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0827b22a",
   "metadata": {},
   "outputs": [],
   "source": [
    "from guizero import *\n",
    "\n",
    "def ask():\n",
    "    filename = select_file(title=\"Choose a text file\", filetypes=[[\"*.md\",\"*.txt\"]])\n",
    "    if not filename:\n",
    "        print(\"No file selected\")\n",
    "    else:\n",
    "        read_file(filename)\n",
    "        \n",
    "def read_file(filename):\n",
    "    f = open(filename)\n",
    "    text = f.read()\n",
    "    f.close()\n",
    "    text_area.value = text\n",
    "    \n",
    "def save_file():\n",
    "    \n",
    "    #❓ test yourself: write your own code here\n",
    "    \n",
    "   \n",
    "    \n",
    "app = App(width=600, height=200)\n",
    "text_area = TextBox(app, width=\"fill\", height=10, multiline=True, scrollbar=True)\n",
    "button = PushButton(app, text=\"Open\", command=ask, align=\"left\")\n",
    "button2 = PushButton(app, text=\"Save\", command=save_file, align=\"right\")\n",
    "app.display()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2e7de9c1",
   "metadata": {},
   "source": [
    "#### 1.4.4 Menus  <a class=\"anchor\" id=\"Ch144\"></a>\n",
    "\n",
    "The guizero also provides a way of adding [menus](https://lawsie.github.io/guizero/menubar/) to the application. Check out the website for examples!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c64a8623",
   "metadata": {},
   "source": [
    "## 2. What is the Raspberry Pi? <a class=\"anchor\" id=\"Ch2\"></a>\n",
    "\n",
    "The Raspberry Pi is a computer that runs the Linux operating system. It has USB sockets you can plug a keyboard and mouse into\n",
    "and HDMI (High-Definition Multimedia Interface) video output you can connect a TV or monitor into. \n",
    "When Raspberry Pi boots up, you get the Linux desktop:\n",
    "\n",
    "![image-3.png](images/pixel1.jpg)\n",
    "\n",
    "This really is a proper computer, able to run an office suite, video playback capabilities, games, and the lot. It’s not Microsoft Windows; instead, it is Windows’ open source rival Linux (Debian Linux), and the windowing environment is called Pixel.\n",
    "\n",
    "It’s small (the size of a credit card) and extremely affordable. Part of the reason for this low cost is that some components are not included with the board or are optional extras. For instance, it does not come in a case to protect it—it is just a bare board. Nor does it come with a power supply, so you will need to find yourself a 5V micro-USB power supply, much like you would use to charge a phone (the power supply capable of supplying 2A and 3A is recommended). \n",
    "\n",
    "### 2.1 What can you do with a Raspberry Pi? <a class=\"anchor\" id=\"Ch21\"></a>\n",
    "\n",
    "You can do pretty much anything on a Raspberry Pi that you can on any other Linux desktop computer, with a few limitations. The Raspberry Pi uses a micro-SD card in place of a hard disk. The older Raspberry Pi models A and B use a full-size SD card, although you can plug in a USB hard disk. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2765c20f",
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "from IPython.display import YouTubeVideo\n",
    "\n",
    "youtube_video = YouTubeVideo('eZ74x6dVYes')\n",
    "\n",
    "# display youtube video\n",
    "display(youtube_video)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a90f12f7",
   "metadata": {},
   "source": [
    "![image.png](images/RP4.png)\n",
    "###### Figure: Raspberry Pi 4\n",
    "\n",
    "![image-2.png](images/RPzero.png)\n",
    "###### Figure: Raspberry Pi Zero\n",
    "\n",
    "The RJ-45 Ethernet connector is to plug your Raspberry Pi directly into a local network. the Raspberry Pi 4 also has a built-in Wi-Fi connector. Immediately above the Ethernet socket you’ll find two pairs of USB sockets. You can plug a keyboard, mouse, or external hard disks into the board. In the bottom-center of the figure you’ll find an audio socket that provides a stereo analog signal for headphones or powered speakers. This socket also provides a composite video signal. The HDMI connector is also sound capable.\n",
    "\n",
    "At the top of the Pi are two rows of pins. These are called GPIO (General Purpose Input/Output) pins, and they allow the Raspberry Pi to be connected to custom electronics. Users of the Arduino and other microcontroller boards will be used to the idea of GPIO pins.\n",
    "\n",
    "The Raspberry Pi has a micro-SD card slot underneath the board. This SD card needs to be at least 8GB - 32 GB in size. It contains the computer’s operating system as well as the file system in which you can store any documents you create. \n",
    "Because no disk is built into your Raspberry Pi, this card is effectively your computer, so you could take it out and put it in a different Raspberry Pi and all your stuff would be there.\n",
    "\n",
    "Below the micro-SD card is the USB-C socket. This is used to supply power to the Raspberry Pi. Therefore, you will need a power supply with a micro-USB connector on the end. This is the same type of connector used by many mobile phones. Do, however, check that it is capable of supplying at least 2.5A; otherwise, your Raspberry Pi may behave erratically.\n",
    "\n",
    "The big square chip in the center of the board is where all the action occurs. This is Broadcom’s “System on a Chip” and includes 1, 4, or 8GB of memory as well as the graphics and general-purpose processors\n",
    "that drive the Raspberry Pi.\n",
    "\n",
    "You may also have noticed flat cable connectors on the Pi. The connector on the far left is for an LCD display and the connector bottom-center is for the special Raspberry Pi Camera Module."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5021fcaf",
   "metadata": {},
   "source": [
    "## 3. Interfacing hardware <a class=\"anchor\" id=\"Ch3\"></a>\n",
    "\n",
    "The Raspberry Pi has a double row of pins on one side of it. These pins are called the GPIO connector (General Purpose Input/Output) and allow you to connect electronic hardware to the Pi as an alternative to using the USB port.\n",
    "\n",
    "The maker and education communities have already started producing expansion and prototyping boards you can attach to your Pi so you can add your own electronics. This includes everything from simple temperature sensors to relays to IMUs, EMG, force sensors, cameras, or robot controls.\n",
    "\n",
    "In this part, we explore the various ways of connecting the Pi to electronic devices using the GPIO. \n",
    "\n",
    "### 3.1 GPIO Pin Connections <a class=\"anchor\" id=\"Ch31\"></a>\n",
    "\n",
    "All versions of the Raspberry Pi since the Raspberry Pi 2 have two rows of 20 pins, making 40 pins in total. The template of the GPIO pin layout is as follows:\n",
    "\n",
    "![image.png](images/GPIOs.png)\n",
    "\n",
    "#### 3.1.1 Pin functions <a class=\"anchor\" id=\"Ch311\"></a>\n",
    "\n",
    "The pins labeled GPIO can all be used as general-purpose input/output pins. In other words, any one of them can first be set to either an input or an output. If the pin is set to be an input, you can then test to see whether the pin is set to a “1” (above about 1.7V) or a “0” (below 1.7V). Note that all the GPIO pins are 3.3V pins and connecting them to higher voltages than that could damage your Raspberry Pi. When set to be an output, the pin can be either 0V or 3.3V (logical 0 or 1). Pins can only supply or sink a small amount of current (assume 3mA to be safe), so they can just light an LED if you use a high value resistor (say, 470Ω or higher).\n",
    "\n",
    "#### 3.1.2 Serial Interface Pins <a class=\"anchor\" id=\"Ch312\"></a>\n",
    "\n",
    "You will notice that some of the GPIO pins have other letters after their names. Those pins can be used as normal GPIO pins, but also have some special purpose. For example, pins 2 and 3 have the extra names of SDA and SCL. These are the clock and data lines, respectively, for a serial bus type called I2C that is popular for communicating with peripherals such as temperature sensors, LCD displays, and the like.\n",
    "\n",
    "GPIO pins 14 and 15 also double as the TXD and RXT (Transmit and Receive) pins for the Raspberry Pi’s serial port. Yet another type of serial communication is possible through GPIO 9 to 11 (MISO, MOSI, and SCLK). This type of serial interface is called SPI.\n",
    "\n",
    "#### 3.1.3 Power Pins <a class=\"anchor\" id=\"Ch313\"></a>\n",
    "\n",
    "Both GPIO connectors are sprinkled with pins labeled GND (ground). These pins are all connected to the Raspberry Pi’s ground or zero volts. Other power pins are also provided for 3.3V and 5V. You will often use these pins when hooking up external electronics to the Raspberry Pi.\n",
    "\n",
    "#### 3.1.4 Hat Pins <a class=\"anchor\" id=\"Ch314\"></a>\n",
    "\n",
    "Two special pins, only available on the 40-pin variant of the Raspberry Pi, are ID_SD and ID_SC. These are reserved for an advanced interface standard that you can use with the Raspberry Pi 2, B+ and A+. The standard is called HAT (Hardware Attached to Top). This standard does not in any way stop you just using GPIO pins directly; however, interface boards that conform to the HAT standard can call themselves HATs and have the advantage that a HAT must contain a little EEPROM (Electrically Erasable Programmable Read-Only Memory) chip on it that is used to identify the HAT so that ultimately the Raspberry Pi could auto-install necessary software. The pins ID_SD and ID_SC are used to communicate with a HAT EEPROM.\n",
    "\n",
    "#### 3.1.5 Breadboarding with Jumper Wires  <a class=\"anchor\" id=\"Ch315\"></a>\n",
    "\n",
    "Solderless breadboard, often just called breadboard, is a great way of connecting electronics to a Raspberry Pi. There is no soldering to do—you just push electronic components into the breadboard and then connect them to your Raspberry Pi GPIO connector using either special jumper wires.\n",
    "\n",
    "### 3.2 Digital Outputs <a class=\"anchor\" id=\"Ch32\"></a>\n",
    "\n",
    "The GPIO pins can be used to generate a digital output signal, for example to switch a light on and off. To access the GPIO pins, you need to import a library called `RPi.GPIO`. This library is included with Raspbian, so you do not need to install it. You just need to import it into the console by entering the command below:\n",
    "   \n",
    "```python\n",
    "    import gpiozero\n",
    "```\n",
    "\n",
    "When you have a LED connected to the Raspberry Pi, you need to specify the GPIO pin number and whether the pin is an input or an output:\n",
    "\n",
    "```python\n",
    "    led = gpiozero.LED(18)\n",
    "```\n",
    "    \n",
    "    \n",
    "### 3.3 Analog Outputs - Pulse Width Modulation <a class=\"anchor\" id=\"Ch33\"></a>\n",
    "\n",
    "The method used by the `gpiozero` library to produce an “analog” output is called Pulse Width Modulation (PWM). The GPIO pin actually uses a digital output, but generates a series of pulses. The width of the pulses are varied. The larger the proportion of the time that the pulse stays high, the greater the power delivered to the output, and hence the brighter the LED.\n",
    "\n",
    "![image-2.png](images/pulse_modulation.png)\n",
    "\n",
    "\n",
    "The proportion of the time that the pulse is HIGH is called the duty and this is often expressed as a percentage. Even though the LED is actually turning on and off, it happens so fast that your eye is just fooled into thinking the LED is brighter or dimmer depending on the length of the PWM pulse.\n",
    "\n",
    "### 3.4 Digital Inputs <a class=\"anchor\" id=\"Ch34\"></a>\n",
    "\n",
    "Where an LED is the most likely thing to be connected to a digital output, a switch is probably the most likely thing to be connected to a digital input.\n",
    "\n",
    "### 3.5 Analog Inputs <a class=\"anchor\" id=\"Ch35\"></a>\n",
    "\n",
    "Even the Raspberry Pi does not have analog inputs, that is inputs that can measure a voltage rather than simply tell if it is above or below a threshold that indicates the input is high or low. A lot of analog sensors provide an output voltage that is proportional to the thing they are measuring. So, for example, a temperature sensor chip such as the TMP36 has an output pin whose voltage varies depending on the temperature. The only way to use such a sensor with the Raspberry Pi is to use an __ADC (Analog to Digital Convertor)__ chip.\n",
    "\n",
    "However, many sensors are resistive. That is, their resistance changes with the thing they are measuring. A thermistor’s resistance changes with temperature and a photoresistor’s resistance varies depending on the amount of light falling on it. Other types of resistive sensors include gas sensors, strain sensors, and even resistive touch screens. These “resistive” sensors can be used with a Raspberry Pi by timing how long it takes for current to flow through the resistive sensor and charge up a capacitor to the extent that it crosses the threshold of a digital input so that the input counts as HIGH rather than LOW\n",
    "\n",
    "#### 3.5.1 measuring resistance <a class=\"anchor\" id=\"Ch351\"></a>\n",
    "\n",
    "Check out the following use case:\n",
    "![image-3.png](images/resistance_setup.png)\n",
    "\n",
    "To understand how this works, it can help to think of the capacitor as a water tank, the wires as pipes, and the resistors and the photoresistor as faucets that restrict the flow of water in the pipes. First, the capacitor is emptied of charge (the tank is emptied of water) by setting pin 23 to be an output and low. The charge then drains out of the capacitor through R2. R2 is there to make sure the charge doesn’t flow out and into the Pi so fast that it damages the GPIO pin. Next, pin 23 is effectively disconnected by setting it to be an input and pin 18 is set high (3.3V) so that the capacitor starts to fill through both the fixed resistor R1 and the photoresistor. The voltage at the capacitor will then start to rise as the capacitor fills. The capacitor will fill faster the lower the resistance of the photoresistor. This voltage is now monitored by pin 23 now acting as an input until the input goes high at about 1.65V (half of 3.3V). The time taken for this to happen is measured and can then be used to calculate the resistance of the photoresistor, which is an indication of the light level.\n",
    "\n",
    "![image-5.png](images/oscilloscope.png)\n",
    "\n",
    "The figure above a) shows an oscilloscope trace of the voltage at pin 23 as the capacitor charges. The horizontal axis is time and the vertical axis volts, b) shows the same thing but with the photoresistor covered so that it is darker (and higher resistance). As you can see, it takes perhaps three times as long for the voltage to rise in the dark.\n",
    "\n",
    "When a capacitor is charged through a resistor, the time taken for the capacitor voltage to rise to 0.632 of the charging voltage is called the time constant (T). By the miracle of physics, T is also equal to the value of resistance times the capacitance. So, you can work out T from the time taken to charge to 1.65V (t) using the equation:\n",
    "\n",
    "    T = t*3.3*0.632\n",
    "\n",
    "This is because we know how long it got to 1.65V we just need to scale that up a bit to see how long it would take to get to 3.33.3 × 0.632 = 2.09V. You now have a definite value for T.\n",
    "Now you also know that:\n",
    "\n",
    "    T = (R+R1)xC\n",
    "    \n",
    "where R is the photoresistor’s resistance. Rearranging these, you get:\n",
    "\n",
    "    R = (T/C)-R1\n",
    "    \n",
    "Which is the value of resistance of the photoresistor."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "accbd867",
   "metadata": {},
   "source": [
    "__Sources:__\n",
    "* Monk,Simon, Programming the Raspberry Pi, Getting Started with Python"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}