diff --git a/content/components/_index.md b/content/components/_index.md index e805a8d878..2eaefc7ca2 100644 --- a/content/components/_index.md +++ b/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","" diff --git a/content/components/sensor/amg8833.md b/content/components/sensor/amg8833.md new file mode 100644 index 0000000000..4f7cfd829f --- /dev/null +++ b/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, 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" >}} diff --git a/static/images/amg8833.jpg b/static/images/amg8833.jpg new file mode 100644 index 0000000000..28e4cc55e1 Binary files /dev/null and b/static/images/amg8833.jpg differ