[Docs] Add Migration guide + some API updates

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 deinit 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 Guide <migration_guide/migration_guide>
    FAQ <faq>
    Troubleshooting <troubleshooting>
    Contributing <contributing>

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

@@ -0,0 +1,192 @@
+#########################
+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 to version 3.0 of the Arduino ESP32 core. 
+For more information about the changes and new features, check `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.
+
+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 - only returns after sending all data or by timeout. For Async mode use 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`` has 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
+----
+
+Removed APIs
+************
+
+* ``uartDetachPins``
+
+New APIs
+********
+
+* ``uart_get_RxPin`` used to get UART RX pin number.
+* ``uart_get_TxPin`` used to get UART TX pin number.
+
+Changes in APIs
+***************
+
+* ``uartEnd`` input parameter ``uart_t* uart`` has been changed to ``uint8_t uart_num``.
+* ``uartSetMode`` input parameter ``uint8_t mode`` has been changed to ``uart_mode_t mode``.
+* ``uartSetHwFlowCtrlMode`` input parameter ``uint8_t mode`` has been changed to ``uart_hw_flowcontrol_t mode``.

docs/source/migration_guide/migration_guide.rst

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