Merge branch 'next' into patch-1

.github/workflows/lint.yml

@@ -21,7 +21,7 @@ jobs:
     steps:
     - uses: actions/checkout@v4.1.0
     - name: Set up Python 3.8
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: 3.8
     - name: Install dependencies

Doxygen

@@ -38,7 +38,7 @@ PROJECT_NAME           = "ESPHome"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2023.12.0-dev
+PROJECT_NUMBER         = 2024.1.0-dev
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

_static/custom.css

@@ -256,7 +256,7 @@ div.body p, div.body dd, div.body li, div.body blockquote {
       background: #212121;
       color: #ececec;
     }
-    
+
   }
 
   body, div.body {
@@ -281,7 +281,7 @@ div.body p, div.body dd, div.body li, div.body blockquote {
     color: #ececec;
     background-color: #212121;
   }
-  
+
   a, a.reference, a:visited {
     color: #00bfff;
     border-bottom: 1px dotted #00bfff;
@@ -326,7 +326,7 @@ div.body p, div.body dd, div.body li, div.body blockquote {
     color: #e2e2e2;
   }
 
-  div.note, div.tip {
+  div.note, div.tip, div.important {
     background-color: #2d2c2c;
     border: 1px solid #808080;
   }
@@ -339,4 +339,4 @@ div.body p, div.body dd, div.body li, div.body blockquote {
     background-color: #8e8129;
   }
 
-}
+}

_static/version

@@ -1 +1 @@
-2023.12.0-dev
+2024.1.0-dev

changelog/2023.11.0.rst

@@ -106,6 +106,12 @@ Release 2023.11.5 - November 28
 - Add 'voice_assistant.connected' condition :esphomepr:`5845` by :ghuser:`jesserockz`
 
 
+Release 2023.11.6 - November 28
+-------------------------------
+
+- Fix write_speaker without speaker in config :esphomepr:`5847` by :ghuser:`jesserockz`
+
+
 Full list of changes
 --------------------
 

changelog/index.rst

@@ -2,7 +2,7 @@ Changelog
 =========
 
 .. redirect::
-    :url: /changelog/2023.11.0.html
+    :url: /changelog/2023.12.0.html
 
 .. toctree::
     :glob:

components/alarm_control_panel/index.rst

@@ -44,6 +44,11 @@ Configuration variables:
   when the alarm state changes to ``disarmed``. See :ref:`alarm_control_panel_on_disarmed_trigger`.
 - **on_cleared** (*Optional*, :ref:`Action <config-action>`): An automation to perform
   when the alarm clears. See :ref:`alarm_control_panel_on_cleared_trigger`.
+- **on_ready** (*Optional*, :ref:`Action <config-action>`): An automation to perform
+  when the logical 'and' of all the zone sensors change state. See :ref:`alarm_control_panel_on_ready_trigger`.
+- **on_chime** (*Optional*, :ref:`Action <config-action>`): An automation to perform
+  when a zone has been marked as chime in the configuration, and it changes from closed to open. 
+  See :ref:`alarm_control_panel_on_chime_trigger`.
 
 
 Automation:
@@ -184,6 +189,39 @@ This trigger is activated when the alarm changes from to disarmed.
         then:
           - logger.log: "Alarm Disarmed!"
 
+.. _alarm_control_panel_on_ready_trigger:
+
+``on_ready`` Trigger
+********************
+
+This trigger is activated when the logical 'and' of all the alarm sensors change state. This is useful for implementing "alarm ready" LEDs.
+Once this trigger is called, you can get the ready state by calling get_all_sensors_ready() in a lambda block.
+
+.. code-block:: yaml
+
+    alarm_control_panel:
+      # ...
+      on_disarmed:
+        then:
+          - lambda: !lambda |-
+              ESP_LOGI("AlarmPanel", "Sensor ready change to: %s", ((id(acp1).get_all_sensors_ready()) ? (const char *) "True" : (const char *) "False"));
+
+.. _alarm_control_panel_on_chime_trigger:
+
+``on_chime`` Trigger
+********************
+
+This trigger is activated when a zone sensor marked with chime:true changes from closed to open. This is useful for implementing keypad chimes when a zone
+opens.
+
+.. code-block:: yaml
+
+    alarm_control_panel:
+      # ...
+      on_chime:
+        then:
+          - logger.log: "Alarm Chime!"
+
 .. _alarm_control_panel_arm_away_action:
 
 ``arm_away`` Action
@@ -296,13 +334,15 @@ From :ref:`lambdas <config-lambda>`, you can call the following methods:
 - ``arm_home(code)``
 - ``arm_night(code)``
 - ``disarm(code)``
+- ``get_all_sensors_ready()``
 
 .. code-block:: cpp
 
     id(acp1).arm_away();
     id(acp1).arm_home();
     id(acp1).arm_night();
     id(acp1).disarm(std::string("1234"));
+    bool all_sensors_ready = id(acp1).get_all_sensors_ready();
 
 
 Platforms

components/alarm_control_panel/template.rst

@@ -36,6 +36,8 @@ Configuration variables:
   - **input** (**Required**, string): The id of the binary sensor component
   - **bypass_armed_home** (*Optional*, boolean): This binary sensor will not trigger the alarm when in ``armed_home`` state.
   - **bypass_armed_night** (*Optional*, boolean): This binary sensor will not trigger the alarm when in ``armed_night`` state.
+  - **trigger_mode** (*Optional*, string): Sets the trigger mode for this sensor. One of ``delayed``, ``instant``, or ``delayed_follower``. (``delayed`` is the default if not specified)
+  - **chime** (*Optional*, boolean): When set ``true``, the chime callback will be called whenever the sensor goes from closed to open. (``false`` is the default if not specified)
 
 - **restore_mode** (*Optional*, enum):
 
@@ -46,9 +48,33 @@ Configuration variables:
 
 .. note::
 
-    If ``binary_sensors`` is ommited then you're expected to trigger the alarm using
+    If ``binary_sensors`` is omitted then you're expected to trigger the alarm using
     :ref:`alarm_control_panel_pending_action` or :ref:`alarm_control_panel_triggered_action`.
 
+.. _template_alarm_control_panel-trigger_modes:
+
+Trigger Modes
+-------------
+
+Each binary sensor "zone" supports 3 trigger modes. The 3 trigger modes are:
+
+- delayed
+- instant
+- delayed_follower
+
+The ``delayed`` trigger mode is typically specified for exterior doors where entry is required to access an alarm keypad or other arm/disarm method. If the alarm panel is armed, and a zone set to ``delayed`` is "faulted" (i.e. the zone state is ``true``) the alarm state will change from the ``armed`` state to the ``pending`` state. During the ``pending`` state, the user has a preset time to disarm the alarm before it changes to the ``triggered`` state. This is the default trigger mode if not specified.
+
+The ``instant`` trigger mode is typically used for exterior zones (e.g. windows, and glass break detectors).  If the alarm control panel is armed, a fault on this type of zone will cause the alarm to go from the ``armed`` state directly to the ``triggered`` state.
+
+The ``delayed_follower`` trigger mode is typically specifed for interior passive infared (PIR) or microwave sensors. One of two things happen when a ``delayed_follower`` zone is faulted:
+
+1. When the alarm panel is in the armed state, a fault on a zone with ``delayed_follower`` specified will cause the alarm control panel to go directly to the ``triggered`` state.
+
+2. When the alarm panel is in the pending state, a fault on a zone with ``delayed_follower`` specified will remain in the ``pending`` state.
+
+The ``delayed_follower`` trigger mode offers better protection if someone enters a premises via an unprotected window or door. If there is a PIR guarding the main hallway, it will cause an instant trigger of the alarm panel as someone
+entered the premises in a unusual manner. Likewise, if someone enters the premises though a door set to the ``delayed`` trigger mode, and then triggers the PIR, the alarm will stay in the ``pending`` state until either they disarm the alarm, or
+the pending timer expires.
 
 .. _template_alarm_control_panel-state_flow:
 
@@ -63,18 +89,29 @@ State Flow:
 
 3. When the alarm is tripped by a sensor state changing to ``on`` or ``alarm_control_panel_pending_action`` invoked
 
-  a. ``pending_time`` greater than 0 the state is ``PENDING``
-  b. ``pending_time`` is 0 or after the ``pending_time`` delay the state is ``TRIGGERED``
+  1. If trigger_mode is set to ``delayed``:
+
+    1. ``pending_time`` greater than 0 the state is ``PENDING``
+    2. ``pending_time`` is 0 or after the ``pending_time`` delay the state is ``TRIGGERED``
+
+  2. If trigger_mode is set to ``instant``:
+
+    1. The state is set to ``TRIGGERED``
+
+  3. If the trigger_mode is set to ``interior_follower``:
+
+    1. If the current state is ``ARMED_...`` the state will be set to ``TRIGGERED``
+    2. If the current state is ``PENDING`` then nothing will happen and it will stay in the ``PENDING`` state.
 
 4. If ``trigger_time`` greater than 0 and no sensors are ``on`` after ``trigger_time`` delay
    the state returns to ``ARM_...``
 
 .. note::
 
-    Although the interface supports all arming modes only ``away`` and ``home`` have been implemented for now.
+    Although the interface supports all arming modes only ``away``, ``home`` and ``night`` have been implemented for now.
     ``arm_...`` is for either ``arm_away`` or ``arm_home``
-    ``arming_..._time`` is for either ``arming_away_time`` or ``arming_home_time``
-    ``ARMED_...`` is for either ``ARMED_AWAY`` or ``ARMED_HOME``
+    ``arming_..._time`` is for either ``arming_away_time``, ``arming_home_time``, or ``arming_night_time``
+    ``ARMED_...`` is for either ``ARMED_AWAY``, ``ARMED_HOME``, or ``ARMED_NIGHT``
 
 
 Example:
@@ -95,8 +132,16 @@ Example:
       trigger_time: 5min
       binary_sensors:
         - input: zone_1
+          chime: true
+          trigger_mode: delayed
         - input: zone_2
+          chime: true
+          trigger_mode: delayed
+        - input: zone_3
           bypass_armed_home: true
+          trigger_mode: delayed_follower
+        - input: zone_4
+          trigger_mode: instant
         - input: ha_test
       on_state:
         then:
@@ -108,6 +153,15 @@ Example:
       on_cleared:
         then:
           - switch.turn_off: siren
+      on_ready:
+        then:
+         - lambda: !lambda |-
+             ESP_LOGD("TEST", "Sensor ready change to: %s",
+               (id(acp1).get_all_sensors_ready())) ? (const char *) "True" : (const char *) "False");
+      on_chime:
+        then:
+         - lambda: !lambda |-
+             ESP_LOGD("TEST", "Zone with chime mode set opened");
 
     binary_sensor:
       - platform: gpio
