Raspberry Pi · Software

Qué cubre este archivo

Sirve cuando ya tienes la placa encendida y quieres saber qué comando toca qué. No enseña el curso paso a paso y no dibuja el mapa de 40 pines: el número físico de cada GPIO está en Hardware. Aquí los ejemplos usan el número BCM, que es el que piden gpiozero y el device tree.

El lenguaje de los ejemplos es Python 3. Cuando un programa tiene que arrancar solo, más abajo están cron y systemd. La cámara, el sonido y un servidor web mínimo también están aquí, no en el curso.

Sistemas

En el curso: lección 5 y lección 6.

La versión recomendada, a 3 de octubre de 2026, es Raspberry Pi OS basado en Debian 13 Trixie, publicada el 15 de septiembre de 2026, con kernel 6.18. En la página oficial de descargas hay imagen de 64 bits con escritorio, imagen Full e imagen Lite. Bookworm es la generación anterior: sigue existiendo, pero este manual habla de Trixie.

Empieza por la imagen con escritorio si vas a usar pantalla. Lite es el mismo sistema sin escritorio: entra por terminal o por SSH y ocupa menos. Elige Lite cuando la Pi va a hacer un trabajo fijo (un sensor, una cámara, un script) y nadie va a sentarse delante.

Hay otras imágenes. Ubuntu publica escritorio y servidor para Raspberry Pi; en su página de descarga figura 26.04.1 LTS. DietPi es una imagen mínima de terceros: el Imager la ofrece dentro de «Other general-purpose OS». Ninguna de las dos es la base de los ejemplos de este archivo. Si las usas, los nombres de paquete y las rutas de arranque pueden no coincidir.

Imagen y primer arranque

Graba la imagen con Raspberry Pi Imager. En la personalización, el apartado User pide un usuario y una contraseña: ponlos. No dejes el usuario por defecto de los tutoriales viejos.

Wi-Fi y SSH se pueden dejar vacíos. Si no rellenas nada, el escritorio vuelve a preguntar en el primer arranque, y el Wi-Fi se puede saltar. A partir de ahí la Pi trabaja sin red: GPIO, archivos y scripts no la necesitan.

En el curso, la imagen y el primer arranque: lección 3.

Sin pantalla, SSH tiene que quedar activado en el Imager, porque si no, no hay forma de entrar. Cómo entrar está en SSH, no aquí.

SSH

En el curso: lección 36.

SSH es entrar a la terminal de la Pi desde otro equipo. Se activa en el Imager, al grabar, o después en sudo raspi-config, en Interface Options. Sin eso, el puerto no responde.

Desde el otro equipo, con el usuario que creaste (no uno de un tutorial viejo) y la dirección de la Pi en tu red:

ssh TUUSUARIO@DIRECCION

DIRECCION es la IP que le haya dado el router. Si al grabar pusiste un nombre y en tu red resuelve, también vale ese nombre. La contraseña es la del Imager. No hay una de fábrica que sirva.

raspi-config

Es el menú de texto para lo que no quieres editar a mano. Se abre así:

sudo raspi-config

El menú principal, leído del propio programa, es este. No hay opción 7.

1 System Options          sistema
2 Display Options         pantalla
3 Interface Options       buses y servicios (I2C, SPI, 1-Wire, SSH…)
4 Performance Options     rendimiento; solo aparece en un Pi
5 Localisation Options    idioma, teclado, zona horaria, país del Wi-Fi
6 Advanced Options        ajustes finos
8 Update                  actualiza esta herramienta (hace falta red)
9 About raspi-config

Dentro de rendimiento, la documentación oficial nombra cosas concretas y no un overclock genérico. El overclock con presets («4 Performance Options > P1 Overclock») es para Pi 1 y Pi 2. No lo uses como receta en una Pi 4 ni en una Pi 5. También están el ventilador de la caja de la Pi 4, el límite de corriente USB en Pi 5, 500 y 500+, el sistema de archivos en solo lectura (overlay), la velocidad PCIe de la Pi 5, y el consumo al quedar apagada en las familias Pi 4 y Pi 5. Ese último no apaga la placa: cambia lo que hace la alimentación cuando ya está apagada. El apagado en sí está más abajo, en Apagado.

config.txt y cmdline.txt

No hay lección de esto en el curso. Vive aquí.

config.txt lo lee el firmware antes de arrancar Linux. En Raspberry Pi OS, desde Bookworm, el archivo está en /boot/firmware/config.txt. Antes la partición de arranque se montaba en /boot/. Edita siempre la ruta nueva.

