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,
            dev     => '/dev/i2c-1',
            channel => 0,
        );
    
        my $volts   = $apc->volts;
    
        my $percent = $apc->percent;
    
        my $int     = $apc->raw;

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. One of 0 through A3 which specifies which channel to read. If
    not sent in, we default to 0 throughout the object's lifecycle.

 addr($hex)

    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.

 channel($channel)

    Sets/gets the currently registered ADC input channel within the object.

    Parameters:

        $channel

    Optional: String, 0 through 3, representing the ADC's multiplexer input
    channel to read from. Setting through this method overrides the value
    that was set in new() (0 by default if never specified), until it is
    changed again. If you are using more than one channel, it's more useful
    to set the channel in your read calls (volts(), raw() and percent()).

 device($dev)

    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($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]/.

 register($binary)

    Sets/gets the ADC's registers. This has been left public for
    convenience for those who understand the hardware very well. It really
    shouldn't be used otherwise.

    Parameters:

        $binary

    Optional: A binary string (literal 1s and 0s), 32 bits long that
    represents the data we'll write to the ADC device.

DATA RETRIEVAL METHODS

 volts($channel)

    Retrieves the voltage level of the channel.

    Parameters:

        $channel

    Optional: String, 0 through 3, representing 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($channel)

    Retrieves the ADC channel's input value by percentage of maximum input.

    Parameters: See $channel in "volts".

 raw($channel)

    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 (ads_address, dev_name, wbuf1, wbuf2, resolution)
            int     ads_address
            const char * dev_name
            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 (ads_address, dev_name, wbuf1, wbuf2, resolution)
            int     ads_address
            const char * dev_name
            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 (ads_address, dev_name, wbuf1, wbuf2, resolution)
            int     ads_address
            const char * dev_name
            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 (ads_address, dev_name, wbuf1, wbuf2, resolution)
            int     ads_address
            const char * dev_name
            char * wbuf1
            char * wbuf2
            int resolution

    See "fetch" for details on the wbuf arguments.

TECHNICAL DATA

 REGISTERS

    The write buffer consists of an array with three elements. Element 0
    selects the register to use. 0 for the conversion register and 1 for
    the configuration register.

    Element 1 is a byte long, and represents bits 15-8 of a register, while
    element 2 represents bits 7-0.

 CONFIG REGISTER

    Bit 15 should always be set to 1 when writing. This initiates a
    conversation ADC. When reading, this bit will read 1 if a conversion is
    currently occuring, and 0 if the current conversion is complete.

    Bits 14-12 represent the ADC input channel, as well as either a
    single-ended (difference between HIGH and GRD) or differential mode
    (difference between two input channels). Only single-ended is currently
    supported.

    Below is the binary representation for the input channels (bits 14-12):

        Input   Binary
    
        A0      100
        A1      101
        A2      110
        A3      111

    Bits 11-9 are for the programmable gain amplifier. This software uses
    001 or +/-4.096V to cover the Pi's 3.3V output.

        000: FS = +/-6.144V              100: FS = +/-0.512V
        001: FS = +/-4.096V              101: FS = +/-0.256V
        010: FS = +/-2.048V (hw default) 110: FS = +/-0.256V
        011: FS = +/-2.024V              111: FS = +/-0.256V

    Bit 8 is for the conversion operation mode. We use single conversion
    hardware default.

        0: continuous conversion
        1: single conversion (hw default)

    Bits 9-5 represent the data rate. We use 128SPS:

        000 : 128SPS 100 : 1600SPS (hw default)
        001 : 250SPS 101 : 2400SPS
        010 : 490SPS 110 : 3300SPS
        011 : 920SPS 111 : 3300SPS

    Bit 4 is unused.

    Bit 3 is the comparator polarity. We use Active Low by default:

        0 - Active Low (hw default)
        1 - Active High

    Bit 2 is unused.

    Bits 1-0 represent the comparator queue. This software has disabled it:

        00 : Assert after one conversion
        01 : Assert after two conversions
        10 : Assert after four conversions
        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 ADC1xxx 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
    <https://cdn-shop.adafruit.com/datasheets/ads1016.pdf> for further
    information.

SEE ALSO

    WiringPi::API, RPi::WiringPi, RPi::DHT11

AUTHOR

    Steve Bertrand, <steveb@cpan.org>

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.

