Is this book working at the right abstraction level?

[hargoniX]

I was wondering, considering that the embedded discovery book is targeted at people that have never done embedded things in their life before, is it reasonable to show the how to use a PAC instead of demonstrating the embedded-hal APIs etc. in those chapters? Since, if you are new to embedded and embedded rust I feel like the last thing you are going to do is write some implementation for a UART on a chip that doesn't have a HAL yet yourself. If you know people that already do embedded rust (which is probably the case if you are getting into it) you'd most likely be told to get a chip (probably an stm32 or nrf52) which already got good HAL support so you can toy around with it in a more easy way. Instead what the discovery book does from chapter 7 on is teach people how to use a PAC which they will probably not do for a long amount of time.

I propose we instead put in these chapters how to use some of the embedded-hal APIs since really those are the "user facing" APIs we provide in this eco system and not the PAC ones. Knowing how to work with the registers etc. and how that is abstracted away in Rust surely is good knowledge that should be documented somewhere (probably the Embedded Rust Book) but for someone who is just getting started with this it really is just confusing and most of the time they will stick with embedded-hal APIs anyways.

[theunkn0wn1]

I, for one, recently got into embedded rust, thanks to suggestions from someone that already does embedded rust, and one of the first materials i was recommended was this book. This "Discovery" book is, as the initial wording would suggest, aimed to be Beginner friendly, not requiring past embedded experience.

For a piece of educational material aimed at beginners, I found the only chapters that came remotely close to being sufficiently high-level for a beginner like me to understand were the first chapters on turning a LED on and off via some abstraction layer.

The book promptly discarded the majority of this abstraction at chapter 7, jumping into direct register manipulations and other low-level operations. Sure, knowing how to write one's own HAL layer is probably useful for the experienced embedded programmer, it is IMHO both very confusing and not useful to new developers.

The latter two books in the series such as the Embedded rust book and the embedonomicon would be much better candidates for operating below the HAL level of abstraction as they are not aimed at complete beginners.

I ultimately found the contents of chapter 7 onward to be unusable in their entirety, and shifted my focus to other materials and code bases that made use of the "user facing" components such as the embedded_hal and board support crates. The majority of my initial time was thus spent reverse-engineering other open-source projects to figure out how to gain access to, and drive, the peripherals on my stm32(f4) via these embedded_hal and the stm32f4 support crates as they didn't require me, as the new programmer, to operate at a much more practical layer of abstraction.

I concur with @hargoniX 's suggestion of rewriting chapter 7 onward to illustrate how to use the excellent embedded libraries rust has to offer, such as working with the embedded_hal and board support crates instead of focusing on the micro details of how such abstractions are implemented. I suggest differing those advanced details to other books and materials aimed at more advanced users.

[swpease]

One thing that I think might be useful would be a chapter-by-chapter dive from high-level to low-level for the same piece of code. Start with, e.g. this compass code, and explain what absolutely everything is doing. Then spend subsequent chapters doing things like: explaining why we used constrain(); why we need RCC; what's going on with the seven things that are passed to Compass, and what's going on with the things that those things are doing.

One issue I had was seemingly arbitrary set-up being abstracted away. I had to cross-reference with the Embedonomicon, the other Embedded Rust Book, and source code, to get an idea of what was going on.

Chapter 7+ definitely needs some more exposition and/or high-level work. I only grasped how I2C worked after several hours across several days, and I'm still not 100% (e.g. when do I have to wait for stuff vs. when is stuff auto-queued, are there ever race conditions, what's the deal with these interrupts...). But, I feel like, as you say, the registers definitely shouldn't be used heavily by beginners, given that even the HAL crates have comments like this.

[hargoniX]

Just as a side note, since the f3 BSP crate is said to be unmaintained by now I will look into writing the majority of things with just the stm32f3 HAL instead of the BSP. If someone has a good reason to stick with the f3 BSP (or another BSP) please do tell me, however as off now apart from a few method calls being hidden from the people who read the book (and the method calls really not being that scary) I don't see a reason to stick with an unmaintained BSP instead of using HAL + drivers.

[hargoniX]

As per #263 and a rust embedded wg meeting we have come to the conclusion that the rewrite for this book will be done using the micro:bit. Until chapter 6 we will presumably be able to just rewrite and freshen up stuff for the micro:bit however all following chapter are, as this issue mentions, not properly abstracted as per "modern" rust embedded standards.

