1  Introduction
  2  ============
  3  
  4  .. image:: https://readthedocs.org/projects/adafruit-circuitpython-ble_magic_light/badge/?version=latest
  5      :target: https://circuitpython.readthedocs.io/projects/ble_magic_light/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_BLE_Magic_Light/workflows/Build%20CI/badge.svg
 13      :target: https://github.com/adafruit/Adafruit_CircuitPython_BLE_Magic_Light/actions
 14      :alt: Build Status
 15  
 16  BLE service for Magic Light BLE RGB bulbs. Available from Amazon
 17  `here <https://www.amazon.com/gp/product/B073S1KV4F>`_.
 18  
 19  
 20  Dependencies
 21  =============
 22  This driver depends on:
 23  
 24  * `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
 25  
 26  Please ensure all dependencies are available on the CircuitPython filesystem.
 27  This is easily achieved by downloading
 28  `the Adafruit library and driver bundle <https://circuitpython.org/libraries>`_.
 29  
 30  Installing from PyPI
 31  =====================
 32  .. note:: This library is not available on PyPI yet. Install documentation is included
 33     as a standard element. Stay tuned for PyPI availability!
 34  
 35  On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
 36  PyPI <https://pypi.org/project/adafruit-circuitpython-ble_magic_light/>`_. To install for current user:
 37  
 38  .. code-block:: shell
 39  
 40      pip3 install adafruit-circuitpython-ble-magic-light
 41  
 42  To install system-wide (this may be required in some cases):
 43  
 44  .. code-block:: shell
 45  
 46      sudo pip3 install adafruit-circuitpython-ble-magic-light
 47  
 48  To install in a virtual environment in your current project:
 49  
 50  .. code-block:: shell
 51  
 52      mkdir project-name && cd project-name
 53      python3 -m venv .env
 54      source .env/bin/activate
 55      pip3 install adafruit-circuitpython-ble-magic-light
 56  
 57  Usage Example
 58  =============
 59  
 60  .. code:: python
 61  
 62      """This demo connects to a magic light and has it do a color wheel."""
 63      import adafruit_ble
 64      import _bleio
 65  
 66      from adafruit_ble.advertising.standard import ProvideServicesAdvertisement
 67      from adafruit_ble_magic_light import MagicLightService
 68  
 69      def find_connection():
 70          for connection in radio.connections:
 71              if MagicLightService not in connection:
 72                  continue
 73              return connection, connection[MagicLightService]
 74          return None, None
 75  
 76      # Start advertising before messing with the display so that we can connect immediately.
 77      radio = adafruit_ble.BLERadio()
 78  
 79      def wheel(pos):
 80          # Input a value 0 to 255 to get a color value.
 81          # The colours are a transition r - g - b - back to r.
 82          if pos < 0 or pos > 255:
 83              return (0, 0, 0)
 84          if pos < 85:
 85              return (255 - pos * 3, pos * 3, 0)
 86          if pos < 170:
 87              pos -= 85
 88              return (0, 255 - pos * 3, pos * 3)
 89          pos -= 170
 90          return (pos * 3, 0, 255 - pos * 3)
 91  
 92      active_connection, pixels = find_connection()
 93      current_notification = None
 94      app_icon_file = None
 95      while True:
 96          if not active_connection:
 97              print("Scanning for Magic Light")
 98              for scan in radio.start_scan(ProvideServicesAdvertisement):
 99                  if MagicLightService in scan.services:
100                      active_connection = radio.connect(scan)
101                      try:
102                          pixels = active_connection[MagicLightService]
103                      except _bleio.ConnectionError:
104                          print("disconnected")
105                          continue
106                      break
107              radio.stop_scan()
108  
109          i = 0
110          while active_connection.connected:
111              pixels[0] = wheel(i % 256)
112              i += 1
113  
114          active_connection = None
115  
116  Contributing
117  ============
118  
119  Contributions are welcome! Please read our `Code of Conduct
120  <https://github.com/adafruit/Adafruit_CircuitPython_BLE_Magic_Light/blob/master/CODE_OF_CONDUCT.md>`_
121  before contributing to help this project stay welcoming.
122  
123  Documentation
124  =============
125  
126  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>`_.