diff --git a/docs/source/api/ledc.rst b/docs/source/api/ledc.rst index 330ad07cff7..b69f581f5bf 100644 --- 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 index 537c5894d6c..e92f4afaf17 100644 --- 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 index f20aa624740..07acd4d502a 100644 --- 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 index f504dc342e0..0ebdbfeaa5c 100644 --- 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 Tutorials Advanced Utilities + Migration Guide FAQ Troubleshooting 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 new file mode 100644 index 00000000000..1c9ecf0472f --- /dev/null +++ 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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 `_. + +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 new file mode 100644 index 00000000000..2144da52d01 --- /dev/null +++ b/docs/source/migration_guide/migration_guide.rst @@ -0,0 +1,10 @@ +############### +Migration Guide +############### + +.. toctree:: + :caption: Migration Guide: + :maxdepth: 1 + :glob: + + * diff --git a/package/package_esp32_index.template.json b/package/package_esp32_index.template.json index c3588c2790b..10340fe3018 100644 --- a/package/package_esp32_index.template.json +++ b/package/package_esp32_index.template.json @@ -39,7 +39,7 @@ { "packager": "esp32", "name": "esp32-arduino-libs", - "version": "idf-release_v5.1-f0437b945f" + "version": "idf-release_v5.1-cb174b0fe1" }, { "packager": "esp32", @@ -97,63 +97,63 @@ "tools": [ { "name": "esp32-arduino-libs", - "version": "idf-release_v5.1-f0437b945f", + "version": "idf-release_v5.1-cb174b0fe1", "systems": [ { "host": "i686-mingw32", - "url": "https://github.com/espressif/esp32-arduino-libs/releases/download/0.0.0-alpha/esp32-arduino-libs-0.0.0-alpha.zip", - "archiveFileName": "esp32-arduino-libs-0.0.0-alpha.zip", - "checksum": "SHA-256:096aa276bfe07375f1701f84d05039cb439f48ba1a607676fe27d2807037389a", - "size": "333176544" + "url": "https://codeload.github.com/espressif/esp32-arduino-libs/zip/0a2dc510a65c2df6ca1269fed01b1ee7d09f2a56", + "archiveFileName": "esp32-arduino-libs-0a2dc510a65c2df6ca1269fed01b1ee7d09f2a56.zip", + "checksum": "SHA-256:e6670d7f986a351a6da4a53255457a6f7ab7c13d3f5ddbea790e0d7fc025c740", + "size": "362192082" }, { "host": "x86_64-mingw32", - "url": "https://github.com/espressif/esp32-arduino-libs/releases/download/0.0.0-alpha/esp32-arduino-libs-0.0.0-alpha.zip", - "archiveFileName": "esp32-arduino-libs-0.0.0-alpha.zip", - "checksum": "SHA-256:096aa276bfe07375f1701f84d05039cb439f48ba1a607676fe27d2807037389a", - "size": "333176544" + "url": "https://codeload.github.com/espressif/esp32-arduino-libs/zip/0a2dc510a65c2df6ca1269fed01b1ee7d09f2a56", + "archiveFileName": "esp32-arduino-libs-0a2dc510a65c2df6ca1269fed01b1ee7d09f2a56.zip", + "checksum": "SHA-256:e6670d7f986a351a6da4a53255457a6f7ab7c13d3f5ddbea790e0d7fc025c740", + "size": "362192082" }, { "host": "arm64-apple-darwin", - "url": "https://github.com/espressif/esp32-arduino-libs/releases/download/0.0.0-alpha/esp32-arduino-libs-0.0.0-alpha.zip", - "archiveFileName": "esp32-arduino-libs-0.0.0-alpha.zip", - "checksum": "SHA-256:096aa276bfe07375f1701f84d05039cb439f48ba1a607676fe27d2807037389a", - "size": "333176544" + "url": "https://codeload.github.com/espressif/esp32-arduino-libs/zip/0a2dc510a65c2df6ca1269fed01b1ee7d09f2a56", + "archiveFileName": "esp32-arduino-libs-0a2dc510a65c2df6ca1269fed01b1ee7d09f2a56.zip", + "checksum": "SHA-256:e6670d7f986a351a6da4a53255457a6f7ab7c13d3f5ddbea790e0d7fc025c740", + "size": "362192082" }, { "host": "x86_64-apple-darwin", - "url": "https://github.com/espressif/esp32-arduino-libs/releases/download/0.0.0-alpha/esp32-arduino-libs-0.0.0-alpha.zip", - "archiveFileName": "esp32-arduino-libs-0.0.0-alpha.zip", - "checksum": "SHA-256:096aa276bfe07375f1701f84d05039cb439f48ba1a607676fe27d2807037389a", - "size": "333176544" + "url": "https://codeload.github.com/espressif/esp32-arduino-libs/zip/0a2dc510a65c2df6ca1269fed01b1ee7d09f2a56", + "archiveFileName": "esp32-arduino-libs-0a2dc510a65c2df6ca1269fed01b1ee7d09f2a56.zip", + "checksum": "SHA-256:e6670d7f986a351a6da4a53255457a6f7ab7c13d3f5ddbea790e0d7fc025c740", + "size": "362192082" }, { "host": "x86_64-pc-linux-gnu", - "url": "https://github.com/espressif/esp32-arduino-libs/releases/download/0.0.0-alpha/esp32-arduino-libs-0.0.0-alpha.zip", - "archiveFileName": "esp32-arduino-libs-0.0.0-alpha.zip", - "checksum": "SHA-256:096aa276bfe07375f1701f84d05039cb439f48ba1a607676fe27d2807037389a", - "size": "333176544" + "url": "https://codeload.github.com/espressif/esp32-arduino-libs/zip/0a2dc510a65c2df6ca1269fed01b1ee7d09f2a56", + "archiveFileName": "esp32-arduino-libs-0a2dc510a65c2df6ca1269fed01b1ee7d09f2a56.zip", + "checksum": "SHA-256:e6670d7f986a351a6da4a53255457a6f7ab7c13d3f5ddbea790e0d7fc025c740", + "size": "362192082" }, { "host": "i686-pc-linux-gnu", - "url": "https://github.com/espressif/esp32-arduino-libs/releases/download/0.0.0-alpha/esp32-arduino-libs-0.0.0-alpha.zip", - "archiveFileName": "esp32-arduino-libs-0.0.0-alpha.zip", - "checksum": "SHA-256:096aa276bfe07375f1701f84d05039cb439f48ba1a607676fe27d2807037389a", - "size": "333176544" + "url": "https://codeload.github.com/espressif/esp32-arduino-libs/zip/0a2dc510a65c2df6ca1269fed01b1ee7d09f2a56", + "archiveFileName": "esp32-arduino-libs-0a2dc510a65c2df6ca1269fed01b1ee7d09f2a56.zip", + "checksum": "SHA-256:e6670d7f986a351a6da4a53255457a6f7ab7c13d3f5ddbea790e0d7fc025c740", + "size": "362192082" }, { "host": "aarch64-linux-gnu", - "url": "https://github.com/espressif/esp32-arduino-libs/releases/download/0.0.0-alpha/esp32-arduino-libs-0.0.0-alpha.zip", - "archiveFileName": "esp32-arduino-libs-0.0.0-alpha.zip", - "checksum": "SHA-256:096aa276bfe07375f1701f84d05039cb439f48ba1a607676fe27d2807037389a", - "size": "333176544" + "url": "https://codeload.github.com/espressif/esp32-arduino-libs/zip/0a2dc510a65c2df6ca1269fed01b1ee7d09f2a56", + "archiveFileName": "esp32-arduino-libs-0a2dc510a65c2df6ca1269fed01b1ee7d09f2a56.zip", + "checksum": "SHA-256:e6670d7f986a351a6da4a53255457a6f7ab7c13d3f5ddbea790e0d7fc025c740", + "size": "362192082" }, { "host": "arm-linux-gnueabihf", - "url": "https://github.com/espressif/esp32-arduino-libs/releases/download/0.0.0-alpha/esp32-arduino-libs-0.0.0-alpha.zip", - "archiveFileName": "esp32-arduino-libs-0.0.0-alpha.zip", - "checksum": "SHA-256:096aa276bfe07375f1701f84d05039cb439f48ba1a607676fe27d2807037389a", - "size": "333176544" + "url": "https://codeload.github.com/espressif/esp32-arduino-libs/zip/0a2dc510a65c2df6ca1269fed01b1ee7d09f2a56", + "archiveFileName": "esp32-arduino-libs-0a2dc510a65c2df6ca1269fed01b1ee7d09f2a56.zip", + "checksum": "SHA-256:e6670d7f986a351a6da4a53255457a6f7ab7c13d3f5ddbea790e0d7fc025c740", + "size": "362192082" } ] },