Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove 3rd party references in code and documentation #10666

Merged
merged 8 commits into from
Dec 3, 2024
Merged
Show file tree
Hide file tree
Changes from 6 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/Issue-report.yml
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ body:
attributes:
label: IDE Name
description: What IDE are you using?
placeholder: eg. Arduino IDE, PlatformIO, Sloeber...
placeholder: eg. Arduino IDE, VSCode, Sloeber...
validations:
required: true
- type: input
Expand Down
Binary file removed docs/_static/logo_pio.png
Binary file not shown.
11 changes: 5 additions & 6 deletions docs/en/getting_started.rst
Original file line number Diff line number Diff line change
Expand Up @@ -78,14 +78,13 @@ Supported IDEs

Here is the list of supported IDE for Arduino ESP32 support integration.

+-------------------+-------------------+
| |arduino-logo| | |pio-logo| |
+-------------------+-------------------+
| Arduino IDE | PlatformIO |
+-------------------+-------------------+
+-------------------+
| |arduino-logo| |
+-------------------+
| Arduino IDE |
+-------------------+

.. |arduino-logo| image:: ../_static/logo_arduino.png
.. |pio-logo| image:: ../_static/logo_pio.png

See `Installing Guides <installing.html>`_ for more details on how to install the Arduino ESP32 support.

Expand Down
87 changes: 0 additions & 87 deletions docs/en/installing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -63,92 +63,6 @@ To start the installation process using the Boards Manager, follow these steps:

- Restart Arduino IDE.

Installing using PlatformIO
---------------------------

.. figure:: ../_static/logo_pio.png
:align: center
:width: 200
:figclass: align-center

PlatformIO is a professional collaborative platform for embedded development. It has out-of-the-box support for ESP32 SoCs and allows working with Arduino ESP32 as well as ESP-IDF from Espressif without changing your development environment. PlatformIO includes lots of instruments for the most common development tasks such as debugging, unit testing, and static code analysis.

.. warning:: Integration of the Arduino Core ESP32 project in PlatformIO is maintained by PlatformIO developers. Arduino Core ESP32 Project Team cannot support PlatformIO-specific issues. Please report these issues in official `PlatformIO repositories <https://github.com/platformio>`_.

A detailed overview of the PlatformIO ecosystem and its philosophy can be found in `the official documentation <https://docs.platformio.org/en/latest/core/index.html>`_.

PlatformIO can be used in two flavors:

- `PlatformIO IDE <https://platformio.org/platformio-ide>`_ is a toolset for embedded C/C++ development available on Windows, macOS and Linux platforms

- `PlatformIO Core (CLI) <https://docs.platformio.org/en/latest/core/index.html>`_ is a command-line tool that consists of a multi-platform build system, platform and library managers and other integration components. It can be used with a variety of code development environments and allows integration with cloud platforms and web services

To install PlatformIO, you can follow this Getting Started, provided at `docs.platformio.org`_.

Using the stable code
*********************

.. note::
A detailed overview of supported development boards, examples and frameworks can be found on `the official Espressif32 dev-platform page <https://registry.platformio.org/platforms/platformio/espressif32>`_ in the PlatformIO Registry.

The most reliable and easiest way to get started is to use the latest stable version of the ESP32 development platform that passed all tests/verifications and can be used in production.

Create a new project and select one of the available boards. You can change after by changing the `platformio.ini <https://docs.platformio.org/en/latest/projectconf/index.html>`_ file.

- For ESP32

.. code-block:: bash

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino

- For ESP32-S2 (ESP32-S2-Saola-1 board)

.. code-block:: bash

[env:esp32-s2-saola-1]
platform = espressif32
board = esp32-s2-saola-1
framework = arduino

- For ESP32-C3 (ESP32-C3-DevKitM-1 board)

.. code-block:: bash

[env:esp32-c3-devkitm-1]
platform = espressif32
board = esp32-c3-devkitm-1
framework = arduino

How to update to the latest code
********************************

To test the latest Arduino ESP32, you need to change your project *platformio.ini* accordingly.
The following configuration uses the upstream version of the Espressif development platform and the latest Arduino core directly from the Espressif GitHub repository:

