Anyone up for updating the getting started guide?

[a-h]

I've just spent a few hours getting the Raspberry Pi Pico to work as a USB host.

I found the examples a bit confusing, so I took the approach of stripping it all back to get keyboard and mouse input for the Pico:

https://github.com/a-h/pico_usb_kbd_mouse

I have no idea whether it's a sufficiently robust example, or if it has glaring holes that make it completely unacceptable. Some feedback would be useful. Maybe it could make a good example for the repo?

To get started, I tried to start from the documentation, but I struggled to understand it. I'm not expert enough in the project to safely write new documentation, but I can share my experience, and suggest some ways to improve it, or work with someone else to write it up.

To put my experience into context, it's my first time using the project, I have been a software engineer for 20 years using Go, JavaScript, C#, Python etc. day to day. Over the last 5 years I've been making things with ESP8266 boards and the like, writing C (which I last touched 15 years before that, when CMake hadn't been invented yet, so I don't know anything about that). This library seems great, but despite my experience, I didn't find it easy to get started using the project.

My thoughts on "Getting started"

At the time of writing, the getting started guide of TinyUSB says to:

Copy or git submodule this repo into your project in a subfolder. Let’s say it is your_project/tinyusb
Add all the .c in the tinyusb/src folder to your project
Add your_project/tinyusb/src to your include path. Also make sure your current include path also contains the configuration file tusb_config.h.

For the Raspberry Pi Pico, none of these steps are required, since TinyUSB is included in the Raspberry Pi Pico SDK. I also don't know how to add things to an include path. I assume that's something to do with CMakeLists.txt?

• Suggestion - I don't know how to improve this, maybe it's micro-controller specific?

It also says to:

Make sure all required macros are all defined properly in tusb_config.h (configure file in demo application is sufficient, but you need to add a few more such as CFG_TUSB_MCU, CFG_TUSB_OS since they are passed by IDE/compiler to maintain a unique configure for all boards).

I have no idea how to "properly define" the macros, and which ones are "required", and which "few more" I need to add, but I just assumed the Raspberry Pi Pico SDK was taking care of it all. In my example, I was able to take the tusb_config.h and strip it right back.

• Suggestion - define which macros are required and how to define them properly (or where to look!).
• Suggestion - define how you'd know what the other macros are, and whether you need to do anything.

Next, it says:

If you use the device stack, make sure you have created/modified usb descriptors for your own need. Ultimately you need to implement all tud descriptor callbacks for the stack to work.

If you're trying to achieve a goal, like receiving USB input, then I guess you're using the USB host. If you're trying to allow a PC to read from your device over USB, then I guess you're using the device stack?

I have no idea how to find out I'm using the device stack, and how I'd create/modify USB descriptors. And I don't know how I'd "implement all tud descriptor callbacks". I just skipped this and it worked, presumably because I'm using the USB host?

• Suggestion - clarify how you'd know whether you're using the device stack, and how/where you'd define descriptors.
• Suggestion - clarify where the required tud descriptor callbacks are documented.

Add tusb_init() call to your reset initialization code.

No problem here, tusb_init() is present in the example.

Call tud_int_handler() (device) and/or tuh_int_handler() (host) in your USB IRQ Handler

I didn't need to do this at all. I assume the Raspberry Pi Pico SDK is doing this for me? I didn't see anything like this in the examples.

Implement all enabled classes’s callbacks.

This one confused me. How am I supposed to know what I've enabled, and what the callbacks are?

After a bit of messing around, I realised that the tusb_config.h file contains CFG_TUH_HID etc., and that these are enabling classes of USB behaviours.

So, if I enable CFG_TUH_HID, I need to look at the source code in https://github.com/hathach/tinyusb/blob/master/src/class/hid/hid_host.h and read through the Callbacks section to see what the required functions are.

• Suggestion - add an overview of some common use cases and the tasks you'd need to do to achieve the goal?
• Suggestion - clarify how you enable/disable functionality, and what's required for different things to work.
• Suggestion - document where to find information on what callbacks are required.

If you don’t use any RTOSes at all, you need to continuously and/or periodically call tud_task()/tuh_task() function. All of the callbacks and functionality are handled and invoked within the call of that task runner.

This was OK for me, because tuh_task is present in the example.

• Suggestion - clarify why board_init() is present, it doesn't seem to be mentioned in the getting started guide.
• Suggestion - remove "It is relatively simple to incorporate tinyusb to your (existing) project" because it made me feel like an idiot for struggling to do it. 😀

Next steps

If anyone's up for updating the getting started guide, I'd be happy to test out how easy it is to follow, edit the copy, or pair program with someone that's experienced with the project to start up a new project while taking notes, then write it up.

[hathach]

Thank you for your willingness. Yes, there is lots of place that need documentation improvement, since I tend to like to write more code than docs in my little spare time. The getting started along with all other (little) documentation is a generic instructions and does not refer to any specific port since tinyusb support lots of MCUs. It will assume you are already familiar with your own mcu sdk in this case rp2040, and the mcu sdk provide their own documentation if it integrates tinyusb. It will also assume you are familiar with most of USB terminology and how it work (enumeration, protocol, driver etc ...)