Haz una copia antes de tocar nada:

sudo cp /boot/firmware/config.txt /boot/firmware/config.txt.bak

El formato es una línea clave=valor. Un # al principio comenta la línea. cmdline.txt está en la misma partición de arranque: no le añadas flags sueltos copiados de un foro. Si no sabes qué cambia un flag del kernel, no lo pongas.

Claves que la documentación lista y que ya suelen venir en la imagen:

camera_auto_detect=1
display_auto_detect=1

camera_auto_detect=1 carga el overlay de una cámara CSI reconocida. Para quitarlo, ponlo a 0. display_auto_detect hace lo mismo con una pantalla DSI. dtoverlay carga un overlay con nombre. dtparam pasa un parámetro. arm_boost solo aplica a Pi 4B de revisiones tardías y a la Pi 400: sube el turbo de 1,5 GHz a 1,8 GHz y ya viene activado donde toca. No lo añadas a mano en otras placas. power_force_3v3_pwm solo aplica a Pi 5, 500, 500+ y CM5. hdmi_enable_4kp60 solo a Pi 4B, CM4, CM4S y Pi 400, y solo en HDMI0: gasta más y calienta más.

Usuarios, permisos y servicios

En el curso: lección 10, 11, 12, 13, 14 y 16.

Trabaja con tu usuario. sudo es para lo que de verdad toca el sistema: instalar un paquete, editar config.txt, activar un servicio. Un script de GPIO no tiene por qué ser root.

Qué grupos tienes (no los inventes: el comando te los dice):

groups

Un servicio se mira y se deja encendido así. NOMBRE es el del servicio, por ejemplo ssh:

systemctl status NOMBRE
sudo systemctl enable --now NOMBRE

Si algo falló al arrancar, las últimas líneas del registro:

journalctl -n 50 --no-pager

Qué sigue funcionando sin red

En el curso, apt: lección 15.

Una vez grabada la imagen y instalado lo que vayas a usar, la Pi no necesita internet para leer GPIO, guardar un CSV, hacer una foto con la cámara ya configurada ni arrancar un script. Lo que sí pide red es bajar paquetes nuevos: apt update y un pip install contra PyPI.

Por eso este manual no manda a instalar con pip. Si un paquete falta, se busca en apt, y solo entra si ya está en la imagen o en la caché que bajaste antes, con la Pi aún en una red:

apt-cache search gpiozero
sudo apt install python3-gpiozero

El segundo comando falla sin red y sin caché. No es un fallo del programa: no hay de dónde bajarlo.

Python 3

En el curso: lecciones 17 a 22.

Los ejemplos de este archivo son Python 3, el que trae el sistema. Compruébalo:

python3 --version

Un entorno virtual aísla librerías de un proyecto. Créalo y entra:

python3 -m venv --system-site-packages ~/venv
. ~/venv/bin/activate

--system-site-packages deja ver lo que ya vino con la imagen, gpiozero incluido. Sin esa opción el venv no ve el gpiozero del sistema y parece que «no está instalado».

gpiozero

En el curso, la librería: lección 25. El pin y el circuito son las lecciones 23 y 24, en Hardware y en el curso, no aquí.

gpiozero viene con Raspberry Pi OS. Si en tu imagen no está, el paquete apt es python3-gpiozero. No lo instales con pip.

La pin factory por defecto es LGPIOFactory (gpiozero.pins.lgpio) cuando lgpio está instalado. En la Pi 5, de las factories clásicas, la que funciona es lgpio. RPi.GPIO y pigpio no sirven en esa placa.

El número del ejemplo es BCM 17. Qué patilla física es el 17 lo dice Hardware. El dibujo de abajo es el circuito del ejemplo, no el mapa de la placa.

La resistencia va en serie con el LED. 330 Ω es un valor habitual para un LED pequeño a 3,3 V; si el LED trae otra en su ficha, usa esa.

from gpiozero import LED
from time import sleep

led = LED(17)

while True:
    led.on()
    sleep(1)
    led.off()
    sleep(1)

PWM

En el curso: lección 27.

El mismo LED puede no estar solo encendido o apagado. PWMLED reparte el tiempo en alto y en bajo. value va de 0 (apagado) a 1 (siempre en alto). 0,5 es la mitad del brillo, no la mitad de los voltios.

from gpiozero import PWMLED
from time import sleep

led = PWMLED(17)

