Upstream
/
esphome-docs
mirror of https://github.com/esphome/esphome-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Updates

This commit is contained in:
Otto Winter 2019-07-28 12:41:15 +02:00
parent 7299d1e782
commit 8d91d657dc
No known key found for this signature in database
GPG Key ID: DB66C0BE6013F97E
14 changed files with 136 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
changelog/v1.10.0.rst
View File

@ -55,7 +55,7 @@ of time to find+fix some final bugs.
First, make sure you run at least Home Assistant 0.85.0 (currently a
`beta release <https://www.home-assistant.io/docs/installation/updating/#run-the-beta-version>`__).
Then, go through the :ref:`migration guide here <api-mqtt_to_native>`.
Then, go through the migration guide here (removed).
Python 3 Compatibility
----------------------

117
components/api.rst
View File

@ -34,91 +34,9 @@ Configuration variables:
- **reboot_timeout** (*Optional*, :ref:`time <config-time>`): The amount of time to wait before rebooting when no
client connects to the API. This is needed because sometimes the low level ESP functions report that
the ESP is connected to the network, when in fact it is not - only a full reboot fixes it.
Can be disabled by setting this to ``0s``. Defaults to ``5min``.
Can be disabled by setting this to ``0s``. Defaults to ``15min``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
.. _api-mqtt_to_native:
Migrating from MQTT to Native API Setup in Home Assistant
---------------------------------------------------------
The native API is the best way to use ESPHome 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).
If you've previously used ESPHome with Home Assistant via MQTT and have enabled MQTT discovery,
the upgrade process is unfortunately not just swapping out the ``mqtt`` for ``api`` in your configuration:
Home Assistant's `entity registry <https://developers.home-assistant.io/docs/en/entity_registry_index.html>`__ complicates
things a bit. If you don't follow these steps, all your new native API entities will have a trailing
``_2`` at the end of the entity ID.
You can repeat these steps for all your nodes, or convert them over to the new native API one by one.
1. Disable MQTT discovery on ESP side. In your ESPHome configuration, set a special "clean" discovery flag:
.. code-block:: yaml
# In your ESPHome configuration! Not HA config!
mqtt:
# Other settings ...
discovery: clean
2. Compile and upload this new firmware. All entities should now be gone from Home Assistant.
3. Go to your Home Assistant configuration folder and go to the ``.storage`` folder (might be hidden
depending on your operating system). In there you will find a file called ``core.entity_registry`` - open
the file with a text editor and paste the contents below
.. raw:: html
<textarea rows="10" cols="50" id="entity-reg-converter"></textarea>
<button type="button" id="entity-reg-button">Convert Entity Registry</button>
<script>
var elem = document.getElementById("entity-reg-converter");
elem.addEventListener("click", function() {
elem.focus();
elem.select();
});
document.getElementById("entity-reg-button").addEventListener("click", function() {
try {
data = JSON.parse(elem.value);
} catch(e) {
alert(e);
}
var entities = data.data.entities;
var newEntities = [];
for (var i = 0; i < entities.length; i++) {
var entity = entities[i];
if (entity.platform != "mqtt") {
newEntities.push(entity);
}
}
data.data.entities = newEntities;
elem.value = JSON.stringify(data, null, 4);
});
</script>
4. Stop Home Assistant - this is necessary for the entity registry changes not to become overriden.
5. Convert the Entity Registry file above using the "Convert Entity Registry Button", and
override the ``.storage/core.entity_registry`` file with the new contents.
6. Start Home Assistant.
7. Now you can enable the ESPHome native API (and upload the new firmware)
.. code-block:: yaml
# Example configuration entry
api:
8. In Home Assistant, go to "Configuration" -> "Integrations" - if you've set up the ``discovery:`` component,
you'll already see the ESP as a suggestion to be configured. But if you're having issues with that, you can
always manually set up an ESPHome device using "Set up a new integration" -> "ESPHome".
9. Now you can remove ``mqtt:`` from your ESPHome configuration. You don't have to, but doing so will
free up resources (of which these ESPs don't have too much).
.. _api-homeassistant_service_action:
``homeassistant.service`` Action
@ -220,6 +138,11 @@ There are currently 4 types of variables:
- float: A floating point number. C++ type: ``float``
- string: A string. C++ type: ``std::string``
Each of these also exist in array form:
- bool[]: An array of boolean values. C++ type: ``std::vector<bool>``
- ... - Same for other types.
.. _api-connected_condition:
``api.connected`` Condition
@ -257,6 +180,34 @@ never be removed. Features of native API (vs. MQTT):
- **Low Latency:** The native API is optimized for very low latency, usually this is only
a couple of milliseconds and far less than can be noticed by the eye.
.. _api-homeassistant_event_action:
``homeassistant.event`` Action
------------------------------
When using the native API with Home Assistant, you can create events in the Home Assistant event bus
straight from ESPHome :ref:`Automations <automation>`.
.. code-block:: yaml
# In some trigger
on_...:
# Simple
- homeassistant.event:
event: esphome.button_pressed
data:
title: Button was pressed
Configuration options:
- **event** (**Required**, string): The event to create - must begin with ``esphome.``
- **data** (*Optional*, mapping): Optional *static* data to pass along with the event.
- **data_template** (*Optional*, mapping): Optional template data to pass along with the event.
This is evaluated on the Home Assistant side with Home Assistant's templating engine.
- **variables** (*Optional*, mapping): Optional variables that can be used in the ``data_template``.
Values are :ref:`lambdas <config-lambda>` and will be evaluated before sending the request.
See Also
--------

46
components/captive_portal.rst Normal file
View File

@ -0,0 +1,46 @@
Captive Portal
==============
.. seo::
:description: Instructions for setting up the Captive Portal fallback mechanism in ESPHome.
:image: wifi-strength-alert-outline.png
The captive portal component in ESPHome is a fallback mechanism for when connecting to the
configured :doc:`WiFi <wifi>` fails.
After 1 minute of unsuccesful wifi connection attempts, the ESP will start a WiFi hotspot
(with the credentials from your configuration)
.. figure:: images/captive_portal-ui.png
:align: center
:width: 70.0%
In this web interface, you can manually override the WiFi settings of the device (please note
this will be overwritten by any subsequent upload, so make sure to also update your YAML configuration).
Additionally, you can upload a new firmware file.
When you connect to the fallback network, the web interface should open automatically (see also
login to network notifications). If that does not work, you can also navigate to http://192.168.4.1/
manually in your browser.
.. code-block:: yaml
# Example configuration entry
wifi:
# ...
ap:
ssid: "Livingroom Fallback Hotspot"
password: "W1PBGyrokfLz"
captive_portal:
No configuration variables.
See Also
--------
- :doc:`wifi`
- :apiref:`captive_portal/captive_portal.h`
- :ghedit:`Edit`

BIN
components/images/captive_portal-ui.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

2
components/mqtt.rst
View File

@ -60,7 +60,7 @@ Configuration variables:
for verifying SSL connections. See :ref:`mqtt-ssl_fingerprints`
for more information.
- **reboot_timeout** (*Optional*, :ref:`time <config-time>`): The amount of time to wait before rebooting when no
MQTT connection exists. Can be disabled by setting this to ``0s``. Defaults to ``5min``.
MQTT connection exists. Can be disabled by setting this to ``0s``. Defaults to ``15min``.
- **keepalive** (*Optional*, :ref:`config-time`): The time
to keep the MQTT socket alive, decreasing this can help with overall stability due to more
WiFi traffic with more pings. Defaults to 15 seconds.

3
components/sensor/ads1115.rst
View File

@ -33,6 +33,9 @@ Configuration variables:
- **address** (**Required**, int): The i²c address of the sensor.
See :ref:`I²C Addresses <ads1115_i2c_addresses>` for more information.
- **continuous_mode** (*Optional*, boolean): Set if the ADS1115 should continuously measure voltages or
only measure them when an update is called. Please enable this for the :doc:`ct_clamp` integration.
Defaults to ``off``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this ADS1115 Hub. Use this if you
want to use multiple ADS1115 hubs at once.

6
components/sensor/custom.rst
View File

@ -360,12 +360,6 @@ Configuration variables:
- All options from :ref:`Sensor <config-sensor>`.
.. note::
The ``id()`` wrapper for ESPHome-lambdas is not available in custom code. However, in most
cases you can drop the ``id()`` wrapper and use the ID directly: ``id(my_var).state`` ->
``my_var->state``
Logging in Custom Components
----------------------------

25
components/sensor/index.rst
View File

@ -152,6 +152,7 @@ the value the sensor shows.
- platform: dht
# ...
temperature:
name: "DHT22 Temperature"
filters:
- calibrate_linear:
# Map 0.0 (from sensor) to 0.0 (true value)
@ -162,6 +163,30 @@ The arguments are a list of data points, each in the form ``MEASURED -> TRUTH``.
then fit a linear equation to the values (using least squares). So you need to supply at least
two values.
``calibrate_polynomial``
************************
Calibrate your sensor values by fitting them to a polynomial functions. This is similar to
the ``calibrate_linear`` filter, but also allows for higher-order functions like quadratic polynomials.
.. code-block:: yaml
# Example configuration entry
- platform: adc
# ...
filters:
- calibrate_polynomial:
degree: 2
datapoints:
# Map 0.0 (from sensor) to 0.0 (true value)
- 0.0 -> 0.0
- 10.0 -> 12.1
- 13.0 -> 14.0
The arguments are a list of data points, each in the form ``MEASURED -> TRUTH``. Additionally, you need
to specify the degree of the resulting polynomial, the datapoints will then be fitted to the given
degree with a least squares solver.
``filter_out``
**************

14
components/wifi.rst
View File

@ -56,14 +56,16 @@ Configuration variables:
Defaults to 1.
- **manual_ip** (*Optional*): Manually set the IP options for the AP. Same options as
manual_ip for station mode.
- **ap_timeout** (*Optional*, :ref:`time <config-time>`): The time after which to enable the
configured fallback hotspot. Defaults to ``1min``.
- **domain** (*Optional*, string): Set the domain of the node hostname used for uploading.
For example, if it's set to ``.local``, all uploads will be sent to ``<HOSTNAME>.local``.
Defaults to ``.local``.
- **reboot_timeout** (*Optional*, :ref:`time <config-time>`): The amount of time to wait before rebooting when no
WiFi connection exists. Can be disabled by setting this to ``0s``, but note that the low level IP stack currently
seems to have issues with WiFi where a full reboot is required to get the interface back working. Defaults to ``5min``.
- **power_save_mode** (*Optional*, string): The power save mode for the WiFi interface. Defaults to no power saving.
seems to have issues with WiFi where a full reboot is required to get the interface back working. Defaults to ``15min``.
- **power_save_mode** (*Optional*, string): The power save mode for the WiFi interface.
See :ref:`wifi-power_save_mode`
- **fast_connect** (*Optional*, boolean): If enabled, directly connects to WiFi network without doing a full scan
@ -126,11 +128,8 @@ WiFi. While some options *can* reduce the power usage of the ESP, they generally
reliability of the WiFi connection, with frequent disconnections from the router in the highest
power saving mode.
The default is ``none`` (a bit of power saving). If you experience frequent WiFi disconnection problems,
please also try ``light``.
- ``NONE`` (least power saving, Default)
- ``LIGHT``
- ``NONE`` (least power saving, Default for ESP8266)
- ``LIGHT`` (Default for ESP32)
- ``HIGH`` (most power saving)
.. code-block:: yaml
@ -192,5 +191,6 @@ This :ref:`Condition <config-condition>` checks if the WiFi client is currently
See Also
--------
- :doc:`captive_portal`
- :apiref:`wifi/wifi_component.h`
- :ghedit:`Edit`

2
guides/automations.rst
View File

@ -307,6 +307,8 @@ There is one caveat though: ESPHome automatically reboots if no connection to th
made. This is because the ESPs typically have issues in their network stacks that require a reboot to fix.
You can adjust this behavior (or even disable automatic rebooting) using the ``reboot_timeout`` option
in the :doc:`wifi component </components/wifi>` and :doc:`mqtt component </components/mqtt>`.
(Beware that effectively disables the reboot watchdog, so you will need to power cycle the device
if it fails to connect to the network without a reboot)
All Triggers
------------

11
guides/cli.rst
View File

@ -11,7 +11,16 @@ ESPHome's command line interface always has the following format
.. code-block:: console
esphome <CONFIGURATION> <COMMAND> [ARGUMENTS]
esphome <CONFIGURATION...> <COMMAND> [ARGUMENTS]
.. note::
You can specify multiple configuration files in the command line interface,
just list all files in front of the <COMMAND> like so:
.. code-block:: console
esphome livingroom.yaml kitchen.yaml run
``run`` Command

1
images/wifi-strength-alert-outline.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24"><path d="M12 3C7.79 3 3.7 4.41.38 7H.36C4.24 11.83 8.13 16.66 12 21.5c2.34-2.91 4.67-5.82 7-8.72V9.59l-7 8.71L3.27 7.44C5.9 5.85 8.92 5 12 5c3.07 0 6.09.86 8.71 2.45l-.44.55h2.57c.27-.33.53-.67.8-1h.01C20.32 4.41 16.22 3 12 3m9 7v8h2v-8m-2 10v2h2v-2"/></svg>
Side by Side

After

Width:  |  Height:  |  Size: 321 B

2
index.rst
View File

@ -300,6 +300,8 @@ Misc Components
PCF8574 I/O Expander, components/pcf8574, pcf8574.jpg
MCP23017 I/O Expander, components/mcp23017, mcp23017.svg
SIM800L, components/sim800l, sim800l.jpg
Captive Portal, components/captive_portal, wifi-strength-alert-outline.svg
Debug Component, components/debug, bug-report.svg
Additional Custom Components

5
sitemap.py
View File

@ -7,9 +7,12 @@ def setup(app):
app.connect('html-page-context', add_html_link)
app.connect('build-finished', create_sitemap)
app.sitemap_links = []
is_production = os.getenv('PRODUCTION') == 'YES'
return {"version": "1.0.0",
"parallel_read_safe": True,
"parallel_write_safe": True}
"parallel_write_safe": not is_production}
def add_html_link(app, pagename, templatename, context, doctree):