For host and device example, you could check out the https://github.com/hathach/tinyusb/tree/master/examples . With current state of (lacking) docs, if there is anything not clear, please check out the source code and example for how to use it. It is advisable to try out the stock example and get familiar with API.

If you could, please continue to submit PR for documentation or any improvement in general, I will be happy to review them.

[aspdigital]

I'm in the same boat.

I have LPC55, LP546, EFM32GG and SAME70 boards. (I also have TI MSP432 and TM4C hardware.) I have a design in process that will use LPC546 but I need USB support and NXP's idea of a library is awful. Hence, tinyusb.

But where to start? The distribution includes various examples but they don't build. The line is "include tinyusb in your project."

If anyone has a full-up project for any of these boards that builds right out of the box, please send it along.

Once I understand the process I can write a good "getting started" document.

[hathach]

have you tried the build instruction for stock example https://github.com/hathach/tinyusb/blob/master/docs/reference/getting_started.rst#build

it should build and work out of the box for supported boards https://github.com/hathach/tinyusb/blob/master/docs/reference/supported.rst#supported-boards

[SimonMerrett]

I just want to chime in that I'm starting down this route of implementing tusb on a supported board but to integrate it with the rest of the application codebase I need to pull tusb into the vendor's IDE. Because we're using a supported board I'm hopeful that we need to change as little as possible, aside from the compiler aspects, to get things working. I have followed the getting started and previously successfully built and tested an appropriate example but knowing which callbacks need implementing and how to connect them within the existing codebase is quite hard to work out.

I will post more specific questions as I go (@a-h's approach of being specific and detailed is the way to go on these things where you're unsure and need help) and if I find answers, I will share them here, or wherever we end up putting such information ( like a more in-depth appendix to the getting started page).

[hathach]

which board you are using ? there is a board_init() to set up clock/usb controller that need to be done by application before calling tusb_init() as well

[SimonMerrett]

SAME5X config with the Xplained Pro board. main_cdc.c looks like:

#include "atmel_start.h"
#include "atmel_start_pins.h"
#include "tusb/tusb.h"
#include "board.h"

//------------- prototypes -------------//
static void cdc_task(void);

int main(void)
{
	//atmel_start_init();
	board_init(); // tusb initialisation of hardware
	tusb_init();
	while(1)
	{
		tud_task(); // device task
		cdc_task();
	}
}

with cdc_task() and echo_serial_port() also there.

[SimonMerrett]

I must be getting close because:

So the device is configured but not started. Please could you give me any tips about where to check to get the device started?

[hathach]

check out same54xplained board init here for reference https://github.com/hathach/tinyusb/blob/master/hw/bsp/same54xplainedpro/same54xplainedpro.c

my advice would be trying to compile stock example with make BOARD= first, if you have one of supported board (or adopt your to closet board). Once you have an running examples, it is easier to move code/file one by one.

[SimonMerrett]

Thanks @hathach , in my codebase diagram above tusb_supported_board_init.c is same54xplainedpro.c but I was trying to be mcu-agnostic for the sake of this discussion about general porting.

The good news is that the resulting problems were due to me failing to adapt usb_descriptors.c to account for a single port. Once I commented the second interface number out in desc_fs_configuration[] and the ITF_NUM for CDC_1:

// Configuration Descriptor
//--------------------------------------------------------------------+
enum
{
  ITF_NUM_CDC_0 = 0,
  ITF_NUM_CDC_0_DATA,
//   ITF_NUM_CDC_1,
//   ITF_NUM_CDC_1_DATA,
  ITF_NUM_TOTAL
};

It worked fine. One other thing to note, is that I had definition clashes with void _init() in
So I changed it to extern void _init(void); in same54xplainedpro.c.

So hopefully that can serve as an example of integrating tusb into another IDE/toolchain.

[Nikitarc]

Suggestion - remove "It is relatively simple to incorporate tinyusb to your (existing) project" because it made me feel like an idiot for struggling to do it. 😀

This is because TinyUSB is easier to incorporate to a project than some other USB stack. It's a bit of a marketing formula, but for me it's true!

When I understood that it was enough to recover only:

• src folder (removing all the non relevant drivers in portable folder)
• tusb_config.h
• usb_descriptors.c

Then:

• Initialize myself the USB stuff: GPIO DP, DM, VBUS, ID, the USB interrupt priority, USB clock (inspired by a close example of board_init()).
• Then call tusb_init ().

Nothing very complicated.

It becomes a little more vague when using an unsupported RTOS: understand that you have to fill in tusb_os_custom.h and not an osal_xxx.h file (like osal_custom.h).
It will also be necessary to explain how to use the timeout of osal_queue_receive() which will appear in the next version of TinyUSB (currently I put an infinite timeout in tusb_os_custom.h).

And then know whether to create a dedicated TinyUSB task or call tud_task() from the interrupt. There seems to be a line that says so, but a small paragraph on what to do and what not to do when you have an RTOS would be welcome.

Here is my experience after a few days with TinyUSB on various STM32, and the details that I would have liked to find in the doc. But frankly I didn't have any particular difficulty using TinyUSB in CDC in my project.

Then you have to have USB skills to write descriptors and use callbacks. I think it's not the resort of the Tiny USB doc for the moment. But some links to informative sites would be helpful.