esphome-docs/components/output/custom.rst

103 lines
3.0 KiB
ReStructuredText
Raw Normal View History

2018-11-27 17:05:23 +01:00
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 </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`