From fe7d56512b65d09c2dd1450b0a920b4efcb81a79 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Procha=CC=81zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Thu, 13 Jul 2023 15:16:16 +0200 Subject: [PATCH 01/15] Update sigmadelta docs --- docs/source/api/sigmadelta.rst | 50 +++++++++++++++------------------- 1 file changed, 22 insertions(+), 28 deletions(-) diff --git a/docs/source/api/sigmadelta.rst b/docs/source/api/sigmadelta.rst index 537c5894d6c..f9e30c4ca81 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 setup the SigmaDelta channel with selected frequency and attach it to 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 will return ``true`` if configuration is successful. +If ``false`` is returned, error occurs and the SigmaDelta channel was not configured. sigmaDeltaWrite *************** -This function is used to set duty for the SigmaDelta channel. +This function is used to set duty for the SigmaDelta pin. .. 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. + bool sigmaDeltaWrite(uint8_t pin, uint8_t duty); -.. code-block:: arduino - - uint8_t sigmaDeltaRead(uint8_t channel) - -* ``channnel`` select SigmaDelta channel. +* ``pin`` select GPIO pin. +* ``duty`` select duty to be set for selected pin. -This function will return ``duty`` configured for the selected SigmaDelta channel. +This function will return ``true`` if setting duty is 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 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 will return ``true`` if detaching is successful. +If ``false`` is returned, error occurs and pin is not detached. + Example Applications ******************** From c9df9066162017bef1ad48cf7a50b6a9c3dd4254 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Procha=CC=81zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Thu, 13 Jul 2023 15:16:45 +0200 Subject: [PATCH 02/15] minor docs updates --- docs/source/api/ledc.rst | 6 +++++- docs/source/api/timer.rst | 4 +++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/source/api/ledc.rst b/docs/source/api/ledc.rst index 330ad07cff7..a3515b480c5 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 will return ``true`` if detaching is successful. +If ``false`` is returned, error occurs and pin is not detached. + ledcChangeFrequency ******************* 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 From 2306cb1302a3c85eee8343eb187bb03ced5cfcbf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Procha=CC=81zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Thu, 13 Jul 2023 15:16:59 +0200 Subject: [PATCH 03/15] Added migration guide to docs --- docs/source/index.rst | 1 + docs/source/migration_guide/2.x_to_3.0.rst | 174 ++++++++++++++++++ .../migration_guide/migration_guide.rst | 10 + 3 files changed, 185 insertions(+) create mode 100644 docs/source/migration_guide/2.x_to_3.0.rst create mode 100644 docs/source/migration_guide/migration_guide.rst 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..b2ebb75c667 --- /dev/null +++ b/docs/source/migration_guide/2.x_to_3.0.rst @@ -0,0 +1,174 @@ +######################### +Migration from 2.x to 3.0 +######################### + +Introduction +------------ + +This is a guideline for the Arduino ESP32 project documentation. The idea for this guideline is to show how to start collaborating on the project. + +The guideline works to give you the directions and to keep the documentation more concise, helping users to better understand the structure. + +Breaking changes in API +----------------------- + +We all know how important documentation is. This project is no different. + +ADC +*** + +Removed APIs +^^^^^^^^^^^^ + +* ``analogSetClockDiv`` +* ``adcAttachPin`` +* ``analogSetVRefPin`` + + +Hall Sensor +*********** + +Hall sensor is no longer supported. + +Removed APIs +^^^^^^^^^^^^ + +* ``hallRead`` + +I2S +*** + +I2S driver has beed completely redesigned and refactored to use new ESP-IDF driver. +For more informations about the new API check `I2S API `_. + +LEDC +**** + +LEDC API has been changed in order to support the Peripheral Manager and easier use as LEDC channels are now automaticaly assigned to pins. +For more informations about the new API check `LEDC API `_. + +Removed APIs +^^^^^^^^^^^^ + +* ``ledcSetup`` +* ``ledcAttachPin`` + +New APIs +^^^^^^^^ + +* ``ledcAttach`` used to setup LEDC pin (merged ``ledcSetup`` and ``ledcAttachPin`` functions). +* ``timerGetFrequency`` used to get actual frequency of the timer. +* ``timerAttachInterruptArg`` used to attach interrupt to timer using argument. + +Changes in APIs +^^^^^^^^^^^^^^^ + +* ``ledcDetachPin`` renamed to ``ledcDetach``. +* In all functions input parameter ``channel`` have been changed to ``pin``. + +RMT +**** + +TODO: +For more informations about the new API check `RMT API `_. + +Removed APIs +^^^^^^^^^^^^ + +TODO: + +New APIs +^^^^^^^^ + +TODO: + +Changes in APIs +^^^^^^^^^^^^^^^ + +TODO: + +SigmaDelta +********** + +SigmaDelta has been refactored to use new ESP-IDF driver. +For more informations about the new API check `SigmaDelta API `_. + +Removed APIs +^^^^^^^^^^^^ + +* ``sigmaDeltaSetup`` +* ``sigmaDeltaRead`` + +New APIs +^^^^^^^^ + +* ``sigmaDeltaAttach`` used to setup SigmaDelta pin (channel is aquired automatically). +* ``timerGetFrequency`` used to get actual frequency of the timer. +* ``timerAttachInterruptArg`` used to attach interrupt to timer using argument. + +Changes in APIs +^^^^^^^^^^^^^^^ + +* ``sigmaDeltaDetachPin`` renamed to ``sigmaDeltaDetach``. +* ``sigmaDeltaWrite`` input parameter ``channel`` have been changed to ``pin``. + +Timer +***** + +Timer has been refactored to use new ESP-IDF driver and its API got simplified. For more informations 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 setup Alarm for timer and enables it automaticaly (merged ``timerAlarmWrite`` and ``timerAlarmEnable`` functions). +* ``timerGetFrequency`` used to get actual frequency of the timer. +* ``timerAttachInterruptArg`` used to attach interrupt to timer using argument. + +Changes in APIs +^^^^^^^^^^^^^^^ + +* ``timerBegin`` now have only 1 parameter wich is frequency. There is an automatic calculation of divider through different clock sources¨ + to achieve selected frequency. +* ``timerAttachInterrupt`` now have only 2 parameters -> parameter ``edge`` has been removed. + +UART +**** + +TODO: +For more informations about the new API check `UART API `_. + +Removed APIs +^^^^^^^^^^^^ + +TODO: + +New APIs +^^^^^^^^ + +TODO: + +Changes in APIs +^^^^^^^^^^^^^^^ + +TODO: \ No newline at end of file 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: + + * From 2d17cfb4887f2477037d9324e17477ffc6d8954a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Procha=CC=81zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Thu, 13 Jul 2023 15:38:31 +0200 Subject: [PATCH 04/15] Update Introduction to migration guide --- docs/source/migration_guide/2.x_to_3.0.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/source/migration_guide/2.x_to_3.0.rst b/docs/source/migration_guide/2.x_to_3.0.rst index b2ebb75c667..b43f6cb8c75 100644 --- a/docs/source/migration_guide/2.x_to_3.0.rst +++ b/docs/source/migration_guide/2.x_to_3.0.rst @@ -5,9 +5,8 @@ Migration from 2.x to 3.0 Introduction ------------ -This is a guideline for the Arduino ESP32 project documentation. The idea for this guideline is to show how to start collaborating on the project. - -The guideline works to give you the directions and to keep the documentation more concise, helping users to better understand the structure. +This is a guide to show breaking changes and to help migrate porjects from 2.X version to 3.0 version of Arduino ESP32 core. +For more informations about all changes and new features check `RELESE NOTES `_. Breaking changes in API ----------------------- From 68b5f7039c5605ce384e13197931a35523d3f671 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Procha=CC=81zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Thu, 13 Jul 2023 15:44:04 +0200 Subject: [PATCH 05/15] update formatting --- docs/source/migration_guide/2.x_to_3.0.rst | 55 ++++++++++------------ 1 file changed, 25 insertions(+), 30 deletions(-) diff --git a/docs/source/migration_guide/2.x_to_3.0.rst b/docs/source/migration_guide/2.x_to_3.0.rst index b43f6cb8c75..ceb1c3db60d 100644 --- a/docs/source/migration_guide/2.x_to_3.0.rst +++ b/docs/source/migration_guide/2.x_to_3.0.rst @@ -8,16 +8,11 @@ Introduction This is a guide to show breaking changes and to help migrate porjects from 2.X version to 3.0 version of Arduino ESP32 core. For more informations about all changes and new features check `RELESE NOTES `_. -Breaking changes in API ------------------------ - -We all know how important documentation is. This project is no different. - ADC -*** +--- Removed APIs -^^^^^^^^^^^^ +************ * ``analogSetClockDiv`` * ``adcAttachPin`` @@ -25,100 +20,100 @@ Removed APIs Hall Sensor -*********** +----------- Hall sensor is no longer supported. Removed APIs -^^^^^^^^^^^^ +************ * ``hallRead`` I2S -*** +--- I2S driver has beed completely redesigned and refactored to use new ESP-IDF driver. For more informations about the new API check `I2S API `_. LEDC -**** +---- LEDC API has been changed in order to support the Peripheral Manager and easier use as LEDC channels are now automaticaly assigned to pins. For more informations about the new API check `LEDC API `_. Removed APIs -^^^^^^^^^^^^ +************ * ``ledcSetup`` * ``ledcAttachPin`` New APIs -^^^^^^^^ +******** * ``ledcAttach`` used to setup LEDC pin (merged ``ledcSetup`` and ``ledcAttachPin`` functions). * ``timerGetFrequency`` used to get actual frequency of the timer. * ``timerAttachInterruptArg`` used to attach interrupt to timer using argument. Changes in APIs -^^^^^^^^^^^^^^^ +*************** * ``ledcDetachPin`` renamed to ``ledcDetach``. * In all functions input parameter ``channel`` have been changed to ``pin``. RMT -**** +--- TODO: For more informations about the new API check `RMT API `_. Removed APIs -^^^^^^^^^^^^ +************ TODO: New APIs -^^^^^^^^ +******** TODO: Changes in APIs -^^^^^^^^^^^^^^^ +*************** TODO: SigmaDelta -********** +---------- SigmaDelta has been refactored to use new ESP-IDF driver. For more informations about the new API check `SigmaDelta API `_. Removed APIs -^^^^^^^^^^^^ +************ * ``sigmaDeltaSetup`` * ``sigmaDeltaRead`` New APIs -^^^^^^^^ +******** * ``sigmaDeltaAttach`` used to setup SigmaDelta pin (channel is aquired automatically). * ``timerGetFrequency`` used to get actual frequency of the timer. * ``timerAttachInterruptArg`` used to attach interrupt to timer using argument. Changes in APIs -^^^^^^^^^^^^^^^ +*************** * ``sigmaDeltaDetachPin`` renamed to ``sigmaDeltaDetach``. * ``sigmaDeltaWrite`` input parameter ``channel`` have been changed to ``pin``. Timer -***** +----- Timer has been refactored to use new ESP-IDF driver and its API got simplified. For more informations about the new API check `TIMER API `_. Removed APIs -^^^^^^^^^^^^ +************ * ``timerGetConfig`` * ``timerSetConfig`` @@ -138,36 +133,36 @@ Removed APIs * ``timerAttachInterruptFlag`` New APIs -^^^^^^^^ +******** * ``timerAlarm`` used to setup Alarm for timer and enables it automaticaly (merged ``timerAlarmWrite`` and ``timerAlarmEnable`` functions). * ``timerGetFrequency`` used to get actual frequency of the timer. * ``timerAttachInterruptArg`` used to attach interrupt to timer using argument. Changes in APIs -^^^^^^^^^^^^^^^ +*************** * ``timerBegin`` now have only 1 parameter wich is frequency. There is an automatic calculation of divider through different clock sources¨ to achieve selected frequency. * ``timerAttachInterrupt`` now have only 2 parameters -> parameter ``edge`` has been removed. UART -**** +---- TODO: For more informations about the new API check `UART API `_. Removed APIs -^^^^^^^^^^^^ +************ TODO: New APIs -^^^^^^^^ +******** TODO: Changes in APIs -^^^^^^^^^^^^^^^ +*************** TODO: \ No newline at end of file From 033aa1aa0d8fb38c5ed33d1c9adb6be5a2a2708b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Procha=CC=81zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Thu, 13 Jul 2023 15:45:21 +0200 Subject: [PATCH 06/15] fix typo --- docs/source/migration_guide/2.x_to_3.0.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/migration_guide/2.x_to_3.0.rst b/docs/source/migration_guide/2.x_to_3.0.rst index ceb1c3db60d..afff54c707d 100644 --- a/docs/source/migration_guide/2.x_to_3.0.rst +++ b/docs/source/migration_guide/2.x_to_3.0.rst @@ -5,7 +5,7 @@ Migration from 2.x to 3.0 Introduction ------------ -This is a guide to show breaking changes and to help migrate porjects from 2.X version to 3.0 version of Arduino ESP32 core. +This is a guide to show breaking changes in API and to help migrate projects from 2.X version to 3.0 version of Arduino ESP32 core. For more informations about all changes and new features check `RELESE NOTES `_. ADC From 1ef69afdc53f79ca30123322b3db6016301a975b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Procha=CC=81zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Fri, 14 Jul 2023 15:05:21 +0200 Subject: [PATCH 07/15] Add BLE breaking changes --- docs/source/migration_guide/2.x_to_3.0.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/source/migration_guide/2.x_to_3.0.rst b/docs/source/migration_guide/2.x_to_3.0.rst index afff54c707d..788cbf5da7a 100644 --- a/docs/source/migration_guide/2.x_to_3.0.rst +++ b/docs/source/migration_guide/2.x_to_3.0.rst @@ -18,6 +18,14 @@ Removed APIs * ``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 ----------- From 8b6269ab0a61d4716b9a05ffb64101d3843cdead Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Proch=C3=A1zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Wed, 6 Sep 2023 09:08:07 +0200 Subject: [PATCH 08/15] Apply changes from code review by @lucasssvaz Co-authored-by: Lucas Saavedra Vaz --- docs/source/api/ledc.rst | 4 +- docs/source/api/sigmadelta.rst | 18 ++++---- docs/source/migration_guide/2.x_to_3.0.rst | 50 +++++++++++----------- 3 files changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/source/api/ledc.rst b/docs/source/api/ledc.rst index a3515b480c5..b69f581f5bf 100644 --- a/docs/source/api/ledc.rst +++ b/docs/source/api/ledc.rst @@ -130,8 +130,8 @@ This function is used to detach the pin from LEDC. * ``pin`` select LEDC pin. -This function will return ``true`` if detaching is successful. -If ``false`` is returned, error occurs and pin is not detached. +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 f9e30c4ca81..e92f4afaf17 100644 --- a/docs/source/api/sigmadelta.rst +++ b/docs/source/api/sigmadelta.rst @@ -26,7 +26,7 @@ Arduino-ESP32 SigmaDelta API sigmaDeltaAttach **************** -This function is used to setup the SigmaDelta channel with selected frequency and attach it to selected pin. +This function is used to set up the SigmaDelta channel with the selected frequency and attach it to the selected pin. .. code-block:: arduino @@ -37,8 +37,8 @@ This function is used to setup the SigmaDelta channel with selected frequency an * range is 1-14 bits (1-20 bits for ESP32). -This function will return ``true`` if configuration is successful. -If ``false`` 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 *************** @@ -49,16 +49,16 @@ This function is used to set duty for the SigmaDelta pin. bool sigmaDeltaWrite(uint8_t pin, uint8_t duty); -* ``pin`` select GPIO pin. -* ``duty`` select duty to be set for selected pin. +* ``pin`` selects the GPIO pin. +* ``duty`` selects the duty to be set for selected pin. -This function will return ``true`` if setting duty is successful. +This function returns ``true`` if setting the duty was successful. If ``false`` is returned, error occurs and duty was not set. sigmaDeltaDetach **************** -This function is used to detach pin from SigmaDelta and deinit the channel that was attached to the pin. +This function is used to detach a pin from SigmaDelta and deinit the channel that was attached to the pin. .. code-block:: arduino @@ -66,8 +66,8 @@ This function is used to detach pin from SigmaDelta and deinit the channel that * ``pin`` select GPIO pin. -This function will return ``true`` if detaching is successful. -If ``false`` is returned, error occurs and pin is not detached. +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/migration_guide/2.x_to_3.0.rst b/docs/source/migration_guide/2.x_to_3.0.rst index 788cbf5da7a..50e3866c08d 100644 --- a/docs/source/migration_guide/2.x_to_3.0.rst +++ b/docs/source/migration_guide/2.x_to_3.0.rst @@ -5,8 +5,8 @@ Migration from 2.x to 3.0 Introduction ------------ -This is a guide to show breaking changes in API and to help migrate projects from 2.X version to 3.0 version of Arduino ESP32 core. -For more informations about all changes and new features check `RELESE NOTES `_. +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 --- @@ -40,14 +40,14 @@ Removed APIs I2S --- -I2S driver has beed completely redesigned and refactored to use new ESP-IDF driver. -For more informations about the new API check `I2S API `_. +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 ---- -LEDC API has been changed in order to support the Peripheral Manager and easier use as LEDC channels are now automaticaly assigned to pins. -For more informations about the new API check `LEDC API `_. +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 ************ @@ -58,21 +58,21 @@ Removed APIs New APIs ******** -* ``ledcAttach`` used to setup LEDC pin (merged ``ledcSetup`` and ``ledcAttachPin`` functions). -* ``timerGetFrequency`` used to get actual frequency of the timer. -* ``timerAttachInterruptArg`` used to attach interrupt to timer using argument. +* ``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`` have been changed to ``pin``. +* In all functions, input parameter ``channel`` has been changed to ``pin``. RMT --- TODO: -For more informations about the new API check `RMT API `_. +For more information about the new API, check `RMT API `_. Removed APIs ************ @@ -92,8 +92,8 @@ TODO: SigmaDelta ---------- -SigmaDelta has been refactored to use new ESP-IDF driver. -For more informations about the new API check `SigmaDelta API `_. +SigmaDelta has been refactored to use the new ESP-IDF driver. +For more information about the new API, check `SigmaDelta API `_. Removed APIs ************ @@ -104,20 +104,20 @@ Removed APIs New APIs ******** -* ``sigmaDeltaAttach`` used to setup SigmaDelta pin (channel is aquired automatically). -* ``timerGetFrequency`` used to get actual frequency of the timer. -* ``timerAttachInterruptArg`` used to attach interrupt to timer using argument. +* ``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`` have been changed to ``pin``. +* ``sigmaDeltaWrite`` input parameter ``channel`` has been changed to ``pin``. Timer ----- -Timer has been refactored to use new ESP-IDF driver and its API got simplified. For more informations about the new API check +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 @@ -143,22 +143,22 @@ Removed APIs New APIs ******** -* ``timerAlarm`` used to setup Alarm for timer and enables it automaticaly (merged ``timerAlarmWrite`` and ``timerAlarmEnable`` functions). -* ``timerGetFrequency`` used to get actual frequency of the timer. -* ``timerAttachInterruptArg`` used to attach interrupt to timer using argument. +* ``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`` now have only 1 parameter wich is frequency. There is an automatic calculation of divider through different clock sources¨ - to achieve selected frequency. -* ``timerAttachInterrupt`` now have only 2 parameters -> parameter ``edge`` has been removed. +* ``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 ---- TODO: -For more informations about the new API check `UART API `_. +For more information about the new API, check `UART API `_. Removed APIs ************ From cf7d5077bcc22886bc88bf0ad0973b588baf99f5 Mon Sep 17 00:00:00 2001 From: Jan Prochazka <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Thu, 5 Oct 2023 14:47:11 +0200 Subject: [PATCH 09/15] uart migration --- docs/source/migration_guide/2.x_to_3.0.rst | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/docs/source/migration_guide/2.x_to_3.0.rst b/docs/source/migration_guide/2.x_to_3.0.rst index 50e3866c08d..1c9ecf0472f 100644 --- a/docs/source/migration_guide/2.x_to_3.0.rst +++ b/docs/source/migration_guide/2.x_to_3.0.rst @@ -157,20 +157,12 @@ Changes in APIs UART ---- -TODO: -For more information about the new API, check `UART API `_. - Removed APIs ************ -TODO: - -New APIs -******** - -TODO: +* ``uartDetachPins`` Changes in APIs *************** -TODO: \ No newline at end of file +* ``uartSetPins`` first input parameter ``uint8_t uart_num`` has been changed to ``uart_t* uart``. From 70432008bc4d315ce42648acdf217798e1618fce Mon Sep 17 00:00:00 2001 From: Jan Prochazka <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Tue, 10 Oct 2023 12:41:34 +0200 Subject: [PATCH 10/15] added RMT and UART + links fix --- docs/source/migration_guide/2.x_to_3.0.rst | 46 ++++++++++++++++------ 1 file changed, 35 insertions(+), 11 deletions(-) diff --git a/docs/source/migration_guide/2.x_to_3.0.rst b/docs/source/migration_guide/2.x_to_3.0.rst index 1c9ecf0472f..22a272de6a3 100644 --- a/docs/source/migration_guide/2.x_to_3.0.rst +++ b/docs/source/migration_guide/2.x_to_3.0.rst @@ -41,13 +41,13 @@ 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 `_. +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 `LEDC API `_. +For more information about the new API, check :doc:`/api/ledc`. Removed APIs ************ @@ -71,29 +71,46 @@ Changes in APIs RMT --- -TODO: -For more information about the new API, check `RMT API `_. +For more information about the new API, check :doc:`/api/rmt`. Removed APIs ************ -TODO: +* ``_rmtDumpStatus`` +* ``rmtSetTick`` +* ``rmtWriteBlocking`` +* ``rmtEnd`` +* ``rmtBeginReceive`` +* ``rmtReadData`` New APIs ******** -TODO: +* ``rmtWriteAsync`` +* ``rmtTransmitCompleted`` +* ``rmtSetRxMinThreshold`` + Changes in APIs *************** -TODO: +* 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 `SigmaDelta API `_. +For more information about the new API, check :doc:`/api/sigmadelta`. Removed APIs ************ @@ -117,8 +134,7 @@ Changes in APIs 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 `_. +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 ************ @@ -161,8 +177,16 @@ 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 *************** -* ``uartSetPins`` first input parameter ``uint8_t uart_num`` has been changed to ``uart_t* uart``. +* ``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``. From ad2fb13a0a9199edd011dc9e943c5be127cc10ea Mon Sep 17 00:00:00 2001 From: Jan Prochazka <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Tue, 10 Oct 2023 12:41:46 +0200 Subject: [PATCH 11/15] fix renamed BLE examples --- docs/source/api/ble.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/api/ble.rst b/docs/source/api/ble.rst index 12a8e1280b7..05e765f8feb 100644 --- a/docs/source/api/ble.rst +++ b/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 `_. From 2dcf8c2c3e42ad225d5b981d1500cd956d6e66e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Proch=C3=A1zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Tue, 10 Oct 2023 13:18:23 +0200 Subject: [PATCH 12/15] Apply suggestions from code review by @lucasssvaz Co-authored-by: Lucas Saavedra Vaz --- docs/source/migration_guide/2.x_to_3.0.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/migration_guide/2.x_to_3.0.rst b/docs/source/migration_guide/2.x_to_3.0.rst index 22a272de6a3..8ead3360ab8 100644 --- a/docs/source/migration_guide/2.x_to_3.0.rst +++ b/docs/source/migration_guide/2.x_to_3.0.rst @@ -97,14 +97,14 @@ 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. +* ``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`` has been changed to ``uint32_t frequency_Hz, float duty_percent``. +* ``rmtSetCarrier`` input parameters ``uint32_t low, uint32_t high`` have been changed to ``uint32_t frequency_Hz, float duty_percent``. SigmaDelta ---------- From 914de142c72769702f6c65a270f9de362c6e07d3 Mon Sep 17 00:00:00 2001 From: Jan Prochazka <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Tue, 10 Oct 2023 15:09:15 +0200 Subject: [PATCH 13/15] Change UART driver changes to HardwareSerial changes --- docs/source/migration_guide/2.x_to_3.0.rst | 32 +++++++++++----------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/source/migration_guide/2.x_to_3.0.rst b/docs/source/migration_guide/2.x_to_3.0.rst index 8ead3360ab8..25e2baaa0eb 100644 --- a/docs/source/migration_guide/2.x_to_3.0.rst +++ b/docs/source/migration_guide/2.x_to_3.0.rst @@ -170,23 +170,23 @@ Changes in APIs 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. +UART (HardwareSerial) +--------------------- 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``. +* ``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. From 1def2c130ecd3ff84e49490035cd2494bbb53bdc Mon Sep 17 00:00:00 2001 From: Jan Prochazka <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Wed, 11 Oct 2023 14:04:52 +0200 Subject: [PATCH 14/15] update sigmadelta --- docs/source/api/sigmadelta.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/sigmadelta.rst b/docs/source/api/sigmadelta.rst index e92f4afaf17..4505c553cf2 100644 --- a/docs/source/api/sigmadelta.rst +++ b/docs/source/api/sigmadelta.rst @@ -58,7 +58,7 @@ If ``false`` is returned, error occurs and duty was not set. sigmaDeltaDetach **************** -This function is used to detach a pin from SigmaDelta and deinit the channel that was attached to the pin. +This function is used to detach a pin from SigmaDelta and deinitialize the channel that was attached to the pin. .. code-block:: arduino From ca0a943ab0bf50709561b58935ceb16467e9c410 Mon Sep 17 00:00:00 2001 From: Jan Prochazka <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Tue, 17 Oct 2023 13:43:03 +0200 Subject: [PATCH 15/15] BLE and examples update + rename --- docs/source/index.rst | 2 +- docs/source/migration_guide/migration_guide.rst | 10 ---------- .../2.x_to_3.0.rst | 8 ++++++-- docs/source/migration_guides/migration_guides.rst | 10 ++++++++++ 4 files changed, 17 insertions(+), 13 deletions(-) delete mode 100644 docs/source/migration_guide/migration_guide.rst rename docs/source/{migration_guide => migration_guides}/2.x_to_3.0.rst (89%) create mode 100644 docs/source/migration_guides/migration_guides.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 0ebdbfeaa5c..4016f36f3d4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,7 +16,7 @@ Here you will find all the relevant information about the project. Guides Tutorials Advanced Utilities - Migration Guide + Migration Guides FAQ Troubleshooting Contributing diff --git a/docs/source/migration_guide/migration_guide.rst b/docs/source/migration_guide/migration_guide.rst deleted file mode 100644 index 2144da52d01..00000000000 --- a/docs/source/migration_guide/migration_guide.rst +++ /dev/null @@ -1,10 +0,0 @@ -############### -Migration Guide -############### - -.. toctree:: - :caption: Migration Guide: - :maxdepth: 1 - :glob: - - * diff --git a/docs/source/migration_guide/2.x_to_3.0.rst b/docs/source/migration_guides/2.x_to_3.0.rst similarity index 89% rename from docs/source/migration_guide/2.x_to_3.0.rst rename to docs/source/migration_guides/2.x_to_3.0.rst index 25e2baaa0eb..3ccbfba5ffb 100644 --- a/docs/source/migration_guide/2.x_to_3.0.rst +++ b/docs/source/migration_guides/2.x_to_3.0.rst @@ -5,8 +5,11 @@ 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 `_. +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 `_. ADC --- @@ -26,6 +29,7 @@ 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 ----------- diff --git a/docs/source/migration_guides/migration_guides.rst b/docs/source/migration_guides/migration_guides.rst new file mode 100644 index 00000000000..e1254c19ba5 --- /dev/null +++ b/docs/source/migration_guides/migration_guides.rst @@ -0,0 +1,10 @@ +################ +Migration Guides +################ + +.. toctree:: + :caption: Migration Guides: + :maxdepth: 1 + :glob: + + *