.. code-block:: bash

[env:esp32-c3-devkitm-1]
platform = https://github.com/platformio/platform-espressif32.git
board = esp32-c3-devkitm-1
framework = arduino
platform_packages =
framework-arduinoespressif32 @ https://github.com/espressif/arduino-esp32#master


To get more information about PlatformIO, see the following links:

- `PlatformIO Core (CLI) <https://docs.platformio.org/en/latest/core/index.html>`_

- `PlatformIO Home <https://docs.platformio.org/en/latest/home/index.html>`_

- `Tutorials and Examples <https://docs.platformio.org/en/latest/tutorials/index.html>`_

- `Library Management <https://docs.platformio.org/en/latest/librarymanager/index.html>`_


Windows (manual installation)
-----------------------------

Expand Down Expand Up @@ -360,4 +274,3 @@ Where ``~/Documents/Arduino`` represents your sketch book location as per "Ardui
- Restart Arduino IDE.

.. _Arduino.cc: https://www.arduino.cc/en/Main/Software
.. _docs.platformio.org: https://docs.platformio.org/en/latest/integration/ide/pioide.html
3 changes: 1 addition & 2 deletions docs/en/tutorials/blink.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Introduction

This is the interactive blink tutorial using `Wokwi`_. For this tutorial, you don't need the ESP32 board or the Arduino toolchain.

.. note:: If you don't want to use this tutorial with the simulation, you can copy and paste the :ref:`blink_example_code` from `Wokwi`_ editor and use it on the `Arduino IDE`_ or `PlatformIO`_.
.. note:: If you don't want to use this tutorial with the simulation, you can copy and paste the :ref:`blink_example_code` from `Wokwi`_ editor and use it on the `Arduino IDE`.

About this Tutorial
-------------------
Expand Down Expand Up @@ -109,5 +109,4 @@ Resources

.. _ESP32 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf
.. _Wokwi: https://wokwi.com/
.. _PlatformIO: https://docs.espressif.com/projects/arduino-esp32/en/latest/installing.html#platformio
.. _Arduino IDE: https://docs.espressif.com/projects/arduino-esp32/en/latest/installing.html#installing-using-boards-manager
Original file line number Diff line number Diff line change
Expand Up @@ -62,10 +62,6 @@ To get more information about the Espressif boards see [Espressif Development Ki
* Before Compile/Verify, select the correct board: `Tools -> Board`.
* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port.

#### Using Platform IO

* Select the COM port: `Devices` or set the `upload_port` option on the `platformio.ini` file.

## Troubleshooting

***Important: Make sure you are using a good quality USB cable and that you have a reliable power source***
Expand Down
238 changes: 117 additions & 121 deletions libraries/ESP32/examples/FreeRTOS/Mutex/README.md
Original file line number Diff line number Diff line change
@@ -1,121 +1,117 @@
# Mutex Example

This example demonstrates the basic usage of FreeRTOS Mutually Exclusive Locks (Mutex) for securing access to shared resources in multi-threading.
Please refer to other examples in this folder to better understand the usage of tasks.
It is also advised to read the documentation on FreeRTOS web pages:
https://www.freertos.org/a00106.html

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.
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.
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.
Watch the writes and read in secure mode when using the mutex (default) as the results are as you would expect them.
Then try to comment the USE_MUTEX and watch again - there will be a lot of mismatches!

### Theory:
Mutex is a specialized version of Semaphore (please see the Semaphore example for more info).
In essence, the mutex is a variable whose value determines if the mute is taken (locked) or given (unlocked).
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
which will write to this variable and when the previous task runs again it will read something different.

Mutexes and binary semaphores are very similar but have some subtle differences:
Mutexes include a priority inheritance mechanism, whereas binary semaphores do not.
This makes binary semaphores the better choice for implementing synchronization (between tasks or between tasks and an interrupt), and mutexes the better
choice for implementing simple mutual exclusion.
What is priority inheritance?
If a low-priority task holds the Mutex but gets interrupted by a Higher priority task, which
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.
Semaphores don't have the logic to handle this, in part because Semaphores aren't 'owned' by the task that takes them.

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
for other tasks only when it is given the same number of times that it was taken.

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.


# Supported Targets

This example supports all ESP32 SoCs.

## How to Use Example

Flash and observe the serial output.

Comment the `USE_MUTEX` definition, save and flash again and observe the behavior of unprotected access to the shared variable.

* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide).

