:mod:`multi_led` -- control of WS2812 LEDs
===========================================

.. module:: multi_led
	:synopsis: control of WS1812 LED strip

This module provides a driver for WS2812 LEDs.

.. note:: The module may be unavailable on some boards (either completely unavailable, or replaced by the :mod:`~signal_led` module).
	It is **not** recommended to create an instance of either class in this module. Instead, import ``RGB`` (an instance of the SmartLED class), or ``GLED`` and ``RLED`` instances of the SignalLED class from the ``rfid_utils`` module

class SmartLED
--------------

This class stores pixel data for a WS2812 LED strip connected to a pin.

.. class:: SmartLED(pin, count=1)

	Construct a SmartLED object. The parameters are:

		- *pin* is a GPIO number
		- *count* is the number of the LEDs in the strip

	.. method:: set(rgb, show=True)

		Set the RGB color of the first led in the strip. If ``show==True``, apply changes immediately. The ``rgb`` parameter may be an integer (``0xRRGGBB``), a string / a bytes-like object (``'#RRGGBB'`` or ``'#RGB'``), or a tuple of 3 integer values in the [0..255] range.

	.. method:: color(index, value=None, show=True)

		Get (if ``value==None``) or set the color component ``index`` of the led (the indices start from **zero**: ``0 - red``, ``1 - green``, ``2 - blue``). The ``value`` must be an integer in the range ``[0..255]``.

		The returned value is an integer in the same range representing the color component of the LED (the current one or the newly set).

	.. method:: led(index, clr)

		Creates and returns an instance of the SignalLED class. The instance will control the corresponding LED in the strip (no. ``index``) with the selected color. The format of the ``clr`` parameter is the same as outlined above.

	.. method:: __len__()

		Returns the number of LEDs in the strip (ref. to the ``count`` parameter of the constructor)

	.. method:: __getitem__(idx)

		Returns the color of the LED ``idx`` (the valid range for the ``idx`` value is ``[0..len()-1]``). The returned value is an integer (``0xRRGGBB``).

	.. method:: __setitem__(idx, value)

		Sets the color for the LED at *index*. The change is applied immediately. The format of the value must be the same as the one for the :meth:`~multi_led.SmartLED.set` method.

	.. method:: fill(value)

		Sets the color of each LED in the strip. This is a more effective version of::

			for i in range(len(instance)):
				instance.set(i, show=(i == len(instance) - 1))


class SignalLED
---------------

This class provides a wrapper over a single WS2812 LED, converting it into a virtual fixed-color LED.

.. note:: It is possible to create multiple instances of the SignaLED class that control the same LED. This will work as intended as long as only one virtual LED is switched on at a time. The :obj:`~rfid_utils.GLED` and :obj:`~rfid_utils.RLED` objects in the :mod:`~rfid_utils` are an example of such a case.

.. class:: SignalLED(parent, idx, color)

	Construct a SignalLED object

		- *parent* - an instance of the SmartLED class
		- *idx* - the index of the LED in the strip
		- *color* - this object's fixed color value (ref :meth:`~multi_led.SmartLED.set` for the format)

	.. method:: on()

		Switch the LED on

	.. method:: off()

		Switch the LED off

	.. property:: extended

		Read-only. Returns ``False``. This can be used to determine which module is being used: ``multi_led`` (this one, ``False``), or ``signal_led`` (will return ``True``).

	.. property:: enabled

		Getter: Returns the LED state.
		Setter: calls ``on()`` or ``off()`` respectively