HOW CAN I CONTROL A RASPBERRY PI GPIO FROM BASH-SYSFS?
1. Required components and Circuit connection
Before running the commands, you must correctly assemble the electronic circuit to avoid damaging the components and the Raspberry Pi.
a) Materials:
- A Raspberry Pi running Raspberry Pi OS Trixie.
- An LED (any color).
- A 220-ohm to 330-ohm resistor. This limits the current and prevents the LED from burning out.
- A breadboard.
- Jumper wires.
- A suitable power supply for the Raspberry Pi (cable).
- A microSD card with Raspberry Pi OS Trixie installed.
b) Circuit connection:
1. Place the LED: Connect the anode (long leg) of the LED to GPIO17, which corresponds to physical pin 11.
2. Connect the resistor: Connect the cathode (short leg) of the LED to a 220–330 Ω resistor.
3. Close the circuit to ground: Connect the other end of the resistor to GND—for example, to physical pin 6.
4. Insert the microSD card into the Raspberry Pi.
5. Connect the USB-to-micro-USB cable to the computer and the Raspberry Pi. The cable should be connected to the second port on the Raspberry Pi, right where it says "USB."
6. Wait for the Raspberry Pi OS Trixie operating system to fully boot up before opening the terminal.
2. GPIO Interfaces available in Raspberry Pi OS Trixie
Raspberry Pi OS Trixie features modern tools for controlling GPIO via the GPIO Character Device interface, utilizing libgpiod tools such as: gpioinfo, gpioget, gpioset, gpiomon, and gpiofind. Similarly, there is the Sysfs interface located at /sys/class/gpio, which allows for exporting GPIOs via the export and unexport files and controlling their direction and value via the direction and value files. However, this interface is currently considered obsolete by the Linux kernel, and using the Character Device interface is recommended.
This project specifically uses the Sysfs interface, as the goal is to learn how to control a GPIO directly from Bash using system files.
3. Identifying GPIO pins
The Raspberry Pi labels its pins in two different ways. The first is the physical pin number, which refers to the pin's actual position on the 40-pin header. The second is the GPIO number (BCM), which is the internal identifier used by the Broadcom processor.
To check the pin layout from the terminal at any time, run the following command:
pinout
This command displays a graphical layout of the board on the screen, confirming which physical pin corresponds to a specific GPIO. In this case, it will show that physical pin 11 corresponds to GPIO17.
4. Step-by-step procedure via the terminal (Bash-Sysfs)
1. Next, open the terminal. The Sysfs interface for GPIO is typically located at:
/sys/class/gpio
2. Verify that the directory exists:
ls /sys/class/gpio
ls lists the contents of a directory. The two files we are interested in seeing are export and unexport. export allows you to request access to a pin, while unexport allows you to release it later.
3. Enter the directory. To enter the directory, use the cd (change directory) command:
cd /sys/class/gpio
4. To see which directory you are currently in, run pwd; the following should appear:
/sys/class/gpio
5. Export GPIO17. Before you can control a GPIO via Sysfs, you must export it:
echo 17 | sudo tee export
Note: The | symbol is called a pipe; it passes the output of the first command to the next one. tee writes the received value into the export file, and sudo performs the operation with administrator privileges.
After running this command, a directory named the following should appear:
gpio17
Run ls to verify this.
6. Enter the gpio17 directory. To enter the directory, run:
cd gpio17
Run ls to verify; the files direction (which controls whether the GPIO acts as an input or output) and value (which controls the logic state) should appear.
7. Check the current direction.
cat direction
cat displays the contents of a file. If in appears, it means the GPIO is configured as an input.
8. Configure GPIO17 as an output. Since we want to control an LED, GPIO17 must be configured as an output. To do this, run the following line of code:
echo out | sudo tee direction
Run cat direction to verify; out should now appear.
9. Check the initial state of the GPIO. Run:
cat value
The result should be the number 0, indicating a low level—meaning the LED is off.
10. Turn on the LED. To turn on the LED, execute the following line of code:
echo 1 | sudo tee value
Here, the number 1 signifies that the LED is on (high level). Observe the LED on the breadboard turning on.
11. Check the status. To verify the stored value, execute the following code:
cat value
A 1 should appear here. Therefore, GPIO17 = 1, meaning the LED is on.
12. Turn off the LED. To turn off the LED, type:
echo 0 | sudo tee value
13. Check the LED status again. Execute:
cat value
A 0 should now appear (LED off).
14. Turn the LED on and off multiple times. To do this, repeat steps 10 through 13 to verify operation.
15. Automatic test. If you want the LED to turn on and off automatically, execute the following code, where sleep specifies the number of seconds to wait between turning the LED on and off.
echo 1 | sudo tee value
sleep 2
echo 0 | sudo tee value
16. Return to the directory. When the exercise is finished, exit the GPIO17 directory. To do this, enter:
cd ..
After executing this, you should be back in /sys/class/gpio. To verify, execute pwd; it should display /sys/class/gpio.
17. Release GPIO17. To release the GPIO, type:
echo 17 | sudo tee unexport
18. Verify that GPIO17 was released. Using the ls command, you should see the following:
export
unexport
