espressif · P-R-O-C-H-Y · Aug 30, 2023 · Sep 1, 2023 · Sep 3, 2023 · Sep 15, 2023
diff --git a/docs/source/api/ledc.rst b/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
 *******************
 

diff --git a/docs/source/api/sigmadelta.rst b/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
 ********************
 

diff --git a/docs/source/api/timer.rst b/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

diff --git a/docs/source/index.rst b/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>

diff --git a/docs/source/migration_guide/2.x_to_3.0.rst b/docs/source/migration_guide/2.x_to_3.0.rst
@@ -0,0 +1,168 @@
+#########################
+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 `I2S API <https://docs.espressif.com/projects/arduino-esp32/en/latest/api/i2s.html>`_.
+
+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 `LEDC API <https://docs.espressif.com/projects/arduino-esp32/en/latest/api/ledc.html>`_.
+
+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
+---
+
+TODO:
+For more information about the new API, check `RMT API <https://docs.espressif.com/projects/arduino-esp32/en/latest/api/rmt.html>`_.
+
+Removed APIs
+************
+
+TODO:
+
+New APIs
+********
+
+TODO:
+
+Changes in APIs
+***************
+
+TODO:
+
+SigmaDelta
+----------
+
+SigmaDelta has been refactored to use the new ESP-IDF driver.
+For more information about the new API, check `SigmaDelta API <https://docs.espressif.com/projects/arduino-esp32/en/latest/api/sigmadelta.html>`_.
+
+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
+`TIMER API <https://docs.espressif.com/projects/arduino-esp32/en/latest/api/timer.html>`_.
+
+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``
+
+Changes in APIs
+***************
+
+* ``uartSetPins`` first input parameter ``uint8_t uart_num`` has been changed to ``uart_t* uart``.
diff --git a/docs/source/migration_guide/migration_guide.rst b/docs/source/migration_guide/migration_guide.rst
@@ -0,0 +1,10 @@
+###############
+Migration Guide
+###############
+
+.. toctree::
+    :caption: Migration Guide:
+    :maxdepth: 1
+    :glob:
+
+    *