#### Using Arduino IDE

To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits).

* Before Compile/Verify, select the correct board: `Tools -> Board`.
* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port.

#### Using Platform IO

* Select the COM port: `Devices` or set the `upload_port` option on the `platformio.ini` file.

## Example Log Output

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.

```
Task 0 | Task 1
| Starting
| 0 <- 227
Starting |
| R: 227
227 <- 737 |
R: 737 |
| 737 <- 282
| R: 282
282 <- 267 |
```

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!

```
Task 0 | Task 1
| Starting
| 0 <- 333
Starting |
333 <- 620 |
R: 620 |
620 <- 244 |
| R: 244
| Mismatch!
| 244 <- 131
R: 131 |
Mismatch! |
131 <- 584 |
| R: 584
| Mismatch!
| 584 <- 134
| R: 134
| 134 <- 554
R: 554 |
Mismatch! |
554 <- 313 |
```

## Troubleshooting

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

## Contribute

To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst)

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!

Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else.

## Resources

* Official ESP32 Forum: [Link](https://esp32.com)
* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32)
* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf)
* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf)
* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf)
* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf)
* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com)
# Mutex Example

This example demonstrates the basic usage of FreeRTOS Mutually Exclusive Locks (Mutex) for securing access to shared resources in multi-threading.
Please refer to other examples in this folder to better understand the usage of tasks.
It is also advised to read the documentation on FreeRTOS web pages:
https://www.freertos.org/a00106.html

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.
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.
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.
Watch the writes and read in secure mode when using the mutex (default) as the results are as you would expect them.
Then try to comment the USE_MUTEX and watch again - there will be a lot of mismatches!

### Theory:
Mutex is a specialized version of Semaphore (please see the Semaphore example for more info).
In essence, the mutex is a variable whose value determines if the mute is taken (locked) or given (unlocked).
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
which will write to this variable and when the previous task runs again it will read something different.

Mutexes and binary semaphores are very similar but have some subtle differences:
Mutexes include a priority inheritance mechanism, whereas binary semaphores do not.
This makes binary semaphores the better choice for implementing synchronization (between tasks or between tasks and an interrupt), and mutexes the better
choice for implementing simple mutual exclusion.
What is priority inheritance?
If a low-priority task holds the Mutex but gets interrupted by a Higher priority task, which
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.
Semaphores don't have the logic to handle this, in part because Semaphores aren't 'owned' by the task that takes them.

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
for other tasks only when it is given the same number of times that it was taken.

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.


# Supported Targets

This example supports all ESP32 SoCs.

## How to Use Example

Flash and observe the serial output.

Comment the `USE_MUTEX` definition, save and flash again and observe the behavior of unprotected access to the shared variable.

* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide).

#### Using Arduino IDE

To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits).

* Before Compile/Verify, select the correct board: `Tools -> Board`.
* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port.

## Example Log Output

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.

```
Task 0 | Task 1
| Starting
| 0 <- 227
Starting |
| R: 227
227 <- 737 |
R: 737 |
| 737 <- 282
| R: 282
282 <- 267 |
```

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!

```
Task 0 | Task 1
| Starting
| 0 <- 333
Starting |
333 <- 620 |
R: 620 |
620 <- 244 |
| R: 244
| Mismatch!
| 244 <- 131
R: 131 |
Mismatch! |
131 <- 584 |
| R: 584
| Mismatch!
| 584 <- 134
| R: 134
| 134 <- 554
R: 554 |
Mismatch! |
554 <- 313 |
```

## Troubleshooting

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

## Contribute

To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst)

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!

Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else.

## Resources

* Official ESP32 Forum: [Link](https://esp32.com)
* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32)
* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf)
* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf)
* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf)
* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf)
* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com)
Loading
Loading