[Docs] Add Migration guide + some API updates (espressif#8716)

* Update sigmadelta docs

* minor docs updates

* Added migration guide to docs

* Update Introduction to migration guide

* update formatting

* fix typo

* Add BLE breaking changes

* Apply changes from code review by @lucasssvaz

Co-authored-by: Lucas Saavedra Vaz <lucassvaz@yahoo.com.br>

* uart migration

* added RMT and UART + links fix

* fix renamed BLE examples

* Apply suggestions from code review by @lucasssvaz

Co-authored-by: Lucas Saavedra Vaz <lucassvaz@yahoo.com.br>

* Change UART driver changes to HardwareSerial changes

* update sigmadelta

* BLE and examples update + rename

---------

Co-authored-by: Lucas Saavedra Vaz <lucassvaz@yahoo.com.br>

Author: P-R-O-C-H-Y

docs/source/api/ble.rst

@@ -15,13 +15,13 @@ To get started with BLE, you can try:
 BLE Scan
 ********
 
-.. literalinclude:: ../../../libraries/BLE/examples/BLE_scan/BLE_scan.ino
+.. literalinclude:: ../../../libraries/BLE/examples/Scan/Scan.ino
     :language: arduino
 
 BLE UART
 ********
 
-.. literalinclude:: ../../../libraries/BLE/examples/BLE_uart/BLE_uart.ino
+.. literalinclude:: ../../../libraries/BLE/examples/UART/UART.ino
     :language: arduino
 
 Complete list of `BLE examples <https://github.com/espressif/arduino-esp32/tree/master/libraries/BLE/examples>`_. 

docs/source/api/ledc.rst

@@ -17,6 +17,7 @@ ESP32-S2  8
 ESP32-S3  8
 ESP32-C3  6
 ESP32-C6  6
+ESP32-H2  6
 ========= =======================
 
 Arduino-ESP32 LEDC API
@@ -125,10 +126,13 @@ This function is used to detach the pin from LEDC.
 
 .. code-block:: arduino
 
-    void ledcDetach(uint8_t pin);
+    bool ledcDetach(uint8_t pin);
 
 * ``pin`` select LEDC pin.
 
+This function returns ``true`` if detaching was successful.
+If ``false`` is returned, an error occurred and the pin was not detached.
+
 ledcChangeFrequency
 *******************
 

docs/source/api/sigmadelta.rst

@@ -14,67 +14,61 @@ ESP32 SoC Number of SigmaDelta channels
 ========= =============================
 ESP32     8
 ESP32-S2  8
-ESP32-C3  4
 ESP32-S3  8
+ESP32-C3  4
+ESP32-C6  4
+ESP32-H2  4
 ========= =============================
 
 Arduino-ESP32 SigmaDelta API
 ----------------------------
 
-sigmaDeltaSetup
-***************
+sigmaDeltaAttach
+****************
 
-This function is used to setup the SigmaDelta channel frequency and resolution.
+This function is used to set up the SigmaDelta channel with the selected frequency and attach it to the selected pin.
 
 .. code-block:: arduino
 
-    uint32_t sigmaDeltaSetup(uint8_t pin, uint8_t channel, uint32_t freq);
+    bool sigmaDeltaAttach(uint8_t pin, uint32_t freq);
 
 * ``pin`` select GPIO pin.
-* ``channel`` select SigmaDelta channel.
 * ``freq`` select frequency.
 
   * range is 1-14 bits (1-20 bits for ESP32).
 
-This function will return ``frequency`` configured for the SigmaDelta channel.
-If ``0`` is returned, error occurs and the SigmaDelta channel was not configured.
+This function returns ``true`` if the configuration was successful.
+If ``false`` is returned, an error occurred and the SigmaDelta channel was not configured.
 
 sigmaDeltaWrite
 ***************
 
-This function is used to set duty for the SigmaDelta channel.
-
-.. code-block:: arduino
-
-    void sigmaDeltaWrite(uint8_t channel, uint8_t duty);
-
-* ``channel`` select SigmaDelta channel.
-* ``duty`` select duty to be set for selected channel.
-
-sigmaDeltaRead
-**************
-
-This function is used to get configured duty for the SigmaDelta channel.
+This function is used to set duty for the SigmaDelta pin.
 
 .. code-block:: arduino
 
-    uint8_t sigmaDeltaRead(uint8_t channel)
+    bool sigmaDeltaWrite(uint8_t pin, uint8_t duty);
 
-* ``channnel`` select SigmaDelta channel.
+* ``pin`` selects the GPIO pin.
+* ``duty`` selects the duty to be set for selected pin.
 
-This function will return ``duty`` configured for the selected SigmaDelta channel.
+This function returns ``true`` if setting the duty was successful.
+If ``false`` is returned, error occurs and duty was not set.
 
-sigmaDeltaDetachPin
-*******************
+sigmaDeltaDetach
+****************
 
-This function is used to detach pin from SigmaDelta.
+This function is used to detach a pin from SigmaDelta and deinitialize the channel that was attached to the pin.
 
 .. code-block:: arduino
 
-    void sigmaDeltaDetachPin(uint8_t pin);
+    bool sigmaDeltaDetach(uint8_t pin);
 
 * ``pin`` select GPIO pin.
 
+This function returns ``true`` if detaching was successful.
+If ``false`` is returned, an error occurred and pin was not detached.
+
 Example Applications
 ********************
 

docs/source/api/timer.rst

@@ -14,8 +14,10 @@ ESP32 SoC Number of timers
 ========= ================
 ESP32     4
 ESP32-S2  4
-ESP32-C3  2
 ESP32-S3  4
+ESP32-C3  2
+ESP32-C6  2
+ESP32-H2  2
 ========= ================
 
 Arduino-ESP32 Timer API

docs/source/index.rst

@@ -16,6 +16,7 @@ Here you will find all the relevant information about the project.
    Guides <guides/guides>
    Tutorials <tutorials/tutorials>
    Advanced Utilities <advanced_utils>
+   Migration Guides <migration_guides/migration_guides>
    FAQ <faq>
    Troubleshooting <troubleshooting>
    Contributing <contributing>

docs/source/migration_guides/2.x_to_3.0.rst

@@ -0,0 +1,196 @@
+#########################
+Migration from 2.x to 3.0
+#########################
+
+Introduction
+------------
+
+This is a guide to highlight **breaking changes** in the API and to help the migration of projects from versions 2.X (based on ESP-IDF 4.4) to version 3.0 (based on ESP-IDF 5.1) of the Arduino ESP32 core.
+
+All the examples on the version 3.0.0 were updated to be compatible to the new API. The old examples from the versions below 3.0.0 will be not compatible with the version 3.0.0 or newer releases.
+
+For more information about all changes and new features, check project `RELEASE NOTES <https://github.com/espressif/arduino-esp32/releases>`_.
+
+ADC
+---
+
+Removed APIs
+************
+
+* ``analogSetClockDiv``
+* ``adcAttachPin``
+* ``analogSetVRefPin``
+
+BLE
+---
+
+Changes in APIs
+***************
+
+* Changed APIs return and parameter type from ``std::string`` to Arduino style ``String``.
+* Changed UUID data type from ``uint16_t`` to ``BLEUUID`` class.
+* ``BLEScan::start`` and ``BLEScan::getResults`` methods return type changed from ``BLEScanResults`` to ``BLEScanResults*``.
+
+Hall Sensor
+-----------
+
+Hall sensor is no longer supported.
+
+Removed APIs
+************
+
+* ``hallRead``
+
+I2S
+---
+
+The I2S driver has been completely redesigned and refactored to use the new ESP-IDF driver. 
+For more information about the new API, check :doc:`/api/i2s`.
+
+LEDC
+----
+
+The LEDC API has been changed in order to support the Peripheral Manager and make it easier to use, as LEDC channels are now automatically assigned to pins.
+For more information about the new API, check :doc:`/api/ledc`.
+
+Removed APIs
+************
+
+* ``ledcSetup``
+* ``ledcAttachPin``
+
+New APIs
+********
+
+* ``ledcAttach`` used to set up the LEDC pin (merged ``ledcSetup`` and ``ledcAttachPin`` functions).
+* ``timerGetFrequency`` used to get the actual frequency of the timer.
+* ``timerAttachInterruptArg`` used to attach the interrupt to a timer using arguments.
+
+Changes in APIs
+***************
+
+* ``ledcDetachPin`` renamed to ``ledcDetach``.
+* In all functions, input parameter ``channel`` has been changed to ``pin``.
+
+RMT
+---
+
+For more information about the new API, check :doc:`/api/rmt`.
+
+Removed APIs
+************
+
+* ``_rmtDumpStatus``
+* ``rmtSetTick``
+* ``rmtWriteBlocking``
+* ``rmtEnd``
+* ``rmtBeginReceive``
+* ``rmtReadData``
+
+New APIs
+********
+
+* ``rmtWriteAsync``
+* ``rmtTransmitCompleted``
+* ``rmtSetRxMinThreshold``
+
+
+Changes in APIs
+***************
+
+* In all functions, input parameter ``rmt_obj_t* rmt`` has been changed to ``int pin``.
+* ``rmtInit`` return parameter changed to bool.
+* ``rmtInit`` input parameter ``bool tx_not_rx`` has been changed to ``rmt_ch_dir_t channel_direction``.
+* ``rmtInit`` new input parameter ``uint32_t frequency_Hz`` to set frequency of RMT channel (as function ``rmtSetTick`` was removed).
+* ``rmtWrite`` now sending data in blocking mode. It only returns after sending all data or through a timeout. For Async mode use the new ``rmtWriteAsync`` function.
+* ``rmtWrite`` new input parameter ``uint32_t timeout_ms``.
+* ``rmtLoop`` renamed to ``rmtWriteLooping``.
+* ``rmtRead`` input parameters changed to ``int pin, rmt_data_t* data, size_t *num_rmt_symbols, uint32_t timeout_ms``.
+* ``rmtReadAsync`` input parameters changed to ``int pin, rmt_data_t* data, size_t *num_rmt_symbols``.
+* ``rmtSetRxThreshold`` renamed to ``rmtSetRxMaxThreshold`` and input parameter ``uint32_t value`` has been changed to ``uint16_t idle_thres_ticks``.
+* ``rmtSetCarrier`` input parameters ``uint32_t low, uint32_t high`` have been changed to ``uint32_t frequency_Hz, float duty_percent``.
+
+SigmaDelta
+----------
+
+SigmaDelta has been refactored to use the new ESP-IDF driver.
+For more information about the new API, check :doc:`/api/sigmadelta`.
+
+Removed APIs
+************
+
+* ``sigmaDeltaSetup``
+* ``sigmaDeltaRead``
+
+New APIs
+********
+
+* ``sigmaDeltaAttach`` used to set up the SigmaDelta pin (channel is acquired automatically).
+* ``timerGetFrequency`` used to get the actual frequency of the timer.
+* ``timerAttachInterruptArg`` used to attach the interrupt to a timer using arguments.
+
+Changes in APIs
+***************
+
+* ``sigmaDeltaDetachPin`` renamed to ``sigmaDeltaDetach``.
+* ``sigmaDeltaWrite`` input parameter ``channel`` has been changed to ``pin``.
+
+Timer
+-----
+
+Timer has been refactored to use the new ESP-IDF driver and its API got simplified. For more information about the new API check :doc:`/api/timer`.
+
+Removed APIs
+************
+
+* ``timerGetConfig``
+* ``timerSetConfig``
+* ``timerSetDivider``
+* ``timerSetCountUp``
+* ``timerSetAutoReload``
+* ``timerGetDivider``
+* ``timerGetCountUp``
+* ``timerGetAutoReload``
+* ``timerAlarmEnable``
+* ``timerAlarmDisable``
+* ``timerAlarmWrite``
+* ``timerAlarmEnabled``
+* ``timerAlarmRead``
+* ``timerAlarmReadMicros``
+* ``timerAlarmReadSeconds``
+* ``timerAttachInterruptFlag``
+
+New APIs
+********
+
+* ``timerAlarm`` used to set up Alarm for the timer and enable it automatically (merged ``timerAlarmWrite`` and ``timerAlarmEnable`` functions).
+* ``timerGetFrequency`` used to get the actual frequency of the timer.
+* ``timerAttachInterruptArg`` used to attach the interrupt to a timer using arguments.
+
+Changes in APIs
+***************
+
+* ``timerBegin`` has now only 1 parameter (frequency). There is an automatic calculation of the divider using different clock sources
+  to achieve the selected frequency.
+* ``timerAttachInterrupt`` has now only 2 parameters. The ``edge`` parameter has been removed.
+
+UART (HardwareSerial)
+---------------------
+
+Changes in APIs
+***************
+
+* ``setHwFlowCtrlMode`` input parameter ``uint8_t mode`` has been changed to ``SerialHwFlowCtrl mode``.
+* ``setMode`` input parameter ``uint8_t mode`` has been changed to ``SerialMode mode``.
+
+Functional changes
+******************
+
+* It is now possible to detach UART0 pins by calling ``end()`` with no previous call of ``begin()``.
+* It is now possible to call ``setPins()`` before ``begin()`` or in any order.
+* ``setPins(``) will detach any previous pins that have been changed.
+* ``begin(baud, rx, tx)`` will detach any previous attached pins.
+* ``setPins()`` or ``begin(baud, rx, tx)`` when called at first, will detach console RX0/TX0, attached in boot.
+* Any pin set as -1 in ``begin()`` or ``setPins()`` won't be changed nor detached.
+* ``begin(baud)`` will not change any pins that have been set before this call, through a previous ``begin(baud, rx, tx)`` or ``setPin()``.
+* If the application only uses RX or TX, ``begin(baud, -1, tx)`` or ``begin(baud, rx)`` will change only the assigned pin and keep the other unchanged.

docs/source/migration_guides/migration_guides.rst

@@ -0,0 +1,10 @@
+################
+Migration Guides
+################
+
+.. toctree::
+    :caption: Migration Guides:
+    :maxdepth: 1
+    :glob:
+
+    *