Skip to content

Commit cb672d8

Browse files
SuGliderSuGlider
committed
feat(support): readme files, commentaries and examples
1 parent 34f15c0 commit cb672d8

File tree

25 files changed

+387
-846
lines changed

25 files changed

+387
-846
lines changed

Diff for: ‎libraries/ESP32/examples/FreeRTOS/BasicMultiThreading/README.md

-4
Original file line numberDiff line numberDiff line change
@@ -62,10 +62,6 @@ To get more information about the Espressif boards see [Espressif Development Ki
6262
* Before Compile/Verify, select the correct board: `Tools -> Board`.
6363
* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port.
6464

65-
#### Using Platform IO
66-
67-
* Select the COM port: `Devices` or set the `upload_port` option on the `platformio.ini` file.
68-
6965
## Troubleshooting
7066

7167
***Important: Make sure you are using a good quality USB cable and that you have a reliable power source***

Diff for: ‎libraries/ESP32/examples/FreeRTOS/Mutex/README.md

+117-121
Original file line numberDiff line numberDiff line change
@@ -1,121 +1,117 @@
1-
# Mutex Example
2-
3-
This example demonstrates the basic usage of FreeRTOS Mutually Exclusive Locks (Mutex) for securing access to shared resources in multi-threading.
4-
Please refer to other examples in this folder to better understand the usage of tasks.
5-
It is also advised to read the documentation on FreeRTOS web pages:
6-
https://www.freertos.org/a00106.html
7-
8-
This example creates 2 tasks with the same implementation - they write into a shared variable and then read it and check if it is the same as what they have written.
9-
In single-thread programming like on Arduino this is of no concern and will be always ok, however when multi-threading is used the execution of the task is switched by the FreeRTOS and the value can be rewritten from another task before reading again.
10-
The tasks print write and read operation - each in their column for better reading. Task 0 is on the left and Task 1 is on the right.
11-
Watch the writes and read in secure mode when using the mutex (default) as the results are as you would expect them.
12-
Then try to comment the USE_MUTEX and watch again - there will be a lot of mismatches!
13-
14-
### Theory:
15-
Mutex is a specialized version of Semaphore (please see the Semaphore example for more info).
16-
In essence, the mutex is a variable whose value determines if the mute is taken (locked) or given (unlocked).
17-
When two or more processes access the same resource (variable, peripheral, etc) it might happen, for example, that when one task starts to read a variable and the operating system (FreeRTOS) will schedule the execution of another task
18-
which will write to this variable and when the previous task runs again it will read something different.
19-
20-
Mutexes and binary semaphores are very similar but have some subtle differences:
21-
Mutexes include a priority inheritance mechanism, whereas binary semaphores do not.
22-
This makes binary semaphores the better choice for implementing synchronization (between tasks or between tasks and an interrupt), and mutexes the better
23-
choice for implementing simple mutual exclusion.
24-
What is priority inheritance?
25-
If a low-priority task holds the Mutex but gets interrupted by a Higher priority task, which
26-
then tries to take the Mutex, the low-priority task will temporarily ‘inherit’ the high priority so a middle-priority task can't block the low-priority task, and thus also block the high priority task.
27-
Semaphores don't have the logic to handle this, in part because Semaphores aren't 'owned' by the task that takes them.
28-
29-
A mutex can also be recursive - if a task that holds the mutex takes it again, it will succeed, and the mutex will be released
30-
for other tasks only when it is given the same number of times that it was taken.
31-
32-
You can check the danger by commenting on the definition of USE_MUTEX which will disable the mutex and present the danger of concurrent access.
33-
34-
35-
# Supported Targets
36-
37-
This example supports all ESP32 SoCs.
38-
39-
## How to Use Example
40-
41-
Flash and observe the serial output.
42-
43-
Comment the `USE_MUTEX` definition, save and flash again and observe the behavior of unprotected access to the shared variable.
44-
45-
* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide).
46-
47-
#### Using Arduino IDE
48-
49-
To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits).
50-
51-
* Before Compile/Verify, select the correct board: `Tools -> Board`.
52-
* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port.
53-
54-
#### Using Platform IO
55-
56-
* Select the COM port: `Devices` or set the `upload_port` option on the `platformio.ini` file.
57-
58-
## Example Log Output
59-
60-
The expected output of shared variables protected by mutex demonstrates mutually exclusive access from tasks - they do not interrupt each other and do not rewrite the value before the other task has read it back.
61-
62-
```
63-
Task 0 | Task 1
64-
| Starting
65-
| 0 <- 227
66-
Starting |
67-
| R: 227
68-
227 <- 737 |
69-
R: 737 |
70-
| 737 <- 282
71-
| R: 282
72-
282 <- 267 |
73-
```
74-
75-
The output of unprotected access to shared variable - it happens often that a task is interrupted after writing and before reading the other task write a different value - a corruption occurred!
76-
77-
```
78-
Task 0 | Task 1
79-
| Starting
80-
| 0 <- 333
81-
Starting |
82-
333 <- 620 |
83-
R: 620 |
84-
620 <- 244 |
85-
| R: 244
86-
| Mismatch!
87-
| 244 <- 131
88-
R: 131 |
89-
Mismatch! |
90-
131 <- 584 |
91-
| R: 584
92-
| Mismatch!
93-
| 584 <- 134
94-
| R: 134
95-
| 134 <- 554
96-
R: 554 |
97-
Mismatch! |
98-
554 <- 313 |
99-
```
100-
101-
## Troubleshooting
102-
103-
***Important: Make sure you are using a good quality USB cable and that you have a reliable power source***
104-
105-
## Contribute
106-
107-
To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst)
108-
109-
If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome!
110-
111-
Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else.
112-
113-
## Resources
114-
115-
* Official ESP32 Forum: [Link](https://esp32.com)
116-
* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32)
117-
* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf)
118-
* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf)
119-
* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf)
120-
* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf)
121-
* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com)
1+
# Mutex Example
2+
3+
This example demonstrates the basic usage of FreeRTOS Mutually Exclusive Locks (Mutex) for securing access to shared resources in multi-threading.
4+
Please refer to other examples in this folder to better understand the usage of tasks.
5+
It is also advised to read the documentation on FreeRTOS web pages:
6+
https://www.freertos.org/a00106.html
7+
8+
This example creates 2 tasks with the same implementation - they write into a shared variable and then read it and check if it is the same as what they have written.
9+
In single-thread programming like on Arduino this is of no concern and will be always ok, however when multi-threading is used the execution of the task is switched by the FreeRTOS and the value can be rewritten from another task before reading again.
10+
The tasks print write and read operation - each in their column for better reading. Task 0 is on the left and Task 1 is on the right.
11+
Watch the writes and read in secure mode when using the mutex (default) as the results are as you would expect them.
12+
Then try to comment the USE_MUTEX and watch again - there will be a lot of mismatches!
13+
14+
### Theory:
15+
Mutex is a specialized version of Semaphore (please see the Semaphore example for more info).
16+
In essence, the mutex is a variable whose value determines if the mute is taken (locked) or given (unlocked).
17+
When two or more processes access the same resource (variable, peripheral, etc) it might happen, for example, that when one task starts to read a variable and the operating system (FreeRTOS) will schedule the execution of another task
18+
which will write to this variable and when the previous task runs again it will read something different.
19+
20+
Mutexes and binary semaphores are very similar but have some subtle differences:
21+
Mutexes include a priority inheritance mechanism, whereas binary semaphores do not.
22+
This makes binary semaphores the better choice for implementing synchronization (between tasks or between tasks and an interrupt), and mutexes the better
23+
choice for implementing simple mutual exclusion.
24+
What is priority inheritance?
25+
If a low-priority task holds the Mutex but gets interrupted by a Higher priority task, which
26+
then tries to take the Mutex, the low-priority task will temporarily ‘inherit’ the high priority so a middle-priority task can't block the low-priority task, and thus also block the high priority task.
27+
Semaphores don't have the logic to handle this, in part because Semaphores aren't 'owned' by the task that takes them.
28+
29+
A mutex can also be recursive - if a task that holds the mutex takes it again, it will succeed, and the mutex will be released
30+
for other tasks only when it is given the same number of times that it was taken.
31+
32+
You can check the danger by commenting on the definition of USE_MUTEX which will disable the mutex and present the danger of concurrent access.
33+
34+
35+
# Supported Targets
36+
37+
This example supports all ESP32 SoCs.
38+
39+
## How to Use Example
40+
41+
Flash and observe the serial output.
42+
43+
Comment the `USE_MUTEX` definition, save and flash again and observe the behavior of unprotected access to the shared variable.
44+
45+
* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide).
46+
47+
#### Using Arduino IDE
48+
49+
To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits).
50+
51+
* Before Compile/Verify, select the correct board: `Tools -> Board`.
52+
* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port.
53+
54+
## Example Log Output
55+
56+
The expected output of shared variables protected by mutex demonstrates mutually exclusive access from tasks - they do not interrupt each other and do not rewrite the value before the other task has read it back.
57+
58+
```
59+
Task 0 | Task 1
60+
| Starting
61+
| 0 <- 227
62+
Starting |
63+
| R: 227
64+
227 <- 737 |
65+
R: 737 |
66+
| 737 <- 282
67+
| R: 282
68+
282 <- 267 |
69+
```
70+
71+
The output of unprotected access to shared variable - it happens often that a task is interrupted after writing and before reading the other task write a different value - a corruption occurred!
72+
73+
```
74+
Task 0 | Task 1
75+
| Starting
76+
| 0 <- 333
77+
Starting |
78+
333 <- 620 |
79+
R: 620 |
80+
620 <- 244 |
81+
| R: 244
82+
| Mismatch!
83+
| 244 <- 131
84+
R: 131 |
85+
Mismatch! |
86+
131 <- 584 |
87+
| R: 584
88+
| Mismatch!
89+
| 584 <- 134
90+
| R: 134
91+
| 134 <- 554
92+
R: 554 |
93+
Mismatch! |
94+
554 <- 313 |
95+
```
96+
97+
## Troubleshooting
98+
99+
***Important: Make sure you are using a good quality USB cable and that you have a reliable power source***
100+
101+
## Contribute
102+
103+
To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst)
104+
105+
If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome!
106+
107+
Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else.
108+
109+
## Resources
110+
111+
* Official ESP32 Forum: [Link](https://esp32.com)
112+
* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32)
113+
* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf)
114+
* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf)
115+
* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf)
116+
* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf)
117+
* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com)

