From 53145c4c5f10c3e44ffe174b1e6968792f17ea3a Mon Sep 17 00:00:00 2001
From: Jim Mussared <jim.mussared@gmail.com>
Date: Wed, 11 Aug 2021 16:06:11 +1000
Subject: [PATCH] docs: Add docs for machine.bitstream and neopixel module.

Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
---
 docs/library/index.rst    |  1 +
 docs/library/machine.rst  | 22 ++++++++++++
 docs/library/neopixel.rst | 73 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 96 insertions(+)
 create mode 100644 docs/library/neopixel.rst

diff --git a/docs/library/index.rst b/docs/library/index.rst
index c69050267a..013ff8937d 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -92,6 +92,7 @@ the following libraries.
    framebuf.rst
    machine.rst
    micropython.rst
+   neopixel.rst
    network.rst
    uctypes.rst
 
diff --git a/docs/library/machine.rst b/docs/library/machine.rst
index 26f99680a0..c2a6b39001 100644
--- a/docs/library/machine.rst
+++ b/docs/library/machine.rst
@@ -137,6 +137,28 @@ Miscellaneous functions
    above. The timeout is the same for both cases and given by *timeout_us* (which
    is in microseconds).
 
+.. function:: bitstream(pin, encoding, timing, data, /)
+
+   Transmits *data* by bit-banging the specified *pin*. The *encoding* argument
+   specifies how the bits are encoded, and *timing* is an encoding-specific timing
+   specification.
+
+   The supported encodings are:
+
+     - ``0`` for "high low" pulse duration modulation. This will transmit 0 and
+       1 bits as timed pulses, starting with the most significant bit.
+       The *timing* must be a four-tuple of nanoseconds in the format
+       ``(high_time_0, low_time_0, high_time_1, low_time_1)``. For example,
+       ``(400, 850, 800, 450)`` is the timing specification for WS2812 RGB LEDs
+       at 800kHz.
+
+   The accuracy of the timing varies between ports. On Cortex M0 at 48MHz, it is
+   at best +/- 120ns, however on faster MCUs (ESP8266, ESP32, STM32, Pyboard), it
+   will be closer to +/-30ns.
+
+   .. note:: For controlling WS2812 / NeoPixel strips, see the :mod:`neopixel`
+      module for a higher-level API.
+
 .. function:: rng()
 
    Return a 24-bit software generated random number.
diff --git a/docs/library/neopixel.rst b/docs/library/neopixel.rst
new file mode 100644
index 0000000000..1b37f088ba
--- /dev/null
+++ b/docs/library/neopixel.rst
@@ -0,0 +1,73 @@
+:mod:`neopixel` --- control of WS2812 / NeoPixel LEDs
+=====================================================
+
+.. module:: neopixel
+   :synopsis: control of WS2812 / NeoPixel LEDs
+
+This module provides a driver for WS2818 / NeoPixel LEDs.
+
+.. note:: This module is only included by default on the ESP8266 and ESP32
+   ports. On STM32 / Pyboard, you can `download the module
+   <https://github.com/micropython/micropython/blob/master/drivers/neopixel/neopixel.py>`_
+   and copy it to the filesystem.
+
+class NeoPixel
+--------------
+
+This class stores pixel data for a WS2812 LED strip connected to a pin. The
+application should set pixel data and then call :meth:`NeoPixel.write`
+when it is ready to update the strip.
+
+For example::
+
+    import neopixel
+
+    # 32 LED strip connected to X8.
+    p = machine.Pin.board.X8
+    n = neopixel.NeoPixel(p, 32)
+
+    # Draw a red gradient.
+    for i in range(32):
+        n[i] = (i * 8, 0, 0)
+
+    # Update the strip.
+    n.write()
+
+Constructors
+------------
+
+.. class:: NeoPixel(pin, n, *, bpp=3, timing=1)
+
+    Construct an NeoPixel object.  The parameters are:
+
+        - *pin* is a machine.Pin instance.
+        - *n* is the number of LEDs in the strip.
+        - *bpp* is 3 for RGB LEDs, and 4 for RGBW LEDs.
+        - *timing* is 0 for 400KHz, and 1 for 800kHz LEDs (most are 800kHz).
+
+Pixel access methods
+--------------------
+
+.. method:: NeoPixel.fill(pixel)
+
+    Sets the value of all pixels to the specified *pixel* value (i.e. an
+    RGB/RGBW tuple).
+
+.. method:: NeoPixel.__len__()
+
+    Returns the number of LEDs in the strip.
+
+.. method:: NeoPixel.__setitem__(index, val)
+
+    Set the pixel at *index* to the value, which is an RGB/RGBW tuple.
+
+.. method:: NeoPixel.__getitem__(index)
+
+    Returns the pixel at *index* as an RGB/RGBW tuple.
+
+Output methods
+--------------
+
+.. method:: NeoPixel.write()
+
+    Writes the current pixel data to the strip.