New USB Host library for Teensy 4.x

[jmarsh]

I've written a new USB Host support library for Teensy 4.x boards: https://github.com/A-Dunstan/teensy4_usbhost

Key features:
- dynamic driver instantiation, e.g. can support any number of hubs or other devices since driver objects can be created as needed
- transparent support for using any type of memory (DTCM/OCRAM/EXTMEM/SDRAM), all cache operations are taken care of
- supports both synchronous and asynchronous transfers (using std::function callbacks)
- makes an effort to return errors using errno
- fully supports isochronous endpoints / transfers (both full and high speed). These are commonly used by devices that deliver realtime data such as audio input/output DACs, or webcams:

It makes use of a threading library (which is a modified version of AtomThreads) which is written to be as minimally intrusive as possible; you can use the synchronization objects it provides if you want, but otherwise its existence can be ignored. It's a submodule of the git repository so do a "submodule init" after cloning it.

For the time being the only available documentation is in the examples and the included drivers; there's still a lot of code to be cleaned up before it starts being documented properly.

 

[wwatson]

Exellent work Tried the USBHost storage "basic.ino" on a FAT32 formatted USB stick through a HUB. Result:

Found a FAT32 partition.
Checking free space... Done.
Bytes free: 30812176384 of 30927306752 (99%)
--- FILE LISTING BEGIN ---
DIRECTORY: /
Modified: 07:21:22 Mar 27 2021    Size: 10845    Name: dfs_ext.c
Modified: 07:21:22 Mar 27 2021    Size: 1147    Name: dfs_ext.h
Modified: 17:47:14 Oct 15 2023    Size: 2127672    Name: dosemu_1.4.0.7+20130105+b028d3f-2build1_amd64.deb
Modified: 17:05:52 Nov 7 2023    Size: 45123    Name: fail.jpg
Modified: 20:39:04 Oct 29 2023    Size: 2379894    Name: ff15.zip
Modified: 20:39:22 Oct 29 2023    Size: 8151962    Name: ffsample.zip
Modified: 20:23:44 Feb 6 2024    Size: 9430734    Name: fltk-master.zip
Modified: 17:41:14 Oct 28 2023    Size: 16688    Name: fontcnvt
Modified: 17:41:02 Oct 28 2023    Size: 955    Name: fontcnvt.c
Modified: 16:15:22 Dec 10 2023    Size: 92613306    Name: FreeRTOSv202212.01.zip
Modified: 19:15:56 Feb 4 2024    Size: 946    Name: libpng3_1.2.54-1ubuntu1.1+1~ppa0~jammy0_amd64.deb
Modified: 19:17:28 Feb 4 2024    Size: 116466    Name: libpng12-0_1.2.54-1ubuntu1_amd64.deb
Modified: 19:11:32 Feb 4 2024    Size: 19036    Name: libpng_1.2.54-1ubuntu1.1+1~ppa0~jammy0.debian.tar.xz
Modified: 00:21:22 May 16 2022    Size: 4096    Name: sansurf.fnt
Modified: 17:41:22 Oct 28 2023    Size: 22050    Name: sansurf.h
Modified: 07:21:22 Mar 27 2021    Size: 1211    Name: SConscript
--- FILE LISTING COMPLETE ---

USB Drive may now be removed, press return to scan again

Can't wait to test with all of the other features...

EDIT: Did anybody mention CD/DVD usage:

Found 1 USB Storage devices
Found a USB Mass Storage device 0x20206ce0, has 1 logical units
USB 0x20206ce0:0 Vendor: PBDS, Product: CDRWDVD DH-48C2S
USB 0x20206ce0:0 LBA count: 23340, LBA size: 2048
Found 1 partitions
USB 0x20206ce0:0 Partition 0: Type ISO9660, start 0 - end 23187

Press return to search again

Again, Nice work...

 

[KurtE]

Looks like fun.
Who knows, maybe it can replace the USBHost_t36... I always wanted to use something like threads, but...

Note: If I try to clone it using Windows github desktop it gives me a real strange error message.
Maybe the submodule... Will investigate later.

But looks like great stuff!

 

