1  # The MIT License (MIT)
  2  #
  3  # Copyright (c) 2016 Damien P. George
  4  # Copyright (c) 2017 Scott Shawcroft for Adafruit Industries
  5  # Copyright (c) 2019 Carter Nelson
  6  # Copyright (c) 2019 Roy Hooper
  7  #
  8  # Permission is hereby granted, free of charge, to any person obtaining a copy
  9  # of this software and associated documentation files (the "Software"), to deal
 10  # in the Software without restriction, including without limitation the rights
 11  # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 12  # copies of the Software, and to permit persons to whom the Software is
 13  # furnished to do so, subject to the following conditions:
 14  #
 15  # The above copyright notice and this permission notice shall be included in
 16  # all copies or substantial portions of the Software.
 17  #
 18  # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 19  # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 20  # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 21  # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 22  # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 23  # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 24  # THE SOFTWARE.
 25  
 26  """
 27  `neopixel` - NeoPixel strip driver
 28  ====================================================
 29  
 30  * Author(s): Damien P. George, Scott Shawcroft, Carter Nelson, Roy Hooper
 31  """
 32  
 33  # pylint: disable=ungrouped-imports
 34  import sys
 35  import digitalio
 36  from neopixel_write import neopixel_write
 37  
 38  if sys.implementation.version[0] < 5:
 39      import adafruit_pypixelbuf as _pixelbuf
 40  else:
 41      try:
 42          import _pixelbuf
 43      except ImportError:
 44          import adafruit_pypixelbuf as _pixelbuf
 45  
 46  
 47  __version__ = "0.0.0-auto.0"
 48  __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_NeoPixel.git"
 49  
 50  
 51  # Pixel color order constants
 52  RGB = "RGB"
 53  """Red Green Blue"""
 54  GRB = "GRB"
 55  """Green Red Blue"""
 56  RGBW = "RGBW"
 57  """Red Green Blue White"""
 58  GRBW = "GRBW"
 59  """Green Red Blue White"""
 60  
 61  
 62  class NeoPixel(_pixelbuf.PixelBuf):
 63      """
 64      A sequence of neopixels.
 65  
 66      :param ~microcontroller.Pin pin: The pin to output neopixel data on.
 67      :param int n: The number of neopixels in the chain
 68      :param int bpp: Bytes per pixel. 3 for RGB and 4 for RGBW pixels.
 69      :param float brightness: Brightness of the pixels between 0.0 and 1.0 where 1.0 is full
 70        brightness
 71      :param bool auto_write: True if the neopixels should immediately change when set. If False,
 72        `show` must be called explicitly.
 73      :param str: Set the pixel color channel order. GRBW is set by default.
 74  
 75      Example for Circuit Playground Express:
 76  
 77      .. code-block:: python
 78  
 79          import neopixel
 80          from board import *
 81  
 82          RED = 0x100000 # (0x10, 0, 0) also works
 83  
 84          pixels = neopixel.NeoPixel(NEOPIXEL, 10)
 85          for i in range(len(pixels)):
 86              pixels[i] = RED
 87  
 88      Example for Circuit Playground Express setting every other pixel red using a slice:
 89  
 90      .. code-block:: python
 91  
 92          import neopixel
 93          from board import *
 94          import time
 95  
 96          RED = 0x100000 # (0x10, 0, 0) also works
 97  
 98          # Using ``with`` ensures pixels are cleared after we're done.
 99          with neopixel.NeoPixel(NEOPIXEL, 10) as pixels:
100              pixels[::2] = [RED] * (len(pixels) // 2)
101              time.sleep(2)
102  
103      .. py:method:: NeoPixel.show()
104  
105          Shows the new colors on the pixels themselves if they haven't already
106          been autowritten.
107  
108          The colors may or may not be showing after this function returns because
109          it may be done asynchronously.
110  
111      .. py:method:: NeoPixel.fill(color)
112  
113          Colors all pixels the given ***color***.
114  
115      .. py:attribute:: brightness
116  
117          Overall brightness of the pixel (0 to 1.0)
118  
119      """
120  
121      def __init__(
122          self, pin, n, *, bpp=3, brightness=1.0, auto_write=True, pixel_order=None
123      ):
124          if not pixel_order:
125              pixel_order = GRB if bpp == 3 else GRBW
126          else:
127              if isinstance(pixel_order, tuple):
128                  order_list = [RGBW[order] for order in pixel_order]
129                  pixel_order = "".join(order_list)
130  
131          super().__init__(
132              n, brightness=brightness, byteorder=pixel_order, auto_write=auto_write
133          )
134  
135          self.pin = digitalio.DigitalInOut(pin)
136          self.pin.direction = digitalio.Direction.OUTPUT
137  
138      def deinit(self):
139          """Blank out the NeoPixels and release the pin."""
140          self.fill(0)
141          self.show()
142          self.pin.deinit()
143  
144      def __enter__(self):
145          return self
146  
147      def __exit__(self, exception_type, exception_value, traceback):
148          self.deinit()
149  
150      def __repr__(self):
151          return "[" + ", ".join([str(x) for x in self]) + "]"
152  
153      @property
154      def n(self):
155          """
156          The number of neopixels in the chain (read-only)
157          """
158          return len(self)
159  
160      def write(self):
161          """.. deprecated: 1.0.0
162  
163               Use ``show`` instead. It matches Micro:Bit and Arduino APIs."""
164          self.show()
165  
166      def _transmit(self, buffer):
167          neopixel_write(self.pin, buffer)