diff --git a/components/output/mcp4461.rst b/components/output/mcp4461.rst new file mode 100644 index 0000000000..0a53594a69 --- /dev/null +++ b/components/output/mcp4461.rst @@ -0,0 +1,126 @@ +MCP4461 Component +================= + +.. seo:: + :description: Instructions for setting up MCP4461 outputs on the ESP. + :image: mcp4461.jpg + +.. _mcp4461-component: + +The MCP4461 output component enables the use of an 8‑bit external quad digital potentiometer/rheostat via I²C. See the `MCP4461 Datasheet `__ for more information. +Device default address is ``0x2C``. + +.. 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: 0x2C / global I²C) + mcp4461: + - id: mcp4461_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 digipot. Defaults to ``0x2C``. +- **disable_wiper_0** (*Optional*, bool): Disable wiper 0. Defaults to ``false``. +- **disable_wiper_1** (*Optional*, bool): Disable wiper 1. Defaults to ``false``. +- **disable_wiper_2** (*Optional*, bool): Disable wiper 2. Defaults to ``false``. +- **disable_wiper_3** (*Optional*, bool): Disable wiper 3. Defaults to ``false``. + +MCP4461 Output +************** + +The MCP4461 output component exposes 8 MCP4461 (wiper-)channels of a global :ref:`MCP4461 ` as float outputs. + +.. code-block:: yaml + + # Individual outputs + # A-D are volatile wipers 0-3 + # E-H are nonvolatile wipers 0-3 + # (AE, BF, CG, DH belonging together) + output: + - platform: mcp4461 + id: digipot_channel_0 + mcp4461_id: mcp4461_output + channel: A + - platform: mcp4461 + id: digipot_channel_1 + mcp4461_id: mcp4461_output + channel: B + - platform: mcp4461 + id: digipot_channel_2 + mcp4461_id: mcp4461_output + channel: C + - platform: mcp4461 + id: digipot_channel_3 + mcp4461_id: mcp4461_output + channel: D + - platform: mcp4461 + id: digipot_channel_4 + mcp4461_id: mcp4461_output + channel: E + - platform: mcp4461 + id: digipot_channel_5 + mcp4461_id: mcp4461_output + channel: F + - platform: mcp4461 + id: digipot_channel_6 + mcp4461_id: mcp4461_output + channel: G + - platform: mcp4461 + id: digipot_channel_7 + mcp4461_id: mcp4461_output + channel: H + + on_...: + then: + - output.set_level: + id: digipot_channel_0 + level: !lambda return static_cast(x / 1000); + +Configuration variables: +------------------------ + +- **id** (**Required**, :ref:`config-id`): The id to use for this output component. +- **mcp4461_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the + :ref:`MCP4461 `. + Use this if you have multiple MCP4461 ICs you want to use at the same time. +- **channel** (**Required**, string): Choose the channel of this MCP4461 output component. + One of ``A``, ``B``, ``C``, ``D``,``E``, ``F``, ``G`` or ``H``. +- **enable** (**Optional**, bool): Set to ``false`` if terminal "HW" shall be disabled by default. Defaults to ``true`` +- **initial_value** (**Optional**, float): The value the wiper should be set to on boot +- **terminal_a** (**Optional**, bool): Set to ``false`` if terminal "A" shall be disabled on boot. Defaults to ``true`` +- **terminal_b** (**Optional**, bool): Set to ``false`` if terminal "B" shall be disabled on boot. Defaults to ``true`` +- **terminal_w** (**Optional**, bool): Set to ``false`` if terminal "W" shall be disabled on boot. Defaults to ``true`` + +- All other options from :ref:`Output `. + +Tap count for 7/8bit digipot/rheostat devices is usually 100/257. Minimum setting for the output is 0.000, maximum is 0.256 +This example shows how to use this with simple numeric slider (0-256 non-decimal numbers shown) +If initial_value configuration variable is not used, you can use + +.. code-block:: yaml + + esphome: + on_boot: + priority: 100 + then: + - number.set: + id: digipot_volatile_0 + value: !lambda |- + return id(digipot_wiper_0).get_wiper_level(); + +See Also +-------- + +- :doc:`/components/output/index` +- :apiref:`mcp4461/mcp4461.h` +- :ghedit:`Edit` diff --git a/images/mcp4461.jpg b/images/mcp4461.jpg new file mode 100644 index 0000000000..551990e9e5 Binary files /dev/null and b/images/mcp4461.jpg differ diff --git a/index.rst b/index.rst index 71c7e4a4f8..2b60f5e403 100644 --- a/index.rst +++ b/index.rst @@ -1006,6 +1006,7 @@ Output Components GP8403, components/output/gp8403, gp8403.svg GPIO Output, components/output/gpio, gpio.svg LibreTiny PWM, components/output/libretiny_pwm, pwm.png + MCP4461 Potentiometer, components/output/mcp4461, mcp4461.jpg MCP4725, components/output/mcp4725, mcp4725.jpg MCP4728, components/output/mcp4728, mcp4728.jpg MCP47A1, components/output/mcp47a1, mcp47a1.svg