From 411a41e6967e060b9a223f03edddbaae59219ec1 Mon Sep 17 00:00:00 2001 From: puuu Date: Wed, 14 Nov 2018 00:51:42 +0900 Subject: [PATCH] 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 | 30 ++++ .../components/light/monochromatic.rst | 1 + esphomeyaml/components/light/rgb.rst | 1 + esphomeyaml/components/light/rgbw.rst | 1 + esphomeyaml/components/light/rgbww.rst | 1 + esphomeyaml/components/my9231.rst | 144 ++++++++++++++++++ esphomeyaml/components/output/my9231.rst | 45 ++++++ esphomeyaml/images/my9231.svg | 36 +++++ esphomeyaml/index.rst | 2 + 9 files changed, 261 insertions(+) create mode 100644 api/output/my9231.rst create mode 100644 esphomeyaml/components/my9231.rst create mode 100644 esphomeyaml/components/output/my9231.rst create mode 100644 esphomeyaml/images/my9231.svg diff --git a/api/output/my9231.rst b/api/output/my9231.rst new file mode 100644 index 000000000..c8e264eb8 --- /dev/null +++ b/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: diff --git a/esphomeyaml/components/light/monochromatic.rst b/esphomeyaml/components/light/monochromatic.rst index d9a06f12e..433d559d4 100644 --- a/esphomeyaml/components/light/monochromatic.rst +++ b/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 ` - `Edit this page on GitHub `__ diff --git a/esphomeyaml/components/light/rgb.rst b/esphomeyaml/components/light/rgb.rst index 3d1b963ed..99819c196 100644 --- a/esphomeyaml/components/light/rgb.rst +++ b/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 ` - `Edit this page on GitHub `__ diff --git a/esphomeyaml/components/light/rgbw.rst b/esphomeyaml/components/light/rgbw.rst index cae0bef39..86dca3215 100644 --- a/esphomeyaml/components/light/rgbw.rst +++ b/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 ` - `Edit this page on GitHub `__ diff --git a/esphomeyaml/components/light/rgbww.rst b/esphomeyaml/components/light/rgbww.rst index 7da2f364c..656007891 100644 --- a/esphomeyaml/components/light/rgbww.rst +++ b/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 ` - `Edit this page on GitHub `__ diff --git a/esphomeyaml/components/my9231.rst b/esphomeyaml/components/my9231.rst new file mode 100644 index 000000000..1d38e3796 --- /dev/null +++ b/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 `__, +`MY9291 description `__) 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 `. + +.. 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: + platform: ESP8266 + board: esp01_1m + board_flash_mode: dout + + wifi: + ssid: + password: + + mqtt: + broker: + username: + password: + + logger: + + 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: + 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 ` +- `Edit this page on GitHub `__ + +.. disqus:: diff --git a/esphomeyaml/components/output/my9231.rst b/esphomeyaml/components/output/my9231.rst new file mode 100644 index 000000000..55009f0f4 --- /dev/null +++ b/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 `. + +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 ` +- `MY92XX LED driver library for Arduino AVR and ESP8266 `__ by `@xoseperez `__ +- `Edit this page on GitHub `__ + +.. disqus:: diff --git a/esphomeyaml/images/my9231.svg b/esphomeyaml/images/my9231.svg new file mode 100644 index 000000000..a3d4e5a0e --- /dev/null +++ b/esphomeyaml/images/my9231.svg @@ -0,0 +1,36 @@ + +image/svg+xmlMY9231 + \ No newline at end of file diff --git a/esphomeyaml/index.rst b/esphomeyaml/index.rst index c8fbb7ca9..60fdb97e6 100644 --- a/esphomeyaml/index.rst +++ b/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: