Improve docs on async methods?

[peterharperuk]

Wifi support in Pico W could use different methods depending on the users choice, polling or background threadsafe. We could probably do with something to describe the thinking behind this. The latest sdk has a new generic asynchronous API which behaves the same.

Basically if you're a user and you need to use wifi or bluetooth or a network stack or need to do something with the async api you need to make a decision about which method you use and what the implications are. Freertos complicates matters even further.

I'm wondering if we need a separate section in the docs to go into this? It's hard to gain an understanding from the API documentation.

[lurch]

Sounds like content for "Connecting to the Internet with Raspberry Pi Pico W" ? So I've moved it to the pico-feedback repo.

[peterharperuk]

The same issue affects bluetooth or the new async_context API which you could use for anything. It's more of a "driver" thing. An interrupt goes off (e.g. to tell us the wifi chip needs attention) and we have to do the work "somewhere else". This has implications / trade-offs for the user. Maybe if I write something you can knock it into shape and decide where it lives?

[lurch]

Okay, so perhaps it belongs as a new chapter in https://datasheets.raspberrypi.com/pico/raspberry-pi-pico-c-sdk.pdf then? Ultimately it's Alasdair's decision to make, so I'll assign this issue to him (for now). But yeah, I'm sure any notes / documentation you can come up with will be greatly appreciated :+1: Thanks!

[ghazanhaider]

Adding my voice to this. The runtime scheduler and async context are not well described for users with previous embedded background and users who want lower level control of even flows. The hardware_timer and datasheets also do not describe this aspect of the runtime.