Skip to content

Commit 723ad19

Browse files
pre-commit-ci-lite[bot]pre-commit-ci-lite[bot]
authored
ci(pre-commit): Apply automatic fixes
1 parent 47c6146 commit 723ad19

File tree

4 files changed

+384
-384
lines changed

4 files changed

+384
-384
lines changed

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

+117-117
Original file line numberDiff line numberDiff line change
@@ -1,117 +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-
## 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)
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-71
Original file line numberDiff line numberDiff line change
@@ -1,71 +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-
## 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)
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)