Diff for: ‎libraries/ESP32/examples/FreeRTOS/Queue/README.md

+71-75
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,71 @@
1-
# Queue Example
2-
3-
This example demonstrates the basic usage of FreeRTOS Queues which enables tasks to pass data between each other in a secure asynchronous way.
4-
Please refer to other examples in this folder to better understand the usage of tasks.
5-
It is also advised to read the documentation on FreeRTOS web pages:
6-
[https://www.freertos.org/a00106.html](https://www.freertos.org/a00106.html)
7-
8-
This example reads data received on the serial port (sent by the user) pass it via queue to another task which will send it back on Serial Output.
9-
10-
### Theory:
11-
A queue is a simple-to-use data structure (in the most basic way) controlled by `xQueueSend` and `xQueueReceive` functions.
12-
Usually, one task writes into the queue and the other task reads from it.
13-
Usage of queues enables the reading task to yield the CPU until there are data in the queue and therefore not waste precious computation time.
14-
15-
# Supported Targets
16-
17-
This example supports all ESP32 SoCs.
18-
19-
## How to Use Example
20-
21-
Flash and write anything to serial input.
22-
23-
* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide).
24-
25-
#### Using Arduino IDE
26-
27-
To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits).
28-
29-
* Before Compile/Verify, select the correct board: `Tools -> Board`.
30-
* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port.
31-
32-
#### Using Platform IO
33-
34-
* Select the COM port: `Devices` or set the `upload_port` option on the `platformio.ini` file.
35-
36-
## Example Log Output
37-
38-
```
39-
Anything you write will return as echo.
40-
Maximum line length is 63 characters (+ terminating '0').
41-
Anything longer will be sent as a separate line.
42-
43-
```
44-
< Input text "Short input"
45-
46-
``Echo line of size 11: "Short input"``
47-
48-
< Input text "An example of very long input which is longer than default 63 characters will be split."
49-
50-
```
51-
Echo line of size 63: "An example of very long input which is longer than default 63 c"
52-
Echo line of size 24: "haracters will be split."
53-
```
54-
55-
## Troubleshooting
56-
57-
***Important: Make sure you are using a good quality USB cable and that you have a reliable power source***
58-
59-
## Contribute
60-
61-
To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst)
62-
63-
If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome!
64-
65-
Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else.
66-
67-
## Resources
68-
69-
* Official ESP32 Forum: [Link](https://esp32.com)
70-
* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32)
71-
* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf)
72-
* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf)
73-
* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf)
74-
* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf)
75-
* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com)
1+
# Queue Example
2+
3+
This example demonstrates the basic usage of FreeRTOS Queues which enables tasks to pass data between each other in a secure asynchronous way.
4+
Please refer to other examples in this folder to better understand the usage of tasks.
5+
It is also advised to read the documentation on FreeRTOS web pages:
6+
[https://www.freertos.org/a00106.html](https://www.freertos.org/a00106.html)
7+
8+
This example reads data received on the serial port (sent by the user) pass it via queue to another task which will send it back on Serial Output.
9+
10+
### Theory:
11+
A queue is a simple-to-use data structure (in the most basic way) controlled by `xQueueSend` and `xQueueReceive` functions.
12+
Usually, one task writes into the queue and the other task reads from it.
13+
Usage of queues enables the reading task to yield the CPU until there are data in the queue and therefore not waste precious computation time.
14+
15+
# Supported Targets
16+
17+
This example supports all ESP32 SoCs.
18+
19+
## How to Use Example
20+
21+
Flash and write anything to serial input.
22+
23+
* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide).
24+
25+
#### Using Arduino IDE
26+
27+
To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits).
28+
29+
* Before Compile/Verify, select the correct board: `Tools -> Board`.
30+
* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port.
31+
32+
## Example Log Output
33+
34+
```
35+
Anything you write will return as echo.
36+
Maximum line length is 63 characters (+ terminating '0').
37+
Anything longer will be sent as a separate line.
38+
39+
```
40+
< Input text "Short input"
41+
42+
``Echo line of size 11: "Short input"``
43+
44+
< Input text "An example of very long input which is longer than default 63 characters will be split."
45+
46+
```
47+
Echo line of size 63: "An example of very long input which is longer than default 63 c"
48+
Echo line of size 24: "haracters will be split."
49+
```
50+
51+
## Troubleshooting
52+
53+
***Important: Make sure you are using a good quality USB cable and that you have a reliable power source***
54+
55+
## Contribute
56+
57+
To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst)
58+
59+
If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome!
60+
61+
Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else.
62+
63+
## Resources
64+
65+
* Official ESP32 Forum: [Link](https://esp32.com)
66+
* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32)
67+
* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf)
68+
* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf)
69+
* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf)
70+
* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf)
71+
* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com)

0 commit comments

Comments
 (0)