Ordenador de placa única ResearchGate Raspberry Pi

Información do produto

Especificacións

• Fabricante: Raspberry Pi Ltd
• Data de construción: 01/10/2025
• Versión de compilación: 99a8b0292e31
• Produtos Raspberry Pi compatibles: Pi Zero, Pi Zero 2 W, Pi 1 AB, Pi 2, Pi 3, Pi 4, Pi 5, módulos de computación CM1, CM3, CM4, CM5

Colofón
© 2022-2025 Raspberry Pi Ltd

Esta documentación está licenciada baixo unha licenza de Creative Commons Atribución-SenDerivadas 4.0 Internacional (CC BY-ND).

Lanzamento	1
Data de construción	01/10/2025
Versión de compilación	99a8b0292e31

Aviso legal de exención de responsabilidade
OS DATOS TÉCNICOS E DE FIABILIDADE DOS PRODUTOS RASPBERRY PI (INCLUÍDAS AS FOLLAS DE DATOS) SEGUNDO AS MODIFICACIÓNS PERIODICAS (“RECURSOS”) SON PROPORCIONADOS POR RASPBERRY PI LTD (“RPL”) “TAL CAL” E RENUNCIAN CALQUERA GARANTÍA EXPLÍCITA OU IMPLÍCITA, INCLUÍDAS, ENTRE OUTRAS, AS GARANTÍAS IMPLÍCITAS DE COMERCIABILIDADE E IDONEIDADE PARA UN FIN DETERMINADO. NA MEDIDA MÁXIMA PERMITIDA POLA LEI APLICABLE, EN NINGÚN CASO RPL SERÁ RESPONSABLE DE NINGÚN DANO DIRECTO, INDIRECTO, INCIDENTAL, ESPECIAL, EXEMPLAR OU CONSECUENTE (INCLUÍNDO, PERO SEN LIMITARSE A, A OBTENCIÓN DE BENS OU SERVIZOS SUBSTITUTOS; PERDA DE USO, DATOS OU BENEFICIOS; OU INTERRUPCIÓN DO NEGOCIO) INDEPENDENTEMENTE DA SÚA CAUSA E BASE A CALQUERA TEORÍA DE RESPONSABILIDADE, XA SEXA POR CONTRATO, RESPONSABILIDADE ESTRICTA OU AGRAVIO (INCLUÍNDO NEGLIXENCIA OU OUTRO XEITO) DERIVADOS DE CALQUERA XEITO DO USO DOS RECURSOS, INCLUSO SE SE FOI ADVERTIDO DA POSIBILIDADE DE TALES DANOS.

RPL resérvase o dereito de facer calquera mellora, mellora, corrección ou calquera outra modificación nos RECURSOS ou en calquera produto descrito neles en calquera momento e sen previo aviso.
Os RECURSOS están destinados a usuarios cualificados con niveis axeitados de coñecemento do deseño. Os usuarios son os únicos responsables da súa selección e uso dos RECURSOS e de calquera aplicación dos produtos descritos neles. O usuario comprométese a indemnizar e eximir a RPL de todas as responsabilidades, custos, danos ou outras perdas derivadas do uso dos RECURSOS.
RPL concede aos usuarios permiso para usar os RECURSOS unicamente xunto cos produtos Raspberry Pi. Queda prohibido calquera outro uso dos RECURSOS. Non se concede ningunha licenza a ningún outro RPL ou dereito de propiedade intelectual de terceiros.

ACTIVIDADES DE ALTO RISCO. Os produtos Raspberry Pi non están deseñados, fabricados nin destinados a ser utilizados en ambientes perigosos que requiren un rendemento seguro, como no funcionamento de instalacións nucleares, sistemas de navegación ou comunicación de aeronaves, control de tráfico aéreo, sistemas de armas ou aplicacións críticas para a seguridade (incluído o soporte vital). sistemas e outros dispositivos médicos), nos que a falla dos produtos pode provocar directamente a morte, danos persoais ou graves danos físicos ou ambientais (“Actividades de alto risco”). RPL renuncia específicamente a calquera garantía expresa ou implícita de aptitude para actividades de alto risco e non acepta ningunha responsabilidade polo uso ou inclusión de produtos Raspberry Pi en actividades de alto risco.
Os produtos Raspberry Pi ofrécense suxeitos ás Condicións estándar de RPL. A disposición de RPL dos RECURSOS non amplía nin modifica de ningún xeito as Condicións estándar de RPL, incluíndo, entre outras, as renuncias e garantías expresadas nelas.

