# Introduction to Raspberry Pi OS and GPIO

## 1. Objectives

At the end of this lecture, the student should be able to:

- Identify the basic components of Raspberry Pi OS.
- Navigate through the Linux filesystem using the terminal.
- Create, copy, move, and remove files and directories.
- Update the operating system.
- Install software packages using `apt`.
- Understand the basic purpose of `/sys` and Sysfs.
- Identify the GPIO interfaces exposed by the GNU-Linux system.
- Configure and control a GPIO pin from the command line.

---

# 2. Raspberry Pi OS

Raspberry Pi OS is a Linux-based operating system developed for Raspberry Pi computers|boards.

The OS provides an interface between:

```mermaid
flowchart TB
    A[Applications]
    B[Linux Operating System]
    C[Device Drivers]
    D[Raspberry Pi Hardware]

    A --> B
    B --> C
    C --> D
```

When working with embedded Linux, hardware peripherals are normally accessed through the operating system and its device drivers rather than by directly manipulating processor registers.

---

# 3. Opening the Terminal

The **shell** provides a command-line interface to the operating system.

A typical prompt may look like:

```bash
pi@raspberrypi:~ $
```

The prompt provides useful information:

```text
pi              → current user
raspberrypi     → hostname
~               → current directory
$               → normal user
```

The `~` symbol represents the current user's home directory.

To determine the current user:

```bash
whoami
```

To determine the computer hostname:

```bash
hostname
```

To obtain information about the operating system:

```bash
cat /etc/os-release
```

Information about the Linux kernel can be obtained with:

```bash
uname -a
```

---

# 4. Linux Filesystem

Linux uses a hierarchical filesystem beginning at the root directory:

```text
/
├── bin
├── boot
├── dev
├── etc
├── home
├── proc
├── sys
├── tmp
├── usr
└── var
```

Some important directories are:

| Directory | Purpose |
|---|---|
| `/` | Root of the filesystem |
| `/home` | User directories |
| `/etc` | System configuration |
| `/dev` | Device interfaces |
| `/proc` | Kernel and process information |
| `/sys` | Kernel objects and hardware information |
| `/usr` | Applications and libraries |
| `/var` | Logs and variable data |
| `/boot` | Boot-related files |

For embedded systems, `/dev`, `/proc`, and `/sys` are particularly important because they provide interfaces to the operating system and hardware.

---

# 5. Basic Linux Commands

## 5.1 Current directory

To display the current working directory:

```bash
pwd
```

Example:

```text
/home/pi
```

---

## 5.2 Listing files

```bash
ls
```

A detailed listing can be obtained with:

```bash
ls -l
```

To include hidden files:

```bash
ls -la
```

---

## 5.3 Changing directories

```bash
cd directory
```

For example:

```bash
cd /home
```

Return to the home directory:

```bash
cd ~
```

Move one directory upward:

```bash
cd ..
```

---

## 5.4 Creating directories

```bash
mkdir gpio-lab
```

Enter the new directory:

```bash
cd gpio-lab
```

Check the current location:

```bash
pwd
```

---

## 5.5 Creating and reading files

Create an empty file:

```bash
touch example.txt
```

Display its contents:

```bash
cat example.txt
```

Edit the file:

```bash
nano example.txt
```

Later, we will install and use `vim` as another terminal-based text editor.

---

## 5.6 Copying, moving, and removing files

Copy:

```bash
cp example.txt copy.txt
```

Rename or move:

```bash
mv copy.txt data.txt
```

Remove:

```bash
rm data.txt
```

Remove a directory:

```bash
rmdir directory
```

For a directory containing files:

```bash
rm -r directory
```

> **Warning:** Linux normally does not provide an automatic recycle bin for files deleted with `rm`.

---

# 6. Administrator Privileges

Linux separates normal users from administrative operations.

The command:

```bash
sudo
```

executes another command with elevated privileges.

For example:

```bash
sudo apt update
```

Administrative privileges should only be used when necessary.

---

# 7. Updating Raspberry Pi OS

Raspberry Pi OS uses the Debian package management system.

Before installing software, update the package information:

```bash
sudo apt update
```

This command **does not install all updates**. It downloads the current package information from the configured repositories.

Available package upgrades can then be installed with:

```bash
sudo apt upgrade
```

Therefore:

```text
apt update
     ↓
Update package information

apt upgrade
     ↓
Install available updates
```

A common sequence is:

```bash
sudo apt update
sudo apt upgrade
```

---

# 8. Installing Packages

The general syntax is:

