diff --git a/components/esp32_camera.rst b/components/esp32_camera.rst index 034a9f474..d0cdddaef 100644 --- a/components/esp32_camera.rst +++ b/components/esp32_camera.rst @@ -89,8 +89,8 @@ Frame Settings: .. note:: - The camera integration in Home Assistant isn't in stable or beta HA builds, so until 0.91 - ships or goes into beta you will need to use a development version of Home Assistant. + Camera uses PWM timer #1. If you need PWM (via the ``ledc`` platform) you need to manually specify + a channel there (with the ``channel: 2`` parameter) Configuration for Ai-Thinker Camera ----------------------------------- diff --git a/cookbook/arduino_port_extender.rst b/cookbook/arduino_port_extender.rst new file mode 100644 index 000000000..5231e87a6 --- /dev/null +++ b/cookbook/arduino_port_extender.rst @@ -0,0 +1,326 @@ +Arduino Port Expander +===================== + +.. seo:: + :description: Instructions on using an Arduino board, like the Pro Mini for expanding ports of a ESPHome node + :image: arduino_pro_mini.jpg + :keywords: Arduino port expander extender ESPHome + +With this sketch you can control pins of a remote Arduino board through ESPHome. The Arduino acts as a port +expander, allowing you to use more pins than a standard ESP8266/ESP32 has. + +.. figure:: images/arduino_pro_mini.jpg + :align: center + :width: 75.0% + +The Arduino is connected to the ESP via I²C. Most Arduinos use the ``A4`` and ``A5`` pins for the I²C bus +so those pins are not available to read from ESPHome. +It is recommended to use a 3.3V I/O level Arduino, however using 5V Arduinos seems to work too. In the latter +case you should power your 5V Arduino with 3.3V otherwise you will need a level converter for the +I²C bus. + +Currently it is supported: + + - reading digital inputs + - reading analog inputs + - writing digital outputs + +The Arduino sketch can be retrieved from `here `__ +you can rename it to ``.ino`` and use the Arduino IDE to program it. + +You need to download `arduino_port_expander.h `__ and include the ape.h in the ESPHome configuration. + +.. code-block:: yaml + + esphome: + # ... + includes: + - arduino_port_expander.h + +Setup your :ref:`I²C Bus ` and assign it an ``id``: + +.. code-block:: yaml + + i2c: + id: i2c_component + +By default ESP8266 uses ``SDA`` pin ``GPIO4`` which you need to connect to Arduino's ``A4`` and the ``SCL`` +is ``GPIO5`` which goes to Arduino's ``A5``. + +Then create a ``custom_component``, this will be the main component we will be referencing later when creating +individual IOs. + +.. code-block:: yaml + + custom_component: + - id: ape + lambda: |- + auto ape_component = new ArduinoPortExpander(i2c_component, 0x08); + return {ape_component}; + +By default the I²C address is ``0x08`` but you can change it on the arduino sketch so you can have more slaves +on the same bus. + +Now it is time to add the ports. + +Binary_Sensor +------------- + +When adding binary sensors the pins are configured as INPUT_PULLUP, you can use any PIN from 0 to 13 or +``A0`` to ``A3`` (``A4`` and ``A5`` are used for I²C and ``A6`` and ``A7`` do not support internal pull up) + +.. note:: + + Arduino PIN 13 usually has a LED conected to it and using it as digital input with the built in internal + pull up might be problematic, using it as an output is preferred. + +To setup binary sensors, create a custom platform as below, list in braces all the sensors you want, +in the example below two binary sensors are declared on pin 9 and A0 (number 14) + +Then declare the ESPHome reference of the binary sensor in the same order as declared in the lambda: + +.. code-block:: yaml + + binary_sensor: + - platform: custom + lambda: |- + return {ape_binary_sensor(ape, 9), + ape_binary_sensor(ape, 14) // 14 = A0 + }; + + binary_sensors: + - id: binary_sensor_pin2 + name: Binary sensor pin 2 + - id: binary_sensor_pin3 + name: Binary sensor pin 3 + on_press: + ... + +The listed ``binary_sensors`` supports all options from :ref:`Binary Sensor ` like +automations and filters. + +Sensor +------ + +Sensors allows for reading the analog value of an analog pin, those are from ``A0`` to ``A7`` except for +``A4`` and ``A5``. The value returned goes from 0 to 1023 (the value returned by the arduino ``analogRead`` +function). + +Arduino analog inputs measures voltage. By default the sketch is configured to use the Arduino internal VREF +comparer setup to 1 volt, so voltages bigger are read as 1023. You can configure Arduino to compare the +voltage to VIN voltage, this voltage might be 5 volts or 3.3 volts, depending on how you are powering it. To +do so, pass an additional true value to the hub constructor: + +.. code-block:: cpp + + auto ape_component = new ArduinoPortExpander(i2c_component, 0x08, true); + +To setup sensors, create a custom platform as below, list in braces all the sensors you want, +in the example below two sensors are declared on pin ``A1`` and ``A2`` + +Then declare the ESPHome reference of the sensor in the same order as declared in the lambda: + +.. code-block:: yaml + + sensor: + - platform: custom + lambda: |- + return {ape_analog_input(ape, 1), // 1 = A1 + ape_analog_input(ape, 2)}; + sensors: + - name: Analog A1 + id: analog_a1 + filters: + - throttle: 1s + - name: Analog A2 + id: analog_a2 + filters: + - throttle: 2s + +The listed ``sensors`` supports all options from :ref:`Sensor ` like +automations and filters. + +.. note:: + + Sensors are polled by default every loop cycle so it is recommended to use the ``throttle`` filter + to not flood the network. + +Output +------ + +Arduinos binary outputs are supported in pins from 0 to 13. + +To setup outputs, create a custom platform as below, list in braces all the outputs you want, +in the example below two outputs are declared on pin ``3`` and ``4`` + +.. code-block:: yaml + + output: + - platform: custom + type: binary + lambda: |- + return {ape_binary_output(ape, 3), + ape_binary_output(ape, 4)}; + outputs: + - id: output_pin_3 + inverted: true + - id: output_pin_4 + inverted: true + + switch: + - platform: output + name: Switch pin 3 + output: output_pin_3 + + light: + - platform: binary + name: Switch pin 4 + output: output_pin_4 + +Full Example +------------ + +Let's connect a 4 channel relay board and 2 push buttons to toggle the relays, a PIR sensor, a window and a door +a LM35 temperature sensor and a voltage sensor. Seems a bit too much for an ESP8266? You'll still have some +spares I/Os. + + +.. code-block:: yaml + + esphome: + name: test_arduino + platform: ESP8266 + board: nodemcu + includes: + - arduino_port_expander.h + + wifi: + ssid: !secret wifi_ssid + password: !secret wifi_pass + + api: + + ota: + + # define i2c device + # for an ESP8266 SDA is D2 and goes to Arduino's A4 + # SCL is D1 and goes to Arduino's A5 + i2c: + id: i2c_component + + logger: + level: DEBUG + + # define the port expander hub, here we define one with id 'expander1', + # but you can define many + custom_component: + - id: expander1 + lambda: |- + auto expander = new ArduinoPortExpander(i2c_component, 0x08, true); + return {expander}; + + # define binary outputs, here we have 4, as the relays are inverse logic + # (a path to ground turns the relay ON), we defined the inverted: true + # option of ESPHome outputs. + output: + - platform: custom + type: binary + lambda: |- + return {ape_binary_output(expander1, 2), + ape_binary_output(expander1, 3), + ape_binary_output(expander1, 4), + ape_binary_output(expander1, 5)}; + + outputs: + - id: relay_1 + inverted: true + - id: relay_2 + inverted: true + - id: relay_3 + inverted: true + - id: relay_4 + inverted: true + + # connect lights to the first 2 relays + light: + - platform: binary + id: ceiling_light + name: Ceiling light + output: relay_1 + - platform: binary + id: room_light + name: Living room light + output: relay_2 + + # connect a fan to the third relay + fan: + - platform: binary + id: ceiling_fan + output: relay_3 + name: Ceiling fan + + # connect a pump to the 4th relay + switch: + - platform: output + name: Tank pump + id: tank_pump + output: relay_4 + + + # define binary sensors, use the Arduino PIN number for digital pins and + # for analog use 14 for A0, 15 for A1 and so on... + binary_sensor: + - platform: custom + lambda: |- + return {ape_binary_sensor(expander1, 7), + ape_binary_sensor(expander1, 8), + ape_binary_sensor(expander1, 9), + ape_binary_sensor(expander1, 10), + ape_binary_sensor(expander1, 14) // 14 = A0 + }; + + binary_sensors: + - id: push_button1 + internal: true # don't show on HA + on_press: + - light.toggle: ceiling_light + - id: push_button2 + internal: true # don't show on HA + on_press: + - light.toggle: room_light + - id: pir_sensor + name: Living PIR + device_class: motion + - id: window_reed_switch + name: Living Window + device_class: window + - id: garage_door + name: Garage garage + device_class: garage_door + + # define analog sensors + sensor: + - platform: custom + lambda: |- + return {ape_analog_input(expander1, 1), // 1 = A1 + ape_analog_input(expander1, 2)}; + sensors: + - name: LM35 Living room temperature + id: lm35_temp + filters: + # update every 60s + - throttle: 60s + # LM35 outputs 0.01v per ºC, and 1023 means 3.3 volts + - lambda: return x * 330.0 / 1023.0; + - name: Analog A2 + id: analog_a2 + filters: + - throttle: 2s + + + +See Also +-------- + +- :doc:`/devices/nodemcu_esp8266` +- :ghedit:`Edit` diff --git a/cookbook/images/arduino_pro_mini.jpg b/cookbook/images/arduino_pro_mini.jpg new file mode 100644 index 000000000..20c264362 Binary files /dev/null and b/cookbook/images/arduino_pro_mini.jpg differ diff --git a/cookbook/images/zemismart-rgbw-downlight-homeassistant.jpg b/cookbook/images/zemismart-rgbw-downlight-homeassistant.jpg new file mode 100644 index 000000000..c8f1ab0ad Binary files /dev/null and b/cookbook/images/zemismart-rgbw-downlight-homeassistant.jpg differ diff --git a/cookbook/images/zemismart-rgbw-downlight.jpg b/cookbook/images/zemismart-rgbw-downlight.jpg new file mode 100644 index 000000000..0d0146174 Binary files /dev/null and b/cookbook/images/zemismart-rgbw-downlight.jpg differ diff --git a/cookbook/zemismart-rgbw-downlights.rst b/cookbook/zemismart-rgbw-downlights.rst new file mode 100644 index 000000000..5dc2714fc --- /dev/null +++ b/cookbook/zemismart-rgbw-downlights.rst @@ -0,0 +1,196 @@ +Zemismart LED RGBW Downlights +============================= + +The Zemismart LED RGBW Downlight is a tuya based downlight available from various retailers online or from `zemismart.com `__ direct. + +.. figure:: images/zemismart-rgbw-downlight.jpg + :align: center + :width: 50.0% + +Originally intended to be used with their companion app once flashed using `tuya-convert `__ ESPHome generated +firmware can be uploaded allowing you to control the smart plugs via Home Assistant. + +1. Create the ESPHome Firmware +------------------------------ + +#. Refer to either :doc:`/guides/getting_started_command_line` or :doc:`/guides/getting_started_hassio` before moving onto the next step. +#. Select a plug configuration below based on the plug/s you have and copy all of the text in the code block and paste into your + ``name_of_esphome_configuration.yaml`` file. +#. Compile the firmware, again depending on your chosen setup refer to the guides in the first point. + +2. Flashing +----------- + +2.1 Prerequisites +***************** + +#. Before you begin you'll need one of the following linux machines running the latest copy of `Raspbian Stretch Lite + `__ + + a. Raspberry Pi 2B/B+ with `USB WiFi Dongle `__. + b. Raspberry Pi 3B/B+. + +.. note:: + + As per the `tuya-convert documentation `__: + + Any Linux with a Wifi adapter which can act as an Access Point should also work. Please note that we have tested the Raspberry Pi with clean installations + only. If you use your Raspberry Pi for anything else, we recommend using another SD card with a clean installation. + +#. A microSD card (minimum 2GB, 8GB+ recommended). +#. Any WiFi device which can connect to the SSID generated by the Raspberry Pi and eventually the flashed tuya device. **This cannot be an iOS / Apple device. + Android devices will work.** + +2.2 Installing the OS +********************* + +#. It's recommended to read the documentation provided by the Raspberry Pi Foundation on the best way to flash the OS to the microSD card depending on your + platform - `Installing operating system images `__. +#. After you've flashed the microSD card browse to the "boot" partition and add a blank file called "ssh" **(without any extension)** which will enable the + SSH server upon first boot, extended information on this step can be found `here + `__. +#. Plug the microSD card into the Raspberry Pi, connect network cable and power, the Raspberry Pi will start to boot. + +2.3 Connecting to the Pi via SSH +******************************** + +#. Download and install `Putty `__. +#. Open Putty. +#. Enter the IP of Raspberry Pi in the box that says "Host Name", leaving the port set to 22 (default for SSH). A list of recommended ways can be found `here + `__, but the easiest is to download and use `Fing `__ + (`Android `__ / `iOS + `__). +#. In the "Saved Sessions" input box, name the Raspberry Pi connection and then press "Save". +#. Select your new saved session from the list. +#. Press "Open". + +2.4 Configuring the Pi +********************** + +#. In the putty window login with the **pi** as the user and **raspberry** for the password. +#. Type ``sudo apt-get update && sudo apt-get dist-upgrade -y`` and wait for the upgrades to install. +#. Type ``sudo apt-get install git`` and wait for it to install. + +2.5 Setup and Install tuya-convert +********************************** + +#. In the putty window type ``git clone https://github.com/ct-Open-Source/tuya-convert`` press enter and wait while the repository is cloned. +#. Type ``cd tuya-convert`` and press enter. +#. Type ``./install_prereq.sh`` press enter and wait as the script gathers all the required components needed to function. + +2.6 Upload ESPHome Firmware using SFTP +************************************** + +#. Download `FileZilla `__ or `WinSCP `__ or use your preferred FTP + client. +#. Depending on the program you need to connect to the Pi using the IP address as the hostname and the username and password the same as you used to connect + via SSH and ensure your connection type is set to **SFTP** +#. Browse to ``/root/tuya-convert/files``. +#. Upload your compiled ``firmware.bin`` file to this directory. For command line based installs you can access the file under + ``//.pioenvs//firmware.bin`` alternatively Hass.io users can download the file directly from the web ui. + +2.7 Use tuya-convert to install ESPHome Firmware +************************************************ + +#. Type ``./start_flash.sh`` +#. Type ``yes`` to accept the warning. +#. Connect your alternative WiFi device (non iOS / Apple based) to the ``vtrust-flash`` SSID using ``flashmeifyoucan`` as the password. This is the network + being broadcast by the Pi from the tuya flash script. +#. If you haven't already plug your downlight into a powerpoint and turn it on and follow the instructions below: + + #. Once turned on a stable white light will be emitted. + #. Switch off, then back on **3** times ensuring each off-on cycle is no longer 10 seconds apart and between each the light visibly turns off. + #. The light should have entered into a fast flashing state, if this is the case continue onto **Step 5** below. *Otherwise please turn the downlight off-on + within 3 minutes which will restore it back to a stable white light.* + + +#. Press enter on your putty window to start the flash process and wait. If the connection is successful you should see a large amount of scrolling text, this + is the script backing up the factory shipped firmware. +#. Once the process is complete you can type ``curl http://10.42.42.42/flashURL?url=http://10.42.42.1/files/firmware.bin`` +#. The plug will restart and if everything is working correctly after a few seconds you should be able to press the button triggering the relay and turning the + blue led on. + +3. Downlight Configuration +-------------------------- + +Thanks to `@1972rx2 `__ for creating the below ESPHome configuration +which this cookbook article by `@cryptelli `__ is based on. + + +3.1 Zemismart LED RGBW Downlight YAML +************************************* + +.. code-block:: yaml + + esphome: + name: downlight01 + platform: ESP8266 + board: esp01_1m + + wifi: + ssid: "YOUR SSID" + password: "YOUR WIFI PASSWORD" + + # Enable logging + logger: + + # Enable Home Assistant API + api: + + ota: + + my9231: + data_pin: GPIO13 + clock_pin: GPIO15 + num_channels: 4 + num_chips: 1 + + output: + - platform: my9231 + id: output_blue + channel: 1 + - platform: my9231 + id: output_red + channel: 3 + - platform: my9231 + id: output_green + channel: 2 + - platform: my9231 + id: output_white + channel: 0 + + light: + - platform: rgbw + name: Downlight01 + red: output_red + green: output_green + blue: output_blue + white: output_white + +4. Adding to Home Assistant +--------------------------- + +You can now add your downlight to Home Assistant using the below instructions: + +#. In the left hand sidebar, select **Configuration**. +#. Select **Integrations** +#. Click the **Orange** plus button *(lower right hand corner)* and look for **ESPHome** in the list of available integrations and select. +#. Type the host of the downlight, in most cases this is simply the IP address. +#. Leave the port set to the default of ``6053``. +#. Click **Submit** + +If you've gotten this far, congratulations! Below is the card you should see inside Home Assistant which allows you to control the downlight. + + +.. figure:: images/zemismart-rgbw-downlight-homeassistant.jpg + :align: center + :width: 50.0% + +See Also +-------- + +- :doc:`/components/light/index` +- :doc:`/components/light/rgbw` +- :doc:`/components/output/index` +- :doc:`/components/output/my9231` +- :ghedit:`Edit` diff --git a/devices/nodemcu_esp8266.rst b/devices/nodemcu_esp8266.rst index fb6776680..7e3397197 100644 --- a/devices/nodemcu_esp8266.rst +++ b/devices/nodemcu_esp8266.rst @@ -49,7 +49,7 @@ Note that in certain conditions you *can* use the pins marked as ``INTERNAL`` in not be pulled low on startup. You can, however, still use them as output pins. - ``A0``: This pin can be used as a normal GPIO pin (like ``D1`` etc) but additionally can measure voltages from 0 to 1.0V using the :doc:`/components/sensor/adc`. -- ``VIN``: This pin can be used to use an external power supply with the board. Supply a voltage from +- ``VIN``: This board can be powered by an external power supply by using this pin. Supply a voltage between 3.3V to 12V to this pin and the linear voltage regulator on the board will power the board. - ``ENABLE``/``RESET``: When these pins are triggered, the board resets. The difference between the pins is how they can handle voltages above 3.3V. diff --git a/devices/sonoff.rst b/devices/sonoff.rst index 60505c0c9..2bc8a36d4 100644 --- a/devices/sonoff.rst +++ b/devices/sonoff.rst @@ -355,6 +355,19 @@ Teckin SP20 (US) See :doc:`/components/sensor/hlw8012` for measuring power. Example config: `teckin_sp20_us.yaml `__ +TorchStar LED Controller (Nov 2018) +----------------------------------- + +.. pintable:: + + GPIO13, Button (inverted), + GPIO16, Blue LED (inverted), + GPIO4, Red LED (inverted), + GPIO14, Red Channel, + GPIO12, Green Channel, + GPIO5, Blue Channel, + GPIO15, White Channel, + See Also -------- diff --git a/guides/automations.rst b/guides/automations.rst index f20525ae4..94b57b7eb 100644 --- a/guides/automations.rst +++ b/guides/automations.rst @@ -336,7 +336,7 @@ All Actions - :ref:`delay ` - :ref:`lambda ` -- :ref:`if ` / :ref:`while ` / :ref:`wait_util ` +- :ref:`if ` / :ref:`while ` / :ref:`wait_until ` - :ref:`component.update ` - :ref:`script.execute ` / :ref:`script.stop ` / :ref:`script.wait ` - :ref:`logger.log ` diff --git a/guides/contributing.rst b/guides/contributing.rst index 70a0bbff6..471ec453e 100644 --- a/guides/contributing.rst +++ b/guides/contributing.rst @@ -559,7 +559,7 @@ Standard for the esphome-core codebase: - function, method and variable names are ``lower_snake_case`` - class/struct/enum names should be ``UpperCamelCase`` - constants should be ``UPPER_SNAKE_CASE`` - - fields should be ``protected`` and ``lowe_snake_case_with_trailing_underscore_`` (DO NOT use private) + - fields should be ``protected`` and ``lower_snake_case_with_trailing_underscore_`` (DO NOT use private) - It's preferred to use long variable/function names over short and non-descriptive ones. - All uses of class members and member functions should be prefixed with ``this->`` to distinguish them from global functions in code review. diff --git a/guides/faq.rst b/guides/faq.rst index 6ef2c8e2c..64898b746 100644 --- a/guides/faq.rst +++ b/guides/faq.rst @@ -177,6 +177,18 @@ To install the dev version of ESPHome: The latest dev docs are here: `next.esphome.io `__ +How do I use my Home Assistant secrets.yaml? +-------------------------------------------- + +If you want to keep all your secrets in one place, make a ``secrets.yaml`` file in the +esphome directory with these contents (so it pulls in the contents of your main Home Assistant +``secrets.yaml`` file from one directory higher): + +.. code-block:: yaml + + <<: !include ../secrets.yaml + + Does ESPHome support [this device/feature]? ------------------------------------------- diff --git a/images/arduino_logo.svg b/images/arduino_logo.svg new file mode 100644 index 000000000..6ce090ed7 --- /dev/null +++ b/images/arduino_logo.svg @@ -0,0 +1 @@ + diff --git a/images/cookbook-zemismart-rgbw-downlight.jpg b/images/cookbook-zemismart-rgbw-downlight.jpg new file mode 100644 index 000000000..1141e279a Binary files /dev/null and b/images/cookbook-zemismart-rgbw-downlight.jpg differ diff --git a/index.rst b/index.rst index a80eb816c..dc4b3f182 100644 --- a/index.rst +++ b/index.rst @@ -326,6 +326,7 @@ Cookbook .. imgtable:: + Arduino Port Extender, cookbook/arduino_port_extender, arduino_logo.svg Endstop Cover, cookbook/endstop-cover, window-open.svg PIR Sensor, cookbook/pir, pir.jpg Relay, cookbook/relay, relay.jpg @@ -340,6 +341,7 @@ Cookbook Mirabella Genio Bulb, cookbook/mirabella-genio-bulb, cookbook-mirabella-genio-b22-rgbw.jpg Garage Door, cookbook/garage-door, window-open.svg Brilliant / Mirabella Genio Smart Plugs, cookbook/brilliant-mirabella-genio-smart-plugs, cookbook-brilliant-mirabella-genio-smart-plugs.jpg + Zemismart RGBW Downlights, cookbook/zemismart-rgbw-downlights, cookbook-zemismart-rgbw-downlight.jpg Teckin SB50, cookbook/teckin_sb50, teckin_sb50.jpg Do you have other awesome automations or cool setups? Please feel free to add them to the