The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.


RPi::DigiPot::MCP4XXXX - Interface to the MCP4xxxx series digital potentiometers on the Raspbery Pi


This distribution allows you to interface directly with the MCP41xxx and MCP42xxx series digital potentiomenters attached to the SPI bus on the Raspberry Pi.

The MCP41xxx units have a single built-in potentiometer, where the MCP42xxx units have two.

Both series will operate on either 3.3V or 5V, as the potentiometers do not send anything back to the Pi's GPIO.

This software requires wiringPi to be installed, as we use its SPI library to communicate to the potentiometer over the SPI bus.


    # GPIO pin number connected to the potentiometer's
    # CS (Chip Select) pin

    my $cs = 18;  

    # SPI bus channel

    my $chan = 0;

    my $dpot = RPi::DigiPot::MCP4XXXX->new($cs, $chan);

    # potentiometer's output level (0-255).
    # 127 == ~50% output

    my $output = 127; 

    # set the output level


    # shutdown (put to sleep) the potentiometer




Instantiates a new RPi::DigiPot::MCP4XXXX object, initiates communication with the SPI bus, and returns the object.



Mandatory: Integer, the GPIO pin number that connects to the potentiometer's Chip Select CS pin. This is the pin we use to start and finish communication with the device over the SPI bus.


Mandatory: Integer, represents the SPI bus channel that the potentiometer is connected to. 0 for /dev/spidev0.0 or 1 for /dev/spidev0.1.


Optional: Integer. The clock speed to communicate on the SPI bus at. Defaults to 1000000 (ie: 1MHz).


This method allows you to set the variable output on the potentiometer(s). These units have 256 taps, allowing that many different output levels.



Mandatory: Integer bewteen 0 for 0% output and 255 for 100% output.


Optional: Integer, instructs the software which of the onboard potentiometers to set the output voltage on. 1 for the first potentiometer, 2 for the second, and 3 to change the value on both. Defaults to 1.

NOTE: Only the MCP42xxx units have dual built-in potentiometers, so if you have an MCP41xxx unit, leave the default 1 set for this parameter.


The onboard potentiometers allow you to shut them down when not in use, resulting in electricity usage. Using set() will bring it out of sleep.



Optional: Integer, the built-in potentiometer to shut down. 1 for the first potentiometer, 2 for the second, and 3 to change the value on both. Defaults to 1.

NOTE: Only the MCP42xxx units have dual built-in potentiometers, so if you have an MCP41xxx unit, leave the default 1 set for this parameter.


View the MCP4XXX datasheet.


The MCP4xxxx series digital potentiometers operate as follows:

    - CS pin goes LOW, signifying data is about to be sent
    - exactly 16 bits are sent over SPI to the digipot (first 8 bits for control
      second 8 bits for data)
    - CS pin goes HIGH, signifying communication is complete

There must be exactly 16 bits of data clocked in, or the commands and data will be thrown away, and nothing accomplished.

Here's a diagram of the two bytes combined into a single bit string, showing the respective positions of the bits, and their function:

         |<-Byte 1: Control->|<-Byte 0: Data->|
         |                   |                |
    fcn: | command | channel |      data      |
    bit: | 7 6 5 4 | 3 2 1 0 | 7 6 5 4 3 2 1 0|
           ^                                 ^
           |                                 |
       MSB (bit 15)                      LSB (bit 0)


The control byte is the most significant byte of the overall data being clocked into the potentiometer, and consists of a command nibble and a channel nibble.


The command nibble is the most significant (leftmost) 4 bits of the control byte (bits 7-4 in the above diagram). The following diagram describes all possible valid values.

    Bits    Value

    0000    NOOP
    0001    set a new resistance value
    0010    put potentiometer into 'shutdown' mode
    0011    NOOP


The channel nibble is the least significant 4 bits (rightmost) of the control byte (bits 3-0 in the above diagram). Valid values follow. Note that the MCP41xxx series units have only a single potentiometer built in, there's but one valid value for them.

    Bits    Value

    0001    potentiometer 0
    0010    potentiometer 1 (MCP42xxx only)
    0011    both 0 and 1    (MCP42xxx only)


The data byte consists of the least significant 8 bits (rightmost) of the 16 bit combined data destined to the potentiometer. Both the MCP41xxx and MCP42xxx series potentiometers contain 256 taps, so the mapping of this byte is simple: valid values are 0 (0% output) through 255 (100% output).


Here's an overview of the bits in order:

15-14: Unused ("Don't Care Bits", per the datasheet)

13-12: Command bits

11-10: Unused

9-8: Channel (built-in potentiomenter) select bits

7-0: Potentiometer tap setting data (0-255)


Steve Bertrand, <steveb at>


Copyright 2017 Steve Bertrand.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See for more information.