docs/esp32: Explain ESP32 PWM modes, timers, and channels.

docs/esp32/quickref.rst

@@ -16,7 +16,7 @@ working with this board it may be useful to get an overview of the microcontroll
    :maxdepth: 1
 
    general.rst
-   tutorial/intro.rst
+   tutorial/index.rst
 
 Installing MicroPython
 ----------------------
@@ -225,13 +225,31 @@ Use the ``machine.PWM`` class::
     from machine import Pin, PWM
 
     pwm0 = PWM(Pin(0))      # create PWM object from a pin
-    pwm0.freq()             # get current frequency
+    pwm0.freq()             # get current frequency (default 5kHz)
     pwm0.freq(1000)         # set frequency
-    pwm0.duty()             # get current duty cycle
+    pwm0.duty()             # get current duty cycle (default 512, 50%)
     pwm0.duty(200)          # set duty cycle
     pwm0.deinit()           # turn off PWM on the pin
 
-    pwm2 = PWM(Pin(2), freq=20000, duty=512) # create and configure in one go
+    pwm2 = PWM(Pin(2), freq=20000, duty=512)  # create and configure in one go
+
+ESP chips have different hardware peripherals:
+
+=====================================================  ========  ========  ========
+Hardware specification                                    ESP32  ESP32-S2  ESP32-C3
+-----------------------------------------------------  --------  --------  --------
+Number of groups (speed modes)                                2         1         1
+Number of timers per group                                    4         4         4
+Number of channels per group                                  8         8         6
+-----------------------------------------------------  --------  --------  --------
+Different of PWM frequencies (groups * timers)                8         4         4
+Total PWM channels (Pins, duties) (groups * channels)        16         8         6
+=====================================================  ========  ========  ========
+
+A maximum number of PWM channels (Pins) are available on the ESP32 - 16 channels,
+but only 8 different PWM frequencies are available, the remaining 8 channels must
+have the same frequency.  On the other hand, 16 independent PWM duty cycles are
+possible at the same frequency.
 
 ADC (analog to digital conversion)
 ----------------------------------

docs/esp32/tutorial/index.rst

+.. _esp32_tutorial:
+
+MicroPython tutorial for ESP32
+==============================
+
+This tutorial is intended to get you started using MicroPython on the ESP32
+system-on-a-chip.  If it is your first time it is recommended to follow the
+tutorial through in the order below.  Otherwise the sections are mostly self
+contained, so feel free to skip to those that interest you.
+
+The tutorial does not assume that you know Python, but it also does not attempt
+to explain any of the details of the Python language.  Instead it provides you
+with commands that are ready to run, and hopes that you will gain a bit of
+Python knowledge along the way.  To learn more about Python itself please refer
+to `<https://www.python.org>`__.
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+
+   intro.rst
+   pwm.rst

docs/esp32/tutorial/pwm.rst

+.. _esp32_pwm: 
+
+Pulse Width Modulation
+======================
+
+Pulse width modulation (PWM) is a way to get an artificial analog output on a
+digital pin.  It achieves this by rapidly toggling the pin from low to high.
+There are two parameters associated with this: the frequency of the toggling,
+and the duty cycle.  The duty cycle is defined to be how long the pin is high
+compared with the length of a single period (low plus high time).  Maximum
+duty cycle is when the pin is high all of the time, and minimum is when it is
+low all of the time.
+
+More comprehensive example with all 16 PWM channels and 8 timers::
+
+    from machine import Pin, PWM
+    try:
+        f = 100  # Hz
+        d = 1024 // 16  # 6.25%
+        pins = (15, 2, 4, 16, 18, 19, 22, 23, 25, 26, 27, 14 , 12, 13, 32, 33)
+        pwms = []
+        for i, pin in enumerate(pins):
+            pwms.append(PWM(Pin(pin), freq=f * (i // 2 + 1), duty= 1023 if i==15 else d * (i + 1)))
+            print(pwms[i])
+    finally:
+        for pwm in pwms:
+            try:
+                pwm.deinit()
+            except:
+                pass
+
+Output is::
+
+    PWM(pin=15, freq=100, duty=64, resolution=10, mode=0, channel=0, timer=0)
+    PWM(pin=2, freq=100, duty=128, resolution=10, mode=0, channel=1, timer=0)
+    PWM(pin=4, freq=200, duty=192, resolution=10, mode=0, channel=2, timer=1)
+    PWM(pin=16, freq=200, duty=256, resolution=10, mode=0, channel=3, timer=1)
+    PWM(pin=18, freq=300, duty=320, resolution=10, mode=0, channel=4, timer=2)
+    PWM(pin=19, freq=300, duty=384, resolution=10, mode=0, channel=5, timer=2)
+    PWM(pin=22, freq=400, duty=448, resolution=10, mode=0, channel=6, timer=3)
+    PWM(pin=23, freq=400, duty=512, resolution=10, mode=0, channel=7, timer=3)
+    PWM(pin=25, freq=500, duty=576, resolution=10, mode=1, channel=0, timer=0)
+    PWM(pin=26, freq=500, duty=640, resolution=10, mode=1, channel=1, timer=0)
+    PWM(pin=27, freq=600, duty=704, resolution=10, mode=1, channel=2, timer=1)
+    PWM(pin=14, freq=600, duty=768, resolution=10, mode=1, channel=3, timer=1)
+    PWM(pin=12, freq=700, duty=832, resolution=10, mode=1, channel=4, timer=2)
+    PWM(pin=13, freq=700, duty=896, resolution=10, mode=1, channel=5, timer=2)
+    PWM(pin=32, freq=800, duty=960, resolution=10, mode=1, channel=6, timer=3)
+    PWM(pin=33, freq=800, duty=1023, resolution=10, mode=1, channel=7, timer=3)