Documentation of "esp32-hal" vs "esp-idf-hal"

[JasonKleban]

Can it please be clarified how all these repo/crate offerings are intended to work together or not, and for what purposes?

How does "esp32-hal" relate to "esp-idf-hal", for example? I don't see any dependency link between them, but they seem to cover some of the same topics. Why is there no esp32-sys or esp32-svc?

I'm guessing that the answer in documentation somewhere (and cross-linked) would be like:

Crates a, b and c are meant to go together and crates x, y and z are meant to go together. XYZ is newer and will be better than ABC but XYZ doesn't yet have full parity. Dependence on ABC and XYZ are not really meant to be mixed in one crate, though you might have success if ... at the expense of .... Otherwise, check the roadmap wiki for the planned list of capabilities/modules/namespaces in the XYZ crates, check the esp32 chipset datasheet [here] and the c implementations of [x], [y] and [z1], [z2] if you need to port anything sooner than it can be available and possibly contribute it here.

I'm fairly new to embedded development, native development, and rust all at once. I'm choosing this platform combo to learn - maybe there are others like me as an audience? Maybe include some minimum-need-to-know definitions of like IDF and SVD?

Thanks!

[alvaroarenas]

I second you on that. I found out that the the esp-idf-hal is the one to use if you want to have access to the std library. But other than that I am as lost as you.

Additionally, there are some definitions about the gpio in both libraries. However, I found now clear example how to set the pins in the esp-idf-hal. Hopefully, someone could share some light.

[MabezDev]

Please take a look at the book section on this topic. If this doesn't cover the missing information, please open an issue with specifics on the book repo :)

[Codeleiche]

Sorry but that does not clarify it for me... what documentation is to use when I want to use gpio without direct use of the registers? esp-idf-hal seams to have no documentation... and there seams to be no tutorial online were I can clarify that for me...

[JasonKleban]

Please take a look at the book section on this topic.

That's great, Thanks!. I hadn't seen your The Book or known to look for it. Perhaps more cross-posting of that resource in the various readme.mds?

[alvaroarenas]

@MabezDev Thx for pointing to the book. Still, as a newbie is difficult to know what the books is referring. Just to make sure. Does it mean that _nostd is esp32-hal and std is esp32-idf-hal ?

[MabezDev]

esp-idf-hal seams to have no documentation

Unfortunately esp-idf-sys is the problem, it currently requires a network connection to build which the docs.rs sandbox does not permit. I'll discuss this issue again in our community meeting today.

Does it mean that no_std is esp32-hal and std is esp32-idf-hal ?

Apologies if it's not clear! Turns out writing documentation for a project you've been working on for years is hard, as it's easy to gloss over important info. You are correct though. If you think there is a better way to write this section, or some gaps to fill please file an issue on the book repo (or PR if you're feeling adventurous :D).

[alvaroarenas]

@MabezDev Thank you for the explanation. I submitted a PR in an attempt to clarify it.