diff --git a/content/components/sensor/mcp3204.md b/content/components/sensor/mcp3204.md index 22c386c94e..9f394d4aba 100644 --- a/content/components/sensor/mcp3204.md +++ b/content/components/sensor/mcp3204.md @@ -1,77 +1,85 @@ ---- -description: "Instructions for setting up MCP3204 & MCP3208 12-Bit Analog to Digital Converter in ESPHome." -title: "MCP3204 & MCP3208 12-Bit A/D Converters" -params: - seo: +.. seo:: description: Instructions for setting up MCP3204 & MCP3208 12-Bit Analog to Digital Converter in ESPHome. image: mcp3204.jpg ---- -The Microchip Technology Inc. MCP3204 & MCP3208 devices are successive approximation 12-bit Analog-to-Digital (A/D) -converters with on-board sample and hold circuitry. This component is common for both device types. -Configure both devices as MCP3204 and observe the maximum number of channels as per variant used. +MCP3204 & MCP3208 12-Bit A/D Converters +======================================= -{{< img src="mcp3204.jpg" alt="Image" width="50.0%" class="align-center" >}} +The Microchip Technology Inc. MCP3204 & MCP3208 devices are successive approximation 12-bit Analog-to-Digital (A/D) +converters with on-board sample and hold circuitry. This ESPHome component provides support for both device types. +You may configure both devices as :code:`mcp3204` and select the channel count per your variant. -{{< anchor "mcp3204-component" >}} +.. figure:: mcp3204.jpg + :align: center + :width: 50.0% + :alt: MCP3204 image -## Component/Hub +Component/Hub +------------- The MCP3204 component allows you to use MCP3204 or MCP3208 12-Bit A/D Converter -([datasheet](https://ww1.microchip.com/downloads/en/DeviceDoc/21298e.pdf)) in ESPHome. +(`datasheet `_) in ESPHome. The MCP3204 is a 4-channel and MCP3208 is an 8-channel device. -It uses the [SPI Bus](#spi) for communication. +It uses the :doc:`SPI Bus ` for communication. + +Once configured, you can use any of the 4 or 8 pins (depending on device variant) as sensors for your projects. -Once configured, you can use any of the 4 or 8 pins (depending on device variant) as -sensors for your projects. +Each pin will respond with a voltage calculated off of the :code:`reference_voltage` (default is 3.3V). +The voltage is calculated as :code:`reference_voltage * value / 4096` (the percentage of VREF for a 12-bit ADC). -Each pin will respond with a voltage calculated off of the `reference_voltage` (default is 3.3V). -It calculates the voltage by multiplying the `reference_voltage * value` on the pin (basically the percentage of VREF) +Usually, you will set :code:`reference_voltage` to the VREF pin voltage. -Most configurations will set the `reference_voltage` = VREF pin +.. code-block:: yaml -```yaml -# Example configuration entry -mcp3204: - cs_pin: GPIOXX - reference_voltage: 3.3V -``` + mcp3204: + cs_pin: GPIOXX + reference_voltage: 3.3V -### Configuration variables +Configuration variables: -- **id** (**Required**, [ID](#config-id)): The id to use for this MCP3204 component. -- **cs_pin** (**Required**, [Pin Schema](#config-pin_schema)): The SPI cable select pin to use. -- **reference_voltage** (*Optional*, float): The reference voltage. Defaults to `3.3V`. +- **id** (**Required**, :ref:`config-id`): The id to use for this MCP3204 component. +- **cs_pin** (**Required**, :ref:`config-pin_schema`): The SPI cable select pin to use. +- **reference_voltage** (*Optional*, float): The reference voltage. Defaults to :code:`3.3V`. -## Sensor +Sensor +------ -The `mcp3204` sensor allows you to use your MCP3204 or MCP3208 12-Bit A/D Converter sensors with ESPHome. -First, setup a [MCP3204 Hub](#mcp3204-component) for your MCP3204/8 sensor and then use this +The :code:`mcp3204` sensor platform allows you to use MCP3204 or MCP3208 12-Bit A/D sensor channels with ESPHome. +First, setup an :ref:`MCP3204 Hub ` for your MCP3204/8 sensor and then use this sensor platform to create individual sensors that will report the voltage to Home Assistant. -```yaml -# Example config of sensors. -# This is a small 1.5v solar panel power rail attached to pin 0 -# of the MCP3204 -sensor: - - platform: mcp3204 # Attached to pin 0 of the MCP3204. - id: solar_voltage - number: 0 # MCP3204 pin number +.. code-block:: yaml + + sensor: + - platform: mcp3204 # Single-ended mode: pin 0 of MCP3204 + id: solar_voltage + number: 0 + + # Pin 7 of MCP3208 in single-ended mode (for MCP3208, use pin numbers 0-7) + - platform: mcp3204 + id: supply_voltage + number: 7 + + # Differential mode: Measures voltage between channel 0 (IN+) and channel 1 (IN–) + - platform: mcp3204 + id: differential_sensor + number: 0 # Channel 0 (IN+), paired with 1 (IN–) in differential mode + diff_mode: true # Enable differential mode + name: "Differential Voltage CH0–CH1" -# In case MCP3208 is used. you can specify pin number > 4 - - platform: mcp3204 # Attached to pin 7 of the MCP3208. - id: supply_voltage - number: 7 # MCP3208 pin number -``` +Configuration variables: -### Configuration variables +- **mcp3204_id** (**Required**, :ref:`config-id`): ID of the parent MCP3204 component. +- **number** (**Required**, int): The channel number (0-3 for MCP3204, 0-7 for MCP3208). +- **diff_mode** (*Optional*, bool): Enables differential mode. If :code:`true`, the ADC measures the voltage difference between the selected channel and its paired channel (see chip datasheet). Defaults to :code:`false` (single-ended mode). +- **update_interval** (*Optional*, :ref:`config-time`): Interval to update the sensor. Defaults to :code:`60s`. +- All other options from :ref:`Sensor `. -- **mcp3204_id** (**Required**, [ID](#config-id)): The id of the parent MCP3204 component. -- **number** (**Required**, int): The pin number of the MCP3204 -- **update_interval** (*Optional*, [Time](#config-time)): The interval to check the sensor. Defaults to `60s`. -- All other options from [Sensor](#config-sensor). +.. note:: + In differential mode, channel pairing depends on MCP3204/3208 datasheet. The voltage reading represents the difference between the positive input (IN+) and negative input (IN-). In single-ended mode, ADC measures each channel against ground. -## See Also +See Also +-------- -- [SPI Bus](#spi) -- {{< apiref "mcp3204/mcp3204.h" "mcp3204/mcp3204.h" >}} +- :doc:`SPI Bus ` +- :apiref:`mcp3204/mcp3204.h`