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

Merge branch 'current' into beta

Browse Source
This commit is contained in:
Jesse Hills 2025-02-17 12:13:46 +13:00
commit e70ce5fee4
No known key found for this signature in database
GPG Key ID: BEAAE804EFD8E83A
11 changed files with 144 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
components/display/nextion.rst
View File

@ -33,11 +33,11 @@ This permits faster communication with the Nextion display and it is highly reco
.. warning::
**We highly recommend using only** :ref:`uart-hardware_uarts` **with Nextion displays.**
*Use of software UARTs is known to result in unpredictable/inconsistent behavior.*
If you **must** use a software UART, note that baud rates greater than 9600 are extremely likely to cause problems.
In short, avoid using software UARTs with Nextion displays.
.. code-block:: yaml

2
components/display/tm1637.rst
View File

@ -124,7 +124,7 @@ segment of the previous position will be enabled.
// Result: "S 42"
// Print the current time
it.strftime("%H.%M");
it.strftime("%H.%M", id(homeassistant_time).now());
// Result for 10:06:42 -> "10:06" on a display with : and "10.06" on a display with .
Please see :ref:`display-printf` for a quick introduction into the ``printf`` formatting rules and

10
components/pylontech.rst
View File

@ -28,19 +28,27 @@ MAX3232-based transceivers have been tested and work well.
If you have multiple batteries you need to connect to the master battery's console port.
.. list-table:: Pylontech RJ45 Console Port (US2000C, US3000C)
.. list-table:: Pylontech RJ45 Console Port (US2000C, US3000C, US5000C)
:header-rows: 1
* - RJ45 Pin
- TIA-568B Color
- TIA-568A Color
- Function
- Connect to
* - 3
- White/Green
- White/Orange
- Pylontech TX
- ESPHome RX via transceiver
* - 6
- Green
- Orange
- Pylontech RX
- ESPHome TX via transceiver
* - 8
- Brown
- Brown
- GND
- GND

14
components/remote_receiver.rst
View File

@ -120,6 +120,8 @@ ESP32 Arduino configuration variables:
"ESP32-S2", "0, 1, 2, 3"
"ESP32-S3", "4, 5, 6, 7"
"ESP32-C3", "2, 3"
"ESP32-C6", "2, 3"
"ESP32-H2", "2, 3"
- **memory_blocks** (*Optional*, int): The number of RMT memory blocks used. The maximum
number of blocks shared by all receivers and transmitters depends on the ESP32 variant. Defaults to ``3``.
@ -140,7 +142,7 @@ Automations:
ABB-Welcome code has been decoded. A variable ``x`` of type :apiclass:`remote_base::ABBWelcomeData`
is passed to the automation for use in lambdas.
- **on_aeha** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
AEHA remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::AEHAData`
AEHA remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::AEHAData`
is passed to the automation for use in lambdas.
- **on_byronsx** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
Byron SX doorbell RF code has been decoded. A variable ``x`` of type :apistruct:`remote_base::ByronSXData`
@ -152,7 +154,7 @@ Automations:
CanalSatLD remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::CanalSatLDData`
is passed to the automation for use in lambdas.
- **on_coolix** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
Coolix remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::CoolixData`
Coolix remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::CoolixData`
is passed to the automation for use in lambdas.
- **on_dish** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
dish network remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::DishData`
@ -171,13 +173,13 @@ Automations:
KeeLoq RF code has been decoded. A variable ``x`` of type :apistruct:`remote_base::KeeloqData`
is passed to the automation for use in lambdas.
- **on_haier** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
Haier remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::HaierData`
Haier remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::HaierData`
is passed to the automation for use in lambdas.
- **on_lg** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
LG remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::LGData`
is passed to the automation for use in lambdas.
- **on_magiquest** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
MagiQuest wand remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::MagiQuestData`
MagiQuest wand remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::MagiQuestData`
is passed to the automation for use in lambdas.
- **on_midea** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
Midea remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::MideaData`
@ -186,7 +188,7 @@ Automations:
NEC remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::NECData`
is passed to the automation for use in lambdas.
- **on_nexa** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
Nexa RF code has been decoded. A variable ``x`` of type :apiclass:`remote_base::NexaData`
Nexa RF code has been decoded. A variable ``x`` of type :apistruct:`remote_base::NexaData`
is passed to the automation for use in lambdas.
- **on_panasonic** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
Panasonic remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::PanasonicData`
@ -557,7 +559,7 @@ Remote code selection (exactly one of these has to be included):
tolerance: 60%
filter: 4us
idle: 4ms
remote_transmitter:
pin: 1
carrier_duty_percent: 100%

2
components/remote_transmitter.rst
View File

