:mod:`signal_led` -- control if WS2812 LEDs
============================================

.. module:: signal_led
	:synopsis: control of a single WS2812 LED

This module provides a simplified driver for a single WS2812 LED

.. note:: The module may be unavailable on some boards (either completely unavailable, or replaced by the :mod:`~multi_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 connected to a pin.

.. class:: SmartLED(pin)

	Construct a SmartLED object. The parameters are:

		- *pin* is a GPIO number

	.. 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(clr)

		Creates and returns an instance of the SignalLED class. The instance will control the selected color of the LED. The format of the ``clr`` parameter is the same as outlined above.

	.. method:: __len__()

		Returns the number of LEDs in the strip (``1`` for this module).

	.. method:: __getitem__(idx)

		Returns the color of the LED ``idx`` (the only valid value is **zero**). 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:`~signal_led.SmartLED.set` method.

	.. method:: fill(value)

		Sets the color of each LED in the strip. This is effectively the same as ``set(value, show=True)`` (kept for compatibility with the ``multi_led`` module).


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, color)

	Construct a SignalLED object

		- *parent* - an instance of the SmartLED class
		- *color* - this object's fixed color value (ref :meth:`~signal_led.SmartLED.set` for the format)

		Each instance occupies one hardware timer. If no more timers are available, a ``RuntimeError`` is raised.

	.. method:: on()

		Switch the LED on

	.. method:: off()

		Switch the LED off. Also deactivates the "glow", the "heartbeat", and the "blink" effects.

	.. property:: extended

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

	.. property:: enabled

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

	.. method:: blink(ms=500)

		Starts the timer, that will switch the LED on and off at a specified interval.

	.. method:: heartbeat()

		Starts the timer with the heartbeat effect. Deactivates all the other effects.

	.. method:: glow()

		Starts the timer with the glow effect. Deactivates all the other effects.