diff --git a/components/light/images/sonoff_d1.jpg b/components/light/images/sonoff_d1.jpg new file mode 100644 index 000000000..547588ac1 Binary files /dev/null and b/components/light/images/sonoff_d1.jpg differ diff --git a/components/light/images/sonoff_d1_gpio0.jpg b/components/light/images/sonoff_d1_gpio0.jpg new file mode 100644 index 000000000..6e11cb1b9 Binary files /dev/null and b/components/light/images/sonoff_d1_gpio0.jpg differ diff --git a/components/light/images/sonoff_d1_serial.jpg b/components/light/images/sonoff_d1_serial.jpg new file mode 100644 index 000000000..a87a42786 Binary files /dev/null and b/components/light/images/sonoff_d1_serial.jpg differ diff --git a/components/light/sonoff_d1.rst b/components/light/sonoff_d1.rst new file mode 100644 index 000000000..75c4bc6ed --- /dev/null +++ b/components/light/sonoff_d1.rst @@ -0,0 +1,124 @@ +Sonoff D1 Dimmer +================ + +.. seo:: + :description: Instructions for setting up a Sonoff D1 dimmer switch. + :image: brightness-medium.svg + +The ``sonoff_d1`` light platform creates a simple brightness-only light for the +hardware found in `Sonoff D1 dimmer `__. Installations with Sonoff RM433 433MHz radio +remotes are also supported. Use this component to integrate Sonoff D1 dimmer into +ESPHome / Home Assistant ecosystem. + +.. figure:: images/sonoff_d1.jpg + :align: center + :width: 100.0% + + Sonoff D1 dimmer front and back view. Image by `ITEAD `__. + +Sonoff D1 uses another MCU for light dimming and handling of radio commands. +It's hooked up to ESP8266 via UART bus with default RX / TX pins being used on +ESP8266 side. Bi-directional symmetric request / response protocol is implemented +between ESP8266 and MCU. ``sonoff_d1`` component implements this protocol and +translates between HA light commands and serial messages. + +For detailed instructions on how to replace the stock firmware with ESPHome see :doc:`/devices/sonoff_s20`. +You will need to locate GPIO0 pin and serial port. Photos below should help. + +.. figure:: images/sonoff_d1_gpio0.jpg + :align: center + :width: 100.0% + + Photo of GPIO 0, images by `klotzma `__. +.. figure:: images/sonoff_d1_serial.jpg + :align: center + :width: 100.0% + + Photo of serial port pins, images by `klotzma `__. + +Before using this components make sure: + +- board is configured to ``esp8285`` +- :ref:`UART bus ` is configured with default RX / TX pins and 9600 baud rate +- :doc:`logger ` to the serial port is disabled by setting ``baud_rate`` to ``0`` +- in case you need light state restoration on power up, make sure ``restore_from_flash`` is set to ``true`` in the :doc:`ESP8266 platform ` + + +This component is useless for devices other than Sonoff D1 dimmer. + +.. code-block:: yaml + + + # Example configuration entry + esphome: + name: my-d1-dimmer + + # Restore from flash if you want to keep the last state at power up + esp8266: + board: esp8285 + restore_from_flash: true + + # Make sure your WiFi will connect + wifi: + ssid: "ssid" + password: "password" + + # Make sure logging is not using the serial port + logger: + baud_rate: 0 + + # Enable Home Assistant API + api: + + # Make sure you can upload new firmware OTA + ota: + + # D1 dimmer uses hardware serial port on the default pins @ 9600 bps + uart: + rx_pin: RX + tx_pin: TX + baud_rate: 9600 + + # And finally the light component + # gamma correction equal to zero gives linear scale, + # exactly what's needed for this device + light: + - platform: sonoff_d1 + use_rm433_remote: False + name: Sonoff D1 Dimmer + restore_mode: RESTORE_DEFAULT_OFF + gamma_correct: 0.0 + default_transition_length: 1s + + +Configuration variables +----------------------- + +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **name** (**Required**, string): The name of the light. +- **use_rm433_remote** (*Optional*, boolean): Set to ``True`` if your setup uses Sonoff RM433 + or any other radio remote control. Properly setting this parameter allows the platform to + identify what to do with incoming UART commands. RF chip is known to catch random commands + if not paired with a real remote (so called ghost commands). This problem is observed even + with the stock firmware and most probably is a bug in the MCU firmware or in the RF chip + firmware. Setting this to ``False`` instructs the platform to properly ignore such commands + and thus prevent unexpected switches or light intensity changes. +- **min_value** (*Optional*, int): The lowest dimmer value allowed. Acceptable value for your + setup will depend on actual light bulbs installed and number of them. Start with the default + value and check what will be the minimal brightness bulbs can render. Pay attention that for + some dimmable LED lamps minimal turn-on brightness will be higher that the minimal achievable + brightness if you just decrease it when lamp is already turned on. Defaults to 0. +- **max_value** (*Optional*, int): The highest dimmer value allowed. Use this to hard-limit light + intensity for your setup. For some bulbs this parameter might be also useful to prevent + flickering at high brightness values. Defaults to 100. +- All other options from :ref:`Light `. + + +See Also +-------- + +- :doc:`/components/light/index` +- :doc:`/components/uart` +- :doc:`/components/logger` +- :doc:`/components/esp8266` +- :ghedit:`Edit` diff --git a/images/sonoff_d1.jpg b/images/sonoff_d1.jpg new file mode 100644 index 000000000..7597689ec Binary files /dev/null and b/images/sonoff_d1.jpg differ diff --git a/index.rst b/index.rst index 819331f32..edb4eee41 100644 --- a/index.rst +++ b/index.rst @@ -468,6 +468,7 @@ Light Components Custom Light, components/light/custom, language-cpp.svg H-bridge Light, components/light/hbridge, brightness-medium.svg + Sonoff D1 Dimmer, components/light/sonoff_d1, sonoff_d1.jpg Looking for WS2811 and similar individually addressable lights? Have a look at the :doc:`FastLED Light `.