Should the examples default to using stdio USB?

[peterharperuk]

Some of the examples only really "work" if you can see the output. But by default we enabled UART which means you have to own a USB adapter.

Maybe we should default to using USB, or have some clearer explicit way for the user to specify their choice? I have a load of aliases to make the switch for me

alias cmaked="cmake -DCMAKE_BUILD_TYPE=Debug"
alias cmakeu="cmake -DPICO_STDIO_UART=0 -DPICO_STDIO_USB=1"
alias cmakedu="cmaked -DPICO_STDIO_UART=0 -DPICO_STDIO_USB=1"
alias cmaken="cmake -G Ninja"
alias cmakedn="cmaken -DCMAKE_BUILD_TYPE=Debug"
alias cmakeun="cmaken -DPICO_STDIO_UART=0 -DPICO_STDIO_USB=1"
alias cmakedun="cmakedn -DPICO_STDIO_UART=0 -DPICO_STDIO_USB=1"

[kilograham]

yeah, we need to go thru and try them to make sure they do indeed actually work without deadlocks ;-)

[peterharperuk]

I've had no problems so far on develop

[lurch]

I suspect that the reason the examples all default to using UART-stdio is that using the hardware UART has much less software-overhead on the RP2040 than using USB-stdio, and so when doing low-level debugging it's much easier to see what's going on when the USB device stack isn't being used on the RP2040 at the same time. But the software running on the RP2040 has now probably matured to a point where that's less of a concern, and using USB-stdio by default is certainly much more user-friendly for those people that don't have a USB-UART adapter. For maximum-compatibility reasons, would there be any reason not to do "-DPICO_STDIO_UART=1 -DPICO_STDIO_USB=1" (wherever possible) rather than "-DPICO_STDIO_UART=0 -DPICO_STDIO_USB=1" ? With https://github.com/raspberrypi/pico-examples/tree/master/hello_world being an obvious exception to the rule!

Also, it's possible to leave a serial-terminal program (on the PC) connected to the hardware-UART (e.g. via a FTDI USB->UART adapter) during resets of the RP2040, and the terminal remains open and catches all and any UART-stdio output; whereas when using a serial-terminal program to connect directly to the USB device on the RP2040, it disconnects when the RP2040 resets and then has to be manually reconnected, meaning that USB-stdio output can be "lost" if it gets printed before the serial-terminal program on the PC has re-enumerated and reconnected to RP2040's serial-USB device. I can't remember the details off the top of my head, but IIRC @kilograham (later) added some (optional?) mechanism to the SDK to detect when there's "something connected" to the other side of the USB connection.
(.... ahhh, I might be thinking of the PICO_STDIO_USB_CONNECT_WAIT_TIMEOUT_MS and PICO_STDIO_USB_POST_CONNECT_WAIT_DELAY_MS options? See Appendix B of https://datasheets.raspberrypi.com/pico/raspberry-pi-pico-c-sdk.pdf ....)

There's been several pico-examples bug reports where people have enabled USB-stdio support for one of the example-apps, and then complained that the example-app isn't working; because what has actually happened is that the example-app has started up, done "it's thing", printed some result to stdio, and then exited, all before the PC-side terminal program has even connected to the USB-serial device. And of course once the example-app has exited, then the USB stack on the RP2040 is no longer running, and so there's no USB-serial device for the PC-side terminal program to actually connect to!
So when enabling USB-stdio support for an example-app, I guess you'll need to check that it's either running in a loop and continually/periodically printing output to stdio (so that there's always fresh output visible, regardless of when the serial-terminal program actually connects, and the example-app never actually exits); or that it's using the aforementioned "don't actually print anything to USB-stdio until something has actually connected to the other end of the USB connection" mechanism. (Although on second thoughts the latter might cause problems for anybody using UART-stdio and not using USB-stdio?)

Bit of a long random waffle @peterharperuk , but hopefully it's useful background / historical context 🙂

WRT your cmake aliases, it's unfortunate that "USB" and UART" both start with a "U" 😆
Perhaps

alias cmakes="cmake -DPICO_STDIO_UART=0 -DPICO_STDIO_USB=1"
alias cmakeh="cmake -DPICO_STDIO_UART=1 -DPICO_STDIO_USB=0"
alias cmakeb="cmake -DPICO_STDIO_UART=1 -DPICO_STDIO_USB=1"

for Software, Hardware and Both.

[lurch]

raspberrypi/pico-feedback#253 points out that we'll also need to fix section 2.4 of https://datasheets.raspberrypi.com/picow/connecting-to-the-internet-with-pico-w.pdf which just uses inline-C-code, rather than pulling in some external pico-examples files.