Historial de versións do documento

Lanzamento	Data	Descrición
1	1 de outubro de 2025	Lanzamento inicial

Alcance do documento
Este documento aplícase aos seguintes produtos Raspberry Pi:

Computadoras de placa única / SBC

Pi Cero	Pi Cero 2	Pi 1	Pi 2	Pi 3	Pi 4	Pi 5
✓	✓	✓	✓	✓	✓	–

Módulos de computación

CM1	CM3	CM4	CM5
✓	✓	✓	✓

Introdución

USB On-The-Go (OTG) é unha especificación que permite que un dispositivo funcione como un host USB (como un PC) ou como un dispositivo/periférico USB (como un teclado, un adaptador Ethernet ou un dispositivo de almacenamento masivo). A páxina de Wikipedia "USB On-The-Go" ofrece moitos detalles sobre a especificación OTG: https://en.wikipedia.org/wiki/USB_On-The-Go.
Normalmente, unha conexión USB implica un servidor fixo (por exemplo, un ordenador) e un periférico (por exemplo, un rato). O USB OTG permite que un dispositivo cambie entre os dous. Por exemploampé dicir, unha Raspberry Pi podería actuar como anfitrión ao ler filedesde unha unidade flash ou funcionar como unha unidade flash cando se conectan a un ordenador.

A familia Raspberry Pi inclúe varias placas que poden funcionar en modo OTG/periférico, pero a compatibilidade varía segundo o modelo e o sistema no chip (SoC). Cando actúa neste modo periférico, o dispositivo adoita denominarse "gadget".
Este documento técnico percorre a gama de SBC de Raspberry Pi, explica as súas capacidades OTG e proporciona exemplos de configuración/código.amples. Abarca dous mecanismos OTG distintos: o método legado, que aínda é moi popular e se describe primeiro, seguido do esquema recomendado actualmente, ConfigFS.

OTG herdado

Raspberry Pi Zero / Zero W / Zero 2 W
Estas placas son as máis compatibles con OTG da familia Raspberry Pi. Expoñen o controlador USB do SoC directamente no porto de datos USB (o que está etiquetado como USB, non PWR IN) e o software integrado pódese configurar para que a túa Raspberry Pi actúe como un dispositivo OTG.

Activación do modo OTG

Consello: Dado que estás a usar o único porto USB da Raspberry Pi Zero para fins OTG, non poderás conectar un teclado nin un rato. Podes usar unha conexión Wi-Fi e SSH para comunicarte coa Raspberry Pi Zero…

dtoverlay=dwc2

Agora precisamos configurar o software para conectar o controlador OTG solicitado ao sistema USB…

console=serial0,115200 console=tty1 root=PARTUUID=xxxxxxxx-02 rootfstype=ext4 fsck.repair=yes rootwait modules-load=dwc2,g_ether

Outros módulos de dispositivos
No canto de g_ether, podes probar:

• g_serialAparece como un dispositivo serie USB
• g_mass_storage: Expón unha imaxe file como unha unidade flash
• g_compositeEmula un dispositivo composto

Consello
Un dispositivo composto USB é un único dispositivo físico que funciona como varios dispositivos independentes para un ordenador, aparecendo como varias interfaces ou clases de dispositivos separadas. Combina diferentes funcionalidades, como un teclado e un rato, ou unha unidade de almacenamento e un webcámara, nun único dispositivo e conector USB. Cando se conecta, o sistema operativo recoñece e usa controladores separados para cada unha das funcións distintas do dispositivo, o que lles permite funcionar de forma independente.

Para crear un dispositivo serie USB, podemos cargar o módulo axeitado desde a liña de comandos:

• Código
• sudo modprobe g_serial

Cando se conecta a un PC con Windows, a Raspberry Pi aparecerá como un porto COM no Xestor de dispositivos; cando se conecta a un dispositivo Linux (por exemplo, un SBC de Raspberry Pi), aparecerá como un dispositivo serie, como /dev/ttyACM0.

Raspberry Pi 4 e 5 (OTG no porto de alimentación USB-C)
O porto de alimentación/OTG USB-C da Raspberry Pi 4 admite o modo periférico cando non se usa para alimentar a placa.
A Raspberry Pi 5 introduce un controlador USB conectado a PCIe, que non admite OTG. Non obstante, do mesmo xeito que coa Raspberry Pi 4, a función periférica OTG nativa do SoC expóñese a través do conector de alimentación.

