From 71111cffbaef778635e212550ff3f0521c43f592 Mon Sep 17 00:00:00 2001 From: IhorNehrutsa Date: Sun, 19 Sep 2021 00:41:42 +0300 Subject: [PATCH] docs/esp32: Explain ESP32 PWM modes, timers, and channels. --- docs/esp32/quickref.rst | 26 ++++++++++++++++--- docs/esp32/tutorial/index.rst | 22 ++++++++++++++++ docs/esp32/tutorial/pwm.rst | 49 +++++++++++++++++++++++++++++++++++ 3 files changed, 93 insertions(+), 4 deletions(-) create mode 100644 docs/esp32/tutorial/index.rst create mode 100644 docs/esp32/tutorial/pwm.rst diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst index 3153ebd571..7391a4aa4b 100644 --- a/docs/esp32/quickref.rst +++ b/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) ---------------------------------- diff --git a/docs/esp32/tutorial/index.rst b/docs/esp32/tutorial/index.rst new file mode 100644 index 0000000000..e9cfd9db10 --- /dev/null +++ b/docs/esp32/tutorial/index.rst @@ -0,0 +1,22 @@ +.. _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 ``__. + +.. toctree:: + :maxdepth: 1 + :numbered: + + intro.rst + pwm.rst diff --git a/docs/esp32/tutorial/pwm.rst b/docs/esp32/tutorial/pwm.rst new file mode 100644 index 0000000000..0c1afb213b --- /dev/null +++ b/docs/esp32/tutorial/pwm.rst @@ -0,0 +1,49 @@ +.. _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)