```bash
sudo apt install package-name
```

## Vim

Install Vim:

```bash
sudo apt install vim
```

Verify:

```bash
vim --version
```

Create a file:

```bash
vim example.txt
```

Some basic Vim commands are:

| Command | Function |
|---|---|
| `i` | Enter insert mode |
| `Esc` | Leave insert mode |
| `:w` | Save |
| `:q` | Quit |
| `:wq` | Save and quit |
| `:q!` | Quit without saving |

---

## Git

Install Git:

```bash
sudo apt install git
```

Verify:

```bash
git --version
```

Git will later allow us to download and manage source-code repositories.

---

# 9. Linux and Hardware

A major difference between a microcontroller and an embedded Linux computer is how applications interact with hardware.

A simplified architecture is:

```text
User Application
       │
       ▼
Linux Interface
       │
       ▼
Device Driver
       │
       ▼
Hardware
```

The Linux kernel controls hardware resources through **device drivers**.

Applications can communicate with these drivers using interfaces exposed by Linux.

Important locations include:

```text
/dev
/proc
/sys
```

---

# 10. What is Sysfs?

**Sysfs** is a virtual filesystem provided by the Linux kernel.

It is normally mounted at:

```text
/sys
```

Explore it with:

```bash
cd /sys
ls
```

Typical directories include:

```text
block
bus
class
devices
firmware
kernel
module
```

Unlike normal files stored on the SD card, many files under `/sys` represent information maintained dynamically by the Linux kernel.

We can think of Sysfs conceptually as:

```text
User
  │
  │ read/write
  ▼
/sys
  │
  ▼
Linux Kernel
  │
  ▼
Device Driver
  │
  ▼
Hardware
```

---

# 11. Exploring Hardware Through Sysfs

For example:

```bash
ls /sys/class
```

The exact contents depend on the kernel and hardware configuration.

You may find classes corresponding to:

```text
leds
net
thermal
pwm
i2c-dev
```

For example, network interfaces can be inspected with:

```bash
ls /sys/class/net
```

Possible output:

```text
eth0
lo
wlan0
```

Information can then be obtained from individual interfaces.

For example:

```bash
cat /sys/class/net/eth0/address
```

This illustrates an important Linux concept:

> Hardware and kernel information can often be inspected through filesystem-like interfaces.

---

# 12. GPIO on the Raspberry Pi

GPIO means:

**General-Purpose Input/Output**

A GPIO pin can generally operate as:

```text
GPIO
├── Input
│   ├── Button
│   ├── Digital sensor
│   └── Logic signal
│
└── Output
    ├── LED
    ├── Digital control
    └── External interface
```

GPIO pins operate with **3.3 V logic**.

> Do not directly apply 5 V to a Raspberry Pi GPIO input.

---

# 13. GPIO Numbering

Be careful with Raspberry Pi pin numbering.

Two numbers are commonly encountered:

```text
Physical pin number
        ≠
BCM GPIO number
```

For example, physical header pin **11** corresponds to:

```text
GPIO17
```

Thus:

```text
Physical pin 11 → GPIO17
```

In Linux GPIO tools, the GPIO/BCM numbering is generally more relevant than the physical connector position.

---

# 14. GPIO and Sysfs

Historically, Linux allowed GPIO pins to be controlled through:

```text
/sys/class/gpio
```

Older tutorials therefore contain commands such as:

```bash
echo 17 | sudo tee /sys/class/gpio/export
```

followed by operations involving:

```text
/sys/class/gpio/gpio17/direction
/sys/class/gpio/gpio17/value
```

This interface is useful for understanding the relationship:

```text
Filesystem
    ↓
Kernel
    ↓
GPIO driver
    ↓
Physical GPIO
```

However, the GPIO Sysfs interface is **deprecated in modern Linux kernels**.

For new applications, Linux provides the **GPIO character-device interface**.

---

# 15. Modern Linux GPIO Interface

GPIO devices can be exposed under `/dev`.

Check:

```bash
ls /dev/gpiochip*
```

Depending on the Raspberry Pi model and operating-system version, you may see one or more devices:

```text
/dev/gpiochip0
/dev/gpiochip1
...
```

These are GPIO character devices managed by the Linux kernel.

The command-line tools used to interact with them are provided by **libgpiod**.

---

# 16. Installing GPIO Tools

Install the GPIO utilities:

```bash
sudo apt update
sudo apt install gpiod
```

Verify that the tools are available:

```bash
gpiodetect
```

This displays the GPIO controllers detected by Linux.

To inspect GPIO lines, use:

