S0_SetUpRaspberryPi/S0_SetUpRaspberryPi.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "fe8ed4c6",
   "metadata": {},
   "source": [
    "# `S0`: Sensor Lab 0: Set Up the Raspberry Pi\n",
    "\n",
    "In this lecture, we will get started with the Raspberry Pi. By the end of this part, you should have:\n",
    "\n",
    "- Joined the same WiFi network as your Pi\n",
    "- Connected to the Pi via VNC\n",
    "- Configured/setup the Pi\n",
    "- Explored the Raspberry Pi's Desktop environment\n",
    "- Know what the python editor, terminal (shell), and programs are\n",
    "- Know how to run a Python program via the terminal\n",
    "\n",
    "\n",
    "__Outline:__\n",
    "\n",
    "* [1. Join the Same WiFi Network as the Pi](#join-wifi-network)\n",
    "  * [1.1 Figure Out Your Laptop's MAC Address](#find-mac-address)\n",
    "  * [1.2 Get a `TUD-facility` WiFi License Barcode](#get-wifi-license)\n",
    "  * [1.3 Use the License Barcode to Register Your Laptop with `TUD-facility`](#register-laptop-wifi)\n",
    "  * [1.4 Join the `TUD-facility` WiFi Network on Your Laptop](#join-tud-facility)\n",
    "* [2. Connect to the Pi](#connect-to-pi)\n",
    "  * [2.1 Figure out your Pi's IP Address](#find-pi-ip-address)\n",
    "  * [2.2 Connect to the Pi Using VNC Connect](#connect-to-pi-vnc)\n",
    "* [3. Configure the Pi via VNC](#configure-pi)\n",
    "* [4. Explore the Raspberry Pi Desktop Environment](#explore-pi)\n",
    "  * [4.1 The Command Line](#explore-cmdline)\n",
    "  * [4.2 Navigating With the Terminal](#navigating-terminal)\n",
    "  * [4.3 `sudo`](#sudo-cmd)\n",
    "  * [4.4 MU & Thonny](#mu-and-thonny)\n",
    "  * [4.5 Python Shell](#python-shell)\n",
    "  * [4.6 Python Editor](#python-editor)\n",
    "  * [4.7 Running Python Program from the Terminal](#run-python-from-terminal)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8d2003c9",
   "metadata": {},
   "source": [
    "## 1. Join the Same WiFi Network as the Pi <a id=\"join-wifi-network\" />\n",
    "\n",
    "Although the Raspberry Pi can be used with a monitor, mouse, and keyboard, we will control it via an VNC-connection. This is convenient because it requires fewer wires and enables multiple computers to connect to the Pi simultaneously. However, it requires setting up a suitable network.\n",
    "\n",
    "In 2023, all Pis are registered to the `TUD-facility` WiFi network before the course begins. **The only way to connect to your Pi is for your laptop to also join the `TUD-facility` WiFi network, which we describe here.**\n",
    "\n",
    "### 1.1 Figure Out Your Laptop's MAC Address  <a id=\"find-mac-address\" />\n",
    "\n",
    "Joining `TUD-facility` requires that your laptop's MAC address is pre-registered with the network. Therefore, you **must** find out your device's (laptop's) WiFi networking card's MAC address.\n",
    "\n",
    "[This](https://itssc.rpi.edu/hc/en-us/articles/360001995831-How-to-find-your-MAC-Address-for-MacOS-Linux-Windows#:~:text=MacOS%2FLinux%20To%20locate%20the%20MAC%20Address%20on%20MacOS%2C,your%20IP%20address%20as%20well%20your%20MAC%20address) guide explains how to find your MAC address on MacOS, Linux, or Windows. Googling \"Mac/Windows/Linux find wifi adapter MAC address\" will show you other options.\n",
    "\n",
    "- **Windows**: If you have multiple network adaptors (e.g. on Windows, you might have several LAN adaptors), then the adaptor you register should be your WiFi adapter. If you are on `eduroam` then your adaptor will probably have an IP address that begins with `145.94.xxx.xxx`\n",
    "- **Mac**: If you have multiple network adapters, then the adapter will *probably* be `eno0`. You can tell which one it is by checking the `inet` field. If you are connected to `eduroam`, then your WiFi adaptor will have an `inet` that begins with `145.94.xxx.xxx`. Your MAC address is the `ether` field, just above that.\n",
    "\n",
    "> ❗**Important**: By the end of this step, you should have a MAC address for your WiFi adapter that looks like: `1C-81-9F-53-91-22` or `1c:81:9f:53:91:22`.\n",
    ">\n",
    "> The `TUD-facility` registration site **requires** this address in order to register your device with the network.\n",
    "\n",
    "\n",
    "### 1.2 Get a `TUD-facility` WiFi License Barcode  <a id=\"get-wifi-license\" />\n",
    "\n",
    "You need a license to join `TUD-facility`. The course organizer should have given you a QR-code containing the license.\n",
    "\n",
    "The QR-code should look something like this:\n",
    "\n",
    "![Example 2D Barcode](images/example_qrcode.png)\n",
    "\n",
    "Your QR-code will be linked to one NETID account and will let that person register up to 3 devices' MAC addresses with the `TUD-facility` WiFi network. If you have fewer QR codes than people in your team, the person who uses the QR code should register a teammate's device.\n",
    "\n",
    "\n",
    "### 1.3 Use the License Barcode to Register Your Laptop with `TUD-facility`  <a id=\"register-laptop-wifi\" />\n",
    "\n",
    "You will use your license to register your device with the `TUD-facility` WiFi, which will give you a password (`iPSK`) that you can use to login to the network from your laptop.\n",
    "\n",
    "- Scan the QR-code with your phone\n",
    "- Open the web link\n",
    "  - **Note**: the link only works if you are on `eduroam`, or the TU Delft VPN\n",
    "- Login to the system with your netID\n",
    "- Click `Claim License` to claim the license against your netID\n",
    "- Click `Register Devices`\n",
    "- Type in your MAC address in the format `1c:81:9f:53:91:22` (**note**: if your MAC address has the format `1C-81-9F-53-91-22`, then replace all `-`'s with `:` and convert all of the letters to lower-case)\n",
    "- Type in a relevant device name (e.g. `AdamLaptop`)\n",
    "- Click `Register MAC Address`\n",
    "\n",
    "You will then be presented with a verification screen. On that screen, the `Registered Devices` table will contain your registration details, with content like this:\n",
    "\n",
    "| Key | Value |\n",
    "| --- | ----- |\n",
    "| MAC adres | `1c:81:9f:53:91:22` |\n",
    "| device naam | AdamLaptop |\n",
    "| vlanID | 1312 |\n",
    "| iPSK | 6446786e9e113 |\n",
    "\n",
    "> ❗**Important**: The `iPSK` field is your device's WiFi login password for `TUD-facility`. Save this somewhere.\n",
    "\n",
    "\n",
    "### 1.4 Join the `TUD-facility` WiFi Network on Your Laptop  <a id=\"join-tud-facility\" />\n",
    "\n",
    "1. Using your laptop's WiFi networking UI, change your WiFi network from whatever it currently is (probably, `eduroam`) to `TUD-facility`.\n",
    "2. When prompted for a password, use the `iPSK` you received after registering your device on the network.\n",
    "3. Your laptop should successfully connect to the network and have internet access\n",
    "\n",
    "\n",
    "## 2. Connect to the Pi  <a id=\"connect-to-pi\" />\n",
    "\n",
    "Now that you are on the same WiFi network as the Pi, you can connect to it. To do this, you first need to figure out the Pi's IP address. You will then use the IP address to connect to the Pi with an appropriate VNC client.\n",
    "\n",
    "\n",
    "### 2.1 Figure out your Pi's IP Address  <a id=\"find-pi-ip-address\" />\n",
    "\n",
    "Before you were given the Pi, the course organizers registered it on the `TUD-facility` network beforehand. The network then gave the Pi an IP address, which is what you need.\n",
    "\n",
    "A list of all IP addresses for all PBL Pis on the `TUD-facility` WiFi network can be found via the web portal:\n",
    "\n",
    "- Go to [https://infra-ict.tudelft.nl/portal/labs](https://infra-ict.tudelft.nl/portal/labs) (ℹ️ **note**: you must be on `eduroam` or the university's VPN for this link to work)\n",
    "- Click `List Labs` on the left-hand navbar\n",
    "- Select the `LAB-B034-3ME-CliTech[12]` lab and click `select LAB`\n",
    "- Under `name`, the names of all Pis are listed\n",
    "  - The `name` of your Pi is prefixes with `pblhost`, followed by a unique letter that is written on your Pi.\n",
    "  - E.g. if your Pi has `a` written on it then your Pi's name on the website will be `pblhosta`\n",
    "- Find your Pi\n",
    "- **Power up your Pi**, so that it joins the WiFi network\n",
    "- After a short while (usually 1-3 minutes), the IP address for your Pi should be shown below its MAC address:\n",
    "  - The Pi must be powered on\n",
    "  - It usually takes 1-3 minutes for a just-powered-on Pi to join the WiFi network\n",
    "  - You need to refresh the web page in order to see any changes\n",
    "  - Your IP address will have a format that looks like: `192.168.7.4`\n",
    "- If you cannot see an IP address below the Pi, then the Pi may not be powered on, or may not have sucessfully connected to `TUD-facility` - ask for help if this is the case\n",
    "\n",
    "> ❗**Important**: By the end of this step, you should have your Pi's IP address, which should look like: `192.168.7.4`\n",
    "\n",
    "---\n",
    "\n",
    "> ℹ️ **Having Trouble Figuring out Your Pi's IP Address?**\n",
    ">\n",
    "> We may be able to help find the IP address for you. For example, by checking the `TUD-facility` web portal from our admin accounts. It can also be the case that your device was incorrectly pre-configured with the network, but we can also help with that.\n",
    "\n",
    "### 2.2 Connect to the Pi Using VNC Connect  <a id=\"connect-to-pi-vnc\" />\n",
    "\n",
    "To access the Raspberry Pi from your machine, you need to install `VNC connect`, a VNC client. The installer and manual can be found here:\n",
    "\n",
    "- https://www.realvnc.com/en/connect/download/viewer/\n",
    "\n",
    "**Note**: you can open VNC viewer without logging in (no account needed). Check the lower part of the window.\n",
    "\n",
    "1. Once installed, start up the `VNC viewer` on your machine. Type in the IP address on the top of the the VNC viewer.\n",
    "\n",
    "![VNC viewer](images/Capture_VNCviewerownmachine.png)\n",
    "\n",
    "\n",
    "\n",
    "    \n",
    "2. When asked for login credentials, you need to use your Raspberry Pi’s credentials. Before you were given the Pi, the PBL organizers flashed each Pi with a user account of `pbl` and a semi-random password. **You should have been supplied with this password, if you don't have it, ask an organizer**.\n",
    "\n",
    "3. You should now see your Raspberry Pi desktop within the VNC viewer. This means you no longer need the screen, mouse and keyboard to work on your Raspberry Pi.\n",
    "\n",
    "\n",
    "## 3. Configure the Pi via VNC  <a id=\"configure-pi\" />\n",
    "\n",
    "In 2023, the PBL organizers flash all Raspberry Pis according to [X0_SoftwareSetup](../X0_SoftwareSetup/README.md) before the course begins. This means that, in most cases, your Pi won't require much software setup.\n",
    "\n",
    "\n",
    "> ℹ️ **Problem With Your Pi?**\n",
    ">\n",
    "> The course organizers have tried their best to ensure all the configuration options and software you'll need is already installed before the course begins, but we can miss things. If you find that the Pi isn't working for you then you can try:\n",
    ">\n",
    "> - Asking for help\n",
    "> - Running `pbl test` in the terminal, which runs some basic checks that ensure things like libraries etc. are installed\n",
    "> - Reinstalling the necessary software by running `sudo pbl install` in the terminal (⚠️ **warning**: takes a long time)\n",
    "> - Manually going through the legacy setup guide [here](Legacy/SetUpRaspberryPi.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b2240ba0",
   "metadata": {},
   "source": [
    "## 4. Explore the Raspberry Pi Desktop Environment <a id=\"explore-pi\" />\n",
    "\n",
    "Now that we are connected to the machine via VNC, let's do some exploring.\n",
    "\n",
    "### 4.1 The Command Line  <a id=\"explore-cmdline\" />\n",
    "\n",
    "If you are a Windows or Mac user, you may have never used the command line. If you are a Linux user, on the other hand, you almost certainly will have done so. Although it is possible to use a Linux system completely via the graphical interface, in general you will need to type commands into the command line. You do this to install new applications and to configure the Raspberry Pi.\n",
    "\n",
    "To open the terminal, click on the `Terminal` icon (on the top of your Pi's desktop - it looks like a monitor with a blank screen).\n",
    "\n",
    "\n",
    "### 4.2 Navigating With the Terminal  <a id=\"navigating-terminal\" />\n",
    "\n",
    "You will find yourself using three commands a lot when you are using the command line. The first command is `pwd`, which is short for `p`rint `w`orking `d`irectory. It prints which directory you are currently in. You can run `pwd` by typing it after the `$` sign in the terminal window:\n",
    "\n",
    "```bash\n",
    "$ pwd\n",
    "/home/pbl  # the output from `pwd`\n",
    "```\n",
    "\n",
    "Another common command is `ls`, which is short for list. It prints a list of files and directories within the working directory. Try the following:\n",
    "\n",
    "```bash\n",
    "$ ls\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6501a9a7",
   "metadata": {},
   "source": [
    "![Terminal commands](images/Capture_RP_pwd_ls.png)\n",
    "        \n",
    "The final command we are going to cover is `cd`, which is short for `c`hange `d`irectory. `cd` is used to naviagate the filesytem by changing the current directory (the thing printed by `pwd`). It can change the directory relative either to the old working directory or to a completely different directory if you specify the whole directory, starting with /.\n",
    "\n",
    "For example, the following command will change the current working directory to `/home/pbl/Desktop`:\n",
    "\n",
    "```bash\n",
    "$ pwd\n",
    "/home/pbl\n",
    "$ cd Desktop\n",
    "$ pwd\n",
    "/home/pbl/Desktop\n",
    "```\n",
    "\n",
    "You could do the same thing by using an *absolute* path:\n",
    "\n",
    "```bash\n",
    "$ cd /home/pbl/Desktop\n",
    "$ pwd\n",
    "/home/pbl/Desktop\n",
    "```\n",
    "\n",
    "Or by navigating to `~`, which is shorthand for \"home directory\":\n",
    "\n",
    "```bash\n",
    "$ cd ~\n",
    "$ pwd\n",
    "/home/pbl\n",
    "$ cd ~/Desktop\n",
    "$ pwd\n",
    "/home/pbl/Desktop\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "215bc422",
   "metadata": {},
   "source": [
    "Note that when entering a directory or filename, you do not have to type all of it. Instead, at any time after you have typed some of the name, you can press the TAB key. If the filename is unique at that point, it will be automatically completed for you.\n",
    "\n",
    "\n",
    "### 4.3 `sudo`  <a id=\"sudo-cmd\" />\n",
    "\n",
    "Another command that you will probably use a lot is `sudo` (for `su`peruser-user `do`). This runs whatever command you type after it as if you were a super-user.\n",
    "\n",
    "You might be wondering why, as the sole user of this computer, you are not automatically a super-user. The answer is that, by default, your regular user account (username: `pbl`, password: given to you by the course organizers) does not have privileges that, say, allow you to go to some vital part of the operating system and start deleting files. Instead, to cause such mayhem, you have to prefix those commands with `sudo`. This just adds a bit of protection against accidents. For the commands we have discussed so far, you will not need to prefix them with `sudo`. However, just for interest, try typing the following:\n",
    "\n",
    "```bash\n",
    "$ sudo ls\n",
    "```\n",
    "        \n",
    "This will work the same way ls on its own works; you are still in the same working directory."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a2bdbd03",
   "metadata": {},
   "source": [
    "### 4.4 MU & Thonny  <a id=\"mu-and-thonny\" />\n",
    "\n",
    "On the RP there are several Python editors. We recommend either Thonny or Mu.\n",
    "\n",
    "1. Open the program on your Rasbpetty Pi via `Menu` (raspberry icon, top-left) -> `Programming` -> `Mu` or `Thonny`\n",
    "   \n",
    "\n",
    "> ⚠️ **Note**: If the program doesn't show up in your menu you first need to download and install it. To do this follow the steps on this website: https://codewith.mu/en/howto/1.0/install_raspberry_pi (or use an alternative editor).\n",
    ">\n",
    "> If there is an error with the install, first run `sudo apt update` in the terminal\n",
    "\n",
    "\n",
    " ![Terminal commands](images/Capture_MU_select_pyhton3.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f402a7f7",
   "metadata": {},
   "source": [
    "### 4.5 Python Shell  <a id=\"python-shell\" />\n",
    "\n",
    "Since you might be fairly new to Python, it's helpful to interactively type in Python commands and see what this does. Click on the REPL icon at the top of the `Mu` window. The window will split opening up an area at the borrom of the screen where you can type commands (similar to what we know in Matlab). This area is called REPL for Read-Evaluate-Print-Loop.\n",
    "\n",
    "\n",
    "### 4.6 Python Editor  <a id=\"python-editor\" />\n",
    "\n",
    "The REPL is a great place to experiment, but not the right place to write a program. Python programs are saved in files, so that you do nothave to retype all the commands seperately.The editor area is where you can either write code for a new program, or open an existing python program. Let's run a very simple example.\n",
    "\n",
    "1. Create a python program that prints `Hello` and then `World` in Mu:\n",
    "\n",
    "```python\n",
    "# create a new python file and write this:\n",
    "\n",
    "print('Hello')\n",
    "print('World')\n",
    "```\n",
    "        \n",
    "2. Save this as a Python program called `hello.py`. If you do not change the directory, it will be saved in the folder `/home/pbl/mu_code`\n",
    "\n",
    "3. Now that you have saved it, you can run the program in Mu using the `Run` button. The result will be shown in the Python Shell\n",
    "\n",
    "\n",
    "### 4.7 Running Python Program from the Terminal <a id=\"run-python-from-terminal\" />\n",
    "\n",
    "An already saved python program does not necessarily need to be run via an editor. Another way of running a Python shell is to use the Terminal. To run your `hello.py` program, first navigate to the right directory in the terminal:\n",
    "\n",
    "```bash\n",
    "cd /home/pbl/mu_code/\n",
    "```\n",
    "\n",
    "Then tell it run the program using python3:\n",
    "\n",
    "```bash\n",
    "python3 hello.py\n",
    "```"
   ]
  }
 ],
 "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.9.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}