docs/esp32: Add quickref and full docs for esp32.SigmaDelta class.

mcauser · mcauser · commit 4e40899fb893 · 2020-01-13T10:25:04.000+11:00
diff --git a/docs/esp32/general.rst b/docs/esp32/general.rst
@@ -53,6 +53,7 @@ For your convenience, some of technical specifications are provided below:
 * ADC: 12-bit SAR ADC up to 18 channels
 * DAC: 2 8-bit DACs
 * RMT: 8 channels allowing accurate pulse transmit/receive
+* SigmaDelta: 8 channels of hardware sigma-delta modulated output
 * Programming: using BootROM bootloader from UART - due to external FlashROM
   and always-available BootROM bootloader, the ESP32 is not brickable
 
diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst
@@ -379,6 +379,20 @@ The RMT is ESP32-specific and allows generation of accurate digital pulses with
     # The channel resolution is 100ns (1/(source_freq/clock_div)).
     r.write_pulses((1, 20, 2, 40), start=0) # Send 0 for 100ns, 1 for 2000ns, 0 for 200ns, 1 for 4000ns
 
+Sigma-Delta
+-----------
+
+An ESP32-specific peripheral for generating hardware sigma-delta modulated output
+on any GPIO. See :ref:`esp32.SigmaDelta <esp32.SigmaDelta>` for details. Usage is::
+
+    import esp32
+    from machine import Pin
+
+    sd = esp32.SigmaDelta(0, pin=Pin(4), duty=0, prescale=80)
+    sd.duty(20)  # -128 to 127
+    sd.prescale(160)  # 0 to 255
+    sd.deinit()
+
 OneWire driver
 --------------
 
diff --git a/docs/library/esp32.rst b/docs/library/esp32.rst
@@ -173,6 +173,45 @@ For more details see Espressif's `ESP-IDF RMT documentation.
     stream starts at 0 or 1.
 
 
+Sigma-Delta
+-----------
+
+ESP32 has a second-order sigma-delta modulation module. Each of the eight
+independent channels (0-7) are capable of outputting a binary hardware generated
+signal with the sigma-delta modulation::
+
+    import esp32
+    from machine import Pin
+
+    sd = esp32.SigmaDelta(3, pin=Pin(4), duty=0, prescale=80)
+    sd  # SigmaDelta(channel=3, pin=4, duty=0, prescale=80)
+    sd.duty(90)
+    sd.prescale(8)
+    sd.deinit()
+
+For more details see Espressif's `ESP-IDF Sigma-delta documentation.
+<https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/sigmadelta.html>`_.
+
+.. class:: SigmaDelta(channel, \*, pin=None, duty=0, prescale=80)
+
+    This class provides access to the Sigma-Delta hardware signal generator.
+
+.. method:: SigmaDelta.duty(duty)
+
+    Set the duty of the output signal in the range -128 to 127. A zero value will
+    result in the output signal's duty of around 50%. Recommended range is -90 to 90.
+
+.. method:: SigmaDelta.prescale(prescale)
+
+    Set the sigma-delta channel's clock pre-scale value. The source clock is
+    APP_CLK, 80MHz. The clock frequency of the sigma-delta channel is
+    ``APP_CLK / pre_scale``.
+
+.. method:: SigmaDelta.deinit()
+
+    Disconnect the signal generator from the pin.
+
+
 Ultra-Low-Power co-processor
 ----------------------------
 
