USB Host Co-Processor

The USB Host co-processor connects USB devices such as USB keyboards to
devolpment boards without USB host ports or without USB host software. The
connection is made via UART. Device specific firmware is programmed into the
USB Host co-processor by dragging and dropping a firmware file.

The USB Host co-processor handles the complexities of USB host protocol and
communicates the raw data via UART. For example, the USB MIDI firmware sends
and receives MIDI messages at 115,200 bits/sec via UART. It is bi-directional
and can handle System Exclusive messages up to 1024 bytes.

This open source project is based on the USB Host Library for
SAMD which is a port of the
USB Host Shield Library 2.0.

The hardware is an Adafruit Trinket M0 with a USB OTG to host cable or adapter.
The Trinket M0 has a UF2 bootloader which means it appears as a USB drive.
Firmware is burned into the device by dragging and dropping a firmware file
on to the USB drive. There is no need to install USB serial drivers, IDEs, or
source code unless you want to change the source code.

See the firmware directory for the latest releases.

Using a UART interface makes it much easier to develop software since all of
the USB complexities are hidden in the co-processor. For example, the following
CircuitPython code shows data arriving on the UART from the USB host
co-processor. It is no more complicated than receiving data from any other
serial device.

import board
import busio
uart = busio.UART(board.TX, board.RX, baudrate=115200)
while True:
    data = uart.read(1)
    if data is not None:
        # Show the byte as 2 hex digits then in the default way
        print("%02x " % (data[0]), end='')
        print(data)

Related Projects

• Convert USB keyboard to Bluetooth LE
• USB Host MIDI for Two

USB Host MIDI to UART

MIDIUARTUSBH is a bi-directional converter for USB host MIDI and UART MIDI. The
UART speed is 115,200 bits/sec. Modify the code if MIDI standard 31,250
bits/sec is required. Not all MIDI gear is MIDI class compliant. Also gear with
internal USB hubs is not supported.

This is an example of Controlling the RGB colors of a NeoPixel using a MIDI
controller.

USB Host keyboard to ASCII UART

KBDUARTUSBH when used with a USB keyboard outputs ASCII on the UART. UART input
is ignored. Many keys on a USB keyboard do not have an ASCII code so nothing
will be produced. For example, F1-F12 keys and any combination using the ALT or Win
Logo key do not produce any output.

Some other USB devices emulate USB keyboards such as barcode and RFID readers.
Some barcode readers default to USB keyboard mode but others use USB serial or
USB Point of Sale. Some readers can be configured so consult the reader manual.

USB RFID readers (at least, the cheap ones) can only read the card unique
serial number.

USB Host keyboard advanced

KBDADVUARTUSBH when used with a USB keyboard outputs USB keyboard HID reports
on the UART. UART input is ignored. All USB keyboard keycodes are supported.
For example, Ctrl-ALT-Shift-F12 is a valid keystroke as well as Ctrl-ALT-DEL.
The CircuitPython program kbdhid.py receives the HID report and sends it
out. Two Trinket M0 cross connected via UART Tx and Rx, one running KBDADVUARTUSBH
and the other running kbdhid.py, act as a USB keyboard pass through. Either
program can be modified to swap keys, expand macros, etc.

USB keyboard > USB OTG to host > Trinket M0-A > UART TX/RX > Trinket M0-B > computer
                                 KBDADVUARTUSBH              kbdhid.py

USB Host mouse advanced

MSEADVUARTUSBH when used with a USB mouse outputs USB mouse HID reports on the
UART. UART input is ignored. The UART runs as 921,600 bits/sec (8*115200).

Each mouse HID report appears on the UART TX in the following format.

uint8_t mouseHID[7];

mouseHID[0] = 0x02; // (STX)
mouseHID[1] = 0x24; // Mouse report 4 bytes follow
mouseHID[2] = 0xhh; // Mouse button bitmap, 1=button pressed
mouseHID[3] = 0xhh; // int8_t X-axis relative movement
mouseHID[4] = 0xhh; // int8_t Y-axis relative movement
mouseHID[5] = 0x00; // int8_t scroll wheel movement (not used)
mouseHID[6] = 0x03; // (ETX)

See https://github.com/gdsports/usbmseble for a sketch that parses the UART
stream and extracts the HID report.

USB mouse > USB OTG to host > Trinket M0    > UART TX
                              MSEADVUARTUSBH

USB Host CDC ACM to UART

CDCACMUSBH bi-directionally transfers data between a USB device with CDC ACM
USB serial to a UART port runnning at 115,200. This provides access to data
from a USB CDC ACM device such as an Arduino board to another device with a
UART but no USB hardware. For example, connect an ESP32 to a Pro Micro board.
The Pro Micro has a USB native hardware port and lots of 5V digital and analog
I/O, PWM, etc. Firmata might work here.

USB CDC ACM -> USB OTG host cable -> Trinket M0 -> UART Tx/Rx -> ESP32
Pro Micro                            CDCACMUSBH

Logitech Extreme 3D Pro USB Joystick

LE3DPUSBH takes input from the Logitech joystick and outputs JSON on the
Trinket M0 UART Tx pin at 921,600 bits/sec. This high speed is used because
JSON is verbose.

This was tested with a SparkFun ESP32 Thing running MicroPython.

Logitech joystick -> USB OTG host cable -> Trinket M0 -> ESP32 -> Computer
                                           LE3DPUSBH     uPython

The buttons are labelled but the numbers in a hard read gray-on-black and using
an odd looking typeface.

buttons_a

buttons_b

See the firmware directory for the latest binary releases.

Sample minimum MicroPython code for ESP32.

from machine import UART
import ujson
uart = UART(2, tx=17, rx=16)
uart.init(8*115200, bits=8, parity=None, stop=1)
while True:
    # Read line of JSON from Trinket M0 connected to the joystick
    data = uart.readline()
    if data is not None:
        try:
            # Convert JSON string to Python dictionary
            joy = ujson.loads(data)
            print(joy)
            print(joy['X'])
            # Insert code to change motor or servo direction and speed based
            # on joy['X'], joy['Y'], joy['hat'], etc.
        except:
            print("json error")

Thrustmaster T.16000M USB Joystick

Experimental support for the Thrustmaster T.16000M joystick has been added. It
is automatically detected.

buttons