Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2024-11-10 10:11:29 +01:00
Code Issues Projects Releases Wiki Activity

Merge branch 'current' into next

Browse Source
This commit is contained in:
Jesse Hills 2023-11-03 08:11:42 +13:00
commit c499ef2522
No known key found for this signature in database
GPG Key ID: BEAAE804EFD8E83A
17 changed files with 189 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
changelog/2023.10.0.rst
View File

@ -66,6 +66,14 @@ Release 2023.10.4 - October 30
- Fix bug when requesting italic gfonts :esphomepr:`5623` by :ghuser:`dewet22`
- Handle enum type in tuya text_sensor :esphomepr:`5626` by :ghuser:`jesserockz`
Release 2023.10.5 - November 1
------------------------------
- Add connection triggers to api :esphomepr:`5628` by :ghuser:`jesserockz`
- Add on_client_connected and disconnected to voice assistant :esphomepr:`5629` by :ghuser:`jesserockz`
- Ensure that all uses of strncpy in wifi component are safe. :esphomepr:`5636` by :ghuser:`kpfleming`
- Remove some explicit IPAddress casts :esphomepr:`5639` by :ghuser:`HeMan`
Breaking changes
----------------

4
components/api.rst
View File

@ -7,7 +7,7 @@ Native API Component
:keywords: Native API, ESPHome, Home Assistant
The ESPHome native API is used to communicate with clients directly, with a highly-optimized
network protocol. Currently, only the ESPHome tool and Home Assistant use this native API.
network protocol. Currently, only the ESPHome tool, Home Assistant and ioBroker use this native API.
After adding an ``api:`` line to your ESPHome configuration you can go to the Home Assistant
web interface and navigate to the "Integrations" screen in the "Configuration" panel. Then wait
@ -330,7 +330,7 @@ Advantages over MQTT
--------------------
The ESPHome native API has many advantages over using MQTT for communication with Home
Automation software (currently only Home Assistant). But MQTT is a great protocol and will
Automation software (currently only Home Assistant and ioBroker). But MQTT is a great protocol and will
never be removed. Features of native API (vs. MQTT):
- **Much more efficient:** ESPHome encodes all messages in a highly optimized format with

10
components/binary_sensor/custom.rst
View File

@ -1,6 +1,16 @@
Custom Binary Sensor
====================
.. warning::
Custom components are deprecated, 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`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
This integration can be used to create custom binary sensors in ESPHome
using the C++ (Arduino) API.

10
components/climate/custom.rst
View File

@ -1,6 +1,16 @@
Custom Climate
==============
.. warning::
Custom components are deprecated, 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`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
This integration can be used to create custom climate devices in ESPHome
using the C++ (Arduino) API.

10
components/cover/custom.rst
View File

@ -1,6 +1,16 @@
Custom Cover
============
.. warning::
Custom components are deprecated, 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`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
This integration can be used to create custom covers in ESPHome
using the C++ (Arduino) API.

62
components/external_components.rst
View File

@ -8,6 +8,8 @@ External Components
You can easily import community or personal components using the external components feature.
Bundled components can be overridden using this feature.
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
.. code-block:: yaml
external_components:
@ -91,15 +93,15 @@ Given the above example of ``my_components``, the folder structure must look lik
├── node2.yaml
└── my_components
├── my_component1
  │   ├── __init__.py
  │   ├── component1.cpp
  │   ├── component1.h
  │   └── sensor.py
  └── my_component2
     ├── __init__.py
     ├── component2.cpp
     ├── component2.h
     └── switch.py
│ ├── __init__.py
│ ├── component1.cpp
│ ├── component1.h
│ └── sensor.py
└── my_component2
├── __init__.py
├── component2.cpp
├── component2.h
└── switch.py
.. _external-components_git:
@ -119,16 +121,16 @@ For repositories where you share one or a few components:
.. code-block:: text
components
  ├── my_component1
  │   ├── __init__.py
  │   ├── component1.cpp
  │   ├── component1.h
  │   └── sensor.py
  └── my_component2
     ├── __init__.py
     ├── component2.cpp
     ├── component2.h
     └── switch.py
├── my_component1
│ ├── __init__.py
│ ├── component1.cpp
│ ├── component1.h
│ └── sensor.py
└── my_component2
├── __init__.py
├── component2.cpp
├── component2.h
└── switch.py
example_component1.yaml <- not required but recommended
README.md
@ -140,17 +142,17 @@ repository:
esphome
├── components
│   ├── my_component1
│   │   ├── __init__.py
│   │   ├── component1.cpp
│   │   ├── component1.h
│   │   └── sensor.py
│   ├── my_component2
│   │   ├── __init__.py
│   │   ├── component2.cpp
│   │   ├── component2.h
│   │   └── switch.py
│  ...
│ ├── my_component1
│ │ ├── __init__.py
│ │ ├── component1.cpp
│ │ ├── component1.h
│ │ └── sensor.py
│ ├── my_component2
│ │ ├── __init__.py
│ │ ├── component2.cpp
│ │ ├── component2.h
│ │ └── switch.py
│ ...
...
HTTP git repositories in general are supported with this configuration:

10
components/light/custom.rst
View File

@ -1,6 +1,16 @@
Custom Light Output
===================
.. warning::
Custom components are deprecated, 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`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
This integration can be used to create custom lights in ESPHome
using the C++ (Arduino) API.