while True:
    led.value = 0
    sleep(1)
    led.value = 0.5
    sleep(1)
    led.value = 1
    sleep(1)

Antirrebotes

En el curso: lección 26.

Un botón mecánico no cierra limpio: al pulsarlo rebota y el programa puede ver varios cambios. bounce_time es el tiempo, en segundos, que se ignoran los cambios después del primero. Por defecto es None, o sea sin antirrebotes. 0,2 s basta para un pulsador de tablero.

from gpiozero import LED, Button
from signal import pause

led = LED(17)
# El 2 sale en el ejemplo oficial. Si ese pin está en el bus I2C,
# elige otro GPIO libre. El mapa está en Hardware.
boton = Button(2, bounce_time=0.2)

boton.when_pressed = led.on
boton.when_released = led.off
pause()

La otra forma oficial es alimentar el botón desde 3,3 V y crear el Button con pull_up=False. Nunca desde 5 V.

Si el LED no enciende

El programa de gpiozero corre y el LED no se ve. Mira en este orden. Para en cuanto uno falle: el siguiente no va a arreglarlo.

1. La terminal tiene que seguir en el programa, sin un error en rojo. Si dice que el pin está ocupado o que no encuentra gpiozero, el LED no entra: lee esa línea. En una Pi 5 la factory tiene que ser lgpio. Si forzaste RPi.GPIO o pigpio, no va a encender.
2. El 17 del ejemplo es el número BCM, no el de la patilla contando desde el borde. Qué agujero físico es el BCM 17 lo dice Hardware. Un cable en el agujero de al lado es otro GPIO, o es tierra, o es 5 V.
3. El LED tiene lado. El lado del GPIO (pasando la resistencia) es el ánodo, la pata larga en un LED nuevo. Al revés no luce. Con resistencia y 3,3 V, ponerlo al revés no suele romperlo.
4. La resistencia va en serie, en el camino del GPIO al LED. Puenteada (las dos patas del LED en el mismo punto) no limita nada: o no se ve, o el pin sufre.
5. La otra pata del LED tiene que llegar a una tierra del conector, GND, no a un segundo GPIO ni a 5 V.
6. Prueba solo esto, diez segundos. Si este tampoco luce, no es el programa largo: es el cable o el número de pin.

from gpiozero import LED
from time import sleep

led = LED(17)
led.on()
sleep(10)
led.off()

I2C

En el curso: lección 31.

I2C es un bus de dos hilos. Qué pines físicos son el reloj y los datos lo dice Hardware. Aquí solo se enciende el bus y se habla con un chip cuya dirección ya conoces.

Por raspi-config: Interface Options, I2C, activar, reiniciar. A mano, en /boot/firmware/config.txt, la línea que escribe raspi-config es:

dtparam=i2c_arm=on

Después de reiniciar, el bus del conector GPIO se ve así en los modelos donde ese bus es el 1. Si i2cdetect no está, el paquete es i2c-tools, y sin red solo entra si ya estaba en la caché:

sudo i2cdetect -y 1

En Debian Trixie el acceso desde Python es el paquete python3-smbus. La dirección y el registro no los pone este manual: salen de la hoja del chip. El 0x48 de abajo es un ejemplo de forma, no un chip concreto. Cámbialo.

from smbus import SMBus

bus = SMBus(1)
direccion = 0x48          # la de TU chip, en hexadecimal
registro = 0              # el que diga su hoja
valor = bus.read_byte_data(direccion, registro)
print(valor)
bus.close()

SPI

SPI es otro bus, más rápido, con una línea de selección por dispositivo. Los pines físicos están en Hardware.

Actívalo en Interface Options, o con la línea que escribe raspi-config:

dtparam=spi=on

Reinicia. SPI0 aparece entonces como /dev/spidev0.0 y /dev/spidev0.1 (dos selecciones). El paquete Python se busca en la propia Pi (apt-cache search spidev), sin darlo por hecho. Este programa solo abre el dispositivo 0.0 y manda un byte: los bytes de verdad los dicta el chip, no los copies de otro proyecto.

import spidev

spi = spidev.SpiDev()
spi.open(0, 0)            # bus 0, selección 0 → /dev/spidev0.0
spi.max_speed_hz = 50000
respuesta = spi.xfer2([0x00])
print(respuesta)
spi.close()

1-Wire

1-Wire lleva datos por un solo GPIO. El pin físico por defecto no lo fijo aquí: lo confirma Hardware y el overlay. raspi-config, al activarlo, escribe esto en config.txt:

dtoverlay=w1-gpio

Reinicia. Un sensor de temperatura de la familia 28 (el DS18B20 es el habitual) aparece como carpeta 28-… dentro de /sys/bus/w1/devices/. La lectura vale si el fichero contiene YES. El número que sigue a t= está en milésimas de grado.

from pathlib import Path

base = Path("/sys/bus/w1/devices")
for f in sorted(base.glob("28-*/w1_slave")):
    texto = f.read_text(encoding="ascii", errors="replace")
    if "YES" not in texto:
        print(f.parent.name, "lectura no válida")
        continue
    bruto = texto.split("t=")[-1].strip()
    print(f.parent.name, int(bruto) / 1000)

Si no aparece ninguna carpeta 28-, el overlay no cargó o el sensor no está en el pin que el overlay usa. No inventes un gpiopin= sin mirar Hardware.

libgpiod

Es la capa con la que Linux habla con los GPIO, por debajo de lgpio y, por tanto, de gpiozero. El curso no la practica: la nombra en la lección 25.

Las herramientas de línea de comandos suelen llamarse gpiodetect, gpioinfo, gpioset y gpioget. Si no están, no des por hecho el nombre del paquete:

apt-cache search gpiodetect

Sirven para ver qué chip GPIO tiene la placa y el estado de una línea, sin escribir un programa. En la Pi 5 el chip no es el mismo que en las anteriores: gpiodetect te dice el nombre real. No lo copies de un tutorial de la Pi 4.

pigpio

pigpio es un demonio (pigpiod) que temporiza los GPIO con más precisión que el Python a pelo. El curso no lo practica: lo nombra en la lección 25.

En la Pi 5 no lo uses. Ahí la factory que funciona es lgpio, y gpiozero ya la elige solo. Arrancar pigpiod en una Pi 5 no te da los pines.

Cámara

En el curso: lección 33 y lección 34.

Los comandos actuales son rpicam-still y rpicam-vid. raspistill y raspivid son los nombres viejos: no los pongas en un script nuevo. Las opciones concretas cambian con la versión. Míralas en la propia Pi, no en una chuleta:

rpicam-still --help
rpicam-vid --help

Una foto a un archivo, con las opciones por defecto del comando (si el help de tu versión usa otro nombre de opción, manda el help):

rpicam-still -o foto.jpg

Esa -o es la opción de salida que la documentación de libcamera viene usando. Si tu --help no la lista, no la fuerces.

En Python el módulo se llama picamera2. El nombre del paquete apt no lo afirmes a ciegas:

apt-cache search picamera2

camera_auto_detect=1 ya viene en config.txt. Si la cámara es CSI y no aparece, mira primero que esa línea siga en 1 y que el conector sea el de Hardware, antes de instalar nada.

Audio

No hay lección de audio en el curso. Vive aquí.

Para oír un wav por ALSA:

aplay -l
aplay sonido.wav

aplay -l lista las salidas: HDMI y, si la hay, la analógica. El número de tarjeta y de dispositivo sale en esa lista. Para forzar una:

aplay -D plughw:TARJETA,DISPOSITIVO sonido.wav

Sustituye TARJETA y DISPOSITIVO por lo que haya impreso aplay -l. No des por hecho que el escritorio de Trixie manda el sonido solo por ALSA: la sesión puede tener otro servidor encima. Si aplay dice que reprodujo y no oyes nada, la salida por defecto no es el cable que estás mirando. Cámbiala con -D antes de tocar config.txt.

Servidor web en la propia Pi

Para ver una carpeta de archivos desde el navegador de esa Pi, sin analytics y sin CDN, basta la biblioteca estándar. Átalo a localhost para que no escuche en la red:

cd /ruta/de/la/carpeta
python3 -m http.server 8080 --bind 127.0.0.1

Abres http://127.0.0.1:8080/ en el navegador de la propia Pi. Parar: Ctrl+C.

CSV en disco

En el curso: lección 21.

Las medidas se quedan en un archivo. El módulo csv viene con Python. newline="" evita filas en blanco de más.

import csv
from datetime import datetime
from pathlib import Path

ruta = Path.home() / "medidas.csv"
nuevo = not ruta.exists()

with ruta.open("a", newline="", encoding="utf-8") as fh:
    w = csv.writer(fh)
    if nuevo:
        w.writerow(["fecha", "valor"])
    w.writerow([datetime.now().isoformat(timespec="seconds"), 21.5])

