Hardware example inconsistency (STM32F3 versus TM4C123x)

[laanwj]

from: rust-embedded/wg#365 (reported by @josephpenafiel)

---

I couldn't find any site where I could write the Rust guys directly, so here I am. I just want to point out an inconsistency in this book. If you introduce a specific hardware in this book (the STM32F3 discovery board), why are you writing example code about different hardware??? (tm4c123x, in Section 2 Memory map registers). It's just plain confusing and annoying.
Stick with st or ti, don't mix things up. I think that just scares people away. I know that this book is aimed at people that have some knowledge about embedded systems in general, but my point is about consistency.
That's just something I wanted to get off my chest. Anyone else agree with me? am I wrong?

Regards!

[bobgates]

Supported. I bought the STM32F3 discovery board to follow the book, but just as the content gets interesting, the code stops working on the F3 Discovery. It's difficult to figure where it is going wrong for a relative beginner. The "starting at the bottom" section works for STM32F30x, but the Using a Peripheral Access Crate doesn't, even with all the appropriate tm4c123x entries switched to stm32f30x entries. That fails on things like:

error[E0432]: unresolved import stm32f30x_hal::serial::NewlineMode
--> src/main.rs:13:29
|
13 | use stm32f30x_hal::serial::{NewlineMode, Serial};
| ^^^^^^^^^^^ no NewlineMode in serial

That implies to me that the Hal for the 32F3 is different to that for the tm4c. I know I'm on a learning curve, but this is frustrating!

[therealprof]

I agree that we shouldn't introduce particular hardware; there's also the discovery book which exclusively covers this F3 discovery board. We also should make sure that we're not referring to outdated and unmaintained crates like stm32f30x_hal...

That implies to me that the Hal for the 32F3 is different to that for the tm4c. I know I'm on a learning curve, but this is frustrating!

Yes it is! The only contracts which exist are the embedded-hal traits, the initialisation of objects using those traits is and always will be "custom".

[bobgates]

Thanks for the help. What are the indications that I could use to see that stm32f30x_hal is not maintained? I see there's an alt_stm32f30x_hal, and it looks very similar. It would be good if people starting alt projects could at least mention why on the readme!

On the discovery book, that's where I started, but it doesn't go into non-blocking solutions. I have a background in embedded, but a long time ago and not in Rust.

I'm actually just trying to toggle a pin that isn't an LED, essentially working around f3#106. The stack as reported in four levels has been my guide, but I've fallen into the issue of not being clear where I am in the four levels, and more of not understanding the Rust relationships between the board support crate, the hal and the embedded hal.

I see that a PR has been submitted on my original issue. I'll implement that, then return to this book for the interrupts, etc.

At the moment, I feel like I'm a long way from understanding Rust enough to contribute, but I'd like to help with documentation - what can I do?

[therealprof]

Thanks for the help. What are the indications that I could use to see that stm32f30x_hal is not maintained? I see there's an alt_stm32f30x_hal, and it looks very similar. It would be good if people starting alt projects could at least mention why on the readme!

https://crates.io/crates/stm32f30x-hal

It hasn't been updated for over a year, but yeah, that should probably be deprecated.

Generally those overly specific crates have been superseded by HAL crates covering the whole MCU family, in this particular case that'd be https://crates.io/crates/stm32f3xx-hal .

At the moment, I feel like I'm a long way from understanding Rust enough to contribute, but I'd like to help with documentation - what can I do?

You could try modernizing the examples by using the stm32f3xx-hal crate. The changes should be mostly mechanical but you'll need to specify the stm32f303 feature in order to compile for the MCU present on the F3 discovery.

Other than that you can try to improve the current book by moving the discovery hardware and the specific examples closer together.