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.

# Example configuration entry
mcp4461:
  - id: mcp4461_output

Configuration variables

• id (Optional, 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 MCP4461 as float outputs.

# 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
  initial_value: 0.5  # always initialize volatile wiper 0 with wiper @ medium resistance range on start
- 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

Configuration variables

• id (Required, ID): The id to use for this output component.

• mcp4461_id (Optional, ID): Manually specify the ID of the 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.

• initial_value (Optional, float): Set initial wiper value. Valid range is 0 - 1.0. For the nonvolatile channels E-H, this value is only written when it differs from the value already stored on the chip, to protect the EEPROM’s limited write endurance.

• nonvolatile (Optional, bool): Only for the volatile channels A-D. When enabled, every level change is automatically mirrored into the chip’s matching nonvolatile wiper register once the level has been stable for nonvolatile_write_delay — the chip then restores that level by itself on the next power-on. Defaults to true.

• nonvolatile_write_delay (Optional, Time): How long a level must remain unchanged before it is persisted. This debounces fast level bursts (for example light transitions) and protects the EEPROM endurance (roughly one million write cycles, and each write occupies the chip for up to 10 ms). Defaults to 1s.

• 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 configuration variables from Output.

NOTE

The terminal switches (TCON) are volatile on this chip: at power-on only the wiper levels are restored from the nonvolatile registers, while all terminals reset to connected. The component therefore re-applies your terminal_a/terminal_b/terminal_w configuration on every boot.

The tap count for 7 and 8-bit digipot/rheostat devices is usually 100/257.

For the MCP4461, valid output states in range from 0 - 1.0 will be multiplied internally by 256 to get the integer tap count in range [0-256].

NOTE

If you do not specify the initial_value configuration variable, you can use read_state() and update_state() to fetch the current state at boot. The potentiometer (not rheostat) can be handled in the same way. See the example below.

esphome:
  on_boot:
    priority: 100
    then:
      - number.set:
          id: digipot_volatile_0
          value: !lambda |-
            uint16_t wiper_level = id(digipot_wiper_0).read_state();
            return wiper_level;

      - lambda: |-
          id(digipot_wiper_0).update_state();

Actions

mcp4461.wiper.increase / mcp4461.wiper.decrease Action

Moves the wiper of the given output channel by a single tap. Only valid for the volatile channels A-D — the chip does not accept increment/decrement commands on the nonvolatile registers.

on_...:
  then:
    - mcp4461.wiper.increase: digipot_channel_0
    - mcp4461.wiper.decrease: digipot_channel_0

mcp4461.wiper.store_nonvolatile Action

Immediately persists the current wiper level into the chip’s nonvolatile register, bypassing the nonvolatile_write_delay. Most useful together with nonvolatile: false to persist only at deliberate moments, for example on a button press:

output:
  - platform: mcp4461
    id: digipot_channel_0
    channel: A
    nonvolatile: false

button:
  - platform: template
    name: "Save digipot level"
    on_press:
      - mcp4461.wiper.store_nonvolatile: digipot_channel_0

mcp4461.wiper.set_terminal Action

Connects or disconnects a single resistor-network terminal of the given channel at runtime. terminal is one of a, b, w or h (hardware shutdown state).

on_...:
  then:
    - mcp4461.wiper.set_terminal:
        id: digipot_channel_0
        terminal: a
        enable: false

Configuration variables

• id (Required, ID): The ID of the MCP4461 output channel.
• terminal (Required, string, templatable): One of a, b, w or h (hardware shutdown state).
• enable (Required, bool, templatable): Whether to connect (true) or disconnect (false) the terminal.

See Also

• Output Component
• API Reference: mcp4461.h
• API Reference: mcp4461_output.h