NAME RPi::ADC::ADS - Interface to ADS 1xxx series analog to digital converters (ADC) on Raspberry Pi SYNOPSIS use RPi::ADC::ADS; # instantiation of the object, shown with optional parameters # with their defaults if you don't specify them my $adc = RPi::ADC::ADS->new( model => 'ADS1015', addr => 0x48, device => '/dev/i2c-1', channel => 0, gain => 1, mode => 1, rate => 0, polarity => 0, queue => 3, ); my $volts = $adc->volts; my $percent = $adc->percent; my $int = $adc->raw; # all retrieval methods allow you to specify the channel (0..3) in the call # instead of using the default, or the one set in new() my $percent = $adc->percent(3); ... DESCRIPTION Perl interface to the Texas Instruments/Adafruit ADS 1xxx series Analog to Digital Converters (ADC) on the Raspberry Pi. Provides access via the i2c bus to all four input channels on each ADC, while performing correct bit-shifting between the 12-bit and 16-bit resolution on the differing models. PHYSICAL SETUP List of pinout connections between the ADC and the Raspberry Pi. ADC Pi ----------- VDD Vcc GND Gnd SCL SCL SDA SDA ADDR Gnd (see below for more info) ALRT NC (no connect) Pinouts `A0' through `A3' on the ADC are the analog pins used to connect to external peripherals (specified in this software as `0' through `3'). The `ADDR' pin specifies the memory address of the ADC unit. Four ADCs can be connected to the i2c bus at any one time. By default, this software uses address `0x48', which is the address when the `ADDR' pin is connected to `Gnd' on the Raspberry Pi. Here are the addresses for the four Pi pins: Pin Address --------------- Gnd 0x48 VDD 0x49 SDA 0x4A SCL 0x4B OBJECT METHODS new Instantiates a new RPi::ADC::ADS object. All parameters are optional, and are all sent in as a single hash. Parameters: model => $string Optional. The model number of the ADC. If not specified, we use `ADS1015'. Models that start with `ADS11' have 16-bit accuracy resolution, and models that start with `ADS10' have 12-bit resolution. addr => $hex Optional. The hex location of the ADC. If the pinout in PHYSICAL SETUP is used, this will be `0x48' (which is the default if not supplied). device => $string Optional. The filesystem path to the i2c device file. Defaults to `/dev/i2c-1' channel => $int Optional. See INPUT CHANNELS for parameter values and details. gain => $int Optional. See GAIN AMPLIFIER for parameter values and details. mode => $int Optional. See OPERATION MODE for parameter values and details. rate => $int Optional. See DATA RATE for parameter values and details. polarity => $int Optional. See COMPARATOR POLARITY for parameter values and details. queue => $int Optional. See COMPARATOR QUEUE for parameter values and details. addr Sets/gets the ADC memory address. After object instantiation, this method should only be used to get (ie. don't send in any parameters). Parameters: $hex Optional: A memory address in the form `0xNN'. See PHYSICAL SETUP for full details. device Sets/gets the file path information for the i2c device. This shouldn't be used as a setter after object instantiation. It defaults to `/dev/i2c-1' if not set in the `new()' call (or with this method thereafter). Parameters: $dev Optional: String, the full path of the i2c device in use. Defaults to `/dev/i2c-1'. model Sets/gets the model of the ADC chip that we're connected to. This shouldn't be set after object instantiation. Defaults to `ADS1015' if not set in the `new()' call, or later with this method. Parameters: $model Optional: String, the model name of the ADC unit. Defaults to `ADS1015'. Valid values are `/ADS1[01]1[3458]/'. channel Sets/gets the currently registered ADC input channel within the object. Both single-ended and differential operation mode are available. Parameters: $channel Optional: See INPUT CHANNELS for the parameter values and details. gain Sets/gets the programmable gain amplifier. Parameters: $int Optional: See GAIN AMPLIFIER for the parameter values and details. mode Sets/gets the conversion operation mode, either single conversion or continuous conversion. Parameters: $int Optional: See OPERATION MODE for the parameter values and details. rate Sets/gets the data rate. Parameters: $int Optional: See DATA RATE for the parameter values and details. polarity Sets/gets the comparitor polarity. Parameters: $int Optional: See COMPARATOR POLARITY for the parameter values and details. queue Sets/gets the comparator queue configuration. Parameters: $int Optional: See COMPARATOR QUEUE for the parameter values and details. OPERATIONAL METHODS These methods are for core operation, but are left public as they may be of use for those who want to tinker with the innards. bits Separates the 16-bit wide configuration register and returns an array containing the Most Significant Byte as the first element, and the Least Significant Byte as the second element. Parameters: None Return: Array of two elements (MSB, LSB). register Sets/gets the ADC's config register. This has been left public for convenience for those who understand the hardware very well. It really shouldn't be used otherwise. Parameters: $msb, $lsb Optional: If one is sent in, both must be sent in. `$msb' is the most significant byte of the config register, an integer between 0-255. `$lsb' is the least significant byte of the config register, and must be in the same format as the `$msb'. Return: Array with two elements. First element is the MSB, and the second element is the LSB. DATA RETRIEVAL METHODS volts Retrieves the voltage level of the channel. Parameters: $channel Optional: See INPUT CHANNELS for parameter values and details. Specifies the ADC input channel to read from. Setting this parameter allows you to read all four channels without changing the default set in the object. Return: A floating point number between `0' and the maximum voltage output by the Pi's GPIO pins. percent Retrieves the ADC channel's input value by percentage of maximum input. Parameters: See `$channel' in volts. raw Retrieves the raw value of the ADC channel's input value. Parameters: See `$channel' in volts. C FUNCTIONS The following C functions aren't meant to be called directly. Rather, use the corresponding Perl object methods instead. fetch Fetches the raw data from the channel specified. Implemented as: int fetch (addr, dev, wbuf1, wbuf2, res) int addr char * dev char * wbuf1 char * wbuf2 int resolution `wbuf1' is the most significant byte (bits 15-8) for the configuration register, `wbuf2' being the least significant byte (bits 7-0). voltage_c Fetches the ADC input and returns it as the actual voltage. Implemented as: float voltage_c (addr, dev, wbuf1, wbuf2, res) int addr char * dev char * wbuf1 char * wbuf2 int resolution See fetch for details on the `wbuf' arguments. raw_c Fetches the ADC input and returns it in its raw form. Implemented as: int raw_c (addr, dev, wbuf1, wbuf2, res) int addr char * dev char * wbuf1 char * wbuf2 int resolution See fetch for details on the `wbuf' arguments. percent_c Fetches the ADC input value as a floating point percentage between minimum and maximum input values. Implemented as: float percent_c (addr, dev, wbuf1, wbuf2, res) int addr char * dev char * wbuf1 char * wbuf2 int resolution See fetch for details on the `wbuf' arguments. TECHNICAL DATA REGISTERS Both the conversion and configuration registers are 16-bits wide. The write buffer for the config register consists of an array with three elements. Element `0' is the register pointer, which allows you to select the register to use. Value `0' for the conversion register and `1' for the configuration register. Element `1' is a byte long, and represents the most significant bits (15-8) of each 16-bit register, while element `2' represents the least significant bits, 7-0. It is advised that you don't change any of these except for the input channels unless you know how the hardware works, and you have a good understanding of the specific configuration register options. CONFIG REGISTER CONVERSATION BIT Bit: 15 This bit should always be set to `1' when writing. This initiates a conversation with the ADC. When reading, this bit will read `1' if a conversion is currently occuring, and `0' if the current conversion is complete. INPUT CHANNELS Bit: 14-12 Represents the ADC input channel, as well as either a single-ended (difference between a single input channel and GRD) or differential mode (difference between two input channels). Single mode configuration: Param Value Input --------------------- 0 100 A0 (default) 1 101 A1 2 110 A2 3 111 A3 Differential mode configuration: Param Value Diff between ---------------------------- 4 000 A0 <-> A1 5 001 A0 <-> A3 6 010 A1 <-> A3 7 011 A2 <-> A3 GAIN AMPLIFIER Bit: 11-9 Represents the programmable gain amplifier. This software uses `1' or +/-4.096V to cover the Pi's 3.3V output. Param Value Gain -------------------- 0 000 +/-6.144V 1 001 +/-4.096V (default) 2 010 +/-2.048V 3 011 +/-2.024V 4 100 +/-0.512V 5 101 +/-0.256V 6 110 +/-0.256V 7 111 +/-0.256V OPERATION MODE Bit: 8 Represents the conversion operation mode. We use the single conversion hardware default. Param/Value Mode ------------------ 0 continuous conversion 1 single conversion (default) DATA RATE Bit: 7-5 Represent the data rate. We use 128SPS (128 Samples Per Second) by default: Param Value Rate -------------------- 0 000 128SPS (default) 1 001 250SPS 2 010 490SPS 3 011 920SPS 4 100 1600SPS 5 101 2400SPS 6 110 3300SPS 7 111 3300SPS COMPARATOR POLARITY Bit: 3 Represents the comparator polarity. We use `0' (active low) by default. Param/Value Polarity ---------------------- 0 Active Low (default) 1 Active High COMPARATOR QUEUE Bit: 1-0 Represents the comparator queue. We use `3' (disabled) by default. Param Value Queue --------------------- 0 00 Assert after one conversion 1 01 Assert after two conversions 2 10 Assert after four conversions 3 11 Disable comparator (default) READING DATA Each channel has a conversion register (that contains the actual analog input). This register is 16 bits wide. With that said, the most significant bit is used to identify whether the number is positive or negative, so technically, for the ADC11xx series ADCs, the width is actually 15 bits, and the ADC10xx units are 11 bits wide (as the resolution on these models are only 12-bit as opposed to 16-bit). See the ADC's datasheet for further information. NOTES Bit 4 and 2 of the configuration register are currently unused. SEE ALSO WiringPi::API, RPi::WiringPi, RPi::DHT11 AUTHOR Steve Bertrand, COPYRIGHT AND LICENSE Copyright (C) 2017 by Steve Bertrand This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.22.2 or, at your option, any later version of Perl 5 you may have available.