The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.


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


    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);


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.


List of pinout connections between the ADC and the Raspberry Pi.

    ADC     Pi
    VDD     3.3V+
    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



Instantiates a new RPi::ADC::ADS object. All parameters are optional, and are all sent in as a single hash.


    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.


Sets/gets the ADC memory address. After object instantiation, this method should only be used to get (ie. don't send in any parameters).



Optional: A memory address in the form 0xNN. See "PHYSICAL SETUP" for full details.


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



Optional: String, the full path of the i2c device in use. Defaults to /dev/i2c-1.


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.



Optional: String, the model name of the ADC unit. Defaults to ADS1015. Valid values are /ADS1[01]1[3458]/.


Sets/gets the currently registered ADC input channel within the object. Both single-ended and differential operation mode are available.



Optional: See "INPUT CHANNELS" for the parameter values and details.


Sets/gets the programmable gain amplifier.



Optional: See "GAIN AMPLIFIER" for the parameter values and details.


Sets/gets the conversion operation mode, either single conversion or continuous conversion.



Optional: See "OPERATION MODE" for the parameter values and details.


Sets/gets the data rate.



Optional: See "DATA RATE" for the parameter values and details.


Sets/gets the comparitor polarity.



Optional: See "COMPARATOR POLARITY" for the parameter values and details.


Sets/gets the comparator queue configuration.



Optional: See "COMPARATOR QUEUE" for the parameter values and details.


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.


Merges the two 8-bit bytes of the configuration register as its currently configured, and returns it as one 16-bit integer.

Parameters: None

Return: 16-bit signed integer.


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.


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



Retrieves the voltage level of the 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.


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

Parameters: See $channel in "volts".


Retrieves the raw value of the ADC channel's input value.

Parameters: See $channel in "volts".


The following C functions aren't meant to be called directly. Rather, use the corresponding Perl object methods instead.


Fetches the raw data from the channel specified.

Implemented as:

    fetch (addr, dev, wbuf1, wbuf2, res)
        int addr
        char * dev
        char * wbuf1
        char * wbuf2
        int res

wbuf1 is the most significant byte (bits 15-8) for the configuration register, wbuf2 being the least significant byte (bits 7-0).


Fetches the ADC input and returns it as the actual voltage.

Implemented as:

    voltage_c (addr, dev, wbuf1, wbuf2, res)
        int addr
        char * dev
        char * wbuf1
        char * wbuf2
        int res

See "fetch" for details on the wbuf arguments.


Fetches the ADC input and returns it in its raw form.

Implemented as:

    raw_c (addr, dev, wbuf1, wbuf2, res)
        int addr
        char * dev
        char * wbuf1
        char * wbuf2
        int res

See "fetch" for details on the wbuf arguments.


Fetches the ADC input value as a floating point percentage between minimum and maximum input values.

Implemented as:

    percent_c (addr, dev, wbuf1, wbuf2, res)
        int addr
        char * dev
        char * wbuf1
        char * wbuf2
        int res

See "fetch" for details on the wbuf arguments.



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.



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.


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


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


Bit: 8

Represents the conversion operation mode. We use the single conversion hardware default.

    Param/Value   Mode

    0             continuous conversion
    1             single conversion (default)


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


Bit: 3

Represents the comparator polarity. We use 0 (active low) by default.

    Param/Value   Polarity

    0             Active Low (default)
    1             Active High


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)


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.


Bit 4 and 2 of the configuration register are currently unused.


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


Steve Bertrand, <>


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.