Writing your own application

[MabezDev]

• Logging (esp-println, defmt, etc.)
  • Async
    • Embassy
    • RTIC
    • block_on (???)
• Configuration (i.e. how it works)
• Bootloader/Partition table customization

[SergioGasquez]

I think it would make sense to document esp-rs/espflash#298 in this chapter

[bjoernQ]

I think it would make sense to document esp-rs/espflash#298 in this chapter

Sounds good. Ideally, we would first have the full esp-bootloader-support-esp-idf crate in place

The one thing I don't currently get (and maybe something to be resolved later) is how we want to distinguish between esp-idf-bootloader specifics and (later) MCUboot - e.g. we are talking about partition tables a lot but that is purely an esp-idf construct (MCUboot has a concept of application slots - the config apparently doesn't reside in a dedicated space on flash)

[MabezDev]

Notes from our book review:

• Add a ecosystem overview before getting into these topics
  • 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?)
  • DB: Before getting into specifics, I'm missing a general ecosystem overview - PACs, HALs, embedded-hal, device drivers, and how they all relate to each other
• Rename section (name TBD)
• "Bootloader" section
  • Move application start up flow (from earlier in the book) etc to here (Improve introduction chapter #200)
    • See notes in PDF when moving this section
  • Explain what the bootloader does on a basic level - aka why should they care about it?
  • Make it clear that they are not tied to the esp-idf bootloader, and schemes stemming from that (partition tables are only relevant to esp-idf's bootloader for example).
  • We need to mention that our tooling (probe-rs/espflash) includes a prebuilt bootloader for the supported chips as a convenience to the user, then we can explain about building a custom one at the end or move to the FAQ. This should also note why a user might want to build a custom one (i.e to change config options like octal flash support etc
• Configuration
  • We need to explain how it works from a user perspective. How do they find the possible options? How do they set the options?
  • Explain the config files, and why our configs are in a seperate config file (see Config options for specific chips esp-hal#3020 (comment))
  • ESP_HAL_CONFIG_PLACE_SPI_DRIVER_IN_RAM is no longer a valid config, we should resolve Review config option stability esp-hal#3445 and pick a stable one from there.
  • The esp-config readme is not that useful to users, so avoid linking there as generic advice.
• Logging
  • Remove the installation instructions for defmt/log, esp-generate already does this
  • Expand on the transport methods for these log messages, defmt + probe-rs = debugger transport, log + espflash = serial transport
    • Let's make this very clear which USB port is required for each operation
  • Remove "Integrating defmt with esp-println" esp-generate can do this
• Alloc
  • Instead of the boiler plate, we should expand on why you might reach for alloc, and the possible pitfalls (heap fragmentation, takes up memory which could be used for stack etc)
  • Add a diagram or at the very least explain what we mean by "non-contiguous memory", i.e there is some gap (or in our case, "reserved for ROM code") where we can't read or write to
  • PSRAM "The external memory is usable is the same way" type should be "in"
  • We need to be very clear about the implications of Xtensa + atomics + PSRAM (read: big warning signs) but we must also be sure to explain that our RISCV PSRAM impls are solid.
• Async
  • Move embassy mentions to the embassy section
  • Explain more about async for our hal/crates
    • Drivers can be created in blocking or async mode
    • How to obtain an async driver (into_async) etc
    • Explain why Async drivers aren't Send
  • RTIC needs to be expanded to say its community supported
  • Add ArielOS section (above RTIC)
• Testing (new section, moved from later in the book)
  • Talk about embedded-test as the test framework how it works on a high-ish level
    • The tests are run on the device itself
    • How test results are captured
    • #[should_panic] attribute still works
    • Mention hil-test in esp-hal as reference of this working?
    • Mention IDE integration should just work™️ as embedded-test mimics the default rust test harness
    • Don't mention defmt-test (as it's arm only), but perhaps lift some snippets from their README: https://github.com/knurling-rs/defmt/tree/main/firmware/defmt-test#adding-defmt-test-to-an-existing-project it's quite nice.
    • Optional: We may wish to talk about running tests on the user machine (host machine), but this might be out of scope here.