2019-05-15 10:54:51 +02:00
|
|
|
Custom Cover
|
|
|
|
============
|
|
|
|
|
2023-11-01 06:47:57 +01:00
|
|
|
.. 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`.
|
|
|
|
|
2019-05-15 10:54:51 +02:00
|
|
|
This integration can be used to create custom covers in ESPHome
|
|
|
|
using the C++ (Arduino) API.
|
|
|
|
|
|
|
|
Please first read :doc:`/components/sensor/custom` guide,
|
|
|
|
the same principles apply here.
|
|
|
|
|
|
|
|
The example below is an example of a custom cover - all covers must override
|
|
|
|
two methods:
|
|
|
|
|
|
|
|
- ``get_traits``: This should return a :apiclass:`CoverTraits <cover::CoverTraits>` object
|
|
|
|
representing the capabilities of the cover.
|
|
|
|
- ``control``: This receives a :apiclass:`CoverCall <cover::CoverCall>` object that contains
|
|
|
|
the command the user tried to set.
|
|
|
|
|
|
|
|
.. code-block:: cpp
|
|
|
|
|
|
|
|
#include "esphome.h"
|
|
|
|
|
|
|
|
class MyCustomCover : public Component, public Cover {
|
|
|
|
public:
|
|
|
|
void setup() override {
|
|
|
|
// This will be called by App.setup()
|
|
|
|
pinMode(5, INPUT);
|
|
|
|
}
|
|
|
|
CoverTraits get_traits() override {
|
|
|
|
auto traits = CoverTraits();
|
|
|
|
traits.set_is_assumed_state(false);
|
|
|
|
traits.set_supports_position(true);
|
|
|
|
traits.set_supports_tilt(false);
|
2023-05-31 15:40:41 +02:00
|
|
|
traits.set_supports_stop(true);
|
2019-05-15 10:54:51 +02:00
|
|
|
return traits;
|
|
|
|
}
|
|
|
|
void control(const CoverCall &call) override {
|
|
|
|
// This will be called every time the user requests a state change.
|
|
|
|
if (call.get_position().has_value()) {
|
|
|
|
float pos = *call.get_position();
|
|
|
|
// Write pos (range 0-1) to cover
|
|
|
|
// ...
|
|
|
|
|
|
|
|
// Publish new state
|
|
|
|
this->position = pos;
|
|
|
|
this->publish_state();
|
|
|
|
}
|
|
|
|
if (call.get_stop()) {
|
|
|
|
// User requested cover stop
|
|
|
|
}
|
|
|
|
}
|
|
|
|
};
|
|
|
|
|
|
|
|
(Store this file in your configuration directory, for example ``my_cover.h``)
|
|
|
|
|
|
|
|
And in YAML:
|
|
|
|
|
|
|
|
.. code-block:: yaml
|
|
|
|
|
|
|
|
# Example configuration entry
|
|
|
|
esphome:
|
|
|
|
includes:
|
|
|
|
- my_cover.h
|
|
|
|
|
|
|
|
cover:
|
|
|
|
- platform: custom
|
|
|
|
lambda: |-
|
|
|
|
auto my_custom_cover = new MyCustomCover();
|
|
|
|
App.register_component(my_custom_cover);
|
|
|
|
return {my_custom_cover};
|
|
|
|
|
|
|
|
covers:
|
|
|
|
- name: "My Custom Cover"
|
|
|
|
|
|
|
|
Configuration variables:
|
|
|
|
|
|
|
|
- **lambda** (**Required**, :ref:`lambda <config-lambda>`): The lambda to run for instantiating the
|
|
|
|
cover(s).
|
|
|
|
- **covers** (**Required**, list): A list of covers to initialize. The length here
|
|
|
|
must equal the number of items in the ``return`` statement of the ``lambda``.
|
|
|
|
|
|
|
|
- All options from :ref:`Cover <config-cover>`.
|
|
|
|
|
|
|
|
See :apiclass:`Cover <cover::Cover>`
|
|
|
|
|
|
|
|
See Also
|
|
|
|
--------
|
|
|
|
|
|
|
|
- :ghedit:`Edit`
|