MCP4728 Component
=================

.. seo::
    :description: Instructions for setting up MCP4728 outputs on the ESP.
    :image: mcp4728.jpg

.. _mcp4728-component:

The MCP4728 output component allows to use `12bit external quad DAC
<https://www.adafruit.com/product/4470>`__
in order to have analog outputs on any board by using :ref:`I²C <i2c>`. Devices default address is ``0x60``.

If you only have one, it is not necessary to explicitly specify the ``mcp4728:`` component in the config unless you need to change the parameters.
It will be automatically created with the default settings if you use it.

.. code-block:: yaml

    # Example configuration entry

    # Set a global I²C connection
    i2c:
      sda: 21
      scl: 22
      scan: true

    # Set the component with default (address: 0x60 / global I²C)
    mcp4728:
      - id: dac_output

Configuration variables:
------------------------

- **id** (*Optional*, :ref:`config-id`): The id to use for this output component.
- **address** (*Optional*, int): Manually specify the I2C address of
  the DAC. Defaults to ``0x60``.
- **store_in_eeprom** (*Optional*, boolean): Use SEQ_WRITE mode to also write to EEPROM sequentially. Defaults to ``false``.

MCP4728 Output
**************

The MCP4728 output component exposes 4 MCP4728 channels of a global :ref:`MCP4728 <mcp4728-component>` as float outputs.

.. code-block:: yaml

    # Individual outputs
    output:
    - platform: mcp4728
      id: ac_dimmer_1
      mcp4728_id: dac_output
      channel: A
      vref: vdd
      power_down: normal # default
    - platform: mcp4728
      id: ac_dimmer_2
      mcp4728_id: dac_output
      channel: B
      vref: vdd
      power_down: gnd_1k
    - platform: mcp4728
      id: ac_dimmer_3
      channel: C
      vref: internal
      gain: X1
      power_down: normal # default
    - platform: mcp4728
      id: ac_dimmer_4
      channel: D
      vref: internal
      gain: X2

    on_...:
      then:
        - output.set_level:
            id: ac_dimmer_1
            level: 100%

Configuration variables:
------------------------

- **id** (**Required**, :ref:`config-id`): The id to use for this output component.
- **mcp4728_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the
  :ref:`MCP4728 <mcp4728-component>`.
  Use this if you have multiple MCP4728 chains you want to use at the same time.
- **channel** (**Required**, string): Chose the channel of the MCP4728 chain of
  this output component. One of ``A``, ``B``, ``C`` or ``D``.
- **vref** (*Optional*, string): Chose the VREF source. One of ``vdd`` or ``internal``. Defaults to ``vdd``.
- **gain** (*Optional*, string): Chose the GAIN multiplier for internal VREF. One of ``X1`` or ``X2``. Only useful when ``vdd=internal``. Defaults to ``X1``.
- **power_down** (*Optional*, string): Chose the power down mode. In power down mode (value different from ``normal``) the output pin will be connected to GND using a resistor (1kOhm, 100kOhm or 500kOhm). One of ``normal``, ``gnd_1k``, ``gnd_100k`` or ``gnd_500k``. Defaults to ``normal``.
- All other options from :ref:`Output <config-output>`.

Output voltage range will be different depending on the ``vref`` source and ``gain``.
When ``vref=vdd``, output voltage will range from 0.000V to VDD.
When ``vref=internal``, output voltage will range from 0.000V to 2.048V with ``gain=X1`` and from 0.000V to 4.096V with ``gain=X2``.

See Also
--------

- :doc:`/components/output/index`
- :doc:`/components/output/esp32_dac`
- :apiref:`mcp4728/mcp4728.h`
- :ghedit:`Edit`