Pasos
Alimenta a túa Raspberry Pi a través do conector GPIO (5 V e GND), deixando o USB-C libre.
Conecta o porto USB-C ao teu ordenador anfitrión.

Activar OTG en /boot/firmware/config.txt 

Código
dtoverlay=dwc2,dr_mode=periférico

Nota
Necesitas a opción dr_mode=peripheral na capa superior para forzar o controlador ao modo periférico OTG (en lugar de host), xa que a liña OTG_ID que normalmente faría a selección non está presente en Raspberry Pi 4 ou 5.)

Cargar un módulo de gadget (Ethernet):
Código
sudo modprobe x_ether
A túa Raspberry Pi agora enumerarase como un dispositivo USB no host.

Consello
Non todos os sistemas host xestionan o modo OTG da Raspberry Pi 4 de forma fiable. Ethernet e serie funcionan mellor.

Serie de módulos de computación Raspberry Pi
Os módulos de computación 1, 3, 3+ e 4 de Raspberry Pi expoñen o controlador USB OTG do SoC directamente á placa portadora, o que os fai moi flexibles.
CM1/CM3/CM3+ A interface USB OTG está dispoñible en pines dedicados; as placas base adoitan expoñeraa a través dun porto micro-USB. CM4 ofrece unha interface USB 2.0 compatible con OTG (USB_OTG). Esta está enrutada ao conector micro-USB da placa de E/S do módulo de computación 4.

CM4 OTG example (dispositivo Ethernet)
Conecta un cable micro-USB ao porto USB da placa de E/S.

En /boot/firmware/config.txt, engade:

Código
dtoverlay=dwc2,dr_mode=periférico

En /boot/cmdline.txt, engade:

• Código
• carga-de-módulos=dwc2,g_ether

Reinicia. O módulo de computación 4 aparecerá agora como un adaptador Ethernet USB.

Raspberry Pi A, B, B+, 2B, 3B, 3B+
Os portos USB destes modelos conéctanse a través dun chip concentrador (LAN9512/LAN9514 ou VIA Labs), que elimina as capacidades OTG. Só poden funcionar como hosts USB, polo que non hai compatibilidade con OTG dispoñible.

Usando os distintos tipos de dispositivos
Esta sección describe como configurar os modos de gadget máis habituais.

Dispositivos de almacenamento masivo
Para usar unha Raspberry Pi como dispositivo de almacenamento masivo (como unha memoria USB), necesitarás crear unha copia de seguridade. file para gardar os datos almacenados:

• Código
  • # Example: Crear 256 MB file para actuar como "memoria USB"
  • sudo dd se=/dev/cero de=unidade.bin bs=1M contador=256
  • # Crear unha VFAT file sistema na tenda de apoio
  • sudo mkfs.vfat unidade.bin
• Edita /etc/modprobe.d/g_mass_storage.conf para indicarlle ao sistema que use o almacén de reserva:
  • Código
  • opcións g_mass_storage file=/drive.bin stall=0 extraíble=1
  • Podes examinar o contido do almacén de copias de seguridade montándoo na túa Raspberry Pi. Aquí montámolo nun cartafol chamado mountpoint:
• Código
  • sudo mkdir punto de montaxe
  • sudo mount -o bucle unidade.bin punto de montaxe

Terás que axustar os camiños segundo corresponda.

Dispositivos Ethernet
Cando o dispositivo g_ether está conectado a un servidor Linux, normalmente aparecerá como unha interface de rede chamada usb0 (cando se usa ifconfig).
Podes (normalmente) conectarte ao dispositivo usando SSH, do seguinte xeito:

• Código
• ssh pi@raspberrypi.local

Dispositivos en serie

Cando unha Raspberry Pi se configura como un dispositivo g_serial, aparece un novo dispositivo serie (cando se usa Raspberry Pi OS Bookworm cun kernel 6.12.34, este era /dev/ttyGS0). Cando ese dispositivo Raspberry Pi se conecta a un porto (por exemploample, Linux), o dispositivo recoñecerase como un dispositivo compatible con CDC ACM e aparecerá como outro porto serie. Por exemploampé dicir, nunha Raspberry Pi 500 con Bookworm, aparece como /dev/ttyACM0.
En Linux, podes probar a conexión serie usando a pantalla en cada dispositivo. Se usas Windows no host, algo como Putty debería funcionar ben.

Na túa Raspberry Pi:

• Código
• pantalla /desenvolvemento/ttyGS0

Nun servidor Linux:

• Código
• pantalla /dev/ttyACM0

