Improvements of Examples

[VojtechBartoska]

This issue tracks improvements of all examples in this repository.

Purpose

We've been actively collecting feedback from the Community to figure out how to improve Arduino ESP32 Core framework and make it more accessible and easy to developed with. Main outcome includes improvements of Examples which serve as a solid starting point for most of the applications. Up to that, we sorted our examples and we will be continuously updating them to increase their quality.

Overview

Example improvements includes adding Readmes, headers, inline comments and so on.

Overview is available in this Google Spreadsheet. (Anyone can comment)

To-Do list

• research all existing examples - @pedrominatel
• Added the example guideline and template #7665
• sort examples with high priority
• continuously improve all the examples from the overview
• Add Pull Request template for examples contribution

Contribution

We are looking for your feedback about the examples. Also contribution to current examples is very welcomed (please wait for our example template/guideline)

[dsyleixa]

just out of interest: what are the hard-to-understand MT examples good for?
Finally we have std::thread
std::thread thread_0 (myfunction);

and std::mutex
std::mutex my_mutex;

and so on, which are absolutely common providing an absolutely catchy syntax, plus even vTaskPrioritySet() (which admittedly is not quite POSIX-like though)...?
https://github.com/dsyleixa/Arduino/blob/master/ESP32_Test/std_thread_000/std_thread_000.ino
https://github.com/dsyleixa/Arduino/blob/master/ESP32_Test/std_thread_007/std_thread_007.ino
https://github.com/dsyleixa/Arduino/blob/master/ESP32_Test/esp32_stdmutex_003/esp32_stdmutex_003.ino
https://github.com/dsyleixa/Arduino/blob/master/ESP32_Test/esp32_stdthread_008/esp32_stdthread_008.ino

[PilnyTomas]

@dsyleixa
My examples illustrate how FreeRTOS (on which all ESP32s run) does the multithreading natively.
Why use the existing and well-tested solution? I'll let that answer for you.

[dsyleixa]

aren't std::thread and std::mutex well-tested as well?
And finally this is the arduino-ESP32 section IIUC (please CMIIW)

(but BTW, some more std:: lib and POSIX-like pthread examples and extensions to thread prios, joinable() vs. detached(), queuing, semaphores, atomic, and core assignment would be highly appreciated, too!)

[Xylopyrographer]

What does the green and orange shading in the spreadsheet represent?

[VojtechBartoska]

@Xylopyrographer Green - examples are okay. Orange - examples need some action with higher priority. (known issue, request from community etc.)

[PilnyTomas]

@dsyleixa

aren't std::thread and std::mutex well-tested as well?

Sure they are, but they are not supported by FreeRTOS. If you believe that implementing std::thread and std::mutex to work on FreeRTOS is an easy job we will welcome your PR!

And finally this is the arduino-ESP32 section IIUC (please CMIIW)

Yes, you "UC" - what is your point? As it was pointed out elsewhere - Arduino ESP32 runs on ESP-IDF which runs on FreeRTOS - they are inseparable.

[dsyleixa]

@PilnyTomas
re: "but they are not supported by FreeRTOS"
I have to disagree, std::thread is already powered by RTOS underneath, and they are already working like a charm as has been demonstrated here (no PR needed at all!):
#7659 (comment)
So my point was that I wouldn't expect RTOS MT code in the arduino-esp32 section when std::thread etc are available, because of simplicity, convenience, and user-friendlyness.
(So probably your RTOS-MT code will better fit to the low-level esp32-IDF section instead.)

[PilnyTomas]

@dsyleixa If it is supported we will be happy to review your PR with examples.
You can follow the example of my pseudo library and create a new one named for example "pthread" and include your examples there.

[dsyleixa]

@PilnyTomas
I don't issue PRs, I do not even know how that works, but my examples work as shown above, and if you want you may use them.

[mathertel]

Please don't forget:

There is another example in #7687

• improving static files responses using a http eTag header
• extensive documentation

[VojtechBartoska]

a lot of examples have been improved and we are continuously working on this.

This ticket fulfil it purpose to do the investigation and start the improvements so I am closing it as done.