From bae87951ae69601f199d88b3e747400e7675267f Mon Sep 17 00:00:00 2001 From: Arturo Casal Date: Mon, 21 Feb 2022 12:46:50 +0100 Subject: [PATCH] Add device support: MCP4728 (#1888) * Initial MCP4728 docs * Fixed doc reference labels and links * Fixed link to mcp4728 component. * Changed parameter name * Update components/output/mcp4728.rst Added default value Co-authored-by: Otto Winter * Update components/output/mcp4728.rst Added default value Co-authored-by: Otto Winter * Update components/output/mcp4728.rst Added default value Co-authored-by: Otto Winter * Update components/output/mcp4728.rst Added default value Co-authored-by: Otto Winter * Reduced image size * Extended parameter and output voltage explanation. * Changed index position to keep alphabetical order. Co-authored-by: Otto Winter --- components/output/mcp4728.rst | 100 ++++++++++++++++++++++++++++++++++ images/mcp4728.jpg | Bin 0 -> 16692 bytes index.rst | 1 + 3 files changed, 101 insertions(+) create mode 100644 components/output/mcp4728.rst create mode 100644 images/mcp4728.jpg diff --git a/components/output/mcp4728.rst b/components/output/mcp4728.rst new file mode 100644 index 000000000..567a6a1da --- /dev/null +++ b/components/output/mcp4728.rst @@ -0,0 +1,100 @@ +MCP4728 Output +============== + +.. 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 +`__ +in order to have analog outputs on any board by using :ref:`I²C `. Devices default address is ``0x60``. + +.. 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: + - platform: mcp4728 + id: dac_output + +Configuration variables: +------------------------ + +- **id** (**Required**, :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``. + +Output +****** + +The MCP4728 output component exposes 4 MCP4728 channels of a global :ref:`MCP4728 ` 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 + mcp4728_id: dac_output + channel: C + vref: internal + gain: X1 + power_down: normal # default + - platform: mcp4728 + id: ac_dimmer_4 + mcp4728_id: dac_output + 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 `. + 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 `. + +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/esp32_dac` +- :ghedit:`Edit` diff --git a/images/mcp4728.jpg b/images/mcp4728.jpg new file mode 100644 index 0000000000000000000000000000000000000000..7184b4fe00bb780803fd9cc27210645c06334169 GIT binary patch literal 16692 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