Despois escribe algo en cada xanela; a saída debería aparecer na outra pantalla.

Nota
Se screen non está instalado, use sudo apt install screen nunha xanela de terminal.
É doado ver como esta funcionalidade podería empregarse para proporcionar unha interface serie a un dispositivo Raspberry Pi que monitoriza varios sensores (por exemplo, a través de I2C ou SPI) e transmite a información recompilada de volta, a través do porto serie, ao ordenador anfitrión.

ConfigFS/usb_gadget: un mundo novo e valente

Aínda que son, de lonxe, a forma máis común de configurar OTG en dispositivos Raspberry Pi, os mecanismos descritos anteriormente foron substituídos por algo chamado usb_gadget, que forma parte de ConfigFS.
ConfigFS é unha interface do kernel de Linux (unha interface virtual file sistema montado en /sys/kernel/config) usado para configurar obxectos do kernel, incluídos os controladores de dispositivos USB, de xeito modular. Empregar ConfigFS /usb_gadget é máis flexible que o antigo método g_mass_storage /g_ether, porque permite compor varias funcións USB (por exemplo, Ethernet + serie + almacenamento masivo) á vez.
Non obstante, esta funcionalidade adicional ten un custo de configuración máis elevado.
A idea básica é que un conxunto de cartafoles virtuais e files créase no cartafol /sys/kernel/config, que define o gadget necesario.
Algunha documentación do núcleo sobre usb_gadgets está dispoñible aquí: https://docs.kernel.org/driver-api/usb/gadget.html e https://www.kernel.org/doc/Documentation/ABI/testing/configfs-usb-gadget.

Configuración
A configuración do periférico USB DWC é a mesma que no modo herdado. Edita config.txt como sudo e engade:

Podemos comprobar que se cargou correctamente observando o contido de /sys/kernel/config, que agora debería conter unha carpeta chamada usb_gadget.
A continuación, procedemos á creación do propio dispositivo USB, que implica crear un cartafol co nome do dispositivo e, a seguir, crear un conxunto de entradas dentro dese cartafol para definir as propiedades do dispositivo. Este extracto do script bash realiza a maior parte da configuración necesaria:

Agora que os datos básicos do dispositivo foron configurados, precisamos indicarlle exactamente o que é. Crear cada dispositivo é tan sinxelo como crear unha carpeta na carpeta de funcións do gadget ConfigFS e logo vincular esa carpeta á entrada de configuración dentro do mesmo gadget.

Serie (CDC ACM):

Ethernet (RNDIS e ECM):

Almacenamento masivo:
Do mesmo xeito que coa configuración herdada, precisamos un almacén de apoio para o noso dispositivo de almacenamento masivo:

E para usar iso:

Consello
/sys/class/udc é un directorio dentro de sysfs file sistema que representa os controladores de dispositivos USB (UDC) dispoñibles. Permite que o subsistema de dispositivos USB do núcleo identifique e interactúe cos UDC de hardware dun dispositivo, o que permite que o sistema funcione como un periférico USB. Podes listar o seu contido usando ls /sys/class/udc/ para atopar o nome do UDC, como 3f980000.usb, e despois escribir ese nome na configuración dun dispositivo para vincular o dispositivo ao UDC.

Unha vez completada a configuración, a estrutura e o contido dos cartafoles deberían parecerse aos anteriores.ampa continuación, que configura tanto un dispositivo serie como un dispositivo Ethernet no mesmo dispositivo:

Agora reinicie e conecte o dispositivo Raspberry Pi a un dispositivo anfitrión (por exemplo, outra Raspberry Pi, un PC con Windows ou un PC con Linux). O anfitrión debería ter un dispositivo USB Ethernet e un dispositivo serie conectados.

Facer que todo funcione
Todos os comandos descritos anteriormente deben executarse cada vez que se inicia o dispositivo Raspberry Pi. Dado que Raspberry Pi OS usa systemd, esa é a forma axeitada de executar o script de inicio que realiza toda a configuración. Aquí tes un exemplo.ampo script que recompila todas as instrucións anteriores:

Agora precisamos indicarlle a systemd que execute o noso script ao iniciar.
Crear un file en /lib/systemd/system — o nome que escollas depende de ti (sempre que o sufixo sexa .service ), pero para este exemploampé dicir, usaremos mass-storage-device.service. Introduza o seguinte no campo file (teña en conta que hai moitas opcións diferentes para estes servizos) files; acabamos de usar os que necesitamos):