@ -74,6 +74,8 @@ ESP32 Arduino configuration variables:
"ESP32-S2", "0, 1, 2, 3"
"ESP32-S3", "0, 1, 2, 3"
"ESP32-C3", "0, 1"
"ESP32-C6", "0, 1"
"ESP32-H2", "0, 1"
- **clock_divider** (*Optional*, int): The clock divider used by the RMT peripheral. A clock divider of ``80`` leads to
a resolution of 1 µs per tick, ``160`` leads to 2 µs. Allowed values are in range ``1`` to ``255``. Defaults to ``80``.

2
components/rtttl.rst
View File

@ -175,7 +175,7 @@ Sample code
api:
actions:
- action: play_rtttl
- action: rtttl_play
variables:
song_str: string
then:

4
components/sensor/bme280.rst
View File

@ -58,13 +58,13 @@ Configuration variables:
- **pressure** (*Optional*): The information for the pressure sensor.
- **oversampling** (*Optional*): The oversampling parameter for the temperature sensor.
- **oversampling** (*Optional*): The oversampling parameter for the pressure sensor.
See :ref:`Oversampling Options <bme280-oversampling>`.
- All other options from :ref:`Sensor <config-sensor>`.
- **humidity** (*Optional*): The information for the humidity sensor.
- **oversampling** (*Optional*): The oversampling parameter for the temperature sensor.
- **oversampling** (*Optional*): The oversampling parameter for the humidity sensor.
See :ref:`Oversampling Options <bme280-oversampling>`.
- All other options from :ref:`Sensor <config-sensor>`.

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.7 KiB

After

Width:  |  Height:  |  Size: 3.7 KiB

2
components/sensor/gcja5.rst
View File