[jmarsh]

EDIT: Did anybody mention CD/DVD usage:

Found 1 USB Storage devices
Found a USB Mass Storage device 0x20206ce0, has 1 logical units
USB 0x20206ce0:0 Vendor: PBDS, Product: CDRWDVD DH-48C2S
USB 0x20206ce0:0 LBA count: 23340, LBA size: 2048
Found 1 partitions
USB 0x20206ce0:0 Partition 0: Type ISO9660, start 0 - end 23187

Press return to search again

The CD stuff is a bit of fun... when I get around to it I want to write an ISO9660 filesystem library, so the files can actually be accessed. But in the meantime there's an example that can use CD drives to play audio, and if they have an SPDIF port on the back you can connect it to the Teensy to hear it over USB. The speedtest example can also do digital audio extraction, although it's very basic and doesn't do any verification like a proper extraction app should.

 

[jmarsh]

Looks like fun.
Who knows, maybe it can replace the USBHost_t36... I always wanted to use something like threads, but...

Note: If I try to clone it using Windows github desktop it gives me a real strange error message.
Maybe the submodule... Will investigate later.

But looks like great stuff!

Something you might want to look at is the jpg_server example, for the camera stuff you were working on - it uses QNEthernet to set up a basic webserver to stream continuous jpeg images. You could reuse the EthernetClient related functions to stream images from an OV2640 (or other camera that does mjpg format).

 

[mborgerson]

I've written a new USB Host support library for Teensy 4.x boards: https://github.com/A-Dunstan/teensy4_usbhost

Key features:
- dynamic driver instantiation, e.g. can support any number of hubs or other devices since driver objects can be created as needed
- transparent support for using any type of memory (DTCM/OCRAM/EXTMEM/SDRAM), all cache operations are taken care of
- supports both synchronous and asynchronous transfers (using std::function callbacks)
- makes an effort to return errors using errno
- fully supports isochronous endpoints / transfers (both full and high speed). These are commonly used by devices that deliver realtime data such as audio input/output DACs, or webcams:

It makes use of a threading library (which is a modified version of AtomThreads) which is written to be as minimally intrusive as possible; you can use the synchronization objects it provides if you want, but otherwise its existence can be ignored. It's a submodule of the git repository so do a "submodule init" after cloning it.

For the time being the only available documentation is in the examples and the included drivers; there's still a lot of code to be cleaned up before it starts being documented properly.

This library may bridge one of the great chasms I've been facing in developing USB_UVC cameras for the Teensy: The lack of host support for Isochronous reception from UVC cameras. I've managed to develop drivers for some FLIR thermal imaging cameras only because they use bulk endpoints for image data transfer. All the other cameras I've tested want isochronous endpoints. This will be another continuing education project to keep me busy for the next few months! (As if the USB probe/commit protocols weren't enough to keep me busy!)

I applaud your efforts and look forward to exploring the code.

 

[jmarsh]

Funnily enough, the few cameras I've tested with work fine without even doing any probing/committing... if you just activate the alternate interface without doing any setup they're happy to deliver packets from the streaming endpoint using the default format. That also bypasses activating their "privacy" LED that is meant to indicate when the camera is active...

 

[jmarsh]

Note: If I try to clone it using Windows github desktop it gives me a real strange error message.
Maybe the submodule... Will investigate later.

I tested cloning with github desktop just now and I didn't get any error message, it just stalled indefinitely at the submodule. So I filed an issue.
You can clone the TeensyAtomThreads library by itself: https://github.com/A-Dunstan/TeensyAtomThreads
Luckily I included a check in the usb library that will look for it as an external library if the submodule in the local tree isn't present:

// prefer submodule version if it is present
#if defined __has_include && __has_include("TeensyAtomThreads/TeensyAtomThreads.h")
#include "TeensyAtomThreads/TeensyAtomThreads.h"
#else
#include <TeensyAtomThreads.h>
#endif

 

[jmarsh]

When I added the submodule I used the ssh (git@) URL instead of the web (HTTPS: ) URL. Changing it to https has let github desktop check out the repo without any issues.