@@ -121,14 +175,30 @@ Example:
       - platform: gpio
         id: zone_2
         name: Zone 2
-        device_class: motion
+        device_class: door
         pin:
           number: D2
           mode: INPUT_PULLUP
           inverted: True
+      - platform: gpio
+        id: zone_3
+        name: Zone 3
+        device_class: motion
+        pin:
+          number: D3
+          mode: INPUT_PULLUP
+          inverted: True
+      - platform: gpio
+        id: zone_4
+        name: Zone 4
+        device_class: door
+        pin:
+          number: D4
+          mode: INPUT_PULLUP
+          inverted: True
       - platform: homeassistant
         id: ha_test
-        name: Zone 3
+        name: HA Test
         entity_id: input_boolean.test_switch
 
     switch:

components/binary_sensor/index.rst

@@ -208,6 +208,16 @@ Specify any :ref:`lambda <config-lambda>` for more complex filters. The input va
 the binary sensor is ``x`` and you can return ``true`` for ON, ``false`` for OFF, and ``{}`` to stop
 the filter chain.
 
+``settle``
+**********
+
+(**Required**, time, :ref:`templatable <config-templatable>`): When a signal is received, publish the state
+but wait for the received state to remain the same for specified time period before publishing any
+additional state changes. This filter complements the ``delayed_on_off`` filter but publishes value changes at
+the beginning of the delay period.
+When using a lambda call, you should return the delay value in milliseconds.
+**Useful for debouncing binary switches**.
+
 Binary Sensor Automation
 ------------------------