Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2025-03-01 03:51:36 +01:00
Code Issues Projects Releases Wiki Activity

Merge branch 'current' into next

Browse Source
This commit is contained in:
Jesse Hills 2024-11-19 09:04:23 +13:00
commit 001b212d57
No known key found for this signature in database
GPG Key ID: BEAAE804EFD8E83A
17 changed files with 53 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
components/binary_sensor/custom.rst
View File

@ -9,8 +9,8 @@ Custom Binary Sensor
.. warning::
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
it into your configuration with :doc:`/components/external_components`.
will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
"importing" it into your configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

4
components/climate/custom.rst
View File

@ -9,8 +9,8 @@ Custom Climate
.. warning::
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
it into your configuration with :doc:`/components/external_components`.
will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
"importing" it into your configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

4
components/cover/custom.rst
View File

@ -9,8 +9,8 @@ Custom Cover
.. warning::
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
it into your configuration with :doc:`/components/external_components`.
will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
"importing" it into your configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

11
components/i2c.rst
View File

@ -58,11 +58,12 @@ Configuration variables:
sda: GPIOXX
scl: GPIOXX
scan: true
# Sensors should be specified as follows
- platform: bme680
i2c_id: bus_b
address: 0x76
# ...
# Sensors should be specified as follows
sensor:
- platform: bme680
i2c_id: bus_b
address: 0x76
# ...
For I²C multiplexing see :doc:`/components/tca9548a`.

4
components/light/custom.rst
View File

@ -9,8 +9,8 @@ Custom Light Output
.. warning::
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
it into your configuration with :doc:`/components/external_components`.
will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
"importing" it into your configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

4
components/output/custom.rst
View File

@ -9,8 +9,8 @@ Custom Output
.. warning::
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
it into your configuration with :doc:`/components/external_components`.
will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
"importing" it into your configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

2
components/sensor/bme280.rst
View File

@ -13,6 +13,8 @@ is used in *Forced Mode* where measurement is performed and then
the sensor returns to sleep mode until next measurement. The :ref:`I²C <i2c>` or :ref:`SPI <spi>` is
required to be set up in your configuration for this sensor to work.
**Note:** In :ref:`I²C <i2c>` mode pulling CSB to 3V is recommended, in order to avoid ``[E][sensor.bme280:155]: Communication with BME280 failed!`` error. See the *Connection diagram* chapter in datasheet above.
.. figure:: images/bme280-full.jpg
:align: center
:width: 50.0%

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.5 KiB

After

Width:  |  Height:  |  Size: 3.7 KiB

4
components/sensor/custom.rst
View File

@ -9,8 +9,8 @@ Custom Sensor Component
.. warning::
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
it into your configuration with :doc:`/components/external_components`.
will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
"importing" it into your configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

4
components/switch/custom.rst
View File

@ -9,8 +9,8 @@ Custom Switch
.. warning::
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
it into your configuration with :doc:`/components/external_components`.
will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
"importing" it into your configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

4
components/text_sensor/custom.rst
View File

@ -9,8 +9,8 @@ Custom Text Sensor
.. warning::
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
it into your configuration with :doc:`/components/external_components`.
will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
"importing" it into your configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

4
custom/custom_component.rst
View File

@ -9,8 +9,8 @@ Generic Custom Component
.. warning::
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
it into your configuration with :doc:`/components/external_components`.
will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
"importing" it into your configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

4
custom/i2c.rst
View File

@ -9,8 +9,8 @@ Custom I²C Device
.. warning::
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
it into your configuration with :doc:`/components/external_components`.
will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
"importing" it into your configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

4
custom/spi.rst
View File

@ -9,8 +9,8 @@ Custom SPI Device
.. warning::
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
it into your configuration with :doc:`/components/external_components`.
will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
"importing" it into your configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

4
custom/uart.rst
View File

@ -9,8 +9,8 @@ Custom UART Device
.. warning::
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
it into your configuration with :doc:`/components/external_components`.
will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
"importing" it into your configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

1
guides/configuration-types.rst
View File

@ -162,6 +162,7 @@ There are several ways of doing this. See below examples to see how you can spec
# for all 'update_interval' options, also
update_interval: never # never update
update_interval: 0ms # update in every loop() iteration
update_interval: always # same as 0ms
See Also
--------

