El Teensy 4.1 como dispositivo de entrada para DMA
El montaje completo con Teensy 4.1: soldar los pads del host, flashear con el Teensy Loader, orden de conexión, control por serie o por red, tasas de reporte, trabajo con el descriptor y fallos habituales.
Respuesta corta
Suelda un peine de 5 pines a los pads del host del Teensy 4.1 de 600 MHz y flashea firmware de paso con el Teensy Loader. Enchufa el ratón al puerto host y el puerto device al PC de juego, y luego gobierna la placa por serie.
En esta página12
- Qué es el Teensy 4.1
- Por qué elegir un Teensy en vez de un dispositivo ya hecho
- Cómo soldar el puerto USB host
- Qué software necesitas y dónde están los archivos
- Cómo flashear el firmware y probar el puerto host
- En qué orden conectar los cables
- Elegir el enlace de control y configurar el cheat
- ¿Sirve de algo una tasa de reporte más alta?
- Cómo cambiar el descriptor USB
- Problemas habituales del Teensy y cómo resolverlos
- Preguntas habituales sobre el Teensy
- Fuentes
Qué es el Teensy 4.1
El Teensy 4.1 es una placa microcontroladora de propósito general de PJRC que nunca se diseñó para esto. Por eso es barata, y también por eso se convierte en el más capaz de estos dispositivos de entrada una vez has hecho el trabajo.
- Microcontrolador
- NXP i.MX RT1062, ARM Cortex-M7 con unidad de coma flotante por hardware
- Reloj
- 600 MHz de fábrica, seleccionable en el IDE. No lo overclockees para esta tarea
- Flash
- Unos 8 MB (7936 K), muchísimo más de lo que necesita cualquier firmware de paso
- RAM
- 1024 K en total, 512 K de ellos acoplados directamente al núcleo
- Puerto device
- El conector micro-USB. USB 2.0 high speed, 480 Mbit/s. Este es el extremo que mira al PC de juego
- Puerto host
- Cinco pads pasantes en la placa, sin poblar de fábrica. Funciona a 480, 12 o 1,5 Mbit/s según lo que enchufes. Este es el extremo donde va tu ratón
- 5V del host
- Lo conmuta el chip mediante un interruptor con límite de corriente. Los pads no dan corriente hasta que el firmware llama a la función begin de la librería host
- Serie por hardware
- Ocho UART, por si quieres un enlace serie que no sea el puerto USB device
- Ethernet
- Admite 10/100, pero el magjack es un kit aparte que hay que soldar. No hace falta para un montaje por serie
- Programación
- Teensy Loader, que el IDE de Arduino lanza solo en cuanto instalas Teensyduino. Un botón Program físico fuerza el bootloader
Por qué elegir un Teensy en vez de un dispositivo ya hecho
Hay tres razones, ordenadas según la frecuencia con la que cada una es la razón de verdad. Primera: el firmware lo compilas tú, así que decides qué descriptor USB ve el PC de juego y cada cuánto se envían los reportes, cosa que no te deja hacer ningún dispositivo ya hecho. Segunda: los controladores host y device son totalmente independientes, así que el paso del ratón no compite por ancho de banda con la inyección. Tercera: es barato. El precio a pagar es que el fabricante pasas a ser tú: cuando algo va mal no hay canal de soporte, solo tu cableado y tu código.
Aviso
Cómo soldar el puerto USB host
Esta es la única soldadura obligatoria, y de ella depende que el resto del montaje funcione. Los pads del host son cinco agujeros pasantes metalizados, sin poblar de fábrica, y llevan los 5V del host, el par D- y D+, y masa. Sigue la serigrafía y la tarjeta de pinout oficial para el orden; no lo adivines ni te fíes del esquema de un post de foro.
- Localiza los cinco pads del host en tu placa y confirma su orden con la tarjeta de pinout que PJRC publica para el Teensy 4.1
- Mete un peine macho de 5 pines en los agujeros, o prepara el cable USB host que PJRC vende para el Teensy 3.6 y el 4.1
- Suelda con punta fina y aleación de baja temperatura: son pads pequeños en una placa densa y una punta gorda te los va a puentear
- Revisa cada soldadura con buena luz. Una soldadura mate, granulada o abombada es una soldadura fría, y es el motivo más común de que un puerto host no enumere nada
- Antes de dar corriente a nada, comprueba con el multímetro en continuidad que no hay puentes entre D- y D+
- Si usas cable pelado en vez del cable oficial, deja el par D- y D+ corto y de la misma longitud, porque es un par diferencial que puede llevar hasta 480 Mbit/s
- No conectes a la ligera los 5V del host a una fuente externa: la placa conmuta ese raíl por su cuenta y el interruptor tiene límite de corriente por algo
Qué software necesitas y dónde están los archivos
Necesitas el IDE de Arduino más Teensyduino, el complemento de PJRC. Teensyduino trae la librería host y el Teensy Loader, así que no hay que instalar nada más.
# 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.hAviso
Cómo flashear el firmware y probar el puerto host
Flashea primero el ejemplo Mouse de USBHost_t36 tal cual. Imprime en el monitor serie cada movimiento y cada clic del ratón conectado, así que te demuestra la soldadura en unos treinta segundos. Antes de probar, ten presente que el raíl de 5V de los pads del host lo conmuta el chip en vez de estar cableado fijo. Si la placa corre un firmware que nunca arranca la librería host, un ratón enchufado al puerto host ni siquiera se encenderá. Un puerto host que parece muerto en una placa así no te dice nada. Flashea primero, prueba después, y solo entonces flashea el firmware que espera tu cheat.
- Conecta el puerto device micro-USB del Teensy al PC en el que estás compilando
- Abre el ejemplo Mouse de USBHost_t36, pon Board y USB Type como indica la configuración del toolchain y pulsa Upload
- Teensyduino le pasa la imagen compilada al Teensy Loader, que reinicia la placa y la escribe. En una placa de fábrica esto pasa solo
- Si la subida se queda colgada, pulsa una vez el botón Program del Teensy. Eso fuerza el bootloader y entonces el Loader encontrará la placa
- Enchufa un ratón por cable al puerto host recién soldado y abre el monitor serie
- Mueve el ratón. Si aparecen los eventos de movimiento y de botones, el puerto host funciona y la parte de hardware del montaje está terminada
- Ahora compila y flashea el firmware de paso que documente tu cheat, manteniendo los mismos ajustes de Board y USB Type
- Después del flasheo final, quita y vuelve a dar corriente a la placa en vez de fiarte de un reinicio por software
En qué orden conectar los cables
Si te equivocas en esta secuencia, puedes tirarte una hora depurando un cable. El puerto device mira al PC de juego porque es el extremo que dice ser un ratón, mientras que el puerto host mira a tu mano.
- Enchufa el ratón físico, o el receptor de tu ratón inalámbrico, al puerto USB host soldado del Teensy
- Conecta el puerto device micro-USB del Teensy directamente a un puerto USB trasero del PC DE JUEGO, sin hub y sin conector frontal
- Añade el enlace de control desde el SEGUNDO PC. No puede compartir el puerto device, porque la interfaz serie USB de ese puerto enumera en el PC de juego, que es donde está enchufado el cable
- Usa en su lugar una de las ocho UART por hardware para el enlace de control. Pon un adaptador USB-serie en el extremo del segundo PC para que las dos máquinas no compartan cable nunca
- Arranca el PC de juego y confirma que Windows muestra un dispositivo de ratón y que tu mano mueve el cursor
- Solo entonces inicia el software en el segundo PC y abre el enlace
Consejo
Elegir el enlace de control y configurar el cheat
Un tipo de USB compuesto te da una interfaz de ratón y una interfaz serie en el mismo cable. Esa interfaz serie aparece en el PC de juego, que es donde está enchufado el puerto device, así que el segundo PC no puede abrirla. También significa que la máquina en la que estás jugando tiene un dispositivo serie del mismo gadget compuesto que tu ratón, con las dos interfaces bajo un único descriptor. Así que saca el enlace de control de una UART por hardware y pon un adaptador USB-serie normal en el extremo del segundo PC. El PC de juego ve entonces un dispositivo que es solo un ratón, y eso te da un montaje más limpio a cambio de un cable y una pieza más. Uses el enlace que uses, el protocolo lo define el firmware y el cheat tiene que encajar con él. En el menú de entrada del cheat configuras tres cosas: el tipo de dispositivo, el puerto COM y la velocidad en baudios. El tipo de dispositivo suele aparecer como Teensy o como dispositivo serie genérico. El puerto COM es el que le haya asignado el segundo PC, y la velocidad en baudios es aquella con la que se compiló el firmware. Las tres tienen que coincidir. Una velocidad que no cuadra no da un error claro, porque la conexión se abre y luego no hace nada, que es exactamente lo que parece un dispositivo muerto. Así que mira el número de puerto en el Administrador de dispositivos y fuérzalo por debajo de 10 si el cheat solo lee un dígito, y apunta la velocidad en baudios cuando flashees en vez de adivinarla después.
¿Sirve de algo una tasa de reporte más alta?
El puerto device es USB high speed, así que el descriptor puede pedir intervalos por debajo del suelo de 1 ms que limita a un ratón full speed. En la práctica eso significa reportar por debajo del milisegundo, que es justo lo que le gusta a la gente de esta placa, pero también es donde el entusiasmo se adelanta a la utilidad. Una tasa de reporte muy por encima de lo que consume el propio bucle de entrada del juego no te da ningún beneficio medible. Un flujo de reportes perfectamente regular a una frecuencia rara también es un patrón, y los patrones son precisamente lo que busca el análisis de comportamiento. Pon una frecuencia que un ratón real de esa gama podría usar de forma verosímil. No existe ningún benchmark honesto que demuestre que un número más alto es más seguro, y quien te cite uno en milisegundos se lo está inventando.
Consejo
Cómo cambiar el descriptor USB
Como el firmware lo compilas tú, controlas el vendor ID, el product ID, las cadenas de fabricante y producto, el número de serie y el HID report descriptor. Si no lo tocas, un Teensy presenta la identidad propia de PJRC, es decir, la identidad de una placa de desarrollo en una máquina que no tiene ningún otro motivo para llevar una. Las cadenas y los IDs viven en usb_desc.h y usb_names.h del core, no en tu sketch. El core 4.x ofrece un camino más limpio: definir los descriptores de cadena en un pequeño archivo C aparte dentro de la carpeta del sketch. En cuanto cambias el vendor ID y el product ID, Teensyduino ya no puede encontrar y reiniciar la placa solo, así que a partir de ahí cada subida necesita que pulses el botón Program. Eso es comportamiento esperado, no una placa muerta. Léete la guía de descriptores antes de tocar nada, porque copiar mal la identidad de un ratón real es peor que dejarla de fábrica.
Problemas habituales del Teensy y cómo resolverlos
Ve de arriba abajo. Las cuatro primeras filas cubren casi todo lo que sale mal en un primer montaje, y tres de esas cuatro se reducen a la soldadura.
| Síntoma | Causa probable | Solución |
|---|---|---|
| El ratón enchufado al puerto host no hace nada, ni se le enciende el LED | O hay una soldadura fría en los pads del host, o el firmware nunca arranca la librería host y el raíl de 5V se queda apagado | Flashea primero el ejemplo Mouse de USBHost_t36. Si el ratón sigue sin dar señales de vida, resuelda los cinco pads y comprueba la continuidad |
| El puerto host enumera de forma intermitente, o solo funcionan dispositivos lentos | El par D- y D+ es demasiado largo o tiene longitudes distintas, o hay restos de estaño entre los pads | Acorta el par e iguala las longitudes, o pásate al cable USB host oficial. Limpia los pads con alcohol isopropílico y revísalos con luz |
| El PC de juego no muestra ningún dispositivo de ratón | El USB Type del IDE no incluye Mouse, así que el puerto device nunca presenta una interfaz HID de ratón | Pon en Tools > USB Type una opción que contenga Mouse, recompila, vuelve a flashear y quita y da corriente a la placa |
| La subida falla o se queda colgada en Waiting for Teensy device | El firmware en marcha no responde a la petición de reinicio, o has cambiado el vendor ID y el product ID | Pulsa una vez el botón Program de la placa. Después de cambiar el VID o el PID hay que hacerlo en cada subida |
| El cursor se mueve desde el cheat pero tu propio ratón no hace nada | El paso del ratón no funciona: el lado host está muerto mientras que el lado device va bien | Prueba el puerto host con el ejemplo Mouse, porque la causa es casi siempre la soldadura |
| Tu ratón va bien pero el cheat no consigue abrir el enlace | Puerto COM equivocado, o una velocidad en baudios que no coincide con la del firmware compilado | Busca el puerto en el Administrador de dispositivos, ponlo por debajo de 10 y ajusta la velocidad en baudios al valor con el que se compiló el firmware |
| El movimiento sale tosco o a escalones en vez de suave | El report descriptor usa campos de movimiento de 8 bits, así que los deltas grandes se recortan y se envían en varios pasos | Usa firmware cuyo descriptor declare ejes relativos de 16 bits, y deja que el cheat parta los movimientos grandes en vez de dejárselo al descriptor |
| La placa se calienta y el dispositivo host se cae bajo carga | El dispositivo conectado consume más corriente de la que permite el límite del raíl del host | Usa un ratón por cable normal en lugar de uno cargado de RGB o de un hub alimentado, y no cuelgues nunca del puerto host un hub lleno de dispositivos |
Preguntas habituales sobre el Teensy
¿Puedo usar un Teensy 4.0 en lugar de un 4.1?
No con comodidad. El 4.0 saca las señales del host en dos pads de superficie en vez de cinco agujeros pasantes con gestión de alimentación, así que tienes que cablear D- y D+ a mano y dar los 5V por tu cuenta. Se puede hacer, pero todas las guías y todos los firmware dan por hecho el 4.1.
¿Necesito el cable USB host oficial de PJRC?
No, pero es la opción correcta más fácil, porque encaja con el peine de 5 pines y resuelve bien el par diferencial sin esfuerzo extra. Cablearlo a mano también vale si el par es corto y de longitudes iguales.
¿Un Teensy se detecta menos que un KMBox?
No de forma automática. Lo que te da un Teensy es control: tú decides el descriptor, las cadenas y la tasa de reporte, así que puedes presentar una identidad verosímil en vez de una de fábrica. Si lo dejas con los valores por defecto, presenta la identidad de una placa de desarrollo, que es peor que la de un dispositivo pensado para esto, así que ese control solo es una ventaja si lo usas.
¿Puede el Teensy ejecutar el cheat por sí solo?
No, porque no tiene manera de leer la memoria del PC de juego. Mueve el cursor cuando se lo mandan, mientras que la tarjeta DMA y el segundo PC deciden adónde.
¿Funcionará el receptor de un ratón inalámbrico en el puerto host?
Normalmente sí, porque el host trata al receptor como un dispositivo HID USB. Algunos receptores presentan interfaces extra o un protocolo de configuración propietario que el firmware de paso ignora, así que puede que dejen de funcionar los remapeos de botones guardados en el ratón y algunas funciones del software.
¿Hace falta soldar el kit del magjack Ethernet?
Solo si quieres un enlace de control por IP en vez de por serie. Cuando el segundo PC está al lado del PC de juego, el serie es más sencillo y te ahorra una soldadura.
¿Qué pasa si flasheo el firmware equivocado?
Nada permanente. El bootloader vive en un chip aparte, y el botón Program siempre devuelve la placa a un estado en el que el Teensy Loader puede escribir una imagen nueva. Eso hace que un Teensy sea muy difícil de dejar muerto flasheando.
Fuentes
Ninguna de las fuentes verificadas de nuestra lista cubre el Teensy en sí, así que las especificaciones de la placa, la soldadura, el flasheo y la tabla de fallos salen de trabajo en banco.
- 01Microsoft Learn, USB device descriptors
los campos de vendor id, product id, cadenas de texto y número de serie que defines al compilar tu propio descriptor
learn.microsoft.com
Sigue leyendo
¿Sigues atascado? Abre un ticket en Discord
Todas las guías