ResearchGate Raspberry Pi Komputer jednopłytkowy

Informacje o produkcie

Specyfikacje

• Producent: Raspberry Pi Ltd
• Data budowy: 01
• Wersja kompilacji: 99a8b0292e31
• Obsługiwane produkty Raspberry Pi: Pi Zero, Pi Zero 2 W, Pi 1 AB, Pi 2, Pi 3, Pi 4, Pi 5, moduły obliczeniowe CM1, CM3, CM4, CM5

Kolofon
© 2022-2025 Raspberry Pi Sp. z o.o.

Niniejsza dokumentacja jest licencjonowana na podstawie Creative Commons Uznanie autorstwa-Bez utworów zależnych 4.0 Międzynarodowe (CC BY-ND).

Uwolnienie	1
Data budowy	01/10/2025
Wersja kompilacji	99a8b0292e31

Zastrzeżenie prawne
DANE TECHNICZNE I DOTYCZĄCE NIEZAWODNOŚCI PRODUKTÓW RASPBERRY PI (W TYM ARKUSZE DANYCH), W MODYFIKOWANE OD CZASU DO CZASU („ZASOBY”), SĄ DOSTARCZANE PRZEZ FIRMĘ RASPBERRY PI LTD („RPL”) „W STANIE, W JAKIM SIĘ ZNAJDUJĄ”, A WSZELKIE WYRAŹNE LUB DOROZUMIANE GWARANCJE, W TYM MIĘDZY INNYMI DOROZUMIANE GWARANCJE PRZYDATNOŚCI HANDLOWEJ I PRZYDATNOŚCI DO OKREŚLONEGO CELU, SĄ WYŁĄCZONE. Maksymalnie w zakresie dozwolonym przez obowiązujące prawo, w żadnym wypadku RPL nie ponosi odpowiedzialności za żadne bezpośrednie, pośrednie, przypadkowe, szczególne, przykładowe lub następcze szkody (w tym między innymi za zakup towarów lub usług zastępczych; utratę możliwości użytkowania, danych lub zysków; lub przerwę w działalności) bez względu na przyczynę i na podstawie jakiejkolwiek teorii odpowiedzialności, czy to na podstawie umowy, ścisłej odpowiedzialności, czy czynu niedozwolonego (w tym zaniedbania lub innej przyczyny), wynikające w jakikolwiek sposób z korzystania z zasobów, nawet jeśli poinformowano o możliwości wystąpienia takich szkód.

RPL zastrzega sobie prawo do wprowadzania wszelkich udoskonaleń, poprawek, korekt lub innych modyfikacji ZASOBÓW lub opisanych w nich produktów w dowolnym momencie i bez wcześniejszego powiadomienia.
ZASOBY są przeznaczone dla doświadczonych użytkowników z odpowiednim poziomem wiedzy projektowej. Użytkownicy ponoszą wyłączną odpowiedzialność za swój wybór i użytkowanie ZASOBÓW oraz wszelkie zastosowanie opisanych w nich produktów. Użytkownik zgadza się zabezpieczyć i zwolnić RPL z odpowiedzialności za wszelkie zobowiązania, koszty, szkody lub inne straty wynikające z korzystania z ZASOBÓW.
RPL udziela użytkownikom pozwolenia na korzystanie z ZASOBÓW wyłącznie w połączeniu z produktami Raspberry Pi. Wszelkie inne wykorzystanie ZASOBÓW jest zabronione. Nie udziela się licencji na żadne inne prawa własności intelektualnej RPL ani innych osób trzecich.