10
components/output/custom.rst
View File

@ -1,6 +1,16 @@
Custom Output
=============
.. warning::
Custom components are deprecated, 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`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
This integration can be used to create custom binary and float :doc:`outputs </components/output/index>`
in ESPHome using the C++ (Arduino) API.

10
components/sensor/custom.rst
View File

@ -1,6 +1,16 @@
Custom Sensor Component
=======================
.. warning::
Custom components are deprecated, 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`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
.. seo::
:description: Instructions for setting up Custom C++ sensors with ESPHome.
:image: language-cpp.svg

10
components/switch/custom.rst
View File

@ -1,6 +1,16 @@
Custom Switch
=============
.. warning::
Custom components are deprecated, 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`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
This integration can be used to create custom switches in ESPHome
using the C++ (Arduino) API.

10
components/text_sensor/custom.rst
View File

@ -1,6 +1,16 @@
Custom Text Sensor
==================
.. warning::
Custom components are deprecated, 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`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
This integration can be used to create custom text sensors in ESPHome
using the C++ (Arduino) API.

14
custom/custom_component.rst
View File

@ -1,6 +1,16 @@
Generic Custom Component
========================
.. warning::
Custom components are deprecated, 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`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
This integration can be used to create generic custom components in ESPHome
using the C++ (Arduino) API. This integration should be used in cases where
none of ESPHome's abstraction layers (for example the "sensor", "binary sensor",
@ -50,8 +60,8 @@ And in YAML:
auto my_custom = new MyCustomComponent();
return {my_custom};
components:
- id: my_custom_id
- id: my_custom_id
Configuration variables:

24
custom/i2c.rst
View File

@ -1,6 +1,16 @@
Custom I²C Device
=================
.. warning::
Custom components are deprecated, 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`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
Lots of devices communicate using the I²C protocol. If you want to integrate
a device into ESPHome that uses this protocol you can pretty much use almost
all Arduino-based code because the ``Wire`` library is also available in ESPHome.
@ -47,15 +57,15 @@ It may be useful to write to a register via I²C using a numerical input. For ex
mode: box
id: input_1
icon: "mdi:counter"
We want to write this number to a ``REGISTER_ADDRESS`` on the slave device via I²C. The Arduino-based looping code shown above is modified following the guidance in :doc:`Custom Sensor Component </components/sensor/custom>`.
.. code-block:: cpp
#include "esphome.h"
const uint16_t I2C_ADDRESS = 0x21;
const uint16_t REGISTER_ADDRESS = 0x78;
const uint16_t REGISTER_ADDRESS = 0x78;
const uint16_t POLLING_PERIOD = 15000; //milliseconds
char temp = 20; //Initial value of the register
@ -68,8 +78,8 @@ We want to write this number to a ``REGISTER_ADDRESS`` on the slave device via I
//Add code here as needed
Wire.begin();
}
void update() override {
void update() override {
char register_value = id(input_1).state; //Read the number set on the dashboard
//Did the user change the input?
if(register_value != temp){
@ -81,7 +91,7 @@ We want to write this number to a ``REGISTER_ADDRESS`` on the slave device via I
}
}
};
The ``Component`` class has been replaced with ``PollingComponent`` and the free-running ``loop()`` is changed to the ``update()`` method with period set by ``POLLING_PERIOD``. The numerical value from the dashboard is accessed with its ``id`` tag and its state is set to the byte variable that we call ``register_value``. To prevent an I²C write on every iteration, the contents of the register are stored in ``temp`` and checked for a change. Configuring the hardware with ``get_setup_priority()`` is explained in :doc:`Step 1 </components/sensor/custom>`.

