From 9e17dbe20dc1d9d6f366ba2f0a72330895f184cc 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: Tue, 22 Feb 2022 09:13:45 +0100 Subject: [PATCH 1/5] LEDC preripheral doc --- docs/source/api/ledc.rst | 183 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 docs/source/api/ledc.rst diff --git a/docs/source/api/ledc.rst b/docs/source/api/ledc.rst new file mode 100644 index 00000000000..e392e4c502b --- /dev/null +++ b/docs/source/api/ledc.rst @@ -0,0 +1,183 @@ +################## +LED Control (LEDC) +################## + +About +----- +The LED control (LEDC) peripheral is primarly designed to control the intensity of LEDs, +although it can also be used to generate PWM signals for other purposes. + +ESP32 SoCs has from 6 to 16 channels (variates on socs, see table below) which can generate independent waveforms, that can be used for example to drive RGB LED devices. + +========= ======================= +ESP32 SoC Number of LEDC channels +========= ======================= +ESP32 16 +ESP32-S2 8 +ESP32-C3 6 +ESP32-S3 8 +========= ======================= + +Arduino-ESP32 LEDC API +---------------------- + +ledcSetup +********* + +This function is used to setup LEDC channel frequency and resolution. + +.. code-block:: arduino + + double ledcSetup(uint8_t channel, double freq, uint8_t resolution_bits); + +* ``channel`` select LEDC channel to config. +* ``freq`` select frequency of pwm. +* ``resolution_bits`` select resolution for ledc channel. + + * range is 1-14 bits (1-20 bits for ESP32). + +This function will return ``frequency`` set for LEDC channel. +If ``0`` is returned, error occurs and ledc channel was not configured. + +ledcWrite +********* + +This function is used to set duty for LEDC channel. + +.. code-block:: arduino + + void ledcWrite(uint8_t chan, uint32_t duty); + +* ``chan`` select LEDC channel for writing duty. +* ``duty`` select duty to be set for selected channel. + +ledcRead +******** + +This function is used to get configured duty for LEDC channel. + +.. code-block:: arduino + + uint32_t ledcRead(uint8_t chan); + +* ``chan`` select LEDC channel to read its duty. + +This function will return ``duty`` set for selected LEDC channel. + +ledcReadFreq +************ + +This function is used to get configured frequency for LEDC channel. + +.. code-block:: arduino + + double ledcReadFreq(uint8_t chan); + +* ``chan`` select LEDC channel to read its frequency. + +This function will return ``frequency`` set for selected LEDC channel. + +ledcWriteTone +************* + +This function is used to setup LEDC channel to 50 % PWM tone on selected frequency. + +.. code-block:: arduino + + double ledcWriteTone(uint8_t chan, double freq); + +* ``chan`` select LEDC channel. +* ``freq`` select frequency of pwm signal. + +This function will return ``frequency`` set for channel. +If ``0`` is returned, error occurs and ledc cahnnel was not configured. + +ledcWriteNote +************* + +This function is used to setup LEDC channel to specific note. + +.. code-block:: arduino + + double ledcWriteNote(uint8_t chan, note_t note, uint8_t octave); + +* ``chan`` select LEDC channel. +* ``note`` select note to be set. + +======= ======= ======= ======= ======= ====== +NOTE_C NOTE_Cs NOTE_D NOTE_Eb NOTE_E NOTE_F +NOTE_Fs NOTE_G NOTE_Gs NOTE_A NOTE_Bb NOTE_B +======= ======= ======= ======= ======= ====== + +* ``octave`` select octave for note. + +This function will return ``frequency`` set for channel according to note and octave inputs. +If ``0`` is returned, error occurs and ledc cahnnel was not configured. + +ledcAttachPin +************* + +This function is used to attach GPIO pin to LEDC channel. + +.. code-block:: arduino + + void ledcAttachPin(uint8_t pin, uint8_t chan); + +* ``pin`` select GPIO pin. +* ``chan`` select LEDC channel. + +ledcDetachPin +************* + +This function is used to detach GPIO pin from LEDC. + +.. code-block:: arduino + + void ledcDetachPin(uint8_t pin); + +* ``pin`` select GPIO pin. + +ledcChangeFrequency +******************* + +This function is used to set frequency for LEDC channel. + +.. code-block:: arduino + + double ledcChangeFrequency(uint8_t chan, double freq, uint8_t bit_num); + +* ``channel`` select LEDC channel to config. +* ``freq`` select frequency of pwm. +* ``bit_num`` select resolution for ledc channel. + + * range is 1-14 bits (1-20 bits for ESP32). + +This function will return ``frequency`` set for LEDC channel. +If ``0`` is returned, error occurs and ledc channel frequency was not set. + +analogWrite +*********** + +This function is used to write an analog value (PWM wave) to pin. +It is compatible with Arduinos analogWrite function. + +.. code-block:: arduino + + void analogWrite(uint8_t pin, int value); + +* ``pin`` select the GPIO pin. +* ``value`` select the duty cycle of pwm. + * range is from 0 (always off) to 255 (always on). + +Example Applications +******************** + +LEDC software fade example: + +.. literalinclude:: ../../../libraries/ESP32/examples/AnalogOut/LEDCSoftwareFade/LEDCSoftwareFade.ino + :language: arduino + +LEDC Write RGB example: + +.. literalinclude:: ../../../libraries/ESP32/examples/AnalogOut/ledcWrite_RGB/ledcWrite_RGB.ino + :language: arduino From 38730f597113245f620af206ffd85fb919299230 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: Tue, 22 Feb 2022 09:14:02 +0100 Subject: [PATCH 2/5] SigmaDelta peripheral doc --- docs/source/api/sigmadelta.rst | 84 ++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 docs/source/api/sigmadelta.rst diff --git a/docs/source/api/sigmadelta.rst b/docs/source/api/sigmadelta.rst new file mode 100644 index 00000000000..818aa04d20f --- /dev/null +++ b/docs/source/api/sigmadelta.rst @@ -0,0 +1,84 @@ +########## +SigmaDelta +########## + +About +----- + +ESP32 provides a second-order sigma delta modulation module and 8 (4 for ESP32-C3) +independent modulation channels. The channels are capable to output 1-bit +signals (output index: 100 ~ 107) with sigma delta modulation. + +========= ============================= +ESP32 SoC Number of SigmaDelta channels +========= ============================= +ESP32 8 +ESP32-S2 8 +ESP32-C3 4 +ESP32-S3 8 +========= ============================= + +Arduino-ESP32 SigmaDelta API +---------------------------- + +sigmaDeltaSetup +************** + +This function is used to setup SigmaDelta channel frequency and resolution. + +.. code-block:: arduino + + double ledcSetup(uint8_t channel, double freq, uint8_t resolution_bits); + +* ``pin`` select GPIO pin. +* ``channel`` select SigmaDelta channel to config. +* ``freq`` select frequency. + + * range is 1-14 bits (1-20 bits for ESP32). + +This function will return ``frequency`` set for SigmaDelta channel. +If ``0`` is returned, error occurs and sigmadelta channel was not configured. + +sigmaDeltaWrite +*************** + +This function is used to set duty for SigmaDelta channel. + +.. code-block:: arduino + + void sigmaDeltaWrite(uint8_t channel, uint8_t duty); + +* ``channel`` select SigmaDelta channel to set duty. +* ``duty`` select duty to be set for selected channel. + +sigmaDeltaRead +************** + +This function is used to get configured duty for SigmaDelta channel. + +.. code-block:: arduino + + uint8_t sigmaDeltaRead(uint8_t channel) + +* ``channnel`` select SigmaDelta channel to raed duty. + +This function will return ``duty`` set for selected LEDC channel. + +sigmaDeltaDetachPin +******************* + +This function is used to detach GPIO pin from SigmaDelta. + +.. code-block:: arduino + + void sigmaDeltaDetachPin(uint8_t pin); + +* ``pin`` select GPIO pin. + +Example Applications +******************** + +Here is example use of SigmaDelta: + +.. literalinclude:: ../../../libraries/ESP32/examples/AnalogOut/SigmaDelta/SigmaDelta.ino + :language: arduino From 11624d6b713e0d9c1a6228a4d2c653b6b9484760 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: Tue, 22 Feb 2022 09:35:17 +0100 Subject: [PATCH 3/5] Added missing symbol --- 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 818aa04d20f..df2db4ae613 100644 --- a/docs/source/api/sigmadelta.rst +++ b/docs/source/api/sigmadelta.rst @@ -22,7 +22,7 @@ Arduino-ESP32 SigmaDelta API ---------------------------- sigmaDeltaSetup -************** +*************** This function is used to setup SigmaDelta channel frequency and resolution. From f4e89418b85efc311a161cc0c922f40b736f0d89 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: Tue, 22 Feb 2022 10:20:15 +0100 Subject: [PATCH 4/5] Edited grammar, mistakes --- docs/source/api/ledc.rst | 42 +++++++++++++++++----------------- docs/source/api/sigmadelta.rst | 18 +++++++-------- 2 files changed, 30 insertions(+), 30 deletions(-) diff --git a/docs/source/api/ledc.rst b/docs/source/api/ledc.rst index e392e4c502b..b6c72821304 100644 --- a/docs/source/api/ledc.rst +++ b/docs/source/api/ledc.rst @@ -24,7 +24,7 @@ Arduino-ESP32 LEDC API ledcSetup ********* -This function is used to setup LEDC channel frequency and resolution. +This function is used to setup the LEDC channel frequency and resolution. .. code-block:: arduino @@ -36,51 +36,51 @@ This function is used to setup LEDC channel frequency and resolution. * range is 1-14 bits (1-20 bits for ESP32). -This function will return ``frequency`` set for LEDC channel. +This function will return ``frequency`` configured for LEDC channel. If ``0`` is returned, error occurs and ledc channel was not configured. ledcWrite ********* -This function is used to set duty for LEDC channel. +This function is used to set duty for the LEDC channel. .. code-block:: arduino void ledcWrite(uint8_t chan, uint32_t duty); -* ``chan`` select LEDC channel for writing duty. +* ``chan`` select the LEDC channel for writing duty. * ``duty`` select duty to be set for selected channel. ledcRead ******** -This function is used to get configured duty for LEDC channel. +This function is used to get configured duty for the LEDC channel. .. code-block:: arduino uint32_t ledcRead(uint8_t chan); -* ``chan`` select LEDC channel to read its duty. +* ``chan`` select LEDC channel to read the configured duty. This function will return ``duty`` set for selected LEDC channel. ledcReadFreq ************ -This function is used to get configured frequency for LEDC channel. +This function is used to get configured frequency for the LEDC channel. .. code-block:: arduino double ledcReadFreq(uint8_t chan); -* ``chan`` select LEDC channel to read its frequency. +* ``chan`` select the LEDC channel to read the configured frequency. -This function will return ``frequency`` set for selected LEDC channel. +This function will return ``frequency`` configured for selected LEDC channel. ledcWriteTone ************* -This function is used to setup LEDC channel to 50 % PWM tone on selected frequency. +This function is used to setup the LEDC channel to 50 % PWM tone on selected frequency. .. code-block:: arduino @@ -95,7 +95,7 @@ If ``0`` is returned, error occurs and ledc cahnnel was not configured. ledcWriteNote ************* -This function is used to setup LEDC channel to specific note. +This function is used to setup the LEDC channel to specific note. .. code-block:: arduino @@ -111,13 +111,13 @@ NOTE_Fs NOTE_G NOTE_Gs NOTE_A NOTE_Bb NOTE_B * ``octave`` select octave for note. -This function will return ``frequency`` set for channel according to note and octave inputs. -If ``0`` is returned, error occurs and ledc cahnnel was not configured. +This function will return ``frequency`` configured for the LEDC channel according to note and octave inputs. +If ``0`` is returned, error occurs and the LEDC channel was not configured. ledcAttachPin ************* -This function is used to attach GPIO pin to LEDC channel. +This function is used to attach the pin to the LEDC channel. .. code-block:: arduino @@ -129,7 +129,7 @@ This function is used to attach GPIO pin to LEDC channel. ledcDetachPin ************* -This function is used to detach GPIO pin from LEDC. +This function is used to detach the pin from LEDC. .. code-block:: arduino @@ -140,25 +140,25 @@ This function is used to detach GPIO pin from LEDC. ledcChangeFrequency ******************* -This function is used to set frequency for LEDC channel. +This function is used to set frequency for the LEDC channel. .. code-block:: arduino double ledcChangeFrequency(uint8_t chan, double freq, uint8_t bit_num); -* ``channel`` select LEDC channel to config. +* ``channel`` select LEDC channel. * ``freq`` select frequency of pwm. -* ``bit_num`` select resolution for ledc channel. +* ``bit_num`` select resolution for LEDC channel. * range is 1-14 bits (1-20 bits for ESP32). -This function will return ``frequency`` set for LEDC channel. -If ``0`` is returned, error occurs and ledc channel frequency was not set. +This function will return ``frequency`` configured for the LEDC channel. +If ``0`` is returned, error occurs and the LEDC channel frequency was not set. analogWrite *********** -This function is used to write an analog value (PWM wave) to pin. +This function is used to write an analog value (PWM wave) on the pin. It is compatible with Arduinos analogWrite function. .. code-block:: arduino diff --git a/docs/source/api/sigmadelta.rst b/docs/source/api/sigmadelta.rst index df2db4ae613..f7c957d18f2 100644 --- a/docs/source/api/sigmadelta.rst +++ b/docs/source/api/sigmadelta.rst @@ -24,7 +24,7 @@ Arduino-ESP32 SigmaDelta API sigmaDeltaSetup *************** -This function is used to setup SigmaDelta channel frequency and resolution. +This function is used to setup the SigmaDelta channel frequency and resolution. .. code-block:: arduino @@ -36,38 +36,38 @@ This function is used to setup SigmaDelta channel frequency and resolution. * range is 1-14 bits (1-20 bits for ESP32). -This function will return ``frequency`` set for SigmaDelta channel. -If ``0`` is returned, error occurs and sigmadelta channel was not configured. +This function will return ``frequency`` configured for the SigmaDelta channel. +If ``0`` is returned, error occurs and the SigmaDelta channel was not configured. sigmaDeltaWrite *************** -This function is used to set duty for SigmaDelta channel. +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 to set duty. +* ``channel`` select SigmaDelta channel. * ``duty`` select duty to be set for selected channel. sigmaDeltaRead ************** -This function is used to get configured duty for SigmaDelta channel. +This function is used to get configured duty for the SigmaDelta channel. .. code-block:: arduino uint8_t sigmaDeltaRead(uint8_t channel) -* ``channnel`` select SigmaDelta channel to raed duty. +* ``channnel`` select SigmaDelta channel to read duty. -This function will return ``duty`` set for selected LEDC channel. +This function will return ``duty`` configured for the selected SigmaDelta channel. sigmaDeltaDetachPin ******************* -This function is used to detach GPIO pin from SigmaDelta. +This function is used to detach pin from SigmaDelta. .. code-block:: arduino From c0efb7d222074ae6e604ac6b9bb2112d14fe7097 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: Tue, 22 Feb 2022 10:22:37 +0100 Subject: [PATCH 5/5] quick edit --- docs/source/api/sigmadelta.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/api/sigmadelta.rst b/docs/source/api/sigmadelta.rst index f7c957d18f2..d5036a38487 100644 --- a/docs/source/api/sigmadelta.rst +++ b/docs/source/api/sigmadelta.rst @@ -31,7 +31,7 @@ This function is used to setup the SigmaDelta channel frequency and resolution. double ledcSetup(uint8_t channel, double freq, uint8_t resolution_bits); * ``pin`` select GPIO pin. -* ``channel`` select SigmaDelta channel to config. +* ``channel`` select SigmaDelta channel. * ``freq`` select frequency. * range is 1-14 bits (1-20 bits for ESP32). @@ -60,7 +60,7 @@ This function is used to get configured duty for the SigmaDelta channel. uint8_t sigmaDeltaRead(uint8_t channel) -* ``channnel`` select SigmaDelta channel to read duty. +* ``channnel`` select SigmaDelta channel. This function will return ``duty`` configured for the selected SigmaDelta channel.