esphome-docs/components/output/custom.rst

111 lines
3.3 KiB
ReStructuredText
Raw Normal View History

2018-11-27 17:05:23 +01:00
Custom Output
=============
.. seo::
:description: Instructions for setting up Custom C++ outputs with ESPHome.
:image: language-cpp.svg
:keywords: C++, Custom
.. 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`.
.. warning::
While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less
stable. If something in the APIs needs to be changed in order for something else to work, we will do so.
This component can be used to create custom binary and float :doc:`outputs </components/output/index>`
2019-02-16 23:25:23 +01:00
in ESPHome using the C++ (Arduino) API.
2018-11-27 17:05:23 +01:00
Please first read :doc:`/components/sensor/custom` guide, the same principles apply here.
2018-11-27 17:05:23 +01:00
The example below is an example of a custom float output; this custom output is essentially the
same as the :doc:`ESP8266 software PWM output </components/output/esp8266_pwm>`.
2018-11-27 17:05:23 +01:00
.. code-block:: cpp
2019-02-16 23:25:23 +01:00
#include "esphome.h"
using namespace esphome;
2018-11-27 17:05:23 +01:00
2019-05-12 22:44:59 +02:00
class MyCustomFloatOutput : public Component, public FloatOutput {
2018-11-27 17:05:23 +01:00
public:
void setup() override {
// This will be called by App.setup()
pinMode(5, OUTPUT);
}
void write_state(float state) override {
// state is the amount this output should be on, from 0.0 to 1.0
// we need to convert it to an integer first
int value = state * 1024;
analogWrite(5, value);
}
};
// Custom binary output, for exposing binary states
2019-05-12 22:44:59 +02:00
class MyCustomBinaryOutput : public Component, public BinaryOutput {
2018-11-27 17:05:23 +01:00
public:
void setup() override {
// This will be called by App.setup()
pinMode(5, OUTPUT);
}
void write_state(bool state) override {
digitalWrite(5, state);
}
};
(Store this file in your configuration directory, for example ``my_output.h``)
And in YAML:
.. code-block:: yaml
# Example configuration entry
2019-02-16 23:25:23 +01:00
esphome:
2018-11-27 17:05:23 +01:00
includes:
- my_output.h
output:
- platform: custom
type: float
lambda: |-
auto my_custom_float_output = new MyCustomFloatOutput();
App.register_component(my_custom_float_output);
return {my_custom_float_output};
outputs:
id: custom_float
- platform: custom
type: binary
lambda: |-
auto my_custom_binary_output = new MyCustomBinaryOutput();
App.register_component(my_custom_binary_output);
return {my_custom_binary_output};
outputs:
id: custom_binary
Configuration variables:
- **type** (**Required**, string): The type of output. One of ``binary`` and ``float``.
- **lambda** (**Required**, :ref:`lambda <config-lambda>`): The lambda to run for instantiating the
output(s).
- **outputs** (**Required**, list): A list of outputs to initialize. The length here
must equal the number of items in the ``return`` statement of the ``lambda``.
- All options from :ref:`Output <config-output>`.
2019-05-12 22:44:59 +02:00
See :apiclass:`output::BinaryOutput` and :apiclass:`output::FloatOutput`.
2018-11-27 17:05:23 +01:00
See Also
--------
- :ghedit:`Edit`