@ -39,8 +39,6 @@ Configuration variables:
All options from :ref:`Sensor <config-sensor>`.
- **pm_10_0** (*Optional*): Mass of particles with a diameter of 10 micrometres or less (μg/m^3).
All options from :ref:`Sensor <config-sensor>`.
- **pm_10_0** (*Optional*): Mass of particles with a diameter of 10 micrometres or less (μg/m^3).
All options from :ref:`Sensor <config-sensor>`.
- **pmc_0_3** (*Optional*): Count of particles with diameter > 0.3 um in 0.1 L of air (#/0.1L).
All options from :ref:`Sensor <config-sensor>`.
- **pmc_0_5** (*Optional*): Count of particles with diameter > 0.5 um in 0.1 L of air (#/0.1L).

2
components/sensor/max17043.rst
View File

@ -94,7 +94,7 @@ For example:
Once you have called the ``sleep_mode()`` action, the MAX17043 will stop recalculating the voltage and battery level.
Hence, if you leave the ESP running it will continue to publish the sensor values with the *last* measurements.
The only way to come of sleep mode is to restart the device (either as intended via deep sleep wake; or less ideally with a power cycle).
The only way to come out of sleep mode is to restart the device (either as intended via deep sleep wake; or less ideally with a power cycle).
So, only call ``sleep_mode()`` when you intend to send the ESP into deep sleep.

2
components/xl9535.rst
View File

@ -62,6 +62,6 @@ See Also
- :ref:`i2c`
- :doc:`switch/gpio`
- :doc:`binary_sensor/gpio`
- `XL9535 datasheet <https://datasheet.lcsc.com/lcsc/2211110930_XINLUDA-XL9535_C561273.pdf>`__
- `XL9535 datasheet <https://www.lcsc.com/datasheet/lcsc_datasheet_2410122054_XINLUDA-XL9535_C561273.pdf>`__
- :apiref:`xl9535/xl9535.h`
- :ghedit:`Edit`

127
guides/contributing.rst
View File

@ -851,7 +851,7 @@ the ESPHome core via the defined interfaces (like ``Sensor``, ``BinarySensor`` a
Directory Structure
*******************
After you've :ref:`set up a development environment <setup_dev_env>`, you will have a folder structure like this:
After you've :ref:`set up a development environment <setup_dev_env>`, you will have a directory structure like this:
.. code-block:: text
@ -873,9 +873,24 @@ After you've :ref:`set up a development environment <setup_dev_env>`, you will h
│ │ ├── restart_switch.h
│ │ ├── switch.py
│ ...
├── tests
│ ├── components
│ │ ├── dht12
│ │ │ ├── common.yaml
│ │ │ ├── test.esp32-ard.yaml
│ │ │ ├── test.esp32-c3-ard.yaml
│ │ │ ├── test.esp32-c3-idf.yaml
│ │ │ ├── test.esp32-idf.yaml
│ │ │ ├── test.esp8266-ard.yaml
│ │ │ ├── test.rp2040-ard.yaml
│ ...
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``).
All components are in the "components" directory. Each component is in its own subdirectory which contains the Python
code (``.py``) and the C++ code (``.h`` and ``.cpp``).
In the "tests" directory, a second "components" directory contains configuration files (``.yaml``) used to perform test
builds of each component. It's structured similarly to the "components" directory mentioned above, with subdirectories
for each component.
Consider a YAML configuration file containing the following:
@ -886,24 +901,20 @@ Consider a YAML configuration file containing the following:
sensor:
- platform: hello2
In both cases, ESPHome will automatically look for corresponding entries in the "components" folder and find the
In both cases, ESPHome will automatically look for corresponding entries in the "components" directory and find the
directory with the given name. In this example, the first entry causes ESPHome to look for the
``esphome/components/hello1/__init__.py`` file and the second entry tells ESPHome to look for
``esphome/components/hello2/sensor.py`` or ``esphome/components/hello2/sensor/__init__.py``.
Let's leave what's written in those files for :ref:`the next section <config_validation>`, but for now you should also
know that, whenever a component is loaded, all the C++ source files in the folder of the component are automatically
copied into the generated PlatformIO project. All you need to do is add the C++ source files in the component's folder
know that, whenever a component is loaded, all the C++ source files in the directory of the component are automatically
copied into the generated PlatformIO project. All you need to do is add the C++ source files in the component's directory
and the ESPHome core will copy them with no additional code required by the component developer.
.. note::
For testing, you can use :doc:`/components/external_components`.
ESPHome also has a ``custom_components`` mechanism like `Home Assistant does
<https://developers.home-assistant.io/docs/creating_component_index>`__. Note, however, that
**custom components are deprecated** in favor of :doc:`/components/external_components`.
.. _config_validation:
Config Validation
@ -1014,6 +1025,102 @@ the provided methods.
Finally, your component must have a ``dump_config`` method that prints the complete user configuration.
.. _test_configurations:
Test Configurations
*******************
Each (new) component/platform must have tests. This enables our CI system to perform a test build of the
component/platform to ensure it compiles without any errors. The test file(s) should incorporate the new
component/platform itself as well as all :doc:`automations</automations/actions>` it implements.
Overview
^^^^^^^^
The tests aim to test compilation of the code for each processor architecture:
- Xtensa (ESP8266, original ESP32 and S-series)
- RISC-V (ESP32 C-series)
- ARM (RP2040)
...and for each supported framework:
- Arduino
- `ESP-IDF <https://github.com/espressif/esp-idf/>`__
There should be *at least one test* for each framework/architecture combination. We can probably go without saying it,
but some framework/architecture combinations are simply not supported/possible, so tests for those are impossible and,
as such, are (naturally) omitted.
General Structure
^^^^^^^^^^^^^^^^^
We try to structure the tests in a way so as to minimize repetition. Let's look at the ``dht12`` sensor platform as an
example:
First, you'll find a ``common.yaml`` file which contains this:
.. code-block:: yaml
i2c:
- id: i2c_dht12
scl: ${scl_pin}
sda: ${sda_pin}
sensor:
- platform: dht12
temperature:
name: DHT12 Temperature
humidity:
name: DHT12 Humidity
update_interval: 15s
It's a shared configuration file that defines common settings used across all hardware platforms. Having a "common"
file like this minimizes duplication and ensures test consistency across all platforms.
To use ``common.yaml`` in a test configuration, YAML substitutions and the insertion operator are used (see
:doc:`/components/substitutions`). This allows the test YAML file to reference and include the shared configuration.
For the ``dht12`` platform, one of the test files is named ``test.esp32-ard.yaml`` and it contains this:
.. code-block:: yaml
substitutions:
scl_pin: GPIO16
sda_pin: GPIO17
<<: !include common.yaml
By including ``common.yaml``, all test configurations maintain the same structure while allowing flexibility for
platform-specific substitutions such as pin assignments. This approach simplifies managing multiple test cases across
different hardware platforms.
Which Tests Do I Need?
^^^^^^^^^^^^^^^^^^^^^^
We require a test for each framework/architecture combination the component/platform supports. *Most*
components/platforms include the following test files:
- ``test.esp32-ard.yaml`` - ESP32 (Xtensa)/Arduino
- ``test.esp32-idf.yaml`` - ESP32 (Xtensa)/IDF
- ``test.esp32-c3-ard.yaml`` - ESP32-C3 (RISC-V)/Arduino
- ``test.esp32-c3-idf.yaml`` - ESP32-C3 (RISC-V)/IDF
- ``test.esp8266-ard.yaml`` - ESP8266 (Xtensa)/Arduino
- ``test.rp2040-ard.yaml`` - RP2040 (ARM)/Arduino
In cases where the component/platform implements support for some microcontroller-specific hardware component, tests
should be added to/omitted from the list above as appropriate. The :doc:`/components/sensor/adc` is one example of this.
Running the Tests
^^^^^^^^^^^^^^^^^
You can run the tests locally simply by invoking the test script:
.. code-block:: shell
script/test_build_components -e compile -c dht12
Our CI will also run this script when you create or update your pull request (PR).
.. _delays_in_code:
A Note About Delays in Code