DZIAŁANIA WYSOKIEGO RYZYKA. Produkty Raspberry Pi nie są projektowane, produkowane ani przeznaczone do użytku w niebezpiecznych środowiskach wymagających niezawodnego działania, takich jak eksploatacja obiektów jądrowych, systemów nawigacji lub komunikacji lotniczej, kontroli ruchu lotniczego, systemów uzbrojenia lub zastosowań krytycznych dla bezpieczeństwa (w tym systemów podtrzymywania życia i innych urządzeń medycznych), w których awaria produktów mogłaby prowadzić bezpośrednio do śmierci, obrażeń ciała lub poważnych szkód fizycznych lub środowiskowych („Działania wysokiego ryzyka”). RPL wyraźnie zrzeka się wszelkich wyraźnych lub dorozumianych gwarancji przydatności do działań wysokiego ryzyka i nie ponosi odpowiedzialności za użytkowanie lub włączenie produktów Raspberry Pi do działań wysokiego ryzyka.
Produkty Raspberry Pi są dostarczane zgodnie ze Standardowymi Warunkami RPL. Dostarczanie ZASOBÓW przez RPL nie rozszerza ani w żaden inny sposób nie modyfikuje Standardowych Warunków RPL, w tym, ale nie wyłącznie, zrzeczeń się odpowiedzialności i gwarancji wyrażonych w nich.

Historia wersji dokumentu

Uwolnienie	Data	Opis
1	1 paź 2025	Pierwsze wydanie

Zakres dokumentu
Ten dokument dotyczy następujących produktów Raspberry Pi:

Komputery jednopłytkowe / SBC

Pi-zero	Pi Zero 2	Pi 1	Pi 2	Pi 3	Pi 4	Pi 5
✓	✓	✓	✓	✓	✓	–

Moduły obliczeniowe

CM1	CM3	CM4	CM5
✓	✓	✓	✓

Wstęp

USB On-The-Go (OTG) to specyfikacja, która pozwala urządzeniu działać jako host USB (jak komputer) lub jako urządzenie/urządzenie peryferyjne USB (jak klawiatura, adapter Ethernet lub urządzenie pamięci masowej). Strona Wikipedii „USB On-The-Go” zawiera wiele szczegółowych informacji na temat specyfikacji OTG: https://en.wikipedia.org/wiki/USB_On-The-Go.
Zazwyczaj połączenie USB obejmuje stały host (np. komputer) i urządzenie peryferyjne (np. mysz). USB OTG umożliwia urządzeniu przełączanie się między nimi. Na przykładampnp. Raspberry Pi może pełnić rolę hosta podczas odczytu filez dysku flash lub działać jako dysk flash po podłączeniu do komputera.

Rodzina Raspberry Pi obejmuje kilka płytek, które mogą działać w trybie OTG/peryferyjnym, ale obsługa różni się w zależności od modelu i układu SoC (System-on-Chip). Działając w tym trybie peryferyjnym, urządzenie jest często nazywane „gadżetem”.
W tym dokumencie omówiono gamę procesorów SBC Raspberry Pi, wyjaśniono ich możliwości OTG i przedstawiono przykładowe konfiguracje/kodampObejmuje ona dwa odrębne mechanizmy OTG: metodę legacy, która jest nadal bardzo popularna i jest opisana jako pierwsza, a następnie obecnie zalecany schemat ConfigFS.

Legacy OTG

Raspberry Pi Zero / Zero W / Zero 2 W
Te płytki są najbardziej przyjazne dla OTG w rodzinie Raspberry Pi. Kontroler USB SoC jest bezpośrednio podłączony do portu danych USB (oznaczonego USB, a nie PWR IN), a oprogramowanie wbudowane można skonfigurować tak, aby Raspberry Pi działało jako urządzenie OTG.

Włączanie trybu OTG

Wskazówka: Ponieważ używasz jedynego portu USB w Raspberry Pi Zero do funkcji OTG, nie będziesz mógł podłączyć klawiatury ani myszy. Zamiast tego możesz skorzystać z połączenia Wi-Fi i SSH, aby komunikować się z Raspberry Pi Zero…

dtoverlay=dwc2

Teraz musimy skonfigurować oprogramowanie, aby podłączyć żądany sterownik OTG do systemu USB…

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

Inne moduły gadżetów
Zamiast g_ether, możesz spróbować:

• g_serial:Wyświetla się jako urządzenie szeregowe USB
• g_mass_storage: Naświetla obraz file jako dysk flash
• g_composite:Emuluje urządzenie kompozytowe

Wskazówka
Urządzenie kompozytowe USB to pojedyncze urządzenie fizyczne, które działa jako wiele niezależnych urządzeń w komputerze, występując jako kilka oddzielnych interfejsów lub klas urządzeń. Łączy różne funkcjonalności, takie jak klawiatura i mysz lub dysk pamięci masowej i… webcam, w jedno urządzenie USB i złącze. Po podłączeniu system operacyjny rozpoznaje i używa oddzielnych sterowników dla każdej z funkcji urządzenia, umożliwiając im niezależną pracę.

