/ 
RPi-DAC-MCP4922-2.36.3
River stage one • 1 direct dependent • 2 total dependents
/ RPi::DAC::MCP4922

NAME

RPi::DAC::MCP4922 - Interface to the MCP49x2 series digital to analog converters (DAC) over the SPI bus

DESCRIPTION

Interface to the MCP49x2 series Digital to Analog Converters (DAC) over the SPI bus. These units have two onboard DACs, which are modified independently.

The MCP4902 has 8-bit resolution (max 255 data value), the MCP4912 has 10-bit resolution (max val 1023), and the MCP4922 has 12-bit resolution (max val 4095).

SYNOPSIS

my $dac = RPi::DAC::MCP4922->new(

    model   => 'MCP4922', # mandatory
    channel => 0,         # mandatory (SPI channel)
    cs      => 18,        # mandatory (GPIO pin num)
    buf     => 0,         # optional, default
    gain    => 1,         # optional, default
);

my ($dacA, $dacB) = (0, 1);

$dac->set($dacA, 4095); # 100% output
$dac->set($dacB, 0);    # 0% output

$dac->disable_sw($dacB); # shuts onboard DAC B down
$dac->enable_sw($dacB);  # turns it back on

# NOTE

# the SHDN pin on the IC is normally tied to 3.3v+ or 5v+ which
# signifies that the DACs are always available. This SHDN pin
# enables you to disable both DACs by pulling this pin LOW

# to enable this functionality, connect the ICs SHDN pin to a GPIO
# pin, then in the new() call, add the following param:

shdn => 19 # GPIO pin num

# if you do use this hardware feature, you MUST make a call to
# enable_hw() after initialization of the object before you can
# use either of the onboard DACs

$dac->enable_hw;

...

METHODS

new

Instantiates a new RPi::DAC::MCP4922 object, sets up the GPIO and SPI, and returns the object.

Parameters:

All parameters are sent in within a single hash.

There are three mandatory parameters, the rest are optional with very sane defaults that shouldn't be used unless you understand the ramifications.

model => $str

Mandatory: String. The model number of the MCP49xx DAC you're controlling.

channel => $int

Mandatory: Integer. 0 for SPI channel 0, or 1 for SPI channel 1.

cs => $int

Mandatory: Integer. The GPIO pin number connected to the DACs chip select (CS) pin.

buf => $int

Optional: Integer. 0 for unbuffered output, and 1 for buffered. This software does not at this time use the LDAC latch pin (and should be tied to Gnd), so although this param won't have any meaning, best to leave it set to the default, 0.

gain => $int

Optional: Integer. Sets the gain amplifier. 1 for 1x gain (0v to 255/256 * Vref), and 0 for 2x gain (0v to 255/256 * 2 * Vref). Defaults to 1, or 1x gain.

shdn => $int

Optional: Integer. This is the GPIO pin number if you decide to use the SHDN (hardware shutdown pin #9) on the chip. Typically, this can simply be tied to 3.3v or 5v which means the DACs will always be active. If you do use this pin, you *MUST* make a specific call to $dac-enable_hw()> before using either of the onboard DACs.

set

Writes a new analog output value to one of the onboard DACs.

Parameters:

$dac

Mandatory: Integer. 0 for DAC A, or 1 for DAC B.

$value

Mandatory: Integer. The new value to write to the DAC. See "DESCRIPTION" for the respective values for each IC model.

disable_sw

Disables a specified onboard DAC's output via software. Both DACs are enabled by default.

Parameters:

$dac

Mandatory: Integer. 0 for DAC A, or 1 for DAC B.

enable_sw

Re-enables a specified onboard DAC's output via software.

Parameters:

$dac

Mandatory: Integer. 0 for DAC A, or 1 for DAC B.

enable_hw

NOTE: The MCP49xx DAC IC chips have a SHDN pin, which when pulled LOW, disables via hardware the output on both onboard DACs. Normally, this pin is simply tied to 3.3v+ or 5v+ which informs the hardware that both DACs will always be active.

If you decide you want to tie the SHDN pin to a GPIO pin and control this feature manually, you have to initialize your RPi::DAC::MCP4922 object by setting the shdn = $gpio_pin_num> in your call to new(). Then, before either of the DACs can be used, this method (enable_hw()) MUST be called.

Takes no parameters.

disable_hw

Disables, via the hardware's SHDN pin, the outputs of both onboard DACs.

See "enable_hw" for more information on this feature.

Takes no parameters.

register

This is a helper function which allows you to view the configuration register at various stages of this software's operation. I tend to use it to ensure I'm getting proper bit strings back from the various inner operations:

printf("%b\n", $dac->register);

Takes no parameters, returns the decimal value of the register as it's currently configured.

TECHNICAL INFORMATION

DEVICE SPECIFICS

The MCP49x2 series chips have two onboard DACs (referred to as DAC A and DAC B).

The 4902 unit provides 8-bit output resolution (value 0-255), the 4912, 10-bit (0-1023), and the 4922, 12-bit (0-4095).

DEVICE OPERATION

The MCP49x2 series digital to analog converters (DAC) operate as follows:

- SHDN pin is an override to physically disable the DACs. It can be tied to
  3.3v+ or 5v+ for always-on, or tied to any GPIO pin so you can control the
  physical shutdown by putting the GPIO pin LOW
- on startup, put the CS pin to HIGH. This indicates that there is no
  conversation occuring
- turn the CS pin to LOW to start a conversation
- send 16 bits (the write register) over the SPI bus while CS is LOW
- turn the CS pin HIGH to end the conversation
- as soon as the last bit is clocked in, the specified DAC will update its
  output level

DEVICE REGISTER

The write register is the same for all devices under the MCP49x2 umbrella, with the differing devices having differing sizes for the data portion. Following is a diagram that depicts the register for the different devices, where x shows that the bit is available, with a - signifying that this bit will be ignored. Note that a full 16-bits needs to be sent in regardless of chip type.

        |<---------------- Write Command Register --------------->|
        |                   |                                     |
        |<---- control ---->|<------------ data ----------------->|
        ] 15 | 14 | 13 | 12 | 11 10 09 08 07 06 05 04 03 02 01 00 |
        -----------------------------------------------------------
        | ^  |  ^ |  ^ |  ^ |               ^                     |
        |    |    |    |    |                                     |
        |A/B | BUF|GAIN|SHDN|              DATA                   |
        |---------------------------------------------------------|
MCP4922 | x  |  x |  x |  x |  x  x  x  x  x  x  x  x  x  x  x  x | 12-bit
MCP4912 | x  |  x |  x |  x |  x  x  x  x  x  x  x  x  x  x  -  - | 10-bit
MCP4902 | x  |  x |  x |  x |  x  x  x  x  x  x  x  x  -  -  -  - |  8-bit
        -----------------------------------------------------------

REGISTER BITS

The device register is 16-bits wide.

DAC SELECT BITS

bit 15

Specifies which DAC we're writing to with this write.

Param   Value   DAC
-------------------

0       0b0     A
1       0b1     B

BUFFERED BITS

bit 14

Specifies whether to buffer the data (for use with the LATCH pin, if used) or simply send it straight through to the DAC.

Param   Value   Result
----------------------

0       0b0     Unbuffered (default)
1       0b1     Buffered

GAIN BITS

bit 13

Specifies the value of the gain amplifier.

Param   Value   Gain
--------------------

0       0b0     2x (Vout = 2 * Vref * D/4096)
1       0b1     1x (Vout = Vref * D/4096) (default)

SHUTDOWN BITS

bit 12

Allows you to programmatically shut down both DACs on the chip.

Param  Value   Result
----------------------

0      0b0     DACs active (default)
1      0b1     DACs shut down

DATA BITS

bits 11-0

These bits are used to set the output level.

Model   Value   Bits
--------------------

MCP4922 0-4095  12
MCP4912 0-1023  10
MCP4902 0-255   8

The 10-bit and 8-bit models simply ignore the last 2 and 4 bits respectively.

AUTHOR

Steve Bertrand, <steveb at cpan.org>

LICENSE AND COPYRIGHT

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 http://dev.perl.org/licenses/ for more information.