commit c26a978fa008e8d13b5b5a79ac233adc362bced0 Author: Gerardo Marx Date: Wed Sep 2 21:05:25 2026 -0600 initial commit diff --git a/Readme.md b/Readme.md new file mode 100644 index 0000000..ac5ce52 --- /dev/null +++ b/Readme.md @@ -0,0 +1,892 @@ +# 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. \ No newline at end of file