Modo USB Gadget no Raspberry Pi OS – SSH e rede via USB
Modo USB Gadget no Raspberry Pi OS – SSH e rede via USBData de publicação: 18-02-2026 🕒 6 min de leitura
Usar um Raspberry Pi em modo headless fora do seu ambiente habitual pode rapidamente tornar-se inconveniente. Quartos de hotel sem portas Ethernet disponíveis, redes Wi-Fi escondidas atrás de portais cativos, protocolos locais de descoberta bloqueados ou simplesmente não saber qual endereço IP foi atribuído à sua placa — tudo isso pode transformar uma tarefa simples numa distração desnecessária.
É aqui que o Ethernet via USB (Ethernet over USB) se torna um conceito extremamente apelativo. A ideia é simples: ligar o Raspberry Pi ao computador através de um cabo USB, fazendo com que ele apareça como uma interface de rede, tal como o tethering USB num smartphone. Um único cabo é suficiente para fornecer alimentação, acesso à rede, ligação direta via SSH e — opcionalmente — acesso à internet partilhado a partir da máquina anfitriã.
Historicamente, no entanto, configurar isto estava longe de ser simples. A maioria das soluções dependia de ajustes manuais no sistema, scripts desatualizados ou instruções específicas para determinada plataforma que funcionavam de forma fiável apenas num sistema operativo de cada vez. A Partilha de Ligação à Internet (ICS) era frequentemente tratada como um complemento opcional, em vez de uma parte central do fluxo de trabalho.
O objetivo da nova abordagem foi simplificar esta experiência e oferecer uma solução limpa e integrada, que funcione igualmente bem tanto para utilizadores iniciantes do Raspberry Pi como para implementações headless de maior escala.
rpi-usb-gadget – Rede USB simplificada
A partir das imagens Raspberry Pi OS Trixie datadas de 20 de outubro de 2025 ou posteriores, um novo pacote chamado rpi-usb-gadget está incluído por defeito. Pode ser ativado diretamente no Raspberry Pi Imager com um único interruptor.
Depois de ativado:
- O Raspberry Pi apresenta-se como um dispositivo USB Ethernet
- Pode ligar-se via SSH imediatamente, sem configurar Wi-Fi ou Ethernet
- Se a Partilha de Ligação à Internet estiver ativada no anfitrião, o Raspberry Pi obtém automaticamente acesso à internet
- Um serviço leve em segundo plano monitoriza a conectividade USB e o estado da rede, alternando dinamicamente os modos
- O comportamento geral é muito semelhante ao tethering USB — mas concebido especificamente para o Raspberry Pi
A solução funciona em Windows, macOS e Linux, sem necessidade de seleção manual de modo.
Requisitos de hardware e portas USB
O modo USB Gadget requer uma porta que suporte USB OTG (modo dispositivo). Dependendo do modelo do Raspberry Pi, trata-se de:
| Modelo Raspberry Pi | Porta USB |
|---|---|
| Zero / Zero W / Zero 2 W | porta micro-USB mais próxima da HDMI (não “PWR IN”) |
| Raspberry Pi 4 / 5 / 500 / 500+ | porta USB-C integrada |
| Compute Module 5 | USB-C na placa CM5 IO Board |
| Compute Module 4 | configuração manual necessária |
Importante: depois de ativado o modo gadget, a porta selecionada funciona exclusivamente como entrada de alimentação e rede USB. Já não pode ser utilizada como porta USB host normal para teclados, dispositivos de armazenamento ou outros periféricos.
Placas suportadas
- Raspberry Pi Zero (W) e Zero 2 W
- Raspberry Pi 3 Model A+
- Raspberry Pi 4 Model B
- Raspberry Pi 5, Raspberry Pi 500 e 500+
- Compute Module 5
- Compute Module 4 (suportado com configuração adicional)
Para maior estabilidade — especialmente nos modelos de maior potência — recomenda-se ligar o Raspberry Pi diretamente a uma porta USB do computador anfitrião. Se surgirem problemas relacionados com alimentação, a utilização de um Raspberry Pi USB 3 Hub permite fornecer energia externa enquanto mantém os dados a circular via USB.
Ativar o modo USB Gadget com o Raspberry Pi Imager
A forma mais simples de ativar a funcionalidade é através do Raspberry Pi Imager 2.0:
- Gerar um ficheiro os_list_local.rpi-imager-manifest com capacidades ativadas
- Fazer duplo clique no ficheiro de manifesto gerado para o carregar no Raspberry Pi Imager
- Selecionar uma imagem Raspberry Pi OS Trixie datada de 20.10.2025 ou mais recente
- Abrir o menu Customisation e ativar o SSH, definindo depois um nome de anfitrião (hostname)
- O hostname configurado será utilizado para ligar ao Raspberry Pi via SSH
- Abrir Interfaces & Features e ativar o USB Gadget Mode
- Gravar a imagem, inserir o meio de armazenamento no Raspberry Pi e ligá-lo ao anfitrião usando a porta USB/OTG correta
- Ligar o Raspberry Pi
O primeiro arranque pode demorar mais do que o habitual e pode incluir um reinício automático. Este comportamento é esperado.Após a conclusão do arranque, o Raspberry Pi deverá aparecer no sistema anfitrião como um novo adaptador Ethernet, e o acesso SSH através do hostname configurado deverá estar disponível.
Requisito de driver no Windows
O Windows não inclui um driver nativo para dispositivos USB Ethernet gadget. Por esse motivo, é disponibilizado um instalador dedicado:rpi-usb-gadget-driver-setup.exe
Esta instalação só precisa de ser realizada uma vez por sistema Windows.
Partilha de Ligação à Internet (ICS)
Para fornecer acesso à internet ao Raspberry Pi via USB, é necessário ativar a Partilha de Ligação à Internet (ICS) no computador anfitrião.
No Windows
- Ligar o Raspberry Pi e confirmar que aparece como um novo adaptador Ethernet
- Abrir Network Connections (ncpa.cpl)
- Identificar o adaptador principal ligado à internet (por exemplo, Wi-Fi) e abrir as suas propriedades
- No separador Partilha, ativar a partilha e selecionar o adaptador USB Ethernet do Raspberry Pi
- Confirmar as definições
Dentro de aproximadamente um minuto, o Raspberry Pi deverá receber um endereço IP.
Nota sobre o comportamento do ICS no Windows:Se o ICS estiver ativado enquanto o Raspberry Pi está desligado, o Windows pode associar o serviço DHCP a outra interface. Nestes casos, desativar o ICS em todos os adaptadores, voltar a ligar o Raspberry Pi e reativar o ICS normalmente resolve o problema.
No macOS
- Ligar o Raspberry Pi e aguardar até que apareça como dispositivo USB Ethernet
- Abrir System Settings → General → Sharing → Internet Sharing
- Configurar a fonte de internet (por exemplo, Wi-Fi) e selecionar a interface USB do Raspberry Pi como destino
- Ativar a Partilha de Internet
No LinuxAtivar o encaminhamento (routing) e NAT entre a interface principal de internet e a interface USB gadget do Raspberry Pi usando o NetworkManager ou ferramentas equivalentes. O procedimento exato depende da distribuição e da pilha de rede utilizada.
Ativar o modo USB gadget sem o Imager
Este método aplica-se apenas a sistemas baseados no Raspberry Pi OS Trixie.
Imagens novas (antes do primeiro arranque)
O modo USB gadget pode ser ativado automaticamente através do cloud-init:
rpi:
enable_usb_gadget: true
enable_ssh: trueRecomenda-se fortemente definir uma conta de utilizador e uma chave SSH no mesmo ficheiro de configuração, uma vez que o assistente de configuração não está acessível via SSH e os periféricos USB não podem ser ligados em placas da classe Zero enquanto o modo gadget estiver ativo.
Sistema existente
- Verificar se o sistema está a executar o Raspberry Pi OS Trixie
- Instalar e ativar o pacote:
sudo apt update
sudo apt install rpi-usb-gadget
sudo rpi-usb-gadget on
sudo rebootApós o reinício, a porta USB muda para o modo gadget. Quaisquer sessões SSH ativas serão brevemente interrompidas e voltarão a ligar-se automaticamente quando a interface USB Ethernet estiver disponível.
Detalhes técnicos
O pacote rpi-usb-gadget configura o módulo de kernel USB gadget g_ether, expondo uma interface Ethernet virtual que se adapta ao sistema operativo do anfitrião:
- Hosts Windows utilizam RNDIS
- Hosts macOS e Linux utilizam CDC-ECM
O modo apropriado é selecionado automaticamente durante a negociação do descritor USB, sem necessidade de intervenção do utilizador.
Um serviço em segundo plano monitoriza continuamente o estado da ligação USB, a disponibilidade de DHCP, o encaminhamento e a configuração DNS. Quando a Partilha de Ligação à Internet é detetada no anfitrião, as definições de gateway e DNS são aplicadas automaticamente para garantir conectividade à internet sem interrupções via USB.
Porque não existe consola série USB?
O CDC-ACM (USB série) é intencionalmente excluído. O Windows não consegue associar simultaneamente interfaces de rede RNDIS/ECM e interfaces série ACM a um único dispositivo USB composto utilizando apenas um ficheiro .inf sem drivers específicos do fabricante.
Resolução de problemas
Se a ligação não funcionar de imediato, considere as seguintes verificações:
Hardware e cablagem
Certifique-se de que está a utilizar a porta USB/OTG correta (nos modelos Zero, não pode ser a porta apenas de alimentação).Ligue diretamente ao computador anfitrião, evitando hubs ou docks que possam interferir com a negociação OTG.Utilize apenas um Raspberry Pi em modo gadget de cada vez para evitar conflitos de interface.Se o dispositivo reiniciar ou desligar repetidamente, a causa pode ser alimentação insuficiente.
ICS e DHCP
Aguarde até um minuto após ativar o ICS para a negociação DHCP.No Windows, desative e reative o ICS se a interface aparecer como partilhada, mas sem endereço IP atribuído.Remova ou desative adaptadores Ethernet não utilizados para evitar conflitos de encaminhamento.
Resolução de hostname
Se ssh [email protected] não resolver no Windows, instale suporte mDNS/Bonjour ou ligue-se utilizando o endereço IP atribuído.
Código-fonte e downloads
Embora o modo USB gadget esteja agora incluído por defeito no Raspberry Pi OS Trixie, todo o código-fonte, documentação e o instalador do driver para Windows continuam disponíveis publicamente. O repositório inclui também um sistema de acompanhamento de problemas e relatórios de implementações reais, especialmente relacionados com o comportamento do ICS em diferentes sistemas anfitriões.
Conclusão
O modo USB gadget melhora significativamente a experiência com o Raspberry Pi como uma plataforma de desenvolvimento plug-and-go. Não é necessária configuração de Wi-Fi, saída HDMI, teclado ou descoberta do endereço IP. Um único cabo USB é suficiente para alimentar o dispositivo, estabelecer ligação de rede e começar a trabalhar via SSH.
A solução foi concebida para ser acessível a iniciantes, mantendo-se robusta e escalável para utilizadores avançados e implementações de maior dimensão. Atualizações contínuas irão continuar a aperfeiçoar a deteção do anfitrião, o comportamento da partilha de internet e as capacidades de diagnóstico, com o feedback da comunidade a desempenhar um papel fundamental nas melhorias futuras.
A Transfer Multisort Elektronik (TME) é um dos maiores distribuidores globais de componentes eletrônicos, peças eletrotécnicas, equipamentos de oficina e automação industrial. O catálogo inclui mais de 1.500.000 de produtos de 1.300 fabricantes líderes. Os modernos centros logísticos da TME em Łódź e Rzgów (Polónia), com uma área total superior a 40.000 m², enviam quase 6.000 pacotes diariamente para clientes em mais de 150 países.
A TME também investe no desenvolvimento do conhecimento e das competências de jovens engenheiros e entusiastas da eletrónica através do projeto TME Education e apoia a comunidade tecnológica organizando a série de eventos TechMasterEvent, promovendo a inovação e a troca de experiências.
