Add documentation for ADS1118 (#3606)

Co-authored-by: Solomon <solomon.gorkhover@finnpartners.com>
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

components/sensor/ads1118.rst

@@ -0,0 +1,116 @@
+ADS1118 4-Channel 16-Bit A/D Converter with Internal Temperature Sensor
+=======================================================================
+
+.. seo::
+    :description: Instructions for setting up ADS1118 multiplexed analog voltage sensors.
+    :image: ads1118.jpg
+    :keywords: ADS1118
+
+.. _ads1118-component:
+
+Component/Hub
+-------------
+
+ADS1118 4-Channel 16-Bit A/D Converter (`datasheet <https://www.ti.com/lit/ds/symlink/ads1118.pdf>`__)
+The ``ads1118`` domain creates a global hub so that you can later create
+individual sensors using the :ref:`ADS1118 Sensor Platform <ads1118-sensor>`.
+It uses the :ref:`SPI Bus <spi>` for communication.
+
+.. figure:: images/ads1118-full.jpg
+    :align: center
+    :width: 60.0%
+
+    ADS1118 16-Bit ADC.
+
+.. code-block:: yaml
+
+    ads1118:
+      cs_pin: GPIO15
+
+Configuration variables:
+************************
+
+- **cs_pin** (**Required**, int): The SPI cable select pin to use.
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this ADS1118 Hub. Use this if you
+  want to use multiple ADS1118 hubs at once.
+
+.. _ads1118-sensor:
+
+Sensor
+------
+
+The ``ads1118`` sensor allows you to use your ADS1118 delta-sigma ADC
+sensors (`datasheet <https://www.ti.com/lit/ds/symlink/ads1118.pdf>`__) with ESPHome.
+First, setup an :ref:`ADS1118 Hub <ads1118-component>` for your ADS1118 sensor and then use this
+sensor platform to create individual sensors that will report the voltage.
+
+.. code-block:: yaml
+
+    ads1118:
+      cs_pin: GPIO15
+    sensor:
+      - platform: ads1118
+        type: 'adc'  
+        id: 'batt_volt' 
+        name: "Battery Voltage"
+        multiplexer: 'A3_GND'
+        gain: 4.096
+        update_interval: .01s
+
+Configuration variables:
+************************
+
+- **type** (*Optional*): ``adc``(default) or ``temperature``
+- **ads1118_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the
+   :ref:`ADS1118 Hub <ads1118-component>` you want to use this sensor.
+- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
+- All other options from :ref:`Sensor <config-sensor>`.
+
+ADC Options:
+^^^^^^^^^^^^
+
+-  **multiplexer** (**Required**): The multiplexer channel of this sensor. Effectively means between which pins you want to measure voltage.
+-  **gain** (**Required**, float): The gain of this sensor.
+
+Temperature Options:
+^^^^^^^^^^^^^^^^^^^^
+
+None
+
+Multiplexer and Gain
+--------------------
+
+.. note::
+
+    As per (`datasheet <https://www.ti.com/lit/ds/symlink/ads1118.pdf>`__) Section 7.3 Note 2:
+    "No more than VDD + 0.3V must be applied to the analog inputs of the device."
+    This means if you power the device with 3.3V, take care not to supply the 4 AIN pins with more than 3.6V.
+
+The ADS1118 has a multiplexer that can be configured to measure voltage between several pin configurations. These are:
+
+ - ``A0_A1`` (between Pin 0 and Pin 1)
+ - ``A0_A3`` (between Pin 0 and Pin 3)
+ - ``A1_A3`` (between Pin 1 and Pin 3)
+ - ``A2_A3`` (between Pin 2 and Pin 3)
+ - ``A0_GND`` (between Pin 0 and GND)
+ - ``A1_GND`` (between Pin 1 and GND)
+ - ``A2_GND`` (between Pin 2 and GND)
+ - ``A3_GND`` (between Pin 3 and GND)
+
+Additionally, the ADS1118 has a Programmable Gain Amplifier (PGA) that can help you measure voltages in different ranges, these are:
+
+ - ``6.144`` (measures up to 6.144V)
+ - ``4.096`` (measures up to 4.096V)
+ - ``2.048`` (measures up to 2.048V)
+ - ``1.024`` (measures up to 1.024V)
+ - ``0.512`` (measures up to 0.512V)
+ - ``0.256`` (measures up to 0.256V)
+
+See Also
+--------
+
+- :ref:`sensor-filters`
+- :doc:`adc`
+- :doc:`ads1115`
+- :apiref:`ads1118/ads1118.h`
+- :ghedit:`Edit`

index.rst

@@ -215,6 +215,7 @@ Analogue
     ADC, components/sensor/adc, flash.svg, ESP internal, dark-invert
     ADC128S102, components/sensor/adc128s102, adc128s102.png , 8-channel ADC
     ADS1115, components/sensor/ads1115, ads1115.jpg, 4-channel ADC
+    ADS1118, components/sensor/ads1118, ads1118.jpg, 4-channel ADC
     CD74HC4067, components/sensor/cd74hc4067, cd74hc4067.jpg, 16-channel analog multiplexer
     MCP3008, components/sensor/mcp3008, mcp3008.jpg, 8-channel ADC
     MCP3204 / MCP3208, components/sensor/mcp3204, mcp3204.jpg, 4-channel ADC