Aby utworzyć gadżet szeregowy USB, możemy załadować odpowiedni moduł z wiersza poleceń:

• Kod
• sudo modprobe g_serial

Po podłączeniu do komputera z systemem Windows, Raspberry Pi pojawi się jako port COM w Menedżerze urządzeń; po podłączeniu do urządzenia z systemem Linux (np. komputera SBC Raspberry Pi), pojawi się jako urządzenie szeregowe, takie jak /dev/ttyACM0.

Raspberry Pi 4 i 5 (OTG na porcie zasilania USB-C)
Port zasilania/OTG USB-C Raspberry Pi 4 obsługuje tryb urządzeń peryferyjnych, gdy nie jest używany do zasilania płytki.
Raspberry Pi 5 wprowadza kontroler USB podłączony do PCIe, który nie obsługuje OTG. Jednak, podobnie jak w Raspberry Pi 4, natywna funkcja OTG układu SoC jest dostępna poprzez złącze zasilania.

Kroki
Podłącz Raspberry Pi do złącza GPIO (5 V i GND), pozostawiając wolne złącze USB-C.
Podłącz port USB-C do komputera hosta.

Włącz OTG w pliku /boot/firmware/config.txt 

Kod
dtoverlay=dwc2,dr_mode=peryferyjne

Notatka
Aby wymusić przejście kontrolera w tryb OTG peryferyjny (a nie hosta), należy ustawić opcję dr_mode=peripheral w nakładce, ponieważ linia OTG_ID, która normalnie dokonuje tego wyboru, nie jest dostępna w Raspberry Pi 4 i 5.)

Załaduj moduł gadżetu (Ethernet):
Kod
sudo modprobe g_ether
Twój Raspberry Pi będzie teraz widoczny jako urządzenie USB u hosta.

Wskazówka
Nie wszystkie systemy hosta obsługują niezawodnie tryb OTG Raspberry Pi 4. Najlepiej sprawdzają się Ethernet i port szeregowy.

Seria modułów obliczeniowych Raspberry Pi
Moduły Raspberry Pi Compute 1, 3, 3+ i 4 udostępniają kontroler USB OTG SoC bezpośrednio na płytce nośnej, co zapewnia im dużą elastyczność.
CM1/CM3/CM3+ Interfejs USB OTG jest dostępny na dedykowanych pinach; płytki nośne często udostępniają go poprzez port micro-USB. CM4 oferuje interfejs USB 2.0 (USB_OTG) z obsługą OTG. Jest on podłączony do złącza micro-USB płytki Compute Module 4 IO.

CM4 OTG example (gadżet Ethernet)
Podłącz kabel micro-USB do portu USB na płytce IO.

W pliku /boot/firmware/config.txt dodaj:

Kod
dtoverlay=dwc2,dr_mode=peryferyjne

W pliku /boot/cmdline.txt dodaj:

• Kod
• moduły-ładowanie=dwc2,g_ether

Uruchom ponownie. Moduł Compute Module 4 będzie teraz widoczny jako adapter USB Ethernet.

Raspberry Pi A, B, B+, 2B, 3B, 3B+
Porty USB w tych modelach są połączone za pomocą układu koncentratora (LAN9512/LAN9514 lub VIA Labs), który pozbawia je możliwości obsługi OTG. Mogą one działać jedynie jako hosty USB, więc obsługa OTG nie jest dostępna.

Korzystanie z różnych typów urządzeń
W tej sekcji opisano sposób konfiguracji najpopularniejszych trybów gadżetów.

