NAME
    RPi::ADC::ADS - Interface to ADS 1xxx series analog to digital
    converters (ADC) on Raspberry Pi

SYNOPSIS
        use RPi::ADC::ADS;

        my $adc = RPi::ADC::ADS->new;

        # voltage level

        my $volts = $apc->volts;

        # percent of input capacity

        my $percent = $apc->percent;

        # raw input value 

        my $integer = $apc->raw;

DESCRIPTION
    Perl interface to the 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 pinouts between the ADC and the Raspberry Pi.

        ADC     Pi
        -----------
        VDD     Vcc
        GND     Gnd
        SCL     SCL (NOT SCLK)
        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

METHODS
  new
    Parameters:

    model
    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
    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
    Optional. The filesystem path to the i2c device file. Defaults to
    `/dev/i2c-1'

    channel
    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.

  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.

  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'.

  channel($mux)
    Sets/gets the currently registered ADC input channel within the object.

    Parameters:

    $mux
    Optional: String, `0' through `3', representing the ADC's multiplexer
    input channel to read from.

  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.

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(1)           100: FS = ±0.512V
        001: FS = ±4.096V(1)           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)

    See the https://cdn-shop.adafruit.com/datasheets/ads1015.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.

