1  Introduction
  2  ============
  3  
  4  .. image:: https://readthedocs.org/projects/adafruit-circuitpython-lifx/badge/?version=latest
  5      :target: https://circuitpython.readthedocs.io/projects/lifx/en/latest/
  6      :alt: Documentation Status
  7  
  8  .. image:: https://img.shields.io/discord/327254708534116352.svg
  9      :target: https://adafru.it/discord
 10      :alt: Discord
 11  
 12  .. image:: https://github.com/adafruit/Adafruit_CircuitPython_lifx/workflows/Build%20CI/badge.svg
 13      :target: https://github.com/adafruit/Adafruit_CircuitPython_lifx
 14      :alt: Build Status
 15  
 16  Control `LIFX devices <https://www.lifx.com>`_ over the internet using CircuitPython.
 17  
 18  Dependencies
 19  =============
 20  This driver depends on:
 21  
 22  * `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
 23  
 24  You'll also need a library to communicate with an ESP32 as a coprocessor using a WiFiManager object. This library supports connecting an ESP32 using either SPI or UART.
 25  
 26  * SPI: `Adafruit CircuitPython ESP32SPI <https://github.com/adafruit/Adafruit_CircuitPython_ESP32SPI>`_
 27  
 28  * UART: `Adafruit CircuitPython ESP_ATcontrol <https://github.com/adafruit/Adafruit_CircuitPython_ESP_ATcontrol>`_
 29  
 30  Please ensure all dependencies are available on the CircuitPython filesystem.
 31  This is easily achieved by downloading
 32  `the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
 33  
 34  Installing from PyPI
 35  --------------------
 36  On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
 37  PyPI <https://pypi.org/project/adafruit-circuitpython-lifx/>`_. To install for current user:
 38  
 39  .. code-block:: shell
 40  
 41      pip3 install adafruit-circuitpython-lifx
 42  
 43  To install system-wide (this may be required in some cases):
 44  
 45  .. code-block:: shell
 46  
 47      sudo pip3 install adafruit-circuitpython-lifx
 48  
 49  To install in a virtual environment in your current project:
 50  
 51  .. code-block:: shell
 52  
 53      mkdir project-name && cd project-name
 54      python3 -m venv .env
 55      source .env/bin/activate
 56      pip3 install adafruit-circuitpython-lifx
 57  
 58  Usage Example
 59  =============
 60  
 61  Initialize the LIFX API Client with a WiFiManager object and a
 62  `LIFX Personal Access token <https://cloud.lifx.com/settings>`_:
 63  
 64  .. code-block:: python
 65  
 66      lifx = adafruit_lifx.LIFX(wifi, lifx_token)
 67  
 68  Set a `LIFX selector <https://api.developer.lifx.com/docs/selectors>`_ label to identify the LIFX device to communicate with.
 69  
 70  .. code-block:: python
 71  
 72      lifx_light = 'label:Lamp'
 73  
 74  List all connected LIFX devices:
 75  
 76  .. code-block:: python
 77  
 78      lights = lifx.list_lights()
 79  
 80  Toggle the state of a LIFX device:
 81  
 82  .. code-block:: python
 83  
 84      lifx.toggle_light(lifx_light)
 85  
 86  Set the brightness of a LIFX device to 50%:
 87  
 88  .. code-block:: python
 89  
 90      lifx.set_brightness(lifx_light, 0.5)
 91  
 92  Set the color of a LIFX device to blue and the brightness to 100%:
 93  
 94  .. code-block:: python
 95  
 96      lifx.set_color(lifx_light, 'on', 'blue', brightness=1.0)
 97  
 98  Contributing
 99  ============
100  
101  Contributions are welcome! Please read our `Code of Conduct
102  <https://github.com/adafruit/Adafruit_CircuitPython_lifx/blob/master/CODE_OF_CONDUCT.md>`_
103  before contributing to help this project stay welcoming.
104  
105  Documentation
106  =============
107  
108  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>`_.