23
guides/contributing.rst
View File

@ -207,8 +207,8 @@ adhere to the following order:
.. note::
Referral links are not permitted unless they directly benefit the ESPHome project.
This applies to all official ESPHome documentation or websites.
Referral links are only permitted if they provide a direct benefit to the ESPHome project.
This policy applies to all official ESPHome documentation and websites.
- **References**: To reference another document, use the ``:doc:`` and ``:ref:`` roles (references are set up globally
and can be used between documents):
@ -1017,7 +1017,10 @@ ESPHome's "custom component" mechanism is a holdover from Home Assistant's featu
:doc:`/components/external_components` and offered a way to "hack in" support for devices which were not officially
supported by ESPHome.
ESPHome has since deprecated this feature in favor of :doc:`/components/external_components` for several reasons:
Why are Custom Components Deprecated?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are several reasons for this change.
- Custom components are very fragile:
@ -1026,11 +1029,13 @@ ESPHome has since deprecated this feature in favor of :doc:`/components/external
resulting in compiler errors, unexpected behavior and/or crashes.
- Custom components are difficult to use. You have to manually copy all of the custom component's files into *just
the right location* on your system or else you will receive compiler errors and the component won't work.
- Custom components almost always require C++ code changes when you want them to work even *slightly* differently
than the original author intended.
- Custom components lack flexibility and almost always require C++ code changes when you want them to work even
*slightly* differently than the original author intended/designed. For example, a simple change of input units
(``cm`` to ``m``, for example) could require significant changes to the C++ code, depending on how the original
author designed the custom component.
- :doc:`/components/external_components` initially require a bit more effort by the developer but are ultimately more
robust and easier to use and share:
robust and are easier to use and share:
- Just like any other ESPHome component/platform:
@ -1044,7 +1049,8 @@ ESPHome has since deprecated this feature in favor of :doc:`/components/external
- They tend to be more flexible since they are configured in YAML (as opposed to editing C++ code to make changes).
**So what is the difference between custom components and** :doc:`/components/external_components`?
What's the Difference?
^^^^^^^^^^^^^^^^^^^^^^
Custom components are typically (more or less) just the :ref:`runtime` part of an ESPHome component/platform. On the
other hand, :doc:`/components/external_components` are just like any other ESPHome component -- the only difference is
@ -1058,6 +1064,9 @@ In terms of implementation, custom components just lack the Python part of an ES
As such, most custom components can be made into :doc:`/components/external_components` simply by adding the required
Python parts to make the custom component into a proper, complete ESPHome component.
What's Next?
^^^^^^^^^^^^
We encourage all custom component developers to extend their custom component(s) into proper
:doc:`/components/external_components`; doing so will make your custom component easier to share and use. As you do so,
be sure to have a look at the the :ref:`contributing_to_esphome` section above as it walks through ESPHome (component)

7
guides/faq.rst
View File

@ -374,6 +374,7 @@ And a docker compose file looks like this:
# if needed, add esp device(s) as in command line examples above
- /dev/ttyUSB0:/dev/ttyUSB0
- /dev/ttyACM0:/dev/ttyACM0
# The host networking driver only works on Linux hosts, but is available as a Beta feature, on Docker Desktop version 4.29 and later.
network_mode: host
restart: always
@ -384,9 +385,9 @@ And a docker compose file looks like this:
By default ESPHome uses mDNS to show online/offline state in the dashboard view. So for that feature to work you
need to enable host networking mode.
On MacOS the networking mode ("-net=host" option) doesn't work as expected. You have to use
another way to launch the dashboard with a port mapping option and use alternative to mDNS
to have the online/offline stat (see below)
The `host networking driver <https://docs.docker.com/network/drivers/host/>`_ only works on Linux hosts, but is available as a Beta feature, on Docker Desktop version 4.29 and later.
If you don't want to use the host networking driver, you have to use an alternative method described below.
mDNS might not work if your Home Assistant server and your ESPHome nodes are on different subnets.
If your router supports Avahi (eg. OpenWRT or pfSense), you are able to get mDNS working over different subnets