Teensy 4.1 como dispositivo de entrada em um setup DMA
A montagem completa do Teensy 4.1: soldar os pads do host, gravar com o Teensy Loader, ordem dos cabos, controle por serial ou rede, taxas de relatório, ajuste do descritor e as falhas mais comuns.
Resposta curta
Solde um header de 5 pinos nos pads do host do Teensy 4.1 de 600 MHz e grave um firmware de passthrough com o Teensy Loader. Ligue o mouse na porta host e a porta device no PC de jogo, e comande a placa por serial.
Nesta página12
- O que é o Teensy 4.1
- Por que escolher um Teensy em vez de um dispositivo pronto?
- Como soldar a porta USB host
- Qual software você precisa e onde ficam os arquivos
- Como gravar o firmware e testar a porta host
- Em que ordem ligar os cabos
- Como escolher a conexão de controle e configurar o cheat
- Uma taxa de relatórios maior ajuda?
- Como mudar o descritor USB
- Problemas comuns do Teensy e como resolver
- Perguntas comuns sobre o Teensy
- Fontes
O que é o Teensy 4.1
O Teensy 4.1 é uma placa de microcontrolador de uso geral da PJRC que nunca foi projetada para este trabalho. É por isso que ela é barata, e também por isso que se torna o mais capaz destes dispositivos de entrada depois que você faz a parte difícil.
- Microcontrolador
- NXP i.MX RT1062, ARM Cortex-M7 com unidade de ponto flutuante em hardware
- Clock
- 600 MHz de fábrica, selecionável na IDE. Não faça overclock para este trabalho
- Flash
- Cerca de 8 MB (7936 K), muito mais do que qualquer firmware de passthrough precisa
- RAM
- 1024 K no total, 512 K deles fortemente acoplados ao núcleo
- Porta device
- O soquete micro-USB. USB 2.0 high speed, 480 Mbit/s. É esta ponta que olha para o PC de jogo
- Porta host
- Cinco pads passantes na placa, sem componentes de fábrica. Funciona a 480, 12 ou 1,5 Mbit/s conforme o que você ligar. É nesta ponta que o seu mouse entra
- 5V do host
- Chaveado pelo chip através de uma chave com limite de corrente. Os pads não têm energia até o firmware chamar a função begin da biblioteca de host
- Serial em hardware
- Oito UARTs, caso você queira uma conexão serial que não seja a porta USB device
- Ethernet
- Capaz de 10/100, mas o magjack é um kit separado que você solda. Não é necessário em uma montagem serial
- Gravação
- Teensy Loader, acionado automaticamente pela IDE do Arduino assim que o Teensyduino estiver instalado. Um botão Program físico força o bootloader
Por que escolher um Teensy em vez de um dispositivo pronto?
São três motivos, na ordem de quantas vezes cada um é o motivo de verdade. Primeiro, você compila o firmware, então decide qual descritor USB o PC de jogo vê e com que frequência os relatórios saem, coisa que nenhum dispositivo pronto permite. Segundo, os controladores de host e de device são totalmente independentes, então o passthrough não disputa banda com a injeção. Terceiro, é barato. O custo é que você vira o fabricante: quando algo der errado não existe canal de suporte, só a sua fiação e o seu código.
Atenção
Como soldar a porta USB host
Esta é a única solda obrigatória, e é ela que decide se o resto da montagem funciona. Os pads do host são cinco furos metalizados, sem componentes de fábrica, e levam o 5V do host, o par D-menos e D-mais e o terra. Siga a serigrafia e o cartão oficial de pinagem para a ordem, e não chute nem confie em um diagrama tirado de um post de fórum.
- Identifique os cinco pads de host na sua placa e confirme a ordem deles no cartão de pinagem da própria PJRC para o Teensy 4.1
- Encaixe um header macho de 5 pinos nos furos, ou prepare o cabo USB host que a PJRC vende para o Teensy 3.6 e 4.1
- Solde com ponta fina e liga de baixa temperatura, porque são pads pequenos em uma placa densa e uma ponta grossa vai fazer ponte entre eles
- Inspecione cada junta sob boa luz. Uma junta opaca, granulada ou em bolinha é solda fria, e é o motivo mais comum de uma porta host que não enumera nada
- Antes de energizar qualquer coisa, use o multímetro em continuidade para checar se há ponte entre D-menos e D-mais
- Se você usar fios soltos em vez do cabo, mantenha o par D-menos e D-mais curto e do mesmo comprimento, porque é um par diferencial que chega a 480 Mbit/s
- Não ligue o 5V do host a uma fonte externa por conveniência, porque a placa chaveia esse trilho sozinha e a chave tem limite de corrente por um motivo
Qual software você precisa e onde ficam os arquivos
Você precisa da IDE do Arduino mais o Teensyduino, o complemento da PJRC. O Teensyduino já traz a biblioteca de host e o Teensy Loader, então não é preciso instalar mais nada.
# After installing Teensyduino, set these three in the Arduino IDE:
Tools > Board > Teensy 4.1
Tools > USB Type > Serial + Keyboard + Mouse + Joystick
Tools > CPU Speed > 600 MHz
# The host-side library ships with Teensyduino. Prove the hardware with its own example:
File > Examples > USBHost_t36 > Mouse
# USB identity is defined in the core, not in your sketch:
<arduino>/hardware/teensy/avr/cores/teensy4/usb_desc.h
<arduino>/hardware/teensy/avr/cores/teensy4/usb_names.hAtenção
Como gravar o firmware e testar a porta host
Grave primeiro o exemplo Mouse do USBHost_t36, sem alterações. Ele imprime no monitor serial cada movimento e cada clique do mouse conectado, então prova a sua solda em uns trinta segundos. Antes de testar, lembre que o trilho de 5V dos pads do host é chaveado pelo chip, e não ligado direto. Se a placa estiver rodando um firmware que nunca inicia a biblioteca de host, um mouse na porta host nem vai acender. Uma porta host com cara de morta em uma placa assim não diz nada. Grave primeiro, teste depois e só então grave o firmware que o seu cheat espera.
- Ligue a porta micro-USB device do Teensy ao PC em que você está compilando
- Abra o exemplo Mouse do USBHost_t36, ajuste Board e USB Type como nas configurações da toolchain e clique em Upload
- O Teensyduino entrega a imagem compilada ao Teensy Loader, que reinicia a placa e grava a imagem. Em uma placa de fábrica isso acontece sozinho
- Se o upload travar, aperte uma vez o botão Program do Teensy. Isso força o bootloader, e aí o Loader encontra a placa
- Ligue um mouse com fio na porta host recém-soldada e abra o monitor serial
- Mexa o mouse. Se aparecerem eventos de movimento e de botão, a porta host funciona e a parte de hardware da montagem está pronta
- Agora compile e grave o firmware de passthrough que o seu cheat documenta, mantendo as mesmas configurações de Board e USB Type
- Depois da gravação final, tire a placa da energia e religue em vez de confiar em um reset por software
Em que ordem ligar os cabos
Se você errar essa sequência, é fácil perder uma hora depurando um cabo. A porta device olha para o PC de jogo porque é a ponta que se declara mouse, enquanto a porta host olha para a sua mão.
- Ligue o mouse físico, ou o dongle do seu mouse sem fio, na porta USB host soldada do Teensy
- Ligue a porta micro-USB device do Teensy direto a uma porta USB traseira do PC DE JOGO, sem hub e sem header de painel frontal
- Acrescente a conexão de controle vinda do SEGUNDO PC. Ela não pode dividir a porta device, porque a interface serial USB dessa porta enumera no PC de jogo, que é onde o cabo está ligado
- Use uma das oito UARTs de hardware para a conexão de controle. Coloque um adaptador USB-serial na ponta do segundo PC para que as duas máquinas nunca dividam um cabo
- Ligue o PC de jogo e confirme que o Windows mostra um dispositivo de mouse e que a sua mão move o cursor
- Só então inicie o software no segundo PC e abra a conexão
Dica
Como escolher a conexão de controle e configurar o cheat
Um USB Type composto te dá uma interface de mouse e uma interface serial no mesmo cabo. Essa interface serial aparece no PC de jogo, que é onde a porta device está ligada, então o segundo PC não consegue abri-la. Significa também que a máquina em que você está usando cheat tem um dispositivo serial saído do mesmo gadget composto do seu mouse, com as duas interfaces sob um único descritor. Então tire a conexão de controle de uma UART de hardware e coloque um adaptador USB-serial comum na ponta do segundo PC. O PC de jogo passa a ver um dispositivo que é só um mouse, o que te dá uma montagem mais limpa por um cabo e uma peça a mais. Seja qual for a conexão, o firmware define o protocolo e o cheat tem que combinar com ele. No menu de entrada do cheat você ajusta três coisas: o tipo de dispositivo, a porta COM e o baud rate. O tipo de dispositivo costuma aparecer como Teensy ou como dispositivo serial genérico. A porta COM é a que o segundo PC atribuiu, e o baud rate é aquele com que o firmware foi compilado. Os três têm que bater. Um baud rate errado não gera um erro claro, porque a conexão abre e depois não faz nada, o que é exatamente a cara de um dispositivo morto. Então confira o número da porta no Gerenciador de Dispositivos e force para menos de 10 se o cheat só lê um dígito, e anote o baud rate na hora de gravar em vez de tentar adivinhar depois.
Uma taxa de relatórios maior ajuda?
A porta device é USB high speed, então o descritor pode pedir intervalos menores que o piso de 1 ms que limita um mouse full speed. Na prática isso significa relatórios abaixo de um milissegundo, que é o motivo de as pessoas gostarem desta placa, mas é também onde o entusiasmo passa na frente da utilidade. Uma taxa de relatórios muito acima do que o próprio laço de entrada do jogo consome não traz benefício mensurável. Um fluxo de relatórios perfeitamente regular em uma taxa incomum também é um padrão, e padrões são justamente o que a análise comportamental procura. Use uma taxa que um mouse real daquela classe usaria de forma plausível. Não existe benchmark honesto mostrando que um número maior é mais seguro, e quem te citar um em milissegundos está inventando.
Dica
Como mudar o descritor USB
Como é você quem compila o firmware, você controla o vendor ID, o product ID, as strings de fabricante e de produto, o número de série e o HID report descriptor. Deixado como veio, um Teensy apresenta a identidade da própria PJRC, que é a identidade de uma placa de desenvolvimento em uma máquina que não tem outro motivo para ter uma. As strings e os IDs ficam em usb_desc.h e usb_names.h do core, não no seu sketch. O core 4.x oferece um caminho mais limpo: definir os descritores de string em um pequeno arquivo C separado, dentro da pasta do sketch. Depois que você muda o vendor ID e o product ID, o Teensyduino não consegue mais encontrar e reiniciar a placa sozinho, então todo upload seguinte exige apertar o botão Program. Isso é comportamento esperado, não uma placa inutilizada. Leia o guia de descritores antes de mudar qualquer coisa, porque copiar mal a identidade de um mouse real é pior do que deixar tudo de fábrica.
Problemas comuns do Teensy e como resolver
Trabalhe de cima para baixo. As quatro primeiras linhas cobrem quase tudo o que dá errado em uma primeira montagem, e três dessas quatro se resumem à solda.
| Sintoma | Causa provável | Solução |
|---|---|---|
| Mouse ligado na porta host não faz nada, e não acende nenhum LED no mouse | Ou uma solda fria nos pads do host, ou um firmware que nunca inicia a biblioteca de host e deixa o trilho de 5V desligado | Grave primeiro o exemplo Mouse do USBHost_t36. Se o mouse continuar sem dar sinal de vida, refaça a solda dos cinco pads e cheque a continuidade |
| A porta host enumera de forma intermitente, ou só dispositivos lentos funcionam | O par D-menos e D-mais está longo demais ou com comprimentos diferentes, ou há resíduo de solda entre os pads | Encurte o par e iguale os comprimentos, ou troque pelo cabo USB host adequado. Limpe os pads com álcool isopropílico e inspecione sob luz |
| O PC de jogo não mostra nenhum dispositivo de mouse | O USB Type na IDE não inclui Mouse, então a porta device nunca apresenta uma interface HID de mouse | Ajuste Tools > USB Type para uma opção que contenha Mouse, recompile, regrave e depois tire a placa da energia e religue |
| O upload falha ou trava em Waiting for Teensy device | O firmware em execução não está respondendo ao pedido de reinício, ou você mudou o vendor ID e o product ID | Aperte uma vez o botão Program da placa. Depois de mudar VID ou PID, você precisa fazer isso em todo upload |
| O cursor se move pelo cheat, mas o seu mouse não faz nada | O passthrough não está rodando: o lado host está morto enquanto o lado device funciona | Teste a porta host com o exemplo Mouse, porque a causa é quase sempre a solda |
| O seu mouse funciona, mas o cheat não abre a conexão | Porta COM errada, ou um baud rate que não bate com o firmware compilado | Ache a porta no Gerenciador de Dispositivos, coloque um número abaixo de 10 e ajuste o baud rate para o valor com que o firmware foi compilado |
| O movimento sai grosso ou em degraus, em vez de suave | O report descriptor usa campos de movimento de 8 bits, então deltas grandes saturam e saem em vários passos | Use um firmware cujo descritor declare eixos relativos de 16 bits, e deixe o cheat dividir os movimentos grandes em vez de largar isso para o descritor |
| A placa esquenta e o dispositivo no host cai sob carga | O dispositivo conectado puxa mais corrente do que o limite do trilho do host permite | Use um mouse com fio simples em vez de um cheio de RGB ou de um hub alimentado, e nunca ligue um hub cheio de dispositivos na porta host |
Perguntas comuns sobre o Teensy
Dá para usar um Teensy 4.0 no lugar do 4.1?
Não com conforto. O 4.0 expõe os sinais de host como dois pads de superfície, e não como cinco furos passantes com gerenciamento de energia, então você tem que ligar D-menos e D-mais na mão e fornecer os 5V por conta própria. Dá para fazer, mas todo guia e todo firmware assumem o 4.1.
Preciso do cabo USB host oficial da PJRC?
Não, mas é a opção correta mais fácil, porque ele encaixa no header de 5 pinos e acerta o par diferencial sem esforço extra. Ligar na mão também funciona se o par for curto e com comprimentos iguais.
Um Teensy é menos detectável que um KMBox?
Não automaticamente. O que o Teensy te dá é controle: você decide o descritor, as strings e a taxa de relatórios, então pode apresentar uma identidade plausível em vez de uma de fábrica. Deixado no padrão, ele apresenta a identidade de uma placa de desenvolvimento, o que é pior do que um dispositivo feito para a tarefa, então esse controle só vira vantagem se você usar.
O Teensy consegue rodar o cheat sozinho?
Não, porque ele não tem como ler a memória do PC de jogo. Ele move o cursor quando mandam, enquanto a placa DMA e o segundo PC decidem para onde.
O dongle de um mouse sem fio funciona na porta host?
Normalmente sim, porque o host trata o dongle como um dispositivo USB HID. Alguns dongles apresentam interfaces extras ou um protocolo de configuração proprietário que o firmware de passthrough ignora, então remapeamentos gravados no mouse e alguns recursos do software podem parar de funcionar.
Preciso soldar o kit de magjack Ethernet?
Só se você quiser uma conexão de controle por IP em vez de serial. Quando o segundo PC fica ao lado do PC de jogo, serial é mais simples e te poupa uma solda.
O que acontece se eu gravar o firmware errado?
Nada permanente. O bootloader mora em um chip separado, e o botão Program sempre devolve a placa a um estado em que o Teensy Loader consegue escrever uma imagem nova. Isso faz do Teensy uma placa muito difícil de inutilizar por gravação.
Fontes
Nada na nossa lista de fontes verificadas cobre o Teensy em si, então as specs da placa, a solda, a gravação e a tabela de falhas vêm de trabalho de bancada.
- 01Microsoft Learn, USB device descriptors
os campos vendor id, product id, string e número de série que você define ao compilar o seu próprio descritor
learn.microsoft.com
Leia em seguida
Ainda travado? Abra um ticket no Discord
Todos os guias