[binary_sensor] Document invalidate_state (#4974)

Author: clydebarrow

components/binary_sensor/index.rst

@@ -68,8 +68,10 @@ Advanced options:
 - **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
   (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
   Defaults to ``false``.
-- **publish_initial_state** (*Optional*, boolean): If true, then the sensor will publish its initial state at boot or when
-  HA first connects, depending on the platform.  This means that any applicable triggers will be run. Defaults to ``false``.
+- **trigger_on_initial_state** (*Optional*, boolean): If true, any applicable triggers will be fired when the binary sensor
+  state changes from ``unknown`` to a valid state. This applies to the first valid state set, and any valid state set after
+  a ``binary_sensor.invalidate_state`` action has been excuted. The default is ``false``.
+  **publish_initial_state** (*Optional*, boolean): A deprecated equivalent to ``trigger_on_initial_state``.
 - **entity_category** (*Optional*, string): The category of the entity.
   See https://developers.home-assistant.io/docs/core/entity/#generic-properties
   for a list of available options.
@@ -79,6 +81,27 @@ Advanced options:
 
 .. _binary_sensor-filters:
 
+
+Actions
+-------
+
+.. _binary_sensor-invalidate_state-action:
+
+``binary_sensor.invalidate_state`` Action
+*****************************************
+
+This action will invalidate the current state of the sensor. It is most useful with the Template binary sensor.
+After the state is invalidated, it will be reported to Home Assistant as ``unknown``. Example:
+
+.. code-block:: yaml
+
+    on_...:
+      binary_sensor.invalidate_state: my_binary_sensor_id
+
+
+The state may also be invalidated by an API call in a lambda - see the API reference linked below.
+
+
 Binary Sensor Filters
 ---------------------
 
@@ -274,7 +297,8 @@ Configuration variables: See :ref:`Automation <automation>`.
 
 This automation will be triggered when a new state is received (and thus combines ``on_press``
 and ``on_release`` into one trigger). The new state will be given as the variable ``x`` as a boolean
-and can be used in :ref:`lambdas <config-lambda>`.
+and can be used in :ref:`lambdas <config-lambda>`. It will not be called when the state is invalidated; it will be called when
+the state initially becomes valid only if ``trigger_on_initial_state`` is true.
 
 .. code-block:: yaml
 
@@ -287,6 +311,31 @@ and can be used in :ref:`lambdas <config-lambda>`.
 
 Configuration variables: See :ref:`Automation <automation>`.
 
+.. _binary_sensor-on_state_change:
+
+``on_state_change``
+*******************
+
+An alternative to ``on_state`` that is also triggered when the binary sensor state is invalidated. It is passed two parameters, ``x`` as for ``on_change``
+will be the new value, and ``x_previous`` is the value immediately prior to the change. Both these parameters are of type ``optional<bool>`` so also indicate
+if the values were valid. Note that this is called on all state changes, including initial states.
+
+.. code-block:: yaml
+
+    binary_sensor:
+      - platform: gpio
+        # ...
+        on_state_change:
+          then:
+          - logger.log:
+              format: "Old state was %s"
+              args: ['x_previous.has_value() ? ONOFF(x_previous) : "Unknown"']
+          - logger.log:
+              format: "New state is %s"
+              args: ['x.has_value() ? ONOFF(x) : "Unknown"']
+
+Configuration variables: See :ref:`Automation <automation>`.
+
 .. _binary_sensor-on_click:
 
 ``on_click``