1  
  2  Adafruit CircuitPython NeoPixel
  3  ===============================
  4  
  5  .. image:: https://readthedocs.org/projects/adafruit-circuitpython-neopixel/badge/?version=latest
  6      :target: https://circuitpython.readthedocs.io/projects/neopixel/en/latest/
  7      :alt: Documentation Status
  8  
  9  .. image :: https://img.shields.io/discord/327254708534116352.svg
 10      :target: https://adafru.it/discord
 11      :alt: Discord
 12  
 13  .. image:: https://github.com/adafruit/Adafruit_CircuitPython_NeoPixel/workflows/Build%20CI/badge.svg
 14      :target: https://github.com/adafruit/Adafruit_CircuitPython_NeoPixel/actions/
 15      :alt: Build Status
 16  
 17  Higher level NeoPixel driver that presents the strip as a sequence. This is a
 18  supercharged version of the original MicroPython driver. Its now more like a
 19  normal Python sequence and features slice support, ``repr`` and ``len`` support.
 20  
 21  Colors are stored as tuples by default. However, you can also use int hex syntax
 22  to set values similar to colors on the web. For example, ``0x100000`` (``#100000``
 23  on the web) is equivalent to ``(0x10, 0, 0)``.
 24  
 25  .. note:: The int hex API represents the brightness of the white pixel when
 26    present by setting the RGB channels to identical values. For example, full
 27    white is 0xffffff but is actually (0, 0, 0, 0xff) in the tuple syntax. Setting
 28    a pixel value with an int will use the white pixel if the RGB channels are
 29    identical. For full, independent, control of each color component use the
 30    tuple syntax.
 31  
 32  Dependencies
 33  =============
 34  This driver depends on:
 35  
 36  * `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
 37  
 38  Please ensure all dependencies are available on the CircuitPython filesystem.
 39  This is easily achieved by downloading
 40  `the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
 41  
 42  Installing from PyPI
 43  ====================
 44  
 45  On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
 46  PyPI <https://pypi.org/project/adafruit-circuitpython-neopixel/>`_. To install for current user:
 47  
 48  .. code-block:: shell
 49  
 50      pip3 install adafruit-circuitpython-neopixel
 51  
 52  To install system-wide (this may be required in some cases):
 53  
 54  .. code-block:: shell
 55  
 56      sudo pip3 install adafruit-circuitpython-neopixel
 57  
 58  To install in a virtual environment in your current project:
 59  
 60  .. code-block:: shell
 61  
 62      mkdir project-name && cd project-name
 63      python3 -m venv .env
 64      source .env/bin/activate
 65      pip3 install adafruit-circuitpython-neopixel
 66  
 67  Usage Example
 68  =============
 69  
 70  This example demonstrates the library with the single built-in NeoPixel on the
 71  `Feather M0 Express <https://www.adafruit.com/product/3403>`_ and
 72  `Metro M0 Express <https://www.adafruit.com/product/3505>`_.
 73  
 74  .. code-block:: python
 75  
 76      import board
 77      import neopixel
 78  
 79      pixels = neopixel.NeoPixel(board.NEOPIXEL, 1)
 80      pixels[0] = (10, 0, 0)
 81  
 82  This example demonstrates the library with the ten built-in NeoPixels on the
 83  `Circuit Playground Express <https://www.adafruit.com/product/3333>`_. It turns
 84  off ``auto_write`` so that all pixels are updated at once when the ``show``
 85  method is called.
 86  
 87  .. code-block:: python
 88  
 89      import board
 90      import neopixel
 91  
 92      pixels = neopixel.NeoPixel(board.NEOPIXEL, 10, auto_write=False)
 93      pixels[0] = (10, 0, 0)
 94      pixels[9] = (0, 10, 0)
 95      pixels.show()
 96  
 97  This example demonstrates using a single NeoPixel tied to a GPIO pin and with
 98  a ``pixel_order`` to specify the color channel order. Note that ``bpp`` does not
 99  need to be specified as it is computed from the supplied ``pixel_order``.
100  
101  .. code-block:: python
102  
103      import board
104      import neopixel
105  
106      pixel = neopixel.NeoPixel(board.D0, 1, pixel_order=neopixel.RGBW)
107      pixel[0] = (30, 0, 20, 10)
108  
109  
110  Contributing
111  ============
112  
113  Contributions are welcome! Please read our `Code of Conduct
114  <https://github.com/adafruit/Adafruit_CircuitPython_NeoPixel/blob/master/CODE_OF_CONDUCT.md>`_
115  before contributing to help this project stay welcoming.
116  
117  Documentation
118  =============
119  
120  For information on building library documentation, please check out `this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.