Naming and directory structure for project

[jhodapp]

Getting started on group discussion and documentation for the projects naming decisions and directory structure.

Project name rationale: ESP32-WROOM was chosen to signify that this project will only cover this specific series of ESP32 wifi modules. Others, such as ESP32-WROVER or ESP32-MINI, etc are intentionally out of scope for this project.

Directory structure:

esp32-wroom: parent directory
|
|-- boards: specific WiFi board support packages (BSPs), e.g. Pimoroni Pico Wireless Pack, Adafruit Huzzah32
|-- esp32-wroom: ESP32-WROOM WiFi HAL source code implementation

Any other ideas, objections, questions?

[bortyr]

It's great to see formal crate kicking off! Shouldn't there be some additional prefix added to the project name signaling that the HAL is rust based ? Something like esp32-wroom-rs ?

[jhodapp]

Yeah we discussed that, but because of how the ESP32 series is named by the parent company, we thought it might actually be confusing to have -rs on the end...people might confuse that with a model of the ESP32. What we did forget is a denotation that this is specific to the RP2040 series of microcontrollers, so perhaps something like ESP32-WROOM-RP2040 or ESP32-WROOM-PICO.

If you look at the rp-hal project, they don't have -rs on the end. I think people will understand quickly it's Rust-based when they look at the GitHub repo for it. Do you agree?

[bortyr]

Okay, fair enough. Sounds good to me. The -rs idea here came up for me from the stm32-rs

[jhodapp]

Yeah it's a great thought, thanks for bringing it up for discussion. I did a quick tour of other embedded/HAL crates on crates.io. From what I can tell, most don't use -rs.

Anybody else in the community feel strongly about -rs or no -rs in our new crate name?

[glynos]

I prefer no "-rs", it feels redundant

[jhodapp]

Updated the name to esp32-wroom-rp to signify that we're targeting the RP2040 series of microcontroller boards.

[calebbourg]

@glynos have you had the experience of taking a project that isn't a Cargo Workspace and converting it into one? If that process is an easy one maybe it would make sense to start with a basic Cargo directory structure with the assumption that we may move to using a Cargo Workspace in the future? That way we would be at less risk of overbuilding things before we start to really understand how it will look.
If it's not so trivial to go from non-workspace -> workspace then maybe it makes sense to start as a workspace?

Curious what your thoughts are on that.

[glynos]

@calebbourg, yes it is not a difficult process, just move files and directories around and point to where they are in the root Cargo.toml file. Adding new projects to a workspace is well supported by at least the CLion IDE too.

Generally, I think it's quite easy to set up a workspace and then fit things around once we see the internal packages depend on each other.

[jhodapp]

Great discussion. So it sounds like we should start without a workspace then if we don't have a plainly obvious use for it today, and restructure if/when we do in the future. It's worth doing a bit more research and discussion here to see if we do have a real use for it right now or not.

[calebbourg]

Thank you @glynos for the extra info. That makes sense that it would be straight forward.
In that case I agree @jhodapp that maybe we defer that decision until we think through how we want things structured a bit more.

[jhodapp]

So to capture our early project design decision, for now, we'll hold off on using a Cargo Workspace for now until we see a real need for using one.

[jhodapp]

We've proven that the other ESP32 WiFi co-processor boards all use minor variations of the nina-fw from Arduino. So this means we don't need any special abstraction or accommodation for a different SPI bus command set. This rules out any need for a WiFi board specific directory structure.

Also, rp-hal already abstracts the specific differences between RP2040 series boards, so we won't need any special directory accommodation here either. That means that right now, I think this is what our project directory structure should look like:

esp32-wroom-rp: parent directory
|
|-- .cargo/: standard Cargo project config dir
|-- .github/workflows/: GitHub Action workflows for CI
|-- .vscode/: project-specific Visual Studio Code config
|-- examples/: one or more examples that use this crate in helpful ways to those who wish to use it in their own applications
|-- scripts/: any needed shell scripts for the project
|-- scripts/git/: git hook related shell scripts
|-- src/: all of the crate's source code and tests
|-- tests/: integration tests

This documentation is a great intro to unit/integration testing and how the Rust community thinks about where each type of test belongs.

@calebbourg @glynos @bortyr