diff --git a/esphomeyaml/changelog/v1.10.0.rst b/esphomeyaml/changelog/v1.10.0.rst index fc7478916..56aef3275 100644 --- a/esphomeyaml/changelog/v1.10.0.rst +++ b/esphomeyaml/changelog/v1.10.0.rst @@ -7,7 +7,88 @@ Changelog - Version 1.9.0 :author: Otto Winter :author_twitter: @OttoWinter_ -TODO: Write Changelog, create seo image +Native API +---------- + +This release brings with it lots of goodies, but most important is the :doc:`native API `. +MQTT has been the only way this project communicated with Home Assistant for a while now. And MQTT is a great protocol +to get started, but it always had problems: + +- Another service to install - Users would need to install an MQTT broker in order to get started. +- MQTT Discovery - Home Assistant's MQTT discovery has been great, but always had problems like retained messages etc. +- Inefficient - A typical MQTT message for sending a binary sensor state is about 70 bytes long, and the MQTT library + we used was quite inefficient with runtime memory allocation too. + +So I decided to do something against that: ESPHome now features a native protocol (based on TCP+protocol buffers) +that addresses these issues and has a +`component on the Home Assistant `__ +side too. + +**Does this mean MQTT will be removed?** + +No! MQTT is an awesome protocol with easy integration for many tools like Node-RED and custom MQTT clients. +This native API is only for replacing communications with Home Assistant, so *if* anything gets removed it's +MQTT auto discovery for Home Assistant. Of course both can be used together at the same time too. + +**Should I switch to the native API immediately?** + +You definitely can, but a word of warning first: The MQTT implementation has seen tons of fixes for small quirks +in how the ESP SDK works. From my own testing, the native API seems to be quite stable - but I'm sure it'll take a bit +of time to find+fix some final bugs. + +**How do I migrate from MQTT?** + +First, make sure you run at least Home Assistant 0.85.0. Then, go through the +:ref:`migration guide here `. + +Python 3 Comparability +---------------------- + +PlatformIO has finally implemented `python 3 support `__ +after some quick changes, ESPHome is now also compatible with python 3.5+. So with this new release +you can try ESPHome with Python 3 already. Just make sure to install the development version of platformio first: + +.. code-block:: bash + + pip3 install -U https://github.com/platformio/platformio-core/archive/develop.zip + +I don't particularly like python 2, and in a year's time support for it will officially be ended. So the plan for +ESPHome is to drop python 2 as soon as possible. Once platformio releases version 4.0 (with python 3 support), I +will go through and check everything still works. Maybe ESPHome will support python 2 for 1 or 2 releases after that +but really I want to drop support for python 2 as soon as possible. + +Dashboard & Hass.io Addon Updates +--------------------------------- + +The dashboard and Hass.io addon have seen a lot of ❤️ in this release: The dashboard has seen tons of small +changes to make the user experience better and the Hass.io addon has been completely re-written with the +`Hass.io Community Addon Images `__ as the base. + +- The dashboard now features a built-in YAML editor. +- Configuration wizard now shows a list of boards directly, so you just have to choose them from a dropdown. +- Hass.io Addon: You can log in using your Home Assistant credentials now. +- And many more changes (colored logs, auto-scroll, node status, update notifications, ...) + +Rename: esphome{lib, yaml} -> ESPHome +------------------------------------- + +The name esphomelib and esphomeyaml were too technical, and this project has changed a lot since the first +published release (the yaml part didn't even exist back then). So ... the project is being re-branded slightly: + +- esphomeyaml -> ESPHome +- esphomelib -> ESPHome Core +- esphomedocs -> ESPHome Docs + +As you see, the yaml project is now getting the "fancy" name, because that's by far the best way to use this framework. +As part of this change, using the _core_ framework directly from code (without YAML) is being deprecated, the API docs +have long been inaccurate now and users should really switch over to ESPHome through YAML + +Of course that doesn't mean you won't be able to write custom code. In fact, this release also contains lots of +new guides and changes to make creating custom components much easier. The goal is to have a project where users +can use YAML for the boring boilerplate code but can completely customize everything with custom components. + +This migration is of course huge - almost every single file in the code+docs base has esphome{lib, yaml} somewhere +in it, so it will take time until the next release for this to be finished. Past Changelogs --------------- diff --git a/esphomeyaml/components/api.rst b/esphomeyaml/components/api.rst index eb750bd16..cf9ee4b75 100644 --- a/esphomeyaml/components/api.rst +++ b/esphomeyaml/components/api.rst @@ -32,8 +32,8 @@ Configuration variables: .. _api-mqtt_to_native: -Converting from MQTT to Native API Setup in Home Assistant ----------------------------------------------------------- +Migrating from MQTT to Native API Setup in Home Assistant +--------------------------------------------------------- The native API is the best way to use esphomelib together with Home Assistant - it's fast, highly efficient and requires almost zero setup (whereas MQTT requires you to set up an MQTT broker first). diff --git a/esphomeyaml/components/binary_sensor/index.rst b/esphomeyaml/components/binary_sensor/index.rst index 39a196011..43afba1d0 100644 --- a/esphomeyaml/components/binary_sensor/index.rst +++ b/esphomeyaml/components/binary_sensor/index.rst @@ -39,6 +39,8 @@ Automations: when the button is pressed. See :ref:`binary_sensor-on_press`. - **on_release** (*Optional*, :ref:`Automation `): An automation to perform when the button is released. See :ref:`binary_sensor-on_release`. +- **on_state** (*Optional*, :ref:`Automation `): An automation to perform + when a state is published. See :ref:`binary_sensor-on_state`. - **on_click** (*Optional*, :ref:`Automation `): An automation to perform when the button is held down for a specified period of time. See :ref:`binary_sensor-on_click`. diff --git a/esphomeyaml/components/i2c.rst b/esphomeyaml/components/i2c.rst index f4e92d7ca..d04fe436f 100644 --- a/esphomeyaml/components/i2c.rst +++ b/esphomeyaml/components/i2c.rst @@ -9,7 +9,9 @@ I²C Bus :keywords: i2c, iic, bus This component sets up the i²c bus for your ESP32 or ESP8266. In order for those components -to work correctly, you need to define the i²c bus in your configuration. +to work correctly, you need to define the i²c bus in your configuration. Please note the ESP +will enable its internal 10kΩ pullup resistors for these pins, so you usually don't need to +put on external ones. .. code-block:: yaml diff --git a/esphomeyaml/components/sensor/dht12.rst b/esphomeyaml/components/sensor/dht12.rst index 415f9a9ea..c6b03638a 100644 --- a/esphomeyaml/components/sensor/dht12.rst +++ b/esphomeyaml/components/sensor/dht12.rst @@ -8,7 +8,7 @@ DHT12 Temperature+Humidity Sensor The ``dht12`` Temperature+Humidity sensor allows you to use your DHT12 (`datasheet `__, -`electrodragon`_) i2c-based sensor with esphomelib. +`electrodragon`_) i2c-based sensor with esphomelib. This sensor is also called AM2320 by some sellers. .. figure:: images/dht12-full.jpg :align: center diff --git a/esphomeyaml/devices/sonoff_4ch.yaml b/esphomeyaml/devices/sonoff_4ch.yaml index 74f9b32f0..6843c63b9 100644 --- a/esphomeyaml/devices/sonoff_4ch.yaml +++ b/esphomeyaml/devices/sonoff_4ch.yaml @@ -25,8 +25,7 @@ binary_sensor: inverted: True name: "Sonoff 4CH Button 1" on_press: - then: - switch.toggle: relay_1 + - switch.toggle: relay_1 - platform: gpio pin: number: GPIO9 @@ -34,8 +33,7 @@ binary_sensor: inverted: True name: "Sonoff 4CH Button 2" on_press: - then: - switch.toggle: relay_2 + - switch.toggle: relay_2 - platform: gpio pin: number: GPIO10 @@ -43,8 +41,7 @@ binary_sensor: inverted: True name: "Sonoff 4CH Button 3" on_press: - then: - switch.toggle: relay_3 + - switch.toggle: relay_3 - platform: gpio pin: number: GPIO14 @@ -52,8 +49,7 @@ binary_sensor: inverted: True name: "Sonoff 4CH Button 4" on_press: - then: - switch.toggle: relay_4 + - switch.toggle: relay_4 - platform: status name: "Sonoff 4CH Status" diff --git a/esphomeyaml/devices/sonoff_basic.rst b/esphomeyaml/devices/sonoff_basic.rst index 34130188f..a3c0f72af 100644 --- a/esphomeyaml/devices/sonoff_basic.rst +++ b/esphomeyaml/devices/sonoff_basic.rst @@ -85,13 +85,14 @@ exposes all of the basic functions. mode: INPUT_PULLUP inverted: True name: "Sonoff Basic Button" - - platform: status - name: "Sonoff Basic Status" + on_press: + - switch.toggle: relay switch: - platform: gpio name: "Sonoff Basic Relay" pin: GPIO12 + id: relay output: - platform: esp8266_pwm diff --git a/esphomeyaml/devices/sonoff_s20.yaml b/esphomeyaml/devices/sonoff_s20.yaml index 2a3b32cd9..057d35de6 100644 --- a/esphomeyaml/devices/sonoff_s20.yaml +++ b/esphomeyaml/devices/sonoff_s20.yaml @@ -25,7 +25,6 @@ binary_sensor: inverted: True name: "Sonoff S20 Button" on_press: - then: - switch.toggle: relay - platform: status name: "Sonoff S20 Status" diff --git a/esphomeyaml/guides/automations.rst b/esphomeyaml/guides/automations.rst index 88e84aa38..8a1637109 100644 --- a/esphomeyaml/guides/automations.rst +++ b/esphomeyaml/guides/automations.rst @@ -33,8 +33,8 @@ decided to also install a simple push button next to the dehumidifier on pin GPI A simple push on this button should toggle the state of the dehumidifier. You *could* write an automation to do this task in Home Assistant's automation engine, but -ideally the IoT should work without an internet connection and should not break without -the MQTT server being online. +ideally the IoT should work without an internet connection and should not break with +the MQTT server being offline. That's why, starting with esphomelib 1.7.0, there's a new automation engine. With it, you can write some basic (and also some more advanced) automations using a syntax that is