with ruta.open(newline="", encoding="utf-8") as fh:
    for fila in csv.reader(fh):
        print(fila)

La carpeta tiene que ser de tu usuario. No escribas en /boot/firmware/: eso es la partición de arranque.

systemd

Por qué arrancar solo al encender: lección 41.

Una unidad de sistema lanza el programa al arrancar y lo relanza si se cae. Crea el archivo /etc/systemd/system/medidas.service (hace falta sudo). Cambia la ruta y el usuario por los tuyos. No uses el usuario pi si no es el que creaste en el Imager.

[Unit]
Description=Medidas en CSV
After=multi-user.target

[Service]
User=TUUSUARIO
WorkingDirectory=/home/TUUSUARIO
ExecStart=/usr/bin/python3 /home/TUUSUARIO/medidas.py
Restart=on-failure

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now medidas.service
systemctl status medidas.service
journalctl -u medidas.service -n 30 --no-pager

Si status dice failed, el motivo está en esas líneas de journalctl, no en un reinicio a ciegas.

cron

El mismo porqué, en la lección 41.

cron sirve cuando el programa tiene que lanzarse y terminar, no quedarse vivo. @reboot lo lanza al arrancar, sin esperar a la red.

crontab -e

Una línea, con rutas absolutas:

@reboot /usr/bin/python3 /home/TUUSUARIO/medidas.py >> /home/TUUSUARIO/medidas.log 2>&1

Si no pasa nada, mira el log. cron no enseña el error en pantalla. Para algo que deba seguir corriendo, usa la unidad de systemd de arriba, no cron.

Apagado seguro

En el curso: lección 9.

Apagar el sistema antes de cortar la corriente:

sudo shutdown -h now

Espera a que la actividad de la tarjeta pare (en muchas placas el LED verde deja de parpadear) y solo entonces quita la alimentación. Cortar antes puede romper el sistema de archivos.

Otra cosa distinta es el consumo cuando ya está apagada. En las familias Pi 4 y Pi 5 eso se cambia en raspi-config, en las opciones de rendimiento. No sustituye al comando de arriba.

Reloj, NTP y RTC

Sin red y sin pila de reloj, la hora se pierde al cortar la corriente. Con red, el sistema la pide por NTP. Para ver si está activo:

timedatectl

La línea que importa es la de «NTP service» o «System clock synchronized». Si dice que no, y hay red, no inventes un servidor: en Raspberry Pi OS el cliente ya viene configurado. Revisa antes que la Pi tenga hora de red de verdad (ping no, porque este manual no asume red; timedatectl basta).

Un RTC es una pieza con pila. El overlay depende del chip y está en Hardware. Aquí no hay un dtoverlay de un chip concreto: poner el de otro reloj deja el bus ocupado y la hora igual de mal.

Fuentes

Lo de este archivo se apoya en esto, consultado para el estado a 3 de octubre de 2026. Los enlaces no se abren sin red. Están para saber de dónde sale cada cosa.

• Descargas de Raspberry Pi OS (Trixie, 15 sep 2026, kernel 6.18): https://www.raspberrypi.com/software/operating-systems/
• Anuncio de Trixie: https://www.raspberrypi.com/news/trixie-the-new-version-of-raspberry-pi-os/
• Configuración y raspi-config: https://www.raspberrypi.com/documentation/computers/configuration.html
• config.txt en /boot/firmware/: https://www.raspberrypi.com/documentation/computers/config_txt.html
• Opciones comunes (camera_auto_detect, arm_boost, hdmi_enable_4kp60): https://github.com/raspberrypi/documentation/blob/master/documentation/asciidoc/computers/config_txt/common.adoc
• Menú de raspi-config y dtoverlay=w1-gpio: https://github.com/RPi-Distro/raspi-config
• Recetas gpiozero (LED 17, PWMLED, Button): https://gpiozero.readthedocs.io/en/stable/recipes.html
• Pin factory LGPIOFactory y Pi 5: https://gpiozero.readthedocs.io/en/latest/api_pins.html
• python3-smbus en Debian Trixie: https://packages.debian.org/python3-smbus

Quedó a propósito sin afirmar: el nombre del paquete apt de las herramientas gpiodetect, el de picamera2, el pin por defecto del overlay w1-gpio, y si el escritorio de Trixie enruta el audio solo por ALSA. En la Pi se mira con apt-cache, con el README del overlay y con aplay -l.