General HAL examples

[Sympatron]

At the moment we only have examples for BSPs and while this might be the main use case for most users, I think it would be beneficial to also have examples of using the bare HAL.

The main problem with the current setup is that if you are looking for an example of how to properly use a specific peripheral you kind of have to search through all BSPs to find it.
The other problem is that I felt it's kind of difficult to get the BSP example code to work without a BSP (or with another BSP) if you are not super familiar with the HAL and BSP yet.

The advantage of bare HAL examples would be that they can be used anywhere and would be much easier to maintain than the BSP examples.

What do you think? If the community is interested I could start a PR with a few examples from BSPs.

[vcchtjader]

tl;dr: I fully agree

This "de-BSP-ing" process you describe is something I've also run into when starting out, I can see people having some board A wanting to run an example provided for board B or some other variant of this, where first step is not to "just use HAL" but rather look at how the BSP uses HAL, copy that out from the BSP and implement for your own board.

Another case for these bare-HAL examples are for peripherals which are truly independent of pin mappings, for example the ICM and PUKCC among others.

[bradleyharden]

I'm not opposed. I think it would be a nice addition. My only concern is that any examples involving pins would have to use some arbitrary pin mapping. Thus, instead of being use anywhere, they would in fact be use nowhere. I concede, though, that remapping the pins is usually simple, so it would still be useful to have. In those situations, it may even present an opportunity to introduce the bsp_pins! macro.

[Sympatron]

My only concern is that any examples involving pins would have to use some arbitrary pin mapping. Thus, instead of being use anywhere, they would in fact be use nowhere.

I don't think that such a big deal. If you have a blinky example for example the user would just have to adjust the pin to much their own to get it to work on any board.

In those situations, it may even present an opportunity to introduce the bsp_pins! macro.

The bsp_pins! macro is good for simplifying and consolidating the BSPs, but shouldn't be used here IMO. I think it would be more helpful if the examples were as bare bones as possible to not introduce too much indirection and confusion.

How would you structure the examples?
The problem is that most examples will either work for thumbv6 or thumbv7, not both.
Supporting both in one example will probably do more harm than good (see #529).
Can you put examples in sub directories like /hal/examples/thumbv6/blinky.rs?

[TDHolmes]

@Sympatron you can have sub-directories within examples folder, but you need to explicitly call their path in an [[example]] section of the Cargo.toml. thumbv6m/thumbv7em sub-folders makes sense to me

[pustekuchen91]

How about to extend the documentation for this case? Another useful case for this are people who have designed their own board.