We should discuss what we want to replace these chapters with, what we got available on the micro:bit is;

• An LED matrix
• A UART, connected to a UART to USB converter which we can use similarly to the Arduino.
• 2 User buttons
• A LSM303GR motion sensor @eldruin is writing a driver for
• The NRF51 chip does have a built in temperature sensor
• The NRF51 chip does have bluetooth but the Rust Bluetooth stack is not even close to done yet so that will probably take us some time to use

It would be cool if we could come up with some ideas etc. on what to put in chapter 7+

[eldruin]

There is lots of inspiration to draw from at the microbit site. There are a lot of funny examples there.

[tim-seoss]

Some thoughts...

Although the Rubble Rust Bluetooth stack is at an early stage of development, I think it might still be useful. e.g. it supports Beacons, and these could be used to e.g. implement a simple programmatically changeable beacon could be a useful addition to the book (e.g. it could be used to direct a mobile phone browser to a set of different hosted URLs based on some external stimulus, e.g. orientation, user buttons etc).

Although there are a lot of things that can be done with the onboard peripherals, it might be engaging to get reader's imaginations working will be to interface to a peripheral external to the micro:bit?

One option might be to use a peripheral device which has both a commercially available off-the-shelf (micro:bit specific) implementation (to provide accessibility to those with little HW knowledge or practical skills), and is also available as a cheap generic module (for the EE types, the adventurous, cash-strapped etc.) e.g.

• OLED display
• Microphone

Alternatively something like a micro:bit specific two wheel robot (there are multiple commercial options) should be pretty engaging and would open up a wide variety of possible example projects.

It might be useful to close the book by giving a brief overview of the process for using some arbitrary other peripheral e.g. adopting some concrete example project.

• How to choose what devices might be relevant
• Where to look for existing peripheral crates
• Steps to implementation

... given the online nature of the book, it could suggest users contribute brief (or not so brief) write-ups of their "next-steps" projects in order to grow a list of "beginner-grade" projects to provide inspiration, encouragement etc.

[therealprof]

We had some discussion about this in the current meeting. Some good points have been raised in this issue and with the rewrite being ongoing it seems only natural to explore various ideas and decide on the spot how to proceed so we're unnominating this for now unlesss there's something specific to discuss.

[huntc]

Here's a link to the [a] re-write: https://droogmic.github.io/microrust/index.html

UPDATE: apparently not an official update.

[therealprof]

@huntc That book is not the "offical" discovery rewrite but an independent effort pre-dating it by a few years. It certainly is a good resource (and the author a contributor of the microbit BSP crate) but it shows a few sings of age and doesn't cover the new hardware revision at all.

[huntc]

@huntc That book is not the "offical" discovery rewrite but an independent effort pre-dating it by a few years. It certainly is a good resource (and the author a contributor of the microbit BSP crate) but it shows a few sings of age and doesn't cover the new hardware revision at all.

Apologies for the inaccuracy. I’ve added an update to that comment.

[joaocarvalhoopen]

Congratulations on the new book for microbit V2 with a Cortex M4 with floating point support. Please give also priority to some examples with digital and analog input and output with microbit. With that and what you have made, anyone can go really far. I intend, as soon as the shops have the microbit again (because of chip shortage), I intend to buy 2 microbit’s and teach my daughter on Rust and Rust with micro-controllers with this guide and with what examples or projects I can prepare from the knowledge of the HAL examples project. Note: Interrupts, microphone and speaker support would be also transform this Rust port into a huge platform for audio projects, I’m thinking of the clap project, on small the DSP projects and on small DIY re-implementations of of ML algorithms for vocal commands, pre-recorded adpcm and stuff like that, because 512K is a lot to have on board for audio if you compress it with ADPCM at 8KHz mono. With the microphone and the fast CPU you could also do a AM emitter for simple tone musics and even for audio modulation of AM directly from the microphone.

Best regards, João

[eldruin]

Thanks for the ideas @joaocarvalhoopen. I hope you have a lot of fun with this book. Since you seem to have at least (?) some embedded knowledge, we would very much welcome further chapters to the book adding any interesting examples like the ones that you listed. If you want to do so, please open a PR with some initial version and we can work on it from there.

[joaocarvalhoopen]

Thank you, after getting the 2 boards I will try to contribute with mini projects and explanations of the project as I do them with my daughter.

Best regards, João