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 `_. 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..4505c553cf2 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 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 ******************** 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..4016f36f3d4 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 Guides FAQ Troubleshooting Contributing diff --git a/docs/source/migration_guides/2.x_to_3.0.rst b/docs/source/migration_guides/2.x_to_3.0.rst new file mode 100644 index 00000000000..3ccbfba5ffb --- /dev/null +++ b/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 `_. + +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. 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: + + *