10
custom/spi.rst
View File

@ -1,6 +1,16 @@
Custom SPI Device
=================
.. warning::
Custom components are deprecated, 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`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
Lots of devices communicate using the SPI protocol. If you want to integrate
a device into ESPHome that uses this protocol you can pretty much use almost
all Arduino-based code because the ``SPI`` library is also available in ESPHome.

10
custom/uart.rst
View File

@ -1,6 +1,16 @@
Custom UART Device
==================
.. warning::
Custom components are deprecated, 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`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
Lots of devices communicate using the UART protocol. If you want to integrate
a device into ESPHome that uses this protocol you can pretty much use almost
all Arduino-based code because ESPHome has a nice abstraction over the UART bus.

30
guides/contributing.rst
View File

@ -341,8 +341,8 @@ This is only possible for ``pip`` installs.
git checkout -b my-new-feature
cd ..
The environment is now ready for use, but you need to activate the Python virtual environment
every time you are using it.
The environment is now ready for use, but you need to activate the Python virtual environment
every time you are using it.
.. code-block:: bash
@ -413,6 +413,8 @@ a "rebase". More info `here <https://developers.home-assistant.io/docs/en/develo
git fetch upstream dev
git rebase upstream/dev
.. _contributing_to_esphome:
Contributing to ESPHome
-----------------------
@ -445,18 +447,18 @@ like this:
├── codegen.py
├── config_validation.py
├── components
│   ├── __init__.py
│   ├── dht12
│   │   ├── __init__.py
│   │   ├── dht12.cpp
│   │   ├── dht12.h
│   │   ├── sensor.py
│   ├── restart
│   │   ├── __init__.py
│   │   ├── restart_switch.cpp
│   │   ├── restart_switch.h
│   │   ├── switch.py
│  ...
│ ├── __init__.py
│ ├── dht12
│ │ ├── __init__.py
│ │ ├── dht12.cpp
│ │ ├── dht12.h
│ │ ├── sensor.py
│ ├── restart
│ │ ├── __init__.py
│ │ ├── restart_switch.cpp
│ │ ├── restart_switch.h
│ │ ├── switch.py
│ ...
As you can see, all components are in the "components" folder. Each component is in its own
subfolder which contains the Python code (.py) and the C++ code (.h and .cpp).

3
guides/supporters.rst
View File

@ -601,6 +601,7 @@ Contributors
- `jakehdk (@jakehdk) <https://github.com/jakehdk>`__
- `Jake Shirley (@JakeShirley) <https://github.com/JakeShirley>`__
- `Jakob Reiter (@jakommo) <https://github.com/jakommo>`__
- `jakub-medrzak (@jakub-medrzak) <https://github.com/jakub-medrzak>`__
- `James Braid (@jamesbraid) <https://github.com/jamesbraid>`__
- `James Duke (@jamesduke) <https://github.com/jamesduke>`__
- `James Gao (@jamesgao) <https://github.com/jamesgao>`__
@ -1250,4 +1251,4 @@ Contributors
- `Zsolt Zsiros (@ZsZs73) <https://github.com/ZsZs73>`__
- `Christian Zufferey (@zuzu59) <https://github.com/zuzu59>`__
*This page was last updated October 30, 2023.*
*This page was last updated November 1, 2023.*