docs: Update the PWM examples based on recent API improvements.

This adds the freq and duty_u16 keyword settings to the constructor, and
sometimes other details in the PWM section.

For mimxrt a clarification regarding the PWM invert argument was added, and
for rp2 a few words were spent on PWM output pairs of a channel/slice.

docs/esp32/quickref.rst

@@ -305,8 +305,8 @@ Use the :ref:`machine.PWM <machine.PWM>` class::
 
     from machine import Pin, PWM
 
-    pwm0 = PWM(Pin(0))         # create PWM object from a pin
+    pwm0 = PWM(Pin(0), freq=5000, duty_u16=32768) # create PWM object from a pin
-    freq = pwm0.freq()         # get current frequency (default 5kHz)
+    freq = pwm0.freq()         # get current frequency
     pwm0.freq(1000)            # set PWM frequency from 1Hz to 40MHz
 
     duty = pwm0.duty()         # get current duty cycle, range 0-1023 (default 512, 50%)

docs/library/machine.PWM.rst

@@ -10,7 +10,8 @@ Example usage::
 
     from machine import PWM
 
-    pwm = PWM(pin)          # create a PWM object on a pin
+    pwm = PWM(pin, freq=50, duty_u16=8192)  # create a PWM object on a pin
+                                            # and set freq and duty
     pwm.duty_u16(32768)     # set duty to 50%
 
     # reinitialise with a period of 200us, duty of 5us

docs/mimxrt/quickref.rst

@@ -145,11 +145,12 @@ handling signal groups. ::
 
     from machine import Pin, PWM
 
-    pwm2 = PWM(Pin(2))      # create PWM object from a pin
+    # create PWM object from a pin and set the frequency and duty cycle
-    pwm2.freq()             # get current frequency
+    pwm2 = PWM(Pin(2), freq=2000, duty_u16=32768)
-    pwm2.freq(1000)         # set frequency
+    pwm2.freq()             # get the current frequency
-    pwm2.duty_u16()         # get current duty cycle, range 0-65535
+    pwm2.freq(1000)         # set/change the frequency
-    pwm2.duty_u16(200)      # set duty cycle, range 0-65535
+    pwm2.duty_u16()         # get the current duty cycle, range 0-65535
+    pwm2.duty_u16(200)      # set the duty cycle, range 0-65535
     pwm2.deinit()           # turn off PWM on the pin
     # create a complementary signal pair on Pin 2 and 3
     pwm2 = PWM((2, 3), freq=2000, duty_ns=20000)
@@ -206,8 +207,9 @@ PWM Constructor
       - *align*\=value. Shortcuts for the pulse center setting, causing the pulse either at
         the center of the frame (value=0), the leading edge at the begin (value=1) or the
         trailing edge at the end of a pulse period (value=2).
-      - *invert*\=True|False channel_mask. Setting a bit in the mask inverts the respective channel.
+      - *invert*\=value channel_mask. Setting a bit in the mask inverts the respective channel.
-        Bit 0 inverts the first specified channel, bit 2 the second. The default is 0.
+        Bit 0 inverts the first specified channel, bit 1 the second. The default is 0. For a
+        PWM object with a single channel, True and False may be used as values.
       - *sync*\=True|False. If a channel of a module's submodule 0 is already active, other
         submodules of the same module can be forced to be synchronous to submodule 0. Their
         pulse period start then at at same clock cycle. The default is False.

docs/rp2/quickref.rst

@@ -146,19 +146,30 @@ See :ref:`machine.UART <machine.UART>`. ::
 PWM (pulse width modulation)
 ----------------------------
 
-There are 8 independent channels each of which have 2 outputs making it 16
+There are 8 independent PWM generators called slices, which each have two
-PWM channels in total which can be clocked from 7Hz to 125Mhz.
+channels making it 16 PWM channels in total which can be clocked from
+8Hz to 62.5Mhz at a machine.freq() of 125Mhz. The two channels of a
+slice run at the same frequency, but can have a different duty rate.
+The two channels are usually assigned to adjacent GPIO pin pairs with
+even/odd numbers. So GPIO0 and GPIO1 are at slice 0, GPIO2 and GPIO3
+are at slice 1, and so on. A certain channel can be assigned to
+different GPIO pins (see Pinout). For instance slice 0, channel A can be assigned
+to both GPIO0 and GPIO16.
 
 Use the ``machine.PWM`` class::
 
     from machine import Pin, PWM
 
-    pwm0 = PWM(Pin(0))      # create PWM object from a pin
+    # create PWM object from a pin and set the frequency of slice 0
-    pwm0.freq()             # get current frequency
+    # and duty cycle for channel A
-    pwm0.freq(1000)         # set frequency
+    pwm0 = PWM(Pin(0), freq=2000, duty_u16=32768)
-    pwm0.duty_u16()         # get current duty cycle, range 0-65535
+    pwm0.freq()             # get the current frequency of slice 0
-    pwm0.duty_u16(200)      # set duty cycle, range 0-65535
+    pwm0.freq(1000)         # set/change the frequency of slice 0
-    pwm0.deinit()           # turn off PWM on the pin
+    pwm0.duty_u16()         # get the current duty cycle of channel A, range 0-65535
+    pwm0.duty_u16(200)      # set the duty cycle of channel A, range 0-65535
+    pwm0.duty_u16(0)        # stop the output at channel A
+    print(pwm0)             # show the properties of the PWM object.
+    pwm0.deinit()           # turn off PWM of slice 0, stopping channels A and B
 
 ADC (analog to digital conversion)
 ----------------------------------

docs/samd/quickref.rst

@@ -178,11 +178,12 @@ It supports all basic methods listed for that class. ::
 
     from machine import Pin, PWM
 
-    pwm = PWM(Pin(7))      # create PWM object from a pin
+    # create PWM object from a pin and set the frequency and duty cycle
-    pwm.freq()             # get current frequency
+    pwm = PWM(Pin('D7'), freq=2000, duty_u16=32768)
-    pwm.freq(1000)         # set frequency
+    pwm.freq()             # get the current frequency
-    pwm.duty_u16()         # get current duty cycle, range 0-65535
+    pwm.freq(1000)         # set/change the frequency
-    pwm.duty_u16(200)      # set duty cycle, range 0-65535
+    pwm.duty_u16()         # get the current duty cycle, range 0-65535
+    pwm.duty_u16(200)      # set the duty cycle, range 0-65535
     pwm.deinit()           # turn off PWM on the pin
 
     pwm                    # show the PWM objects properties
@@ -213,9 +214,6 @@ PWM Constructor
       - *freq* should be an integer which sets the frequency in Hz for the
         PWM cycle. The valid frequency range is 1 Hz to 24 MHz.
       - *duty_u16* sets the duty cycle as a ratio ``duty_u16 / 65536``.
-        The duty cycle of a X channel can only be changed, if the A and B channel
-        of the respective submodule is not used. Otherwise the duty_16 value of the
-        X channel is 32768 (50%).
       - *duty_ns* sets the pulse width in nanoseconds. The limitation for X channels
         apply as well.
       - *invert*\=True|False. Setting a bit inverts the respective output.