RFC/Proposal for a rewrite of this book

[bjoernQ]

• current thing is pretty much mimicking std-training which served us well for the start but ...
  • weird unrelated topics - more like explained examples ... would be better to have them as actual examples, then
  • no common thread
  • weird code organization, maintaining it is unnecessary hard, following the examples is hard for readers
  • no async mentioned
• idea!
  • have a "walkthorough" to create a more or less real-world application - e.g. mqtt-temperature-logger - no matter what, should be async
    • start with i2c and getting the sensor values - just print them
    • add wifi, add mqtt - send them to e.g. adafruit.io or any other easily accessible platform w/o setting up much
    • add wifi provisioning - either via BLE or an open access point
    • add OTA updates
  • consider a different application instead to show more other things or extend the mqtt-temp-logger, topics which would be good to cover
    • gpio ... could be a status LED and a button to do a factory reset
    • SPI ... adding a display?
  • "bonus" chapters?
• what should be the format?
  • could https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour be useful?
    • how maintainable are these tours - they are just json files and there are apparently GitHub actions to check if the tour still matches the code
    • could we somehow generate book content (at least parts) from those tours?

[bjoernQ]

Suggestion for an additional topic: TLS - preferably via embedded-tls

Q: What DevKit to use? RustBoard is probably still a good choice since it includes a temperature sensor

[jessebraham]

This seems like a great idea, thanks for taking the time to write this up. I've discussed this briefly with @MabezDev and I think we will be moving forward with this. I will try to come up with a rough outline and think of any remaining questions which need to be answered, and will update here once I have completed with that. Once we have a plan I will begin work on this. If anybody has any further input please feel free to mention it here, of course.

[MabezDev]

What DevKit to use? RustBoard is probably still a good choice since it includes a temperature sensor

I'd prefer something based on the ESP32-C6... however most devkits, even third-party (m5 stack, waveshare) devkits are really quite uninteresting 😅 , but maybe I'm looking in the wrong places 🤔. Another option is to rework the rust board design to facilitate the C6 instead of the C3.

[jessebraham]

Rough draft of the planning can be found below, thanks to @SergioGasquez for helping with this. This is all up for discussion, nothing set in stone at this point. This merely serves as a starting point which we can iterate on, so please share any thoughts/input you may have.

---

The training should walk users through the creation of a non-trivial application, resembling something that may be written in a "real-world" context. This does not necessarily need to be "production ready", however it should be complex enough to demonstrate building out a relatively interesting application, and cover a moderate to large range of topics and functionality.

The following requirements have been proposed, and may be expanded upon further depending on feedback received:

• The application should be asynchronous in nature, rather than using blocking APIs
• Demonstrate the use of at least one, and preferably multiple peripheral drivers
  • I2C is an obvious choice, however perhaps using GPIO, Interrupts, etc. would be nice as well
• Demonstrate use of Wi-Fi, and potentially BLE as well
  • Wi-Fi provisioning can be done using BLE or an open Wi-Fi AP
    • This could further be used to show how drivers can be initialized and then later dropped when no longer required
  • Connecting to an MQTT broker and sending sensor data is a relatively simple and common use case
• Demonstrate how to perform OTA updates

Below is a proposed outline for the training; this will be iterated on and should not be considered as complete/finalized at this point in time.

Introduction
Prerequisites
Building a Data Logger Application
    Project Overview
    Project Setup
    Reading Sensor Data
    Wi-Fi Connectivity
    Wi-Fi Provisioning
    Publishing Data to an MQTT Broker
    Over-the-Air Updates
    Wrapping Up
Bonus Chapters
    TODO: ???

There remain some unanswered questions which should be resolved prior to starting work on this:

• Which devkit should the project target?
  • The ESP32-C3-DevKit-RUST board has been proposed, as this contains on-board sensors (including a temperature sensor)
  • Additional options exist as well (feel free to make suggestions), but may be prohibitive given cost and/or availability
• What tooling should be used to create the training syllabus?
  • MDBook is a common choice, and I think it satisfies our needs
  • Something like CodeTour may also be possible, however given our inexperience with this tooling it's hard to make a proper assessment
    • https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour
• How should the code be structured in the repository?
  • Do we want to split up each chapter into its own project so that there is a working version readers can reference upon completing each chapter, or do we just want to have the final project?
    • Splitting it up by chapter is probably of more utility to readers, however does come with additional maintenance burden

[jessebraham]

Some ideas I had for potential bonus chapters, which may or may not belong in the training proper:

• Using SNTP to get network time and setting the RTC
• Configuring watchdog timers
• Connecting a SPI display (as suggested by @bjoernQ)

[bjoernQ]

Thanks for the detailed outline - pretty much what I had in mind.

I am wondering if the order of "Wi-Fi Provisioning" and "Publishing Data to an MQTT Broker" should be changed and let the user start with hard-coded Wi-Fi credentials - in my head this would feel a bit more "rewarding" and keep readers entertained.

I like the ideas for the bonus chapters - I'm sure we will find more interesting additions over time

[MabezDev]

Overall, I think the plan outline is solid, thank you everyone for taking the time to push this forward!

I think MQTT is a nice choice, and OTA is a really important thing to explain in this book. I think if we can, it would be great to also have server side code in this training. I.e, we run a mqtt broker locally, along with the server that can serve the OTA firmware from the users machine. However, we of course wouldn't walk the user through writing these parts, just have it there as the support for the actual training.

---

Which devkit should the project target

Based on what I've seen, I think I agree with using the established ESP32-C3-DevKit-RUST board. It's quite possible we will get a new revision of this board with a newer MCU, so I think we should stick with this "platform".

What tooling should be used to create the training syllabus

Whilst I think code tours is a cool concept, I don't like the idea of limiting the training to just vscode users. I think MDBook is the pick here.

How should the code be structured in the repository?

I think we should have each chapter as its own project. I think if someone has to read the whole book before they can run any code they'd probably get bored pretty fast. I think it's worth the maintenance burden here.

[brainstorm]

Suggestion of an extra feature that does not add too much complexity on top of the aforementioned outline: NVS/Config handling.

I.e have an AppConfig struct and (de)serialise from/to the different tasks of the project (mostly on init, potentially at runtime if there's appetite to show more fancy dynamics).

... mentioning this since it's on my current implementation pain intake recently and it'd like to see a neat/polished solution by good engineers X"D