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.png
    :keywords: MY9231, MY9291, Sonoff B1, Ai-thinker AiLight WiFi light bulb, Arilux E27 Smart Bulb

.. _my9231-component:

Component
---------

The MY9231/MY9291 component represents a MY9231/MY9291 LED diver 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 blubs:

- 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: GPIO12
        clock_pin: GPIO14

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

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

-  **data_pin** (**Required**, :ref:`config-pin_schema`): The pin which DI is connected
   to.
-  **clock_pin** (**Required**, :ref:`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_depths** (*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.
-  **update_on_boot** (*Optional*, boolean): Update/reset duty data at boot. Defaults to ``True``.
-  **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.

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

This component can be used with a Sonoff B1 smart light blub. 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. For more information
about flashing Sonoff devices, see:
:doc:`/devices/sonoff_s20`. 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: <NAME_OF_NODE>
      platform: ESP8266
      board: esp01_1m

    wifi:
      ssid: <YOUR_SSID>
      password: <YOUR_WIFI_PASSPHRASE>

    api:

    logger:

    ota:
      password: <YOUR_OTA_PASSWORD>

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

    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: <LIGHT_NAME>
        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

.. note::

    One of the features of the MY9231/MY9291 driver is that the chips
    remember their state after a power cycling. Unfortunately, the
    state of the driver can not be read. Therefore, if ESPHome can
    not restore the previous state, it will result in a mismatch of
    the driver output and the internal state (= MQTT state). So you
    can configure the behaviour on boot time:

    ``update_on_boot: True``
      On device power up/boot, the light may flash shortly, to the
      state before powering off.

    ``update_on_boot: False``
      On device power up/boot, the light show the last state, but the
      internal data will not reflect this state. Thus, the first fade
      is wrong, as well as the MQTT state.

.. _my9231-output:

Driver Output
-------------

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

.. code-block:: yaml

    # Example configuration entry
    my9231:
      - data_pin: GPIO12
        clock_pin: GPIO14

    # 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>`.

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:`output/my9231_output_component.h`
- `MY92XX LED driver library for Arduino AVR and ESP8266 <https://github.com/xoseperez/my92xx>`__ by `@xoseperez <https://github.com/xoseperez>`__
- :ghedit:`Edit`