diff --git a/components/display/nextion.rst b/components/display/nextion.rst index b85741973..fecb8881b 100644 --- a/components/display/nextion.rst +++ b/components/display/nextion.rst @@ -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 diff --git a/components/display/tm1637.rst b/components/display/tm1637.rst index 57c339ca8..4c46487eb 100644 --- a/components/display/tm1637.rst +++ b/components/display/tm1637.rst @@ -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 diff --git a/components/pylontech.rst b/components/pylontech.rst index c8d766184..b2dd11e97 100644 --- a/components/pylontech.rst +++ b/components/pylontech.rst @@ -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 diff --git a/components/remote_receiver.rst b/components/remote_receiver.rst index 74c633e82..78737d578 100644 --- a/components/remote_receiver.rst +++ b/components/remote_receiver.rst @@ -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 `): 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 `): 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 `): 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 `): 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 `): 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 `): 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 `): 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 `): 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 `): 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 `): 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% diff --git a/components/remote_transmitter.rst b/components/remote_transmitter.rst index 8c3e2ee85..3ad48ad14 100644 --- a/components/remote_transmitter.rst +++ b/components/remote_transmitter.rst @@ -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``. diff --git a/components/rtttl.rst b/components/rtttl.rst index dd0872e17..77ac0f0d5 100644 --- a/components/rtttl.rst +++ b/components/rtttl.rst @@ -175,7 +175,7 @@ Sample code api: actions: - - action: play_rtttl + - action: rtttl_play variables: song_str: string then: diff --git a/components/sensor/bme280.rst b/components/sensor/bme280.rst index 75e5671a5..f8fdd5323 100644 --- a/components/sensor/bme280.rst +++ b/components/sensor/bme280.rst @@ -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 `. - All other options from :ref:`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 `. - All other options from :ref:`Sensor `. diff --git a/components/sensor/gcja5.rst b/components/sensor/gcja5.rst index e03c11bd0..c9881f4af 100644 --- a/components/sensor/gcja5.rst +++ b/components/sensor/gcja5.rst @@ -39,8 +39,6 @@ Configuration variables: All options from :ref:`Sensor `. - **pm_10_0** (*Optional*): Mass of particles with a diameter of 10 micrometres or less (μg/m^3). All options from :ref:`Sensor `. -- **pm_10_0** (*Optional*): Mass of particles with a diameter of 10 micrometres or less (μg/m^3). - All options from :ref:`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 `. - **pmc_0_5** (*Optional*): Count of particles with diameter > 0.5 um in 0.1 L of air (#/0.1L). diff --git a/components/sensor/max17043.rst b/components/sensor/max17043.rst index 3b8af7add..cec367762 100644 --- a/components/sensor/max17043.rst +++ b/components/sensor/max17043.rst @@ -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. diff --git a/components/xl9535.rst b/components/xl9535.rst index e67a52d31..6b823c1ff 100644 --- a/components/xl9535.rst +++ b/components/xl9535.rst @@ -62,6 +62,6 @@ See Also - :ref:`i2c` - :doc:`switch/gpio` - :doc:`binary_sensor/gpio` -- `XL9535 datasheet `__ +- `XL9535 datasheet `__ - :apiref:`xl9535/xl9535.h` - :ghedit:`Edit` diff --git a/guides/contributing.rst b/guides/contributing.rst index 313cae3d5..1f46aea69 100644 --- a/guides/contributing.rst +++ b/guides/contributing.rst @@ -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 `, you will have a folder structure like this: +After you've :ref:`set up a development environment `, you will have a directory structure like this: .. code-block:: text @@ -873,9 +873,24 @@ After you've :ref:`set up a development environment `, 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 `, 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 - `__. 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` 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 `__ + +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