raspberry-OS-gpios/Readme.md

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:

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:

pi@raspberrypi:~ $

The prompt provides useful information:

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

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

To determine the current user:

whoami

To determine the computer hostname:

hostname

To obtain information about the operating system:

cat /etc/os-release

Information about the Linux kernel can be obtained with:

uname -a

---

4. Linux Filesystem

Linux uses a hierarchical filesystem beginning at the root directory:

/
├── 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:

pwd

Example:

/home/pi

---

5.2 Listing files

ls

A detailed listing can be obtained with:

ls -l

To include hidden files:

ls -la

---

5.3 Changing directories

cd directory

For example:

cd /home

Return to the home directory:

cd ~

Move one directory upward:

cd ..

---

5.4 Creating directories

mkdir gpio-lab

Enter the new directory:

cd gpio-lab

Check the current location:

pwd

---

5.5 Creating and reading files

Create an empty file:

touch example.txt

Display its contents:

cat example.txt

Edit the file:

nano example.txt

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

---

5.6 Copying, moving, and removing files

Copy:

cp example.txt copy.txt

Rename or move:

mv copy.txt data.txt

Remove:

rm data.txt

Remove a directory:

rmdir directory

For a directory containing files:

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:

sudo

executes another command with elevated privileges.

For example:

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:

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:

sudo apt upgrade

Therefore:

apt update
     ↓
Update package information

apt upgrade
     ↓
Install available updates

A common sequence is:

sudo apt update
sudo apt upgrade

---

8. Installing Packages

The general syntax is:

sudo apt install package-name

Vim

Install Vim:

sudo apt install vim

Verify:

vim --version

Create a file:

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:

sudo apt install git

Verify:

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:

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:

/dev
/proc
/sys

---

10. What is Sysfs?

Sysfs is a virtual filesystem provided by the Linux kernel.

It is normally mounted at:

/sys

Explore it with:

cd /sys
ls

Typical directories include:

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:

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

---

11. Exploring Hardware Through Sysfs

For example:

ls /sys/class

The exact contents depend on the kernel and hardware configuration.

You may find classes corresponding to:

leds
net
thermal
pwm
i2c-dev

For example, network interfaces can be inspected with:

ls /sys/class/net

Possible output:

eth0
lo
wlan0

Information can then be obtained from individual interfaces.

For example:

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:

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:

Physical pin number
        ≠
BCM GPIO number

For example, physical header pin 11 corresponds to:

GPIO17

Thus:

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:

/sys/class/gpio

Older tutorials therefore contain commands such as:

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

followed by operations involving:

/sys/class/gpio/gpio17/direction
/sys/class/gpio/gpio17/value

This interface is useful for understanding the relationship:

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:

ls /dev/gpiochip*

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

/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:

sudo apt update
sudo apt install gpiod

Verify that the tools are available:

gpiodetect

This displays the GPIO controllers detected by Linux.

To inspect GPIO lines, use:

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:

GPIO17 ─── resistor ─── LED ─── GND

For example:

GPIO17
   │
   R
   │
   ▼
  LED
   │
  GND

The resistor limits the LED current.

---

18. Identify the GPIO

Before controlling the GPIO, inspect the available GPIO chips:

gpiodetect

Then inspect their lines:

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:

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:

gpioset GPIOCHIP LINE=1

The LED should turn ON.

Setting the output to zero:

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:

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:

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:

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

We also used basic Linux commands:

pwd
ls
cd
mkdir
cp
mv
rm
cat
sudo

and package-management commands:

sudo apt update
sudo apt upgrade
sudo apt install

Finally, we introduced two important Linux hardware interfaces:

/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.