USB Host support (with stm32 HAL implementation)

[ijager]

I am working on a USB Host implementation, working with the STM32G0B1/C1 family.
Currently I have a basic working example doing enumeration of a HID keyboard and I can receive keystrokes.

I am looking into how to fit this best in embassy (assuming embassy would like to add usbhost functionality), and there are quite some decisions to make about what should go where and about the API surface for each layer.

This is what I have now

• Simple HIDKeyboard implementation. Could serve as an example project
• UsbHost (knows about control requests, enumeration, parsing descriptors).
• USBHostDriverTrait that is used by USBHostDriver and imlpemented by HAL
• USBHostDriver HAL implementation for stm32 with usb_v4 IP

STM32 USBHostDriver

Via cfg_attr the HAL choses between 'usb' and 'otg' IP. My current usbhost hal implementation is for usb_v4. As far as I know only _v4 supports host. How to fit in this functionality in with the current usb module structure? I guess we don't want to expose this for non-v4 IP.

My current host implementation is independent of the usb driver implementation. For usb_v4 you could have both, but you cannot use them at the same time since it is the same peripheral. One way is to specify compile time which one you want.

Which is what I did hardcoded during development:

//! Universal Serial Bus (USB)

// #[cfg_attr(usb, path = "usb.rs")]
// #[cfg_attr(otg, path = "otg.rs")]
// mod _version;
// pub use _version::*;

#[cfg_attr(usb, path = "usb_host.rs")]
mod _host_version;
pub use _host_version::*;

Simplest way is to add a usb-host config option to select usb_host.rs instead.
In theory one may wish to switch between host and device runtime, that wouldn't be supported like this.
Another advantage is that this approach does not risk breaking any existing usb functionality. Can always combine it later.

Alternatively if the "usb" implementation supports both device and host then you have to deal with not allowing that for _v1 - _v3. And you end up with a lot of if host { some host logic } else { device logic }

Any ideas?

USBHostDriverTrait

embassy-usb-driver contains the traits for usb device implementations. Currently I have added a host module to this crate for the host traits.

I called it USBHostDriverTrait to differentiate with the USBHostDriver but better naming is desirable.

So far I ended up with this API:

pub trait USBHostDriverTrait {
    type ChannelIn: ChannelIn;
    type ChannelOut: ChannelOut;

    async fn bus_reset(&mut self);

    async fn wait_for_device_connect(&mut self);

    async fn wait_for_device_disconnect(&mut self);

    async fn control_request_out(&mut self, addr: u8, bytes: &[u8]);

    async fn control_request_in(&mut self, addr: u8, bytes: &[u8], dest: &mut [u8]) -> Result<usize, ()>;

    fn reconfigure_channel0(&mut self, max_packet_size: u16, dev_addr: u8) -> Result<(), ()>;

    fn alloc_channel_in(&mut self, desc: &EndpointDescriptor) -> Result<Self::ChannelIn, ()>;
    fn alloc_channel_out(&mut self, desc: &EndpointDescriptor) -> Result<Self::ChannelOut, ()>;
}

pub trait ChannelIn {
    async fn read(&mut self, buf: &mut [u8]) -> Result<usize, EndpointError>;
}

pub trait ChannelOut {
    async fn write(&mut self, buf: &[u8]) -> Result<(), EndpointError>;
}

USBHost

The embassy-usb crate implements various Device Classes. Would USBHost fit in here and how? Or better in a new separate crate such as embassy-usb-host? There are of course some shared data types such as descriptors, but not much shared logic I believe.

---

Also wondering what would be the preferred way to go about the PR process? Everything in one go is a lot to review. but you kinda need all layers for context I think

Happy to discuss!

[nikvoid]

What about multiple connected devices (via usb hub)? I see that now there is only method for changing current device address in user-facing UsbHost struct.

[ijager]

I am not really sure how a hub would change things exactly. I guess it would required an extra level of abstraction since the host would have to channel everything via the hub.
I was aiming for very specific embedded host implementations only.

[nikvoid]

Given that there are things like low-speed preamble, host indeed needs to handle hub specially. I want host support on rp2040 to control 2 usb devices, so I probably will be implementing my own solution inspired from yours. So far I have CONTROL and INTERRUPT IN channels working, and keyboard example works too.

[jakerr]

I just wanted to come say thank you to everyone who's contributing to this in the PR (#3307).
It's been really inspiring to see the awesome collaboration happening in there.

This weekend I checked out nikvoid's embassy/rp2040-usb-host and got it running on a pico2 by just adding this to
examples/rp/src/bin/usb_host_keyboard.rs

#[link_section = ".start_block"]
#[used]
pub static IMAGE_DEF: ImageDef = ImageDef::secure_exe();

and target = "thumbv8m.main-none-eabihf" in .cargo/config.toml

That was pretty much all it took to plug in a keyboard via an OTG adapter and see the demo working :)
I'm really excited to see all this awesome progress!

[JarvisPrestidge]

That was pretty much all it took to plug in a keyboard via an OTG adapter and see the demo working :) I'm really excited to see all this awesome progress!

@jakerr could you link the type adapter you used to get this working? would be much appreciated 🙇

[jakerr]

@JarvisPrestidge

The one I bought was a generic "USB mini OTG adapter" from:
https://www.sengoku.co.jp/mod/sgk_cart/detail.php?code=EEHD-5T7D
I don't think this shop ships outside Japan, however.

[jakerr]

FYI the latest active pull request for this is the draft #4321

[Joeboy]

In case it's somehow useful to somebody, I got it working (for me) with a pico 2 and USB midi keyboard, with this commit on top of the WIP PR branch.

There was an assertion stopping it working with Bulk endpoints, which I had to remove. It seems to work OK without it but maybe it's there for some reason I don't understand (I'm honestly dabbling in things I don't understand well here).

[bugadani]

This issue can probably be closed now that #5633 has been merged

[ijager]

That's amazing! Great work everyone.