Add documentation for AMG8833 Infrared Array Sensor.

content/components/_index.md

@@ -347,6 +347,7 @@ Sensors are organized into categories; if a given sensor fits into more than one
 
 {{< imgtable >}}
 "Absolute Humidity","components/sensor/absolute_humidity","water-drop.svg","dark-invert",""
+"AMG8833","components/sensor/amg8833","amg8833.jpg","Temperature",""
 "AHT10 / AHT20 / AHT21 / DHT20","components/sensor/aht10","aht10.jpg","Temperature & Humidity",""
 "AirThings BLE","components/sensor/airthings_ble","airthings_logo.png","Temperature & Humidity & Pressure",""
 "AM2315C","components/sensor/am2315c","am2315c.jpg","Temperature & Humidity",""

content/components/sensor/amg8833.md

@@ -0,0 +1,284 @@
+---
+description: "Instructions for setting up the AMG8833 8x8 thermal infrared sensor."
+title: "AMG8833 Infrared Array Sensor"
+params:
+  seo:
+    description: Instructions for setting up the AMG8833 8x8 thermal infrared sensor.
+    image: amg8833.jpg
+---
+
+The ``amg8833`` sensor platform allows you to use the **Panasonic AMG8833 Grid-EYE**
+([Datasheet](https://industrial.panasonic.com/cdbs/www-data/pdf/ADI8000/ADI8000C66.pdf))
+infrared array sensor with ESPHome.
+
+This sensor measures temperature using 64 infrared sensors arranged in an 8x8 array,
+and can be used for motion and presence detection, to generate simple thermal heat maps,
+or as input to custom software detection algorithms using [automations](#amg8833-on-measurement).
+
+The [I²C Bus](#i2c) is required to be set up in your configuration for this sensor to work.
+
+{{< note >}}
+The default I²C address is ``0x69``. Some breakout boards allow selecting an alternative
+address ``0x68`` by changing a solder jumper on the PCB.
+{{< /note >}}
+
+{{< img src="amg8833.jpg" alt="Image" caption="AMG8833 Infrared Array Sensor (Grid-EYE)" width="50.0%" class="align-center" >}}
+
+```yaml
+# Example configuration entry
+amg8833:
+  interrupt_pin: True
+
+binary_sensor:
+  - platform: amg8833
+    motion:
+      name: Motion
+```
+
+## Configuration variables
+
+All threshold and hysteresis values are specified in degrees Celsius (°C).
+
+- **fps** (*Optional*, enum): Frame rate of the sensor. Default is ``FPS_1``. Options are:
+
+  - ``FPS_10``: The sensor updates the 8x8 array 10 times per second. This gives faster response
+    but with more noise.
+
+  - ``FPS_1``: The sensor accumulates data and outputs one 8x8 frame per second. This reduces noise
+    and provides more stable readings, but with slower updates. Internally, the sensor still runs with
+    10 FPS and averages 10 frames to produce the output.
+
+- **interrupt_pin** (*Optional*, boolean): Enable or disable the interrupt pin. Default is ``False``.
+  When enabled, the sensor sets the interrupt output depending on the configured thresholds.
+  - If at least one pixel is outside the thresholds, the output is set to a logical ``LOW`` level.
+  - If all pixels are within the thresholds, the output is set to a logical ``HIGH`` level.
+  When disabled, the output remains ``HIGH``.
+
+- **filter** (*Optional*, boolean): Enable or disable twice moving average output mode.
+  Default is ``True``.
+  When enabled, the sensor applies a moving average filter twice to each pixel's temperature readings.
+  This reduces noise by averaging each pixel's value with its previous and next readings, resulting
+  in smoother output.
+
+- **mode** (*Optional*, enum): Selects the method used to set the interrupt pin and the
+  [binary-sensor](#amg8833-binary-sensor). Default is ``MOTION``. Options are:
+
+  - ``MOTION``: The interrupt pin is set based on the temperature changes relative to the
+    previous frame. Each pixel is compared to its value in the previous reading, and if the
+    difference exceeds the maximum or minimum thresholds, the interrupt pin is set to a
+    logical ``LOW`` level.
+
+  - ``PRESENCE``: The interrupt is triggered based on absolute temperature thresholds.
+    Each pixel is compared to the configured lower and upper temperatures thresholds,
+    and the interrupt pin is set to a logical ``LOW`` level if any pixel is outside
+    these thresholds.
+
+  Both modes use two separate sets for thresholds and for hysteresis.
+
+- **motion_maximum** (*Optional*, float): Maximum temperature difference (ΔT) threshold in ``MOTION`` mode. Default: ``0.5``
+- **motion_minimum** (*Optional*, float): Minimum temperature difference (ΔT) threshold in ``MOTION`` mode. Default: ``-0.5``
+- **motion_hysteresis** (*Optional*, float): Hysteresis value for thresholds in ``MOTION`` mode. Default: ``0.25``
+
+- **presence_upper** (*Optional*, float): Upper temperature threshold in ``PRESENCE`` mode. Default: ``25.0``.
+- **presence_lower** (*Optional*, float): Lower temperature threshold in ``PRESENCE`` mode. Default: ``18.0``.
+- **presence_hysteresis** (*Optional*, float): Hysteresis value for thresholds in ``PRESENCE`` mode. Default: ``0.5``
+
+- **software_output** (*Optional*, boolean): When set to ``False``, the [binary-sensor](#amg8833-binary-sensor)
+  is updated based on the sensor's interrupt register, which reflects the state of the interrupt pin.
+  When set to ``True``, the [binary-sensor](#amg8833-binary-sensor) state is not tied to the interrupt logic.
+  Instead, you can implement your own detection algorithm in YAML using the
+  [on_measurement](#amg8833-on-measurement) trigger and call ``publsh_state()`` to control the
+  [binary-sensor](#amg8833-binary-sensor). Default: ``False``.
+  {{< anchor "amg8833-software-output" >}}
+
+{{< note >}}
+  Enabling ``software_output`` does not affect the physical interrupt pin - it will always follow
+  the internal AMG8833 hardware logic.
+{{< /note >}}
+
+## Binary Sensor
+
+{{< anchor "amg8833-binary-sensor" >}}
+
+The ``amg8833`` binary sensor reports motion or presence. The binary sensor is only updated when
+[software_output](#amg8833-software-output) is disabled, i.e when using the sensor's hardware interrupt logic.
+
+```yaml
+    binary_sensor:
+      - platform: amg8833
+        motion:
+        name: Motion
+        presence:
+        name: Presence
+```
+
+### Configuration variables
+
+- **motion** (*Optional*): Reports ``ON`` if motion is detected according to the configured motion thresholds.
+  All options from [Binary Sensor](#config-binary_sensor).
+
+- **presence** (*Optional*): Reports ``ON`` if presence is detected according to the configured presence thresholds.
+  All options from [Binary Sensor](#config-binary_sensor).
+
+## Number
+
+The ``amg8833`` number allows to set thresholds for motion and presence detection.
+
+```yaml
+    number:
+      - platform: amg8833
+        motion_maximum:
+          name: Maximum
+        motion_minimum:
+          name: Minimum
+        motion_hysteresis:
+          name: Motion Hyst.
+        presence_upper:
+          name: Upper
+        presence_lower:
+          name: Lower
+        presence_hysteresis:
+          name: Presence Hyst.
+```
+
+### Configuration variables
+
+- **motion_maximum** (*Optional*): Maximum temperature difference (ΔT) threshold in ``MOTION`` mode.
+  All options from [Number](#config-number).
+
+- **motion_minimum** (*Optional*): Minimum temperature difference (ΔT) threshold in ``MOTION`` mode.
+  All options from [Number](#config-number).
+
+- **motion_hysteresis** (*Optional*): Hysteresis value for thresholds in ``MOTION`` mode.
+  All options from [Number](#config-number).
+
+- **presence_upper** (*Optional*): Upper temperature threshold in ``PRESENCE`` mode.
+  All options from [Number](#config-number).
+
+- **presence_lower** (*Optional*): Lower temperature threshold in ``PRESENCE`` mode.
+  All options from [Number](#config-number).
+
+- **presence_hysteresis** (*Optional*): Hysteresis value for thresholds in ``PRESENCE`` mode.
+  All options from [Number](#config-number).
+
+## Sensor
+
+The ``amg8833`` sensor reports ambient, maximum and minimum temperatures.
+
+```yaml
+    sensor:
+      - platform: amg8833
+        ambient:
+          name: Ambient
+          filters:
+          - offset: -4.0
+        maximum:
+          name: Maximum
+        minimum:
+          name: Minimum
+```
+
+### Configuration variables
+
+- **ambient** (*Optional*): Temperature of the internal thermistor.
+  All options from [Sensor](#config-sensor).
+
+- **maximum** (*Optional*): The maximum temperature of all 8x8 pixels.
+  All options from [Sensor](#config-sensor).
+
+- **minimum** (*Optional*): The minimum temperature of all 8x8 pixels.
+  All options from [Sensor](#config-sensor).
+
+## Select
+
+The ``amg8833`` select allows changing of the frame rate and presence or motion mode.
+
+```yaml
+    select:
+      - platform: amg8833
+        fps:
+          name: FPS
+        mode:
+          name: Mode
+```
+
+### Configuration variables
+
+- **fps** (*Optional*): Frame rate of the sensor.
+  All options from [Select](#config-select).
+
+- **mode** (*Optional*): The method used to set the interrupt pin.
+  All options from [Select](#config-select).
+
+## Switch
+
+The ``amg8833`` switch controls the output filter and the interrupt pin.
+
+```yaml
+    switch:
+      - platform: amg8833
+        filter:
+          name: Filter
+        interrupt_pin:
+          name: Interrupt Pin
+```
+
+### Configuration variables
+
+- **filter** (*Optional*): Enable or disable twice moving average filter.
+  All options from [Switch](#config-switch).
+
+- **interrupt_pin** (*Optional*): Enable or disable the interrupt pin.
+  All options from [Switch](#config-switch).
+
+## Automations
+
+{{< anchor "amg8833-on-measurement" >}}
+
+- **on_measurement** (*Optional*): Triggered each time the sensor has completed a new measurement of the 8x8 array.
+  The trigger provides access to all 64 temperature values as a two-dimensional array (float[8][8])
+  which can be processed in a lambda:
+
+```yaml
+# Example Simple Presence Detector
+amg8833:
+  fps: FPS_10
+  filter: True
+  software_output: True
+  on_measurement:
+    then:
+    - lambda: |-
+        static std::array<std::array<float, 8>, 8> background;
+        static bool init_once = true;
+        float decay = 0.05f;
+        float threshold = 1.0f;
+        if (init_once) {
+          init_once = false;
+          for(int y = 0; y < 8; ++y) {
+            for(int x = 0; x < 8; ++x) {
+              background[y][x] = measurement[y][x];
+            }
+          }
+          return;
+        }
+        int changed_pixels = 0;
+        for(int y = 0; y < 8; ++y) {
+          for(int x = 0; x < 8; ++x) {
+            float diff = fabs(background[y][x] - measurement[y][x]);
+            if (diff > threshold) {
+              ++changed_pixels;
+            } else {
+              background[y][x] = background[y][x] * (1.0f - decay) + decay * measurement[y][x];
+            }
+          }
+        }
+
+        ESP_LOGD("amg8833", "Changed Pixels: %i", changed_pixels);
+        id(amg8833_presence).publish_state(changed_pixels > 0);
+```
+
+## See Also
+
+- [FAQ](https://mediap.industry.panasonic.eu/assets/custom-upload/Components/Sensors/Industrial%20Sensors/Infrared%20Array%20Sensor%20Grid-EYE/faqs_grideye_v1.0.pdf)
+- [Application Notes](https://mediap.industry.panasonic.eu/assets/custom-upload/Components/Sensors/Industrial%20Sensors/Infrared%20Array%20Sensor%20Grid-EYE/application_notes_grid-eye_0.pdf)
+- {{< apiref "amg8833/amg8833.h" "amg8833/amg8833.h" >}}