From b996e377da08f9d04112e126e754765ac55bd465 Mon Sep 17 00:00:00 2001 From: Otto Winter Date: Wed, 17 Oct 2018 20:44:37 +0200 Subject: [PATCH] Add Text sensors (#52) * Add Text Sensors * Add template text sensor --- api/index.rst | 1 + api/text_sensor/index.rst | 40 ++++++++ api/text_sensor/mqtt_subscribe.rst | 16 +++ api/text_sensor/template.rst | 16 +++ api/text_sensor/version.rst | 16 +++ esphomeyaml/components/index.rst | 1 + esphomeyaml/components/sensor/index.rst | 2 +- .../text_sensor/images/version-ui.png | Bin 0 -> 4625 bytes esphomeyaml/components/text_sensor/index.rst | 91 ++++++++++++++++++ .../components/text_sensor/mqtt_subscribe.rst | 54 +++++++++++ .../components/text_sensor/template.rst | 41 ++++++++ .../components/text_sensor/version.rst | 31 ++++++ esphomeyaml/index.rst | 26 +++++ esphomeyaml/text_sensor.csv | 4 + 14 files changed, 338 insertions(+), 1 deletion(-) create mode 100644 api/text_sensor/index.rst create mode 100644 api/text_sensor/mqtt_subscribe.rst create mode 100644 api/text_sensor/template.rst create mode 100644 api/text_sensor/version.rst create mode 100644 esphomeyaml/components/text_sensor/images/version-ui.png create mode 100644 esphomeyaml/components/text_sensor/index.rst create mode 100644 esphomeyaml/components/text_sensor/mqtt_subscribe.rst create mode 100644 esphomeyaml/components/text_sensor/template.rst create mode 100644 esphomeyaml/components/text_sensor/version.rst create mode 100644 esphomeyaml/text_sensor.csv diff --git a/api/index.rst b/api/index.rst index ecae8b456..3ac5275b2 100644 --- a/api/index.rst +++ b/api/index.rst @@ -13,4 +13,5 @@ API Reference Switch Cover Display + Text Sensors Miscellaneous diff --git a/api/text_sensor/index.rst b/api/text_sensor/index.rst new file mode 100644 index 000000000..950980268 --- /dev/null +++ b/api/text_sensor/index.rst @@ -0,0 +1,40 @@ +Text Sensor +=========== + +.. cpp:namespace:: nullptr + +See :cpp:func:`Application::register_text_sensor`. + +.. toctree:: + :maxdepth: 1 + + version + mqtt_subscribe + template + + +API Reference +------------- + +.. cpp:namespace:: nullptr + +TextSensor +********** + +.. doxygenclass:: text_sensor::TextSensor + :members: + :protected-members: + :undoc-members: + +.. doxygenclass:: text_sensor::TextSensorValueTrigger + :members: + :protected-members: + :undoc-members: + +MQTTTextSensor +************** + +.. doxygenclass:: text_sensor::MQTTTextSensor + :members: + :protected-members: + :undoc-members: diff --git a/api/text_sensor/mqtt_subscribe.rst b/api/text_sensor/mqtt_subscribe.rst new file mode 100644 index 000000000..070881de4 --- /dev/null +++ b/api/text_sensor/mqtt_subscribe.rst @@ -0,0 +1,16 @@ +MQTT Subscribe Text Sensor +========================== + +.. cpp:namespace:: nullptr + +See :cpp:func:`Application::make_mqtt_subscribe_text_sensor`. + +API Reference +------------- + +.. cpp:namespace:: nullptr + +.. doxygenclass:: text_sensor::MQTTSubscribeTextSensor + :members: + :protected-members: + :undoc-members: diff --git a/api/text_sensor/template.rst b/api/text_sensor/template.rst new file mode 100644 index 000000000..3953d9d8a --- /dev/null +++ b/api/text_sensor/template.rst @@ -0,0 +1,16 @@ +Template Text Sensor +==================== + +.. cpp:namespace:: nullptr + +See :cpp:func:`Application::make_template_text_sensor`. + +API Reference +------------- + +.. cpp:namespace:: nullptr + +.. doxygenclass:: text_sensor::TemplateTextSensor + :members: + :protected-members: + :undoc-members: diff --git a/api/text_sensor/version.rst b/api/text_sensor/version.rst new file mode 100644 index 000000000..ad646a616 --- /dev/null +++ b/api/text_sensor/version.rst @@ -0,0 +1,16 @@ +Version Text Sensor +=================== + +.. cpp:namespace:: nullptr + +See :cpp:func:`Application::make_version_text_sensor`. + +API Reference +------------- + +.. cpp:namespace:: nullptr + +.. doxygenclass:: text_sensor::VersionTextSensor + :members: + :protected-members: + :undoc-members: diff --git a/esphomeyaml/components/index.rst b/esphomeyaml/components/index.rst index 4ee0bd4cd..0acca161a 100644 --- a/esphomeyaml/components/index.rst +++ b/esphomeyaml/components/index.rst @@ -11,6 +11,7 @@ Components sensor/index switch/index display/index + text_sensor/index ads1115 dallas debug diff --git a/esphomeyaml/components/sensor/index.rst b/esphomeyaml/components/sensor/index.rst index b8b9c181a..76d9a1932 100644 --- a/esphomeyaml/components/sensor/index.rst +++ b/esphomeyaml/components/sensor/index.rst @@ -313,7 +313,7 @@ advanced stuff (see the full :doc:`API Reference ` for more i See Also -******** +-------- - :doc:`API Reference ` - `Edit this page on GitHub `__ diff --git a/esphomeyaml/components/text_sensor/images/version-ui.png b/esphomeyaml/components/text_sensor/images/version-ui.png new file mode 100644 index 0000000000000000000000000000000000000000..61b6ae8c42bb23e1f782e7f6deec7bcdc76aa9fc GIT binary patch literal 4625 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 literal 0 HcmV?d00001 diff --git a/esphomeyaml/components/text_sensor/index.rst b/esphomeyaml/components/text_sensor/index.rst new file mode 100644 index 000000000..228f363a9 --- /dev/null +++ b/esphomeyaml/components/text_sensor/index.rst @@ -0,0 +1,91 @@ +Text Sensor Component +===================== + +Text sensors are a lot like normal :doc:`sensors `. +But where the "normal" sensors only represent sensors that output **numbers**, this +component can represent any *text*. + +.. _config-text_sensor: + +Base Text Sensor Configuration +------------------------------ + +.. code:: yaml + + # Example sensor configuration + name: Livingroom Temperature + + # Optional variables: + icon: "mdi:water-percent" + +Configuration variables: + +- **name** (**Required**, string): The name for the sensor. +- **icon** (*Optional*, icon): Manually set the icon to use for the sensor in the frontend. + +Automations: + +- **on_value** (*Optional*, :ref:`Automation `): An automation to perform + when a new value is published. See :ref:`text_sensor-on_value`. + +Text Sensor Automation +---------------------- + +You can access the most recent state of the sensor in :ref:`lambdas ` using +``id(sensor_id).value``. + +.. _text_sensor-on_value: + +``on_value`` +************ + +This automation will be triggered when a new value is published. +In :ref:`Lambdas ` you can get the value from the trigger with ``x``. + +.. code:: yaml + + text_sensor: + - platform: version + # ... + on_value: + then: + - lambda: |- + ESP_LOGD("main", "The current version is %s", x.c_str()); + +Configuration variables: See :ref:`Automation `. + +lambda calls +************ + +From :ref:`lambdas `, you can call several methods on all text sensors to do some +advanced stuff (see the full :doc:`API Reference ` for more info). + +- ``push_new_value()``: Manually cause the sensor to push out a value. + + .. code:: yaml + + // Within lambda, push a value of "Hello World" + id(my_sensor).push_new_value("Hello World"); + +- ``value``: Retrieve the current value of the sensor as an ``std::string`` object. + + .. code:: yaml + + // For example, create a custom log message when a value is received: + std::string val = id(my_sensor).value; + ESP_LOGI("main", "Value of my sensor: %s", val.c_str()); + +See Also +-------- + +- :doc:`API Reference ` +- `Edit this page on GitHub `__ + +.. toctree:: + :maxdepth: 1 + + version + mqtt_subscribe + template + +.. disqus:: diff --git a/esphomeyaml/components/text_sensor/mqtt_subscribe.rst b/esphomeyaml/components/text_sensor/mqtt_subscribe.rst new file mode 100644 index 000000000..7a4e59a39 --- /dev/null +++ b/esphomeyaml/components/text_sensor/mqtt_subscribe.rst @@ -0,0 +1,54 @@ +MQTT Subscribe Text Sensor +========================== + +The ``mqtt_subscribe`` text sensor platform allows you to get external data into esphomelib. +The sensor will subscribe to messages on the given MQTT topic and save the most recent value +in its ``id(mysensor).value``. + +.. code:: yaml + + # Example configuration entry + text_sensor: + - platform: mqtt_subscribe + name: "Data from topic" + id: mysensor + topic: the/topic + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name of the text sensor. +- **topic** (**Required**, string): The MQTT topic to listen for numeric messages. +- **qos** (*Optional*, int): The MQTT QoS to subscribe with. Defaults to ``0``. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- All other options from :ref:`Text Sensor ` and :ref:`MQTT Component `. + +Example Usage for Displays +-------------------------- + +This integration is especially useful for displays, to show external data on the display. +Please note you have to use the ``.c_str()`` method on the value object together with the ``%s`` format +to use it in ``printf`` expressions. + +.. code:: yaml + + # Example configuration entry + text_sensor: + - platform: mqtt_subscribe + name: "Data from topic" + id: mysensor + topic: the/topic + + display: + - platform: ... + # ... + lambda: |- + it.printf("The data is: %s", id(font), id(mysensor).value.c_str()); + +See Also +-------- + +- :doc:`API Reference ` +- `Edit this page on GitHub `__ + +.. disqus:: diff --git a/esphomeyaml/components/text_sensor/template.rst b/esphomeyaml/components/text_sensor/template.rst new file mode 100644 index 000000000..4331a7e75 --- /dev/null +++ b/esphomeyaml/components/text_sensor/template.rst @@ -0,0 +1,41 @@ +Template Text Sensor +==================== + +The ``template`` text sensor platform allows you to create a text sensor with templated values +using :ref:`lambdas `. + +.. code:: yaml + + # Example configuration entry + text_sensor: + - platform: template + name: "Template Text Sensor" + lambda: |- + return "Hello World"; + update_interval: 15s + + +Possible return values for the lambda: + + - ``return "STRING LITERAL";`` the new value for the sensor of type ``std::string``. + - ``return {};`` if you don't want to publish a new state (advanced). + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name of the text sensor. +- **lambda** (*Optional*, :ref:`lambda `): + Lambda to be evaluated every update interval to get the new value of the text sensor +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the + text sensor. Defaults to ``15s``. See :ref:`sensor-default_filter`. +- **id** (*Optional*,:ref:`config-id`): Manually specify the ID used for code generation. +- All other options from :ref:`Text Sensor ` and :ref:`MQTT Component `. + +See Also +-------- + +- :ref:`automation` +- :doc:`API Reference ` +- `Edit this page on GitHub `__ + +.. disqus:: diff --git a/esphomeyaml/components/text_sensor/version.rst b/esphomeyaml/components/text_sensor/version.rst new file mode 100644 index 000000000..2bff668fc --- /dev/null +++ b/esphomeyaml/components/text_sensor/version.rst @@ -0,0 +1,31 @@ +Version Text Sensor +=================== + +The ``version`` text sensor platform exposes the esphomelib version the firmware +was compiled against as a text sensor. + +.. figure:: images/version-ui.png + :align: center + :width: 80.0% + +.. code:: yaml + + # Example configuration entry + text_sensor: + - platform: version + name: "Esphomelib Version" + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name of the text sensor. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- All other options from :ref:`Text Sensor ` and :ref:`MQTT Component `. + +See Also +-------- + +- :doc:`API Reference ` +- `Edit this page on GitHub `__ + +.. disqus:: diff --git a/esphomeyaml/index.rst b/esphomeyaml/index.rst index 6dda4fc92..21d9f97ca 100644 --- a/esphomeyaml/index.rst +++ b/esphomeyaml/index.rst @@ -624,6 +624,32 @@ Cover Components :class: component-image .. _Template Cover: /esphomeyaml/components/cover/template.html +Text Sensor Components +---------------------- + +================================================== ================================================== ================================================== +|Text Sensor Core|_ |MQTT Subscribe|_ |Version|_ +-------------------------------------------------- -------------------------------------------------- -------------------------------------------------- +`Text Sensor Core`_ `MQTT Subscribe`_ `Version`_ +-------------------------------------------------- -------------------------------------------------- -------------------------------------------------- +|Template Text Sensor|_ +-------------------------------------------------- -------------------------------------------------- -------------------------------------------------- +`Template Text Sensor`_ +================================================== ================================================== ================================================== + +.. |Text Sensor Core| image:: /esphomeyaml/images/folder-open.svg + :class: component-image +.. _Text Sensor Core: /esphomeyaml/components/text_sensor/index.html +.. |MQTT Subscribe| image:: /esphomeyaml/images/mqtt.png + :class: component-image +.. _MQTT Subscribe: /esphomeyaml/components/text_sensor/mqtt_subscribe.html +.. |Version| image:: /esphomeyaml/images/new-box.svg + :class: component-image +.. _Version: /esphomeyaml/components/text_sensor/version.html +.. |Template Text Sensor| image:: /esphomeyaml/images/description.svg + :class: component-image +.. _Template Text Sensor: /esphomeyaml/components/text_sensor/template.html + Misc Components --------------- diff --git a/esphomeyaml/text_sensor.csv b/esphomeyaml/text_sensor.csv new file mode 100644 index 000000000..e32b17958 --- /dev/null +++ b/esphomeyaml/text_sensor.csv @@ -0,0 +1,4 @@ +Text Sensor Core, components/text_sensor/index, folder-open.svg +MQTT Subscribe, components/text_sensor/mqtt_subscribe, mqtt.png +Version, components/text_sensor/version, new-box.svg +Template Text Sensor, components/text_sensor/template, description.svg