Urządzenia pamięci masowej
Aby używać Raspberry Pi jako urządzenia pamięci masowej (np. pendrive'a), należy utworzyć kopię zapasową file do przechowywania zapisanych danych:

• Kod
  • # Byłyample: Zrób 256 MB file działać jako „pamięć USB”
  • sudo dd if=/dev/zero of=drive.bin bs=1M count=256
  • # Utwórz plik VFAT file system na magazynie zapasowym
  • sudo mkfs.vfat drive.bin
• Edytuj plik /etc/modprobe.d/g_mass_storage.conf, aby poinformować system o konieczności użycia magazynu kopii zapasowych:
  • Kod
  • opcje g_mass_storage file=/drive.bin stall=0 removable=1
  • Możesz sprawdzić zawartość magazynu kopii zapasowych, montując go na Raspberry Pi. Tutaj montujemy go w folderze o nazwie mountpoint:
• Kod
  • sudo mkdir punkt montowania
  • sudo mount -o loop drive.bin punkt montowania

Będziesz musiał odpowiednio dostosować ścieżki.

Urządzenia Ethernetowe
Po podłączeniu urządzenia g_ether do hosta Linux, zwykle pojawi się ono jako interfejs sieciowy o nazwie usb0 (w przypadku korzystania z ifconfig).
Zazwyczaj można połączyć się z urządzeniem za pomocą protokołu SSH w następujący sposób:

• Kod
• ssh pi@raspberrypi.local

Urządzenia szeregowe

Po skonfigurowaniu Raspberry Pi jako urządzenia g_serial pojawi się nowe urządzenie szeregowe (w przypadku Raspberry Pi OS Bookworm z kernelem 6.12.34 było to /dev/ttyGS0). Po podłączeniu tego urządzenia Raspberry Pi do (np.ample, Linux), urządzenie zostanie rozpoznane jako urządzenie zgodne ze standardem CDC ACM i pojawi się jako kolejny port szeregowy. Na przykładampnp. na Raspberry Pi 500 z systemem Bookworm, pojawia się jako /dev/ttyACM0.
W systemie Linux można przetestować połączenie szeregowe, używając screena na każdym urządzeniu. Jeśli używasz systemu Windows na hoście, program taki jak Putty powinien działać bez problemu.

Na Twoim Raspberry Pi:

• Kod
• ekran /dev/ttyGS0

Na hoście Linux:

• Kod
• ekran /dev/ttyACM0

Następnie wpisz coś w każdym oknie — wynik powinien pojawić się na drugim ekranie.

Notatka
Jeśli screen nie jest zainstalowany, użyj polecenia sudo apt install screen w oknie terminala.
Łatwo zrozumieć, w jaki sposób tę funkcjonalność można wykorzystać do zapewnienia interfejsu szeregowego dla urządzenia Raspberry Pi, które monitoruje szereg czujników (np. przez I2C lub SPI) i przesyła zebrane informacje z powrotem, przez port szeregowy, do komputera hosta.

ConfigFS/usb_gadget: nowy, wspaniały świat

Mimo że są to zdecydowanie najpopularniejsze sposoby konfiguracji OTG na urządzeniach Raspberry Pi, mechanizmy opisane powyżej zostały już zastąpione przez coś o nazwie usb_gadget, co jest częścią ConfigFS.
ConfigFS to interfejs jądra Linux (wirtualny file System zamontowany w /sys/kernel/config) służy do modułowej konfiguracji obiektów jądra — w tym sterowników gadżetów USB. Korzystanie z ConfigFS/usb_gadget jest bardziej elastyczne niż stara metoda g_mass_storage/g_ether, ponieważ umożliwia jednoczesne łączenie wielu funkcji USB (np. Ethernet + port szeregowy + pamięć masowa).
Jednak ta dodatkowa funkcjonalność wiąże się z wyższymi kosztami konfiguracji.
Podstawowym założeniem jest to, że zestaw wirtualnych folderów i files jest tworzony w folderze /sys/kernel/config i definiuje wymagany gadżet.
Część dokumentacji jądra usb_gadgets jest dostępna tutaj: https://docs.kernel.org/driver-api/usb/gadget.html I https://www.kernel.org/doc/Documentation/ABI/testing/configfs-usb-gadget.

Organizować coś
Konfiguracja urządzenia peryferyjnego USB DWC przebiega tak samo, jak w trybie legacy. Edytuj plik config.txt jako sudo i dodaj:

Możemy sprawdzić, czy zostało ono załadowane prawidłowo, przeglądając zawartość pliku /sys/kernel/config, który powinien teraz zawierać folder o nazwie usb_gadget.
Następnym krokiem jest utworzenie właściwego gadżetu USB, co wymaga utworzenia folderu z nazwą gadżetu, a następnie utworzenia w nim zestawu wpisów definiujących jego właściwości. Ten fragment skryptu powłoki Bash wykonuje większość wymaganych czynności konfiguracyjnych:

Teraz, gdy podstawowe dane urządzenia zostały skonfigurowane, musimy dokładnie określić jego przeznaczenie. Utworzenie każdego urządzenia jest tak proste, jak utworzenie folderu w folderze funkcji gadżetu ConfigFS, a następnie powiązanie go z wpisem konfiguracji w tym samym gadżecie.

Numer seryjny (CDC ACM):

Ethernet (RNDIS i ECM):

Pamięć masowa:
Podobnie jak w przypadku starszej konfiguracji, potrzebujemy magazynu kopii zapasowych dla naszego gadżetu pamięci masowej:

A żeby to wykorzystać:

Wskazówka
/sys/class/udc to katalog w systemie plików sysfs file System reprezentujący dostępne kontrolery urządzeń USB (UDC). Umożliwia on podsystemowi gadżetów USB jądra identyfikację i interakcję ze sprzętowymi kontrolerami UDC w urządzeniu, umożliwiając systemowi funkcjonowanie jako urządzenie peryferyjne USB. Można wyświetlić jego zawartość za pomocą polecenia ls /sys/class/udc/, aby znaleźć nazwę kontrolera UDC, na przykład 3f980000.usb, a następnie zapisać tę nazwę w konfiguracji gadżetu, aby powiązać go z kontrolerem UDC.

Po zakończeniu konfiguracji struktura i zawartość folderów powinny przypominać te z pliku exampPoniżej znajduje się instrukcja, która umożliwia skonfigurowanie zarówno gadżetu szeregowego, jak i gadżetu Ethernet na tym samym urządzeniu:

Teraz uruchom ponownie komputer, a następnie podłącz Raspberry Pi do urządzenia hosta (np. innego Raspberry Pi, komputera z systemem Windows lub Linux). Do hosta powinno być podłączone urządzenie USB Ethernet i urządzenie szeregowe.

Sprawić, żeby wszystko działało
Wszystkie opisane powyżej polecenia należy uruchamiać przy każdym uruchomieniu urządzenia Raspberry Pi. Ponieważ system operacyjny Raspberry Pi korzysta z systemd, jest to właściwy sposób uruchomienia skryptu startowego, który wykonuje wszystkie ustawienia. Oto przykład.ampSkrypt zbierający wszystkie powyższe instrukcje:

Teraz musimy polecić systemd uruchomienie naszego skryptu przy starcie.
Utwórz file w /lib/systemd/system — nazwa, którą wybierzesz, zależy od Ciebie (pod warunkiem, że sufiksem będzie .service), ale w tym przypadkuampczyli użyjemy usługi mass-storage-device.service. Wprowadź poniższe polecenie do file (należy pamiętać, że istnieje wiele różnych opcji dla tej usługi files; użyliśmy tylko tych, których potrzebowaliśmy):

Musisz zmienić wiersz ExecStart, aby wskazywał miejsce zapisania skryptu instalacyjnego. Następnie musisz polecić systemd uruchomienie usługi podczas uruchamiania:

Po podłączeniu Raspberry Pi do hosta, powinno ono pojawić się jako urządzenie pamięci masowej. Możesz wyłączyć usługę systemd w następujący sposób:

Podłączanie konsoli logowania do portu szeregowego

Jeśli skonfigurowałeś Raspberry Pi jako urządzenie szeregowe, możesz chcieć użyć tego urządzenia do logowania się do urządzenia, zamiast używać go tylko do komunikacji szeregowej punkt-punkt. W najnowszej wersji systemu Raspberry Pi z systemem systemd jest to proste. Musisz poinstruować system, aby utworzył getty na porcie szeregowym, a następnie poinstruować systemd, aby go uruchomił. Poniższy kod konfiguruje getty na ttyGS0 (utworzonym podczas konfiguracji urządzenia szeregowego za pomocą ConfigFS); może być konieczne dostosowanie tego ustawienia do urządzenia tty, do którego przypisane jest urządzenie szeregowe.

Spowoduje to uruchomienie urządzenia getty na porcie szeregowym i automatyczne uruchomienie go przy każdym ponownym uruchomieniu.

Wskazówka
Czym jest getty? W systemie Linux getty to program zarządzający terminalami (zarówno fizycznymi portami szeregowymi, jak i konsolami wirtualnymi), umożliwiający wielu użytkownikom logowanie się do systemu. Zajmuje się on takimi zadaniami, jak inicjalizacja terminala, wyświetlanie monitu logowania i wywoływanie programu logowania w celu uwierzytelnienia użytkownika.

Funkcja ta może być szczególnie przydatna w przypadku urządzeń takich jak Raspberry Pi Zero czy Raspberry Pi Zero 2 W. Dzięki tylko jednemu złączu USB, które zapewnia zarówno zasilanie, jak i komunikację szeregową, możesz podłączyć urządzenie i zalogować się do niego za pomocą terminala.

Wniosek
W przypadku prawdziwych projektów gadżetów USB (np. Ethernet, port szeregowy, pamięć masowa) najlepszym wyborem będzie rodzina Raspberry Pi Zero i moduły Raspberry Pi Compute.
Raspberry Pi 4 i Raspberry Pi 5 oferują obsługę OTG, ale ich wymagania dotyczące zasilania mogą stanowić problem.
Płytki Raspberry Pi A, B, 2B, 3B i 3B+ nie obsługują funkcji OTG.
Jeśli Twój projekt w dużym stopniu opiera się na technologii OTG, najlepszym wyborem będzie Raspberry Pi Zero 2 W lub Raspberry Pi Compute Module 4 z płytką Compute Module 4 IO.
Po stronie oprogramowania dostępne są dwie opcje: starszy system jest nadal powszechnie używany i łatwy do skonfigurowania; system ConfigFS wymaga więcej pracy przy konfiguracji, ale oferuje lepszą funkcjonalność.

Szybka tabela odniesienia

Model	Wsparcie OTG	Notatki
Raspberry Pi Zero / Zero W / Zero 2 W	Tak	W pełni obsługiwane przez port danych USB
Raspberry Pi 4	Tak ¹	Port USB-C w trybie urządzenia
Raspberry Pi 5	Tak ¹	Port USB-C w trybie urządzenia
Raspberry Pi A/B/2B/3B/3B+	NIE	Tylko tryb hosta
Moduł obliczeniowy Raspberry Pi 1–3	Tak	Wyeksponowany na pinach OTG
Moduł obliczeniowy Raspberry Pi 4	Tak	micro-USB na płycie IO CM4

¹ Raspberry Pi 4 i 5 zazwyczaj pobierają zasilanie z hosta za pośrednictwem kabla USB, więc mogą występować ograniczenia co do dostępnego prądu ze względu na większe wymagania energetyczne tych urządzeń.

Dane kontaktowe w celu uzyskania dalszych informacji
Proszę o kontakt aplikacje@raspberrypi.com Jeśli masz jakiekolwiek pytania dotyczące tego dokumentu, skontaktuj się z nami. Web: www.raspberrypi.com

Często zadawane pytania

Jakie zagrożenia wiążą się z włączeniem trybu OTG?

Włączenie trybu OTG wymaga edycji systemu files, które mogą stanowić zagrożenie, jeśli zostaną wykonane nieprawidłowo. Zaleca się dokładne przestrzeganie instrukcji i wykonanie kopii zapasowej ważnych danych przed wprowadzeniem zmian.

Czy mogę używać trybu OTG na innych modelach Raspberry Pi niż Zero, Zero W i Zero 2 W?

Chociaż podane instrukcje dotyczą konkretnych modeli, możesz wypróbować podobne konfiguracje na innych komputerach Raspberry Pi SBC po zastosowaniu odpowiednich adaptacji.

Dokumenty / Zasoby

ResearchGate Raspberry Pi Komputer jednopłytkowy [plik PDF] Instrukcja obsługi Komputer jednopłytkowy Raspberry Pi, Raspberry Pi, Komputer jednopłytkowy, Komputer płytkowy, Komputer

Odniesienia

• Instrukcja obsługi