MY9231/MY9291 LED driver documentation (#80)

* API documentation for MY9231/MY9291 LED driver component

* esphomeyaml documentation for MY9231/MY9291 LED driver component

* Corrections

* Create entry for MY9231 in esphomeyaml/index.rst

* Add a note about boot behaviour of MY9231.

* Add Sonoff B1 configuration example.

api/output/my9231.rst

@@ -0,0 +1,30 @@
+MY9231/MY9291 Output
+====================
+
+FloatOutput support for an MY9231/MY9291 LED driver chain.
+
+Example Usage
+-------------
+
+.. code-block:: cpp
+
+    // Create the MY9231 Output hub connected to GPIO12 (DI pin) and
+    // GPIO14 (DCKI pin).
+    auto *pmy9231 = App.make_my9231_component(12, 14);
+
+.. cpp:namespace:: nullptr
+
+See :cpp:func:`Application::make_my9231_component`.
+
+API Reference
+-------------
+
+.. cpp:namespace:: nullptr
+
+MY9231OutputComponent
+**********************
+
+.. doxygenclass:: output::MY9231OutputComponent
+    :members:
+    :protected-members:
+    :undoc-members:

esphomeyaml/components/light/monochromatic.rst

@@ -58,6 +58,7 @@ See Also
 - :doc:`/esphomeyaml/components/output/ledc`
 - :doc:`/esphomeyaml/components/output/esp8266_pwm`
 - :doc:`/esphomeyaml/components/output/pca9685`
+- :doc:`/esphomeyaml/components/output/my9231`
 - :doc:`API Reference </api/light/index>`
 - `Edit this page on GitHub <https://github.com/OttoWinter/esphomedocs/blob/current/esphomeyaml/components/light/monochromatic.rst>`__
 

esphomeyaml/components/light/rgb.rst

@@ -60,6 +60,7 @@ See Also
 - :doc:`/esphomeyaml/components/output/ledc`
 - :doc:`/esphomeyaml/components/output/esp8266_pwm`
 - :doc:`/esphomeyaml/components/output/pca9685`
+- :doc:`/esphomeyaml/components/output/my9231`
 - :doc:`API Reference </api/light/index>`
 - `Edit this page on GitHub <https://github.com/OttoWinter/esphomedocs/blob/current/esphomeyaml/components/light/rgb.rst>`__
 

esphomeyaml/components/light/rgbw.rst

@@ -47,6 +47,7 @@ See Also
 - :doc:`/esphomeyaml/components/output/ledc`
 - :doc:`/esphomeyaml/components/output/esp8266_pwm`
 - :doc:`/esphomeyaml/components/output/pca9685`
+- :doc:`/esphomeyaml/components/output/my9231`
 - :doc:`API Reference </api/light/index>`
 - `Edit this page on GitHub <https://github.com/OttoWinter/esphomedocs/blob/current/esphomeyaml/components/light/rgbw.rst>`__
 

esphomeyaml/components/light/rgbww.rst

@@ -58,6 +58,7 @@ See Also
 - :doc:`/esphomeyaml/components/output/ledc`
 - :doc:`/esphomeyaml/components/output/esp8266_pwm`
 - :doc:`/esphomeyaml/components/output/pca9685`
+- :doc:`/esphomeyaml/components/output/my9231`
 - :doc:`API Reference </api/light/index>`
 - `Edit this page on GitHub <https://github.com/OttoWinter/esphomedocs/blob/current/esphomeyaml/components/light/rgbww.rst>`__
 

esphomeyaml/components/my9231.rst

@@ -0,0 +1,144 @@
+MY9231/MY9291 LED driver 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
+esphomelib. 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
+:doc:`individual output channels </esphomeyaml/components/output/my9231>`.
+
+.. 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 esphomelib 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.
+
+.. code:: 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:`/esphomeyaml/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:: yaml
+
+    esphomeyaml:
+      name: <NAME_OF_NODE>
+      platform: ESP8266
+      board: esp01_1m
+      board_flash_mode: dout
+
+    wifi:
+      ssid: <YOUR_SSID>
+      password: <YOUR_WIFI_PASSPHRASE>
+
+    mqtt:
+      broker: <YOUR_MQTT_BROKER>
+      username: <YOUR_MQTT_USERNAME>
+      password: <YOUR_MQTT_PASSWORD>
+
+    logger:
+
+    ota:
+      password: <YOUR_OTA_PASSWORD>
+
+    my9231:
+     data_pin: GPIO12
+     clock_pin: GPIO14
+     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
+
+See Also
+--------
+
+- :doc:`output/my9231`
+- :doc:`API Reference </api/output/my9231>`
+- `Edit this page on GitHub <https://github.com/OttoWinter/esphomedocs/blob/current/esphomeyaml/components/my9231.rst>`__
+
+.. disqus::

esphomeyaml/components/output/my9231.rst

@@ -0,0 +1,45 @@
+MY9231/MY9291 Output
+====================
+
+The MY931/MY9291 output component exposes a MY931/MY9291 channel of a global
+:doc:`/esphomeyaml/components/my9231` as a float output.
+
+.. code:: 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
+  :doc:`/esphomeyaml/components/my9231`.
+  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:`/esphomeyaml/components/my9231`
+- :doc:`/esphomeyaml/components/output/index`
+- :doc:`/esphomeyaml/components/output/esp8266_pwm`
+- :doc:`/esphomeyaml/components/output/ledc`
+- :doc:`/esphomeyaml/components/light/monochromatic`
+- :doc:`/esphomeyaml/components/fan/speed`
+- :doc:`/esphomeyaml/components/power_supply`
+- :doc:`API Reference </api/output/my9231>`
+- `MY92XX LED driver library for Arduino AVR and ESP8266 <https://github.com/xoseperez/my92xx>`__ by `@xoseperez <https://github.com/xoseperez>`__
+- `Edit this page on GitHub <https://github.com/OttoWinter/esphomedocs/blob/current/esphomeyaml/components/output/my9231.rst>`__
+
+.. disqus::

esphomeyaml/images/my9231.svg

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   viewBox="0 0 240 60"
+   height="60"
+   width="240"
+   xml:space="preserve"
+   id="svg2"
+   version="1.1"><metadata
+     id="metadata8"><rdf:RDF><cc:Work
+         rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" /></cc:Work></rdf:RDF></metadata><defs
+     id="defs6" /><g
+     transform="matrix(1.3333333,0,0,-1.3333333,0,60)"
+     id="g10"><g
+       transform="scale(0.1)"
+       id="g12"><path
+         id="path14"
+         style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none"
+         d="M 148.418,445 H 1651.58 c 77.32,0 140,-62.68 140,-140 V 150 c 0,-77.3203 -62.68,-140 -140,-140 H 148.418 C 71.0977,10 8.41797,72.6797 8.41797,150 v 155 c 0,77.32 62.67973,140 140.00003,140 z" /><path
+         id="path16"
+         style="fill:none;stroke:#000000;stroke-width:10;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1"
+         d="M 148.418,445 H 1651.58 c 77.32,0 140,-62.68 140,-140 V 150 c 0,-77.3203 -62.68,-140 -140,-140 H 148.418 C 71.0977,10 8.41797,72.6797 8.41797,150 v 155 c 0,77.32 62.67973,140 140.00003,140 z" /><g
+         transform="scale(10)"
+         id="g18"><text
+           id="text22"
+           style="font-variant:normal;font-weight:900;font-size:35px;font-family:Montserrat;-inkscape-font-specification:Montserrat-Black;writing-mode:lr-tb;fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none"
+           transform="matrix(1,0,0,-1,12.1375,10.25)"><tspan
+             id="tspan20"
+             y="0"
+             x="0 36.355 63.539997 89.290001 113.57 138.095">MY9231</tspan></text>
+</g></g></g></svg>

esphomeyaml/index.rst

@@ -165,6 +165,7 @@ Output Components
     GPIO Output, components/output/gpio, pin.svg
     ESP32 LEDC, components/output/ledc, pwm.png
     PCA9685, components/output/pca9685, pca9685.jpg
+    MY9231/MY9291, components/output/my9231, my9231.svg
 
 Light Components
 ----------------
@@ -259,6 +260,7 @@ Misc Components
     RDM6300, components/rdm6300, rdm6300.jpg
     Time, components/time, clock-outline.svg
     Stepper, components/stepper/index, stepper.svg
+    MY9231/MY9291 LED driver, components/my9231, my9231.svg
 
 .. _cookbook: