From aba2f3afd54a8524c3143d5bf83c7aca6be0f3b3 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Wed, 1 Nov 2023 18:47:57 +1300 Subject: [PATCH] Add deprecation message to custom component pages (#3318) --- components/binary_sensor/custom.rst | 10 +++++ components/climate/custom.rst | 10 +++++ components/cover/custom.rst | 10 +++++ components/external_components.rst | 62 +++++++++++++++-------------- components/light/custom.rst | 10 +++++ components/output/custom.rst | 10 +++++ components/sensor/custom.rst | 10 +++++ components/switch/custom.rst | 10 +++++ components/text_sensor/custom.rst | 10 +++++ custom/custom_component.rst | 14 ++++++- custom/i2c.rst | 24 +++++++---- custom/spi.rst | 10 +++++ custom/uart.rst | 10 +++++ guides/contributing.rst | 30 +++++++------- 14 files changed, 177 insertions(+), 53 deletions(-) diff --git a/components/binary_sensor/custom.rst b/components/binary_sensor/custom.rst index d857a2c76..d2ee55fdc 100644 --- a/components/binary_sensor/custom.rst +++ b/components/binary_sensor/custom.rst @@ -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. diff --git a/components/climate/custom.rst b/components/climate/custom.rst index 3079c8b50..e4d86f19e 100644 --- a/components/climate/custom.rst +++ b/components/climate/custom.rst @@ -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. diff --git a/components/cover/custom.rst b/components/cover/custom.rst index dcd4a1643..4b49dbc5c 100644 --- a/components/cover/custom.rst +++ b/components/cover/custom.rst @@ -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. diff --git a/components/external_components.rst b/components/external_components.rst index efc31ca89..32a89747b 100644 --- a/components/external_components.rst +++ b/components/external_components.rst @@ -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: diff --git a/components/light/custom.rst b/components/light/custom.rst index 41275810d..03353f6f1 100644 --- a/components/light/custom.rst +++ b/components/light/custom.rst @@ -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. diff --git a/components/output/custom.rst b/components/output/custom.rst index 77e0dd403..501d46725 100644 --- a/components/output/custom.rst +++ b/components/output/custom.rst @@ -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 ` in ESPHome using the C++ (Arduino) API. diff --git a/components/sensor/custom.rst b/components/sensor/custom.rst index 6fa2d7eb4..76caada78 100644 --- a/components/sensor/custom.rst +++ b/components/sensor/custom.rst @@ -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 diff --git a/components/switch/custom.rst b/components/switch/custom.rst index a5837b94b..1f9344980 100644 --- a/components/switch/custom.rst +++ b/components/switch/custom.rst @@ -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. diff --git a/components/text_sensor/custom.rst b/components/text_sensor/custom.rst index e6d463dcf..e43e31f7d 100644 --- a/components/text_sensor/custom.rst +++ b/components/text_sensor/custom.rst @@ -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. diff --git a/custom/custom_component.rst b/custom/custom_component.rst index f794ce590..5544f3aac 100644 --- a/custom/custom_component.rst +++ b/custom/custom_component.rst @@ -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: diff --git a/custom/i2c.rst b/custom/i2c.rst index 78b68fa2d..7b556a9ba 100644 --- a/custom/i2c.rst +++ b/custom/i2c.rst @@ -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 `. - + .. 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 `. diff --git a/custom/spi.rst b/custom/spi.rst index 9bedb501e..1653a282c 100644 --- a/custom/spi.rst +++ b/custom/spi.rst @@ -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. diff --git a/custom/uart.rst b/custom/uart.rst index d5d74f8e4..57c52bcf0 100644 --- a/custom/uart.rst +++ b/custom/uart.rst @@ -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. diff --git a/guides/contributing.rst b/guides/contributing.rst index c84010e6d..c1d5d4560 100644 --- a/guides/contributing.rst +++ b/guides/contributing.rst @@ -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