Documentation for Analog Devices MAX17043 battery fuel gauge (#4299)

Co-authored-by: Keith Burzinski <kbx81x@gmail.com>
esphome · jesserockz · Nov 20, 2024 · Oct 9, 2024 · Oct 6, 2024 · Oct 9, 2024
commit ab9da0a1d8027a4db292a5119633936f94842e8e
diff --git a/components/sensor/images/max17043.jpg b/components/sensor/images/max17043.jpg
diff --git a/components/sensor/max17043.rst b/components/sensor/max17043.rst
@@ -0,0 +1,106 @@
+Analog Devices MAX17043 battery fuel gauge
+==========================================
+
+.. seo::
+    :description: Instructions for setting up Analog Devices MAX17043 battery fuel gauge in ESPHome.
+    :image: max17043.jpg
+
+The MAX17043 platform allows you to use a MAX17043 to more accurately monitor the remaining capacity
+of a LIPO battery (`datasheet <https://www.analog.com/en/products/max17043.html#documentation>`__,
+`DFRobot`_) in ESPHome. It uses the :ref:`I²C Bus <i2c>` for communication (the address is fixed at 0x36).
+
+Once configured, it uses a sophisticated Li+ battery-modeling scheme, called ModelGauge™ to track the
+battery's relative state-of-charge continuously over a widely varying charge/discharge profile.
+Unlike traditional fuel gauges, the ModelGauge algorithm eliminates the need for battery relearn cycles
+and an external current-sense resistor.
+
+In low power applications, it's very important to report battery levels accurately. By utilising ESPHome's ``deep_sleep``
+component together with a MAX17043, projects can run for extended periods and the user can be confident of the amount of battery remaining.
+This overcomes the reality that measured battery voltage does not correlate well at all with remaining battery charge.
+
+.. note::
+
+    See hardware design discussion below - it's important to leave the MAX17043 powered on during deep sleep.
+
+.. figure:: images/max17043.jpg
+    :align: center
+    :width: 60.0%
+
+    DFRobot DFR0563 Gravity I2C 3.7V Li battery fuel gauge.
+
+.. _DFRobot: https://www.dfrobot.com/product-1734.html
+
+Configuration
+*************
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    sensor:
+      - platform: max17043
+        id: max17043_id
+        i2c_id: i2c_max17043
+        battery_voltage:
+          name: "Battery Voltage"
+        battery_level:
+          name: "Battery"
+
+Sensors
+*******
+
+- **battery_voltage** (*Optional*, float): The voltage measured at the LIPO battery.
+
+  - All other options from :ref:`Sensor <config-sensor>`.
+- **battery_level** (*Optional*, float): The percentage of battery remaining using the ModelGauge™ battery-modelling scheme.
+
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+Hardware design considerations
+******************************
+
+It's important to realise that the relationship between battery voltage and remaining battery level
+is poorly correlated as well as being non-linear.
+
+The MAX17043 works by continually monitoring charge and discharge to assess how much battery capacity remains.
+When first powered on, it makes an assumption that the measured voltage has been in a relaxed state for
+30 minutes. This best first guess does not have a lasting impact because it monitors relative state-of-charge
+over time.
+
+Deep sleep cycles are most often designed so the device wakes up for short
+periods to do its business and then sleeps for a much longer period. It's critical to allow the MAX17043 to maintain
+state during the sleep phase.
+
+If power is removed from the MAX17043 then each time the ESP comes out of deep sleep the MAX17043 will
+have to start again from a new best guess.
+It will not be able to use past charge and discharge behaviour to work its magic -
+significantly diminishing the point of using a MAX17043.
+
+Current consumption during device sleep mode is extremely low (maximum of 3µA compared to up to 75µA maximum when active).
+The driver enables the user to put the device to sleep just before deep sleep commences using the `sleep_mode` action.
+When the ESP comes out of deep sleep the driver clears the MAX17043 sleep bit.
+
+For example:
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - max17043.sleep_mode: max17043_id
+        - deep_sleep.enter:
+            id: deep_sleep_1
+            sleep_duration: 20min
+
+.. note::
+
+    Once you have called the ``sleep_mode()`` action, the MAX17043 will stop recalculating the voltage and battery level.
+    Hence, if you leave the ESP running it will continue to publish the sensor values with the *last* measurements.
+    The only way to come of sleep mode is to restart the device (either as intended via deep sleep wake; or less ideally with a power cycle).
+
+    So, only call ``sleep_mode()`` when you intend to send the ESP into deep sleep.
+
+See Also
+--------
+
+- :ref:`i2c`
+- :doc:`/components/deep_sleep`
+- :ghedit:`Edit`
diff --git a/images/max17043.jpg b/images/max17043.jpg
diff --git a/index.rst b/index.rst
@@ -559,12 +559,14 @@ Miscellaneous
     Duty Time, components/sensor/duty_time, timer-play-outline.svg, dark-invert
     EZO sensor circuits, components/sensor/ezo, ezo-ph-circuit.png, (pH)
     FS3000, components/sensor/fs3000, fs3000.jpg, Air velocity
+    GDK101, components/sensor/gdk101, gdk101.jpg, Radiation
     Growatt Solar, components/sensor/growatt_solar, growatt.jpg, Solar rooftop
     Havells Solar, components/sensor/havells_solar, havellsgti5000d_s.jpg, Solar rooftop
     Integration, components/sensor/integration, sigma.svg, dark-invert
     Kuntze pool sensor, components/sensor/kuntze, kuntze.jpg
     LVGL widget, components/sensor/lvgl, lvgl_c_num.png
     M5Stack Unit 8 Angle, components/sensor/m5stack_8angle, m5stack_8angle.png
+    MAX17043, components/sensor/max17043, max17043.jpg, Battery
     MicroNova pellet stove, components/micronova, micronova.svg
     Modbus Sensor, components/sensor/modbus_controller, modbus.png
     Nextion, components/sensor/nextion, nextion.jpg, Sensors from display
@@ -577,7 +579,6 @@ Miscellaneous
     uFire EC sensor, components/sensor/ufire_ec, ufire_ec.png, EC & Temperature
     uFire ISE sensor, components/sensor/ufire_ise, ufire_ise.png, pH & Temperature
     WireGuard, components/wireguard, wireguard_custom_logo.svg, dark-invert
-    GDK101, components/sensor/gdk101, gdk101.jpg, Radiation
 
 Motion
 ******