Terás que cambiar a liña ExecStart para que apunte a onde gardaches o script de configuración. Despois, terás que indicarlle a systemd que execute o servizo ao iniciar:

Agora, cando conectes a túa Raspberry Pi a un host, debería aparecer como un dispositivo de almacenamento masivo. Podes desactivar o servizo systemd do seguinte xeito:

Conectar unha consola de inicio de sesión a un porto serie

Se configuraches a túa Raspberry Pi como un dispositivo serie, quizais queiras usar ese dispositivo serie para iniciar sesión no dispositivo, en lugar de usalo só para a comunicación serie punto a punto. Na última versión de Raspberry Pi OS con systemd, isto é sinxelo. Debes indicarlle ao sistema que cree un getty no porto serie e, a seguir, indicarlle a systemd que o inicie. O seguinte configura o getty en ttyGS0 (o tty creado ao usar ConfigFS para configurar un dispositivo serie); pode que teñas que axustalo para que coincida co tty ao que estea asignado o dispositivo serie.

Isto iniciará getty no porto serie e garantirá que se inicie automaticamente en cada reinicio.

Consello
Que é un getty? En Linux, un getty é un programa que xestiona terminais (tanto portos serie físicos como consolas virtuais) para permitir que varios usuarios inicien sesión nun sistema, xestionando tarefas como inicializar o terminal, mostrar unha mensaxe de inicio de sesión e invocar o programa de inicio de sesión para autenticar o usuario.

Esta funcionalidade pode ser especialmente útil en dispositivos como unha Raspberry Pi Zero ou unha Raspberry Pi Zero 2 W. Cunha soa conexión USB que proporciona alimentación e comunicación en serie, podes conectar o dispositivo e iniciar sesión nel a través dun terminal.

Conclusión
Para proxectos de dispositivos USB reais (por exemplo, Ethernet, serie, almacenamento masivo), a familia Raspberry Pi Zero e os módulos de computación Raspberry Pi son a mellor opción.
A Raspberry Pi 4 e a Raspberry Pi 5 ofrecen compatibilidade con OTG, pero os seus requisitos de alimentación poden ser un problema.
As placas Raspberry Pi A, B, 2B, 3B e 3B+ non admiten OTG.
Se o teu proxecto depende moito de OTG, as mellores opcións son Raspberry Pi Zero 2 W ou Raspberry Pi Compute Module 4 coa placa de E/S Compute Module 4.
Hai dúas opcións no que respecta ao software: o sistema herdado aínda se usa habitualmente e é doado de configurar; o sistema ConfigFS require máis traballo de configuración, pero ofrece unha mellor funcionalidade.

Táboa de referencia rápida

Modelo	Soporte OTG	Notas
Raspberry Pi Zero / Zero W / Zero 2 W	Si	Totalmente compatible co porto de datos USB
Raspberry Pi 4	Si ¹	Porto USB-C no modo de dispositivo
Raspberry Pi 5	Si ¹	Porto USB-C no modo de dispositivo
Raspberry Pi A/B/2B/3B/3B+	Non	Só modo anfitrión
Módulo de computación 1–3 de Raspberry Pi	Si	Exposto en pines OTG
Módulo de cálculo Raspberry Pi 4	Si	micro-USB na placa de E/S CM4

¹ As Raspberry Pi 4 e 5 adoitan consumir enerxía do host a través do cable USB, polo que pode haber limitacións na corrente dispoñible debido aos maiores requisitos de enerxía destes dispositivos.

Datos de contacto para máis información
Póñase en contacto applications@raspberrypi.com se tes algunha dúbida sobre este documento técnico. Web: www.raspberrypi.com

Preguntas frecuentes

Cales son os riscos asociados á activación do modo OTG?

A activación do modo OTG require o sistema de edición fileque poden supoñer un risco se se fan incorrectamente. Recoméndase seguir as instrucións atentamente e facer unha copia de seguridade dos datos importantes antes de facer cambios.

Podo usar o modo OTG en modelos de Raspberry Pi que non sexan Zero, Zero W e Zero 2 W?

Aínda que as instrucións proporcionadas son específicas para os modelos mencionados, podes explorar configuracións semellantes noutros SBC de Raspberry Pi coas adaptacións axeitadas.

Documentos/Recursos

Ordenador de placa única ResearchGate Raspberry Pi [pdfManual de instrucións Ordenador de placa única Raspberry Pi, Raspberry Pi, Ordenador de placa única, Ordenador de placa, Ordenador

Referencias

• Manual de usuario