esphome-docs/components/output/my9231.rst

MY9231/MY9291 LED driver
========================

.. seo::
    :description: Instructions for setting up MY9231 and MY9291 LED drives in ESPHome.
    :image: my9231.svg
    :keywords: MY9231, MY9291, Sonoff B1, Ai-thinker AiLight WiFi light bulb, Arilux E27 Smart Bulb

.. _my9231-component:

Component/Hub
-------------

The MY9231/MY9291 component represents a MY9231/MY9291 LED driver chain
(`MY9231 description <http://www.my-semi.com.tw/file/MY9231_BF_0.91.pdf>`__,
`MY9291 description <http://www.my-semi.com.tw/file/MY9291_BF_0.91.pdf>`__) in
ESPHome. Communication is done with two GPIO pins (DI and DCKI) and multiple
driver chips can be chained. There are two models with different number of
output channels (MY9291 with 4 channels and MY9231 with 3 channels). They are
popular driver chips used in smart light bulbs:

- Sonoff B1 (MY9231)
- Ai-Thinker AiLight WiFi light bulb (MY9291)
- Arilux E27 Smart Bulb (MY9231)

To use the channels of this components, you first need to setup the
global ``my9231`` hub and give it an id, and then define the
:ref:`individual output channels <my9231-output>`.

.. code-block:: yaml

    # Example configuration entry
    my9231:
      - data_pin: GPIOXX
        clock_pin: GPIOXX


Configuration variables:
************************

-  **data_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin which DI is connected
   to.
-  **clock_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin which DCKI is
   connected to.
-  **num_channels** (*Optional*, int): Total number of channels of the whole
   chain. Must be in range from 3 to 1020. Defaults to 6.
-  **num_chips** (*Optional*, int): Number of chips in the chain. Must be
   in range from 1 to 255. Defaults to 2.
-  **bit_depth** (*Optional*, int): The bit depth to use for all output
   channels in this chain. Must be one of 8, 12, 14 or 16. Defaults to 16.
-  **id** (*Optional*, :ref:`config-id`): The id to use for
   this ``my9231`` component. Use this if you have multiple MY9231/MY9291 chains
   connected at the same time.


.. _my9231-output:

Output
------

The MY931/MY9291 output component exposes a MY931/MY9291 channel of a global
:ref:`my9231-component` as a float output.

.. code-block:: yaml

    # Individual outputs
    output:
      - platform: my9231
        id: 'my9231_output1'
        channel: 0

Configuration variables:
************************

- **id** (**Required**, :ref:`config-id`): The id to use for this output component.
- **channel** (**Required**, int): Chose the channel of the MY9231/MY9291 chain of
  this output component. Channel 0 is the most close channel.
- **my9231_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the
  :ref:`my9231-component`.
  Use this if you have multiple MY9231/MY9291 chains you want to use at the same time.
- All other options from :ref:`Output <config-output>`.


Sonoff B1 configuration example
-------------------------------

This component can be used with a Sonoff B1 smart light bulb. To flash
the Sonoff B1, open the plastic cover and connect/solder wires to the
PCB pads (3.3V, RX, TX, GND, GPIO0). If you connect GPIO0 to GND
during power up, the device enters flash mode. All LEDs are connected to a
chain of two MY9321 chips that are connected to GPIO12 and GPIO14. A
complete configuration for a Sonoff B1 looks like:

.. code-block:: yaml

    esphome:
      name: GPIOXX

    esp8266:
      board: esp01_1m

    wifi:
      ssid: !secret wifi_ssid
      password: !secret wifi_password

    api:

    logger:

    ota:

    my9231:
      data_pin: GPIO12  # GPIO13 for AiLight
      clock_pin: GPIO14  # GPIO15 for AiLight
      num_channels: 6
      num_chips: 2
      bit_depth: 8

    output:
      - platform: my9231
        id: output_blue
        channel: 0
      - platform: my9231
        id: output_red
        channel: 1
      - platform: my9231
        id: output_green
        channel: 2
      - platform: my9231
        id: output_warm_white
        channel: 4
      - platform: my9231
        id: output_cold_white
        channel: 5

    light:
      - platform: rgbww
        name: GPIOXX
        red: output_red
        green: output_green
        blue: output_blue
        cold_white: output_cold_white
        warm_white: output_warm_white
        cold_white_color_temperature: 6500 K
        warm_white_color_temperature: 2800 K

And here is a complete configuration for the AiThinker AiLight:

.. code-block:: yaml

    esphome:
      name: GPIOXX

    esp8266:
      board: esp01_1m

    wifi:
      ssid: !secret wifi_ssid
      password: !secret wifi_password

    api:

    logger:

    ota:

    my9231:
      data_pin: GPIO13
      clock_pin: GPIO15
      num_channels: 4
      num_chips: 1
      bit_depth: 8

    output:
      - platform: my9231
        id: output_red
        channel: 3
      - platform: my9231
        id: output_green
        channel: 2
      - platform: my9231
        id: output_blue
        channel: 1
      - platform: my9231
        id: output_cold_white
        channel: 0

    light:
      - platform: rgbw
        name: GPIOXX
        red: output_red
        green: output_green
        blue: output_blue
        white: output_cold_white


See Also
--------

- :doc:`/components/output/index`
- :doc:`/components/output/esp8266_pwm`
- :doc:`/components/output/ledc`
- :doc:`/components/light/monochromatic`
- :doc:`/components/fan/speed`
- :doc:`/components/power_supply`
- :apiref:`my9231/my9231.h`
- `MY92XX LED driver library for Arduino AVR and ESP8266 <https://github.com/xoseperez/my92xx>`__ by `@xoseperez <https://github.com/xoseperez>`__
- :ghedit:`Edit`