Book Rewrite - HackMD

# Book Rewrite - We should have a new-and-improved version of the book available to correspond with the release of `esp-hal@1.0.0` - In order to do this, we must first decide what should be in the book, and what should instead be in documentation and/or other resources :) - Some ideas from ivmarkov: https://github.com/esp-rs/rust/discussions/235#discussioncomment-10760357 - Let's please come up with a game plan for this sooner than later, as this kind of techincal writing always seems to take longer than expected --- - What is our plan with no_std-training? - There are a few issues already: https://github.com/esp-rs/no_std-training/issues, we dont mention that we can use stable... - BQ: IIRC there was the idea to replace our `examples` in esp-hal with something more interesting - if we do that we could also add some markdown documents and replace the training? - JB: I would still like to do this, but there seems to have been a fair bit of resistance when I have brought it up in the past for whatever reason - SM: imo the no_std training is valuable, but might need some love. I see it as the "discovery" book equivalent for us (maybe we should rename it that?) - If possible, we should try and make this training with stable APIs only, and maybe move the others to the advanced section if they depend on unstable APIs? - JB: Agreed, continuing to provide examples using unstable APIs is just creating unnecessary work for ourselves - Shall rip all the std stuff from the book? - BQ: To me covering two very different things in one book is a source of confusion. And https://docs.esp-rs.org/book/overview/using-the-standard-library.html#when-you-might-want-to-use-the-standard-library-std is a little bit too biased towards std (especially since std is not what we want people to use) - SM: We should focus solely on no_std, and take the std content and put it somewhere else (esp-idf-svc readme?) - JB: Yes, I think we should - SG: Follow-up question: What about the std-training? I think its a good resource to have, and does not require much maintenance from our side. Maybe we could still add some note on it referencing to no_std stuff and trying to get people there. --- - Most of the open issues in the `esp-rs/book` repository are still relevant, however some may be outdated or no longer an issue; some further review will be required here to determine which issues this is the case for. - Ivan Markov's comment (linked above) is reasonably comprehensive, and I generally agree with the points he stated. This probably will serve as a good starting point with regards to planning an outline. - What other points might need covering in addition to those he's laid out? This will require some further discussion I imagine. - SM: Over time I think https://docs.rust-embedded.org/book is less and less useful as a resource, anything post chapter 2 is out of date and not relevant anymore so I think in the past we've been afraid of duplicating content from that book, but now we don't have to worry. - The things I'd like the book to cover in general are: - Available tools (espflash, probe-rs, esp-generate) and their capabilities - Installation instructions (imo these are already quite good) - Generating a project - A concepts chapter - the idea behind this is to explain some more complex (but not always complex) ideas that the various projects/HAL uses: - Things like the `Peripheral` pattern - How to register interrupts (this is unstable, so it shouldn't be this just yet, but it's a good example of something we specifically do different to other ecosystem HALs) - A chapter on "how to glue" different bits together? - I see this beginners trip up on this quite often, unsure how to glue two things together either from different crates via traits or some other mechanism - This is somewhat a general Rust learning issue though - Bootloader discussion - The bootloader is quite important, and often overlooked as much of tooling (quite nicely) hides it away until they actually need to interact with it - JB: Configuring/building a bootloader a bit of an annoying proess, as it requires users to download ESP-IDF and set up the tooling in order to build a it. Probably we can just delegate this to the existing documentation for ESP-IDF - Needs to discuss the two supported options (MCUBOOT, esp-idf) - FAQ - This is more for us, so we don't have to repeat ourselves so much but something analogous to https://embassy.dev/book/#_frequently_asked_questions. We have https://docs.esp-rs.org/book/troubleshooting/std.html but it's just for STD --- - Introduction/Resources - Preface expectations - avoid mentioning idf - stable/unstable - ecosystem - support channels, matrix github issues - self hosted docs - devkits (link to espressif docs) - product selector / portfolio - https://products.espressif.com/static/Espressif%20SoC%20Product%20Portfolio.pdf - external resources - awesome list - How TF does this 💩 work - architecture of the system, bootloader to main? - Installation/get started - simplify for no_std only - Tooling - esp-generate - espflash - probe-rs (defer docs here?) - How to work with the tool in a project - --- - openocd (defer to official docs) - xtask reference matklad blog - wokwi/qemu (defer docs) - split this: - how to generate - tools to write code - how to run/log - how to debug - Understanding your project - logging - esp println - defmt (and its limitations) - async - rtic - embassy - block_on? - configuration (how it works) - Bootloader - dont explain how to build - just explain that it exists and its purpose - partition table - Advanced (which is a bad (scary) chapter name) - concepts (patterns etc, gluing) (does this belong in the book?) - API guidelines mention - how to use the hal as it was designed - re using peripherals - drop impls - don't use mem::forget - best practices - testing embedded-test / host tests - debugging - probe-rs docs - core dumps? (might not be ready yet) - IDEs (maybe merge into FAQ) - rust analyzer - FAQ / troubleshooting - size opts - mem opts - git crate usage - stack overflows/exceptions ## Sergio ToC suggestion: 1. Introduction - [Assumptions and prerequisites](https://docs.esp-rs.org/book/#assumptions-and-prerequisites) - Rust embedded ecosystem: - Other [resources](https://docs.esp-rs.org/book/#resources) - [Re-Using this material](https://docs.esp-rs.org/book/#re-using-this-material) - Other materials: - Awesome list - Product selector - Self-hosted docs - Support channels - Shall we mention here the std approach as community driven? And leave some links - Avoid mentioning idf - Stable/Unstable 2. Setting Up a Development Environment - Rust installation - RISC-V targets only - RISC-V and Xtensa targets 3. Writing Your Own Application - How to generate a project - Understanding the generated project - Architecture of the system - bootloader to main - esp-println/defmt - async - configuration - bootloader 4. Tooling - How to flash your project: - espflash - probe-rs - Tools for writing code (IDEs) - Recommended RA settings for different IDEs - How to debug a project - probe-rs - openocd - Core dumps - How to simulate stuff - Wokwi - QEMU? Only supports C3 afaik, maybe just link to docs - How to test your project 5. FAQ/Troubleshooting - size opts - mem opts - git crate usage - stack overflows/exceptions - best practices - API guidelines mention - how to use the hal as it was designed - re using peripherals - drop impls - don't use mem::forget ## Jesse's ToC Suggestions (rough) 1. Preface - [Who is this book for](https://docs.esp-rs.org/book/#who-this-book-is-for) - Scope of the book (e.g. not a Rust tutorial, not an embedded development tutorial) - Set expectations with regards to driver availability and stability - Talk about (lack of) stability in greater Rust ecosystem - Provide additional resources which may help people get up to speed which cover topics outside the scope of this book - [Contributing to this book](https://docs.esp-rs.org/book/#contributing-to-this-book) - Mention available support channels (Matrix, email, etc.) 2. Introduction - Hardware overview, product selector, etc. - System architecture, bootloader to main, etc. - HAL design philsophy, API explanations, etc. (???) 3. Getting Started - Toolchain installation/setup - Tooling - esp-generate - espflash - probe-rs - use `--locked` 4. Writing Your Own Application - Logging (`esp-println`, `defmt`, etc.) - Async - Embassy - RTIC - `block_on` (???) - Configuration (i.e. how it works) - Bootloader/Partition table customization 5. Advanced (???) - Concepts - API guidelines - How to use the HAL as it was designed - Using peripherals (???) - Drop implementations - Don't use `mem::forget` - Best practices - cargo-xtask - Testing (`embedded-test`, host tests (???) ) - Debugging - `probe-rs` docs - Core dumps (???) 6. FAQ - Editor/IDE configuration (`rust-analyzer`, etc.) - Size/memory optimizations - Git crate usage (???) - Stack overflows/exceptions - wokwi/qemu # First Iteration Review ## General questions: JS: 1.) What is the goal of the book? JS: 2.) What should be the style of the book? ## Preface ## Introduction - BQ: Peripheral pattern is already obsolete and the replacement chapter in the API-docs is much better / helpful ## Getting Started ### Application Development - SGA: Both Alloc and Logging chapters explain stuff that are already taken care in `esp-generate`. I think there is some value on explain such things, but we should clearly mark that when using `esp-generate` all that will be handled by the tool. - BQ: Bootloader - maybe we want to give some examples of when they need a custom built bootloader. (e.g. octal flash), I'm not too convinced if that topic should be something discussed that early (i.e. "Install ESP-IDF" is probably not something an aspiring ESP32-Rust developer likes to read during the first 30 minutes into esp-hal?) - BQ: In general this is all a bit fuzzy - seemingly unrelated topics without a "common thread". Maybe having a "big picture" of the esp-hal ecosystem (maybe a diagram with all the relevant crates) would be a better start into these topics. This might also help in identifying gaps (we don't mention wifi, ble, usb etc. at all - at least if this is the first thing a new user will read they probably want to know what they can do with all of this?) - BQ: Not sure "Application Development" makes a great title. It would make me expect this is something we say this book is not (a guide to embedded development). Something like "The esp-hal ecosystem" (yes - not great but something similar maybe) ### Advanced Topics - BQ: obviously lacking content but we should already remove the xtask-chapter ### FAQ - SGA: Should we split every topic(IDE, Size/memory optimizations...) into a different sub-chapter? ### Guidelines ### Content "issues" - SGA: We talk about bootloaders in two places: Intro/ApplicationStartup and AppDevelopment/Bootloader maybe the should be unified (?) - SGA: We should add redirects when possible, eg: https://docs.esp-rs.org/book/installation/index.html should point to the getting started chapter. - I guess a lot of places point to this chapter and we cant update them all.