```bash
gpioinfo
```

> The exact GPIO controller and line mapping can vary between Raspberry Pi models and Raspberry Pi OS/kernel versions. Always inspect the system rather than assuming that `gpiochip0` contains the desired header GPIO.

---

# 17. First GPIO Experiment — LED

We will control an LED connected to a GPIO output.

## Components

- Raspberry Pi
- LED
- 220–330 Ω resistor
- Breadboard
- Jumper wires

A conceptual connection is:

```text
GPIO17 ─── resistor ─── LED ─── GND
```

For example:

```text
GPIO17
   │
   R
   │
   ▼
  LED
   │
  GND
```

The resistor limits the LED current.

---

# 18. Identify the GPIO

Before controlling the GPIO, inspect the available GPIO chips:

```bash
gpiodetect
```

Then inspect their lines:

```bash
gpioinfo
```

Locate the GPIO line corresponding to the pin connected to the LED.

For this experiment, suppose the system identifies GPIO17 on the appropriate GPIO chip.

---

# 19. Set a GPIO Output

With current `libgpiod` tools, a GPIO line can be controlled with `gpioset`.

The exact syntax depends on the installed libgpiod version.

Check it with:

```bash
gpioset --help
```

On current libgpiod releases, the line can be requested and held as an output by `gpioset`.

For example, after identifying the correct chip and line:

```bash
gpioset GPIOCHIP LINE=1
```

The LED should turn **ON**.

Setting the output to zero:

```bash
gpioset GPIOCHIP LINE=0
```

should turn the LED **OFF**.

Replace `GPIOCHIP` and `LINE` with the values identified on the Raspberry Pi.

---

# 20. What Happens Internally?

When executing a GPIO command:

```text
gpioset
   │
   ▼
/dev/gpiochipN
   │
   ▼
Linux GPIO subsystem
   │
   ▼
Raspberry Pi GPIO driver
   │
   ▼
GPIO hardware
   │
   ▼
LED
```

The application therefore does not normally manipulate the GPIO hardware registers directly.

Linux acts as an abstraction layer between the application and the hardware.

---

# 21. First Laboratory Exercise

Create a working directory:

```bash
mkdir ~/gpio-lab
cd ~/gpio-lab
```

Perform the following activities:

1. Determine the Raspberry Pi OS version.
2. Determine the Linux kernel version.
3. Determine the current username and hostname.
4. Update the package repositories.
5. Install `vim`.
6. Install `git`.
7. Install the `gpiod` tools.
8. Explore `/sys/class`.
9. Identify the available GPIO controllers.
10. Identify the GPIO line connected to an LED.
11. Turn the LED ON.
12. Turn the LED OFF.

Record the commands used during the experiment.

---

# 22. Questions

Answer briefly:

1. What is the difference between `/sys` and `/dev`?
2. What is the purpose of Sysfs?
3. Why should an application normally use a Linux driver instead of directly accessing hardware registers?
4. What is the difference between a physical Raspberry Pi header pin number and a BCM GPIO number?
5. Why is `/sys/class/gpio` no longer recommended for new applications?
6. What is `/dev/gpiochipN`?
7. What is the purpose of `gpiodetect`?
8. What is the purpose of `gpioinfo`?
9. Why should a resistor be connected in series with an LED?
10. What voltage level is normally used by Raspberry Pi GPIO pins?

---

# 23. Summary

In this lecture we introduced the basic software architecture of a Raspberry Pi running Linux:

```text
Application
     ↓
Linux userspace interface
     ↓
Kernel
     ↓
Device driver
     ↓
Hardware
```

We also used basic Linux commands:

```bash
pwd
ls
cd
mkdir
cp
mv
rm
cat
sudo
```

and package-management commands:

```bash
sudo apt update
sudo apt upgrade
sudo apt install
```

Finally, we introduced two important Linux hardware interfaces:

```text
/sys                    → Sysfs/kernel information

/dev/gpiochipN          → GPIO character-device interface
```

Understanding this relationship between **applications, Linux, device drivers, and physical hardware** provides the foundation for later experiments involving GPIO, I²C, SPI, UART, sensors, and actuators.

At the end of this lecture, the student should be able to:

Identify the basic components of Raspberry Pi OS.

Navigate through the Linux filesystem using the terminal.

Create, copy, move, and remove files and directories.

Update the operating system.

Install software packages using apt.

Understand the basic purpose of /sys and Sysfs.

Identify the GPIO interfaces exposed by Linux.

Configure and control a GPIO pin from the command line.