From aed19cdb39c0b476ee95371f9dee48dd35fe8e41 Mon Sep 17 00:00:00 2001
From: micronen <micronen@gmail.com>
Date: Tue, 25 Jan 2022 20:18:57 +0200
Subject: [PATCH] Add Heap Sensors - free/max block/fragmentation #1578 (#1041)

Co-authored-by: Oxan van Leeuwen <oxan@oxanvanleeuwen.nl>
---
 components/debug.rst | 63 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 62 insertions(+), 1 deletion(-)

diff --git a/components/debug.rst b/components/debug.rst
index c632ff41a..8245c931e 100644
--- a/components/debug.rst
+++ b/components/debug.rst
@@ -7,6 +7,8 @@ Debug Component
 
 The ``debug`` component can be used to debug problems with ESPHome. At startup, it prints
 a bunch of useful information like reset reason, free heap size, ESPHome version and so on.
+It also allows you get the same information as a text sensor, and to monitor the state of the
+ESP heap memory (free space, maximum free block size and fragmentation level) and the main-loop timing.
 
 .. figure:: images/debug.png
     :align: center
@@ -17,16 +19,75 @@ a bunch of useful information like reset reason, free heap size, ESPHome version
 
     # Example configuration entry
     debug:
+      update_interval: 5s
+      device:
+        name: Device Info
+      free:
+        name: Heap Free
+      fragmentation:
+        name: Heap Fragmentation
+      block:
+        name: Heap Max Block
+      loop_time:
+        name: Loop Time
 
     # Logger must be at least debug (default)
     logger:
       level: debug
 
-No configuration variables.
+Configuration variables:
+------------------------
+
+- **device** (*Optional*): Reports the following device information:
+
+  - ESPHome Version
+  - Free heap size at startup
+  - Flash chip size, speed and mode
+  - ESP32:
+
+    - Chip model, cores, revision
+    - Chip features (BLE / BT / WiFi_BGN / EMB_FLASH / ...)
+    - ESP-IDF version
+    - EFuse MAC
+    - Reset reason
+    - Wakeup reason
+  - ESP8266:
+
+    - Chip id, frequency
+    - Flash id
+    - SDK, Core & Boot versions
+    - Reset reason & information
+    
+  Accepts these options:
+    
+  - **name** (**Required**, string): The name of the sensor.
+  - All other options from :ref:`Text Sensor <config-text_sensor>`.
+
+- **free** (*Optional*): Reports the free heap size in bytes.
+
+  - **name** (**Required**, string): The name of the sensor.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+- **fragmentation** (*Optional*): Reports the fragmentation metric of the heap 
+  (0% is clean, more than ~50% is not harmless). Only available on ESP8266 with Arduino 2.5.2+.
+  
+  - **name** (**Required**, string): The name of the sensor.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+- **block** (*Optional*): Reports the largest contiguous free RAM block on the heap in bytes.
+
+  - **name** (**Required**, string): The name of the sensor.
+  - All other options from :ref:`Sensor <config-sensor>`.
+  
+- **loop_time** (*Optional*): Reports the longest time between successive iterations of the main loop.
+
+  - **name** (**Required**, string): The name of the sensor.
+  - All other options from :ref:`Sensor <config-sensor>`.
 
 See Also
 --------
 
+- :ref:`sensor-filters`
 - :doc:`logger`
 - :apiref:`debug/debug_component.h`
 - :ghedit:`Edit`