From c78d80b8312fdca2193e2cdb8433aacc1e6bc886 Mon Sep 17 00:00:00 2001 From: Sergey Dudanov Date: Thu, 13 Jul 2023 00:48:21 +0400 Subject: [PATCH] New duty_time sensor (#3049) Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com> --- components/sensor/duty_time.rst | 124 ++++++++++++++++++++++++++++++++ components/sensor/index.rst | 2 + images/timer-play-outline.svg | 1 + index.rst | 3 +- 4 files changed, 129 insertions(+), 1 deletion(-) create mode 100644 components/sensor/duty_time.rst create mode 100644 images/timer-play-outline.svg diff --git a/components/sensor/duty_time.rst b/components/sensor/duty_time.rst new file mode 100644 index 000000000..6273c87df --- /dev/null +++ b/components/sensor/duty_time.rst @@ -0,0 +1,124 @@ +Duty Time +========= + +.. seo:: + :description: Instructions for setting up a sensor that tracks the duty time of the some object. + :image: timer-play-outline.svg + +The ``duty_time`` sensor allows you to track the total duty time of the some object, for example, a light bulb, in seconds. +Able to calculate the last turn-on time when an optional sensor ``last_time`` is included in the configuration. + +Supports boolean signal sources: ``binary_sensor`` or ``lambda`` that returns a boolean state of tracked object. +As an alternative to controlling a component in automations, may be used the ``sensor.duty_time.start`` and ``sensor.duty_time.stop`` actions. + + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: duty_time + id: my_climate_work_time + name: My Climate Work Time + # Support logical sources (optional): 'binary_sensor' + sensor: my_binary_sensor + # ... EOR 'lambda' + lambda: "return id(my_climate).mode != CLIMATE_MODE_OFF;" + # Restore (optional, default: False) + restore: false + # Sensor for last turn-on time (optional) + last_time: + name: My Climate Last Turn-On Time + + +Configuration variables: +------------------------ + +- **sensor** (*Optional*, :ref:`config-id`): The ID of the ``binary_sensor`` to track the duty time. *May not be + used with* ``lambda``. +- **lambda** (*Optional*, :ref:`lambda `): Lambda that will be called in a loop to get the current + state of the tracked object. *May not be used with* ``sensor``. +- **last_time** (*Optional*): Information of the last switch-on time sensor. + All options from :ref:`Sensor `. +- **restore** (*Optional*, boolean): Whether to store the intermediate result on the device so that the value can be + restored upon power cycle or reboot. + Warning: this option can wear out your flash. Defaults to ``false``. +- **update_interval** (*Optional*, :ref:`config-time`): The update interval. Defaults to ``60s``. +- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. +- All other options from :ref:`Sensor `. + + +Automations +----------- + +In addition to all basic :ref:`sensor automations `, the component supports the automations below. + +.. _sensor-duty_time-start_action: + +``sensor.duty_time.start`` Action +********************************* + +This action starts/resume time tracking. In lambdas, you may use the ``start()`` method. + +.. code-block:: yaml + + on_...: + then: + - sensor.duty_time.start: my_climate_work_time + + + +.. _sensor-duty_time-stop_action: + +``sensor.duty_time.stop`` Action +******************************** + +This action suspends time tracking. Causes the sensor to be updated, including the ``last_time`` sensor. In lambdas, you may use the ``stop()`` method. + +.. code-block:: yaml + + on_...: + then: + - sensor.duty_time.stop: my_climate_work_time + + +.. _sensor-duty_time-reset_action: + +``sensor.duty_time.reset`` Action +********************************* + +This action resets the duty time counter. Causes a sensor update. Does not affect the ``last_time`` sensor. In lambdas, you may use the ``reset()`` method. + +.. code-block:: yaml + + on_...: + then: + - sensor.duty_time.reset: my_climate_work_time + + +.. _sensor-duty_time-is_running_action: +.. _sensor-duty_time-is_not_running_action: + +``sensor.duty_time.is_running`` / ``sensor.duty_time.is_not_running`` Condition +******************************************************************************* + +This :ref:`Condition ` checks if the ``duty_time`` counter is currently running (or suspended). In lambdas, you may use the ``is_running()`` method. + +.. code-block:: yaml + + # In some trigger: + on_...: + if: + condition: + # Same syntax for 'is_not_running' + sensor.duty_time.is_running: my_climate_work_time + + +See Also +-------- + +- :ref:`config-sensor` +- :ref:`config-lambda` +- :ref:`automation` +- :doc:`/components/binary_sensor/index` +- :apiref:`duty_time/duty_time_sensor.h` +- :ghedit:`Edit` diff --git a/components/sensor/index.rst b/components/sensor/index.rst index 3fb874c7e..fb38df0a3 100644 --- a/components/sensor/index.rst +++ b/components/sensor/index.rst @@ -557,6 +557,8 @@ Fahrenheit. - lambda: return x * (9.0/5.0) + 32.0; unit_of_measurement: "°F" +.. _sensor-automations: + Sensor Automation ----------------- diff --git a/images/timer-play-outline.svg b/images/timer-play-outline.svg new file mode 100644 index 000000000..7916c7b0e --- /dev/null +++ b/images/timer-play-outline.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.rst b/index.rst index 5d9a6de12..8214f0159 100644 --- a/index.rst +++ b/index.rst @@ -160,7 +160,6 @@ Core Sensor Core, components/sensor/index, folder-open.svg, dark-invert Home Assistant, components/sensor/homeassistant, home-assistant.svg, dark-invert - Integration, components/sensor/integration, sigma.svg, dark-invert MQTT Subscribe, components/sensor/mqtt_subscribe, mqtt.png Uptime Sensor, components/sensor/uptime, timer.svg, dark-invert WiFi Signal Strength, components/sensor/wifi_signal, network-wifi.svg, dark-invert @@ -360,9 +359,11 @@ Miscellaneous AS3935, components/sensor/as3935, as3935.jpg, Storm lightning Binary Sensor Map, components/sensor/binary_sensor_map, binary_sensor_map.jpg, Map binary to value b-parasite, components/sensor/b_parasite, b_parasite.jpg, Moisture & Temperature & Humidity & Light + Duty Time, components/sensor/duty_time, timer-play-outline.svg, dark-invert EZO sensor circuits, components/sensor/ezo, ezo-ph-circuit.png, (pH) FS3000, components/sensor/fs3000, fs3000.jpg, Air velocity Havells Solar, components/sensor/havells_solar, havellsgti5000d_s.jpg, Solar rooftop + Integration, components/sensor/integration, sigma.svg, dark-invert Growatt Solar, components/sensor/growatt_solar, growatt.jpg, Solar rooftop Kalman Combinator, components/sensor/kalman_combinator, function.svg, dark-invert Modbus Sensor, components/sensor/modbus_controller, modbus.png