Release first version on crates.io

[MabezDev]

Prerequisites before release:

• Use released embassy-net and embassy-net-driver
• Update README.md (e.g. list and explain feature flags - see Support Modem Sleep #203)
• double check to not have dev-dependencies as regular dependencies (embassy-net, bleps)
• update dependencies (i.e. smoltcp to 0.10.0)
• Next esp-hal release for C6 BLE support
• Update dependencies (Update embassy-net #289) and adapt to changes in esp-hal
• Update embedded-svc and embedded-io (embedded-io should also get updated in BLEPS before)
• Double check docs

Optional before release

• Release bleps on crates.io

[jessebraham]

Any updates here?

[bjoernQ]

We would need at least a published embassy-net-driver - not sure if there are any plans on the embassy side for this in the near future

[jessebraham]

I've asked and there are apparently no further blockers on releasing embassy-net and embassy-net-driver, so hopefully we will see published versions of these both soon.

[MabezDev]

A possible controversial idea before release, remove the example_util support crate with the macros. From a maintainability perspective, definitely a lot easier to manage on our side, but makes it quite tricky to copy example code into users real projects.

imo it's worth the extra hassle on our side if it means users can copy and paste more freely.

[jessebraham]

I don't think that's controversial, I agree it makes things less clear than they could be.

[bjoernQ]

Another idea: have a cargo-generate template to setup things per target? Would be even much more useful I guess. But would be more complex than the basic esp-template

Also would be good to have a template for embassy (doesn't really belong here but anyway)

Updating like 60 files for basic changes in initialization is not super convenient

[bjoernQ]

In theory we are now ready to release 0.1.0.

Would be good to get #198 in first.

Regarding the examples .... maybe we can also add an example for each chip which just shows the initialization without anything else and mention it in the other examples. The init code hopefully won't change too much so it won't need too much maintenance but we keep the example-utils for the other examples?

[MabezDev]

I think the biggest problem is that the util stuff is macros instead of normal rust code. What about converting them from macros to functions? At least then users can just copy from there, right now they would have to copy the macros in their project, or unpick the macro logic which is a pain.

[bjoernQ]

I think the biggest problem is that the util stuff is macros instead of normal rust code. What about converting them from macros to functions? At least then users can just copy from there, right now they would have to copy the macros in their project, or unpick the macro logic which is a pain.

I think I failed miserably trying to use regular functions for that before coming up with these macros 🤔

[DoumanAsh]

Could it not be implemented as free functions within corresponding HALs as most of these macros are just cfg wrappers?

[bjoernQ]

Thinking about this again I wonder if changing the examples would really improve the situation for new users at all.

I assume most users will start from something generated by esp-template. That eliminates the need to deal with almost all the macros - the only one left is the one to get the wifi or ble peripheral via peripherals.RADIO.split()

Besides that, the user needs to create/use the right timer - that's it - the remaining code can be copied from any of the examples.

The harder part is to figure out which dependencies and features are needed. Since we are using workspace dependencies and dynamically activate some features that's slightly inconvenient t.b.h.

Last step the user needs to do is remembering to link rom_functions.x.

With that in mind I propose this

• keep the examples as they are (maybe add a comment to each example with a link to the USERGUIDE.md - see below)
• re-export everything from the relevant crates (so the user doesn't need to think about them at all - just depend on esp-wifi with the right features set)
• Change the README chapter Using in your own binary crate into something like USERGUIDE.md and link to it
• in the USERGUIDE.md (or whatever we name it) we explain the steps needed to go from a freshly generated project to e.g. being able to scan for access-points - then we explain how to adapt code from the examples

[SergioGasquez]

Thinking about this again I wonder if changing the examples would really improve the situation for new users at all.

I assume most users will start from something generated by esp-template. That eliminates the need to deal with almost all the macros - the only one left is the one to get the wifi or ble peripheral via peripherals.RADIO.split()

Besides that, the user needs to create/use the right timer - that's it - the remaining code can be copied from any of the examples.

The harder part is to figure out which dependencies and features are needed. Since we are using workspace dependencies and dynamically activate some features that's slightly inconvenient t.b.h.

Last step the user needs to do is remembering to link rom_functions.x.

With that in mind I propose this

• keep the examples as they are (maybe add a comment to each example with a link to the USERGUIDE.md - see below)
• re-export everything from the relevant crates (so the user doesn't need to think about them at all - just depend on esp-wifi with the right features set)
• Change the README chapter Using in your own binary crate into something like USERGUIDE.md and link to it
• in the USERGUIDE.md (or whatever we name it) we explain the steps needed to go from a freshly generated project to e.g. being able to scan for access-points - then we explain how to adapt code from the examples

A bit off-topic, but maybe we could add a chapter/example on the no_std training where we walk the user through all of this.

[bjoernQ]

A bit off-topic, but maybe we could add a chapter/example on the no_std training where we walk the user through all of this.

I like that idea - we can link to that from the README.md, too

[MabezDev]

Thinking about this again I wonder if changing the examples would really improve the situation for new users at all.

I assume most users will start from something generated by esp-template. That eliminates the need to deal with almost all the macros - the only one left is the one to get the wifi or ble peripheral via peripherals.RADIO.split()

Besides that, the user needs to create/use the right timer - that's it - the remaining code can be copied from any of the examples.

The harder part is to figure out which dependencies and features are needed. Since we are using workspace dependencies and dynamically activate some features that's slightly inconvenient t.b.h.

Last step the user needs to do is remembering to link rom_functions.x.

With that in mind I propose this

• keep the examples as they are (maybe add a comment to each example with a link to the USERGUIDE.md - see below)
• re-export everything from the relevant crates (so the user doesn't need to think about them at all - just depend on esp-wifi with the right features set)
• Change the README chapter Using in your own binary crate into something like USERGUIDE.md and link to it
• in the USERGUIDE.md (or whatever we name it) we explain the steps needed to go from a freshly generated project to e.g. being able to scan for access-points - then we explain how to adapt code from the examples

I like the ideas here, but I'd like to expand on them.

• For rom_functions.x, I think we should just move these into esp-hal, the linker won't use the symbols unless they are referenced so there is no downside to doing this.
• Instead of USERGUIDE.md, I think we should
  • Put this in the crate docs
  • Add an option to esp-template to add esp-wifi support
• (Optional) Simplify some of the startup code with some helpers in esp-hal
  • For example, we could easily add a ClockControl::max(/**/).freeze() which would ramp the clocks to the highest available on the chip
  • We've spoken internally about disabling the watchdogs before main, so we don't have to disable them in the example code, I think this is a good idea.

[MabezDev]

The Clock::max function has been added to esp-hal in esp-rs/esp-hal#701. I also have a proof of concept for the watch dog disable before main: esp-rs/esp-hal#704 which I probably won't finish, myself, but would love for someone to take the reigns on that.

[MabezDev]

I think we're in a good spot functionality-wise, I think we just need to focus on some documentation (not a tonne, but just bit more) and we should be ready for a crates.io release!

[laundmo]

i'm trying to use this crate with embassy right now, and i'm stuck setting up dependencies. when cloning this project, examples work fine, but its not very clear from the examples which dependencies a user needs to specify, and which are just brought in by the workspace on accident.

i think some documentation regarding a full project setup with all dependencies, without having to mentally resolve the workspace like i have to for the examples, should be one of the documentation goals before releasing.

[MabezDev]

i'm trying to use this crate with embassy right now, and i'm stuck setting up dependencies. when cloning this project, examples work fine, but its not very clear from the examples which dependencies a user needs to specify, and which are just brought in by the workspace on accident.

i think some documentation regarding a full project setup with all dependencies, without having to mentally resolve the workspace like i have to for the examples, should be one of the documentation goals before releasing.

Imo examples are not the place to describe project setup, even in the embassy org there are bunch of examples that include deps that are not always needed. You can always just take all of the workspace deps and cut them away one-by-one, checking your project still compiles after each one.

The place we need this is inside esp-template. We should add support for embassy projects, and adding esp-wifi.

[SergioGasquez]

i'm trying to use this crate with embassy right now, and i'm stuck setting up dependencies. when cloning this project, examples work fine, but its not very clear from the examples which dependencies a user needs to specify, and which are just brought in by the workspace on accident.

i think some documentation regarding a full project setup with all dependencies, without having to mentally resolve the workspace like i have to for the examples, should be one of the documentation goals before releasing.

Feel free to take a look at https://esp-rs.github.io/no_std-training/03_5_http_client.html, it might help you as its a standalone example of esp-wifi.

[laundmo]

The place we need this is inside esp-template. We should add support for embassy projects, and adding esp-wifi.

i agree, ideally then the readme should point to that, so that new users dont run into the same issues.

[abergmeier]

As someone who read all this I am sadly still lost.
My immediate questions are:
1. How should I as a user figure out which deps I need?
2. Even if I have figured out the correct deps - it seems very important to choose the correct features to make it all work together.
3. Is using esp-idf* with esp-wifi supported?
4. If I encounter errors - should I write Issues or Stackoverflow for these? How are these problems being recorded so that not everyone makes the same mistakes?

Seems like my problems stemmed from mixing idf /std with nostd.
Actually found that wifi gets enabled using the esp-template advanced options.
Now I only need to figure out how to implement a http server on top of nostd without having to do all the socker communication manually.

[jessebraham]

It's been about 3 months since we decided that there are no blockers remaining here. Can we at least get the task list updated please so we have some idea of where we stand on this?

[bjoernQ]

After the first release we probably should maintain a CHANGELOG.md here

[jessebraham]

Update from the crates.io team:

the crates.io usage policies restrict crates from "using obfuscation to hide or mask functionality". I'm not sure whether pre-compiled closed-source artifacts would fall under that category, but I've put your request on the agenda for our crates.io team meeting on Friday. We'll get back to you once we've made a decision on this.

[bjoernQ]

After merging #343 we are ready to release