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. =head1 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.