• Your shopping cart is empty!

ARD-LTC1863 / ARD-LTC1867 Library Reference

Introduction

The Ard1863 library was designed to make the Iowa Scaled Engineering ARD-LTC1863 / ARD-LTC1867 shield easy to use with the ArduinoTM environment. The ARD-LTC1863 / ARD-LTC1867 shields provide a breakout for the 200ksps, 12-bit LTC1863 or 16-bit LT1867A analog to digital converter (ADC), 128 bytes of onboard EEPROM for storing configuration or calibration values, and a read-only 6-byte EUI-48TM-compatible globally unique ID number.

The library class is actually called "Ard186x", because it can be used with both LTC1863 (12-bit) and LTC1867 (16-bit) converters.

Setup

You'll need to copy the Ard1863 directory (with the Ard1863.cpp and Ard1863.h files) into your arduino/libraries directory. Once the files are there, start your Arduino IDE and you should be able to pick "Ard1863" from "Sketch->Import Library..." to add it to your sketch.

Example Sketch

(AKA... Real developers don't read the documentation first, just shut up and show me some code, sparky!)

A sample Arduino sketch that demonstrates some simple uses of the library is available as part of the source package - it's in the "ard1863_example" directory. You still need to install the library itself, as described in Setup. Once the library's in place, you should be able to open up the ard1863_example.ino sketch and build/upload it.
Source Releases

The latest source code is always available from our GitHub ARD-LTC1863 repository. Look in the src/Ard1863 directory.

A Note About Converter Latency

Important! Note that the LTC1863 / LTC1867 will start a conversion whenever it is read (using ltc186xRead() or similar) or whenever the channel or configuration is changed. Each conversion will take roughly 5uS. During this conversion time, reading from the part will result in garbage data.

To minimize the wasted conversions, functions that read the current value and immediately change the channel (without wasting an entire conversion cycle in between) are provided in addition to the standard read and channel change functions.

License

The Ard1863 library is copyright 2017 by Nathan Holmes and Michael Petersen. It is free software, licensed under the GNU General Public License v3.

Classes and Structures

class Ard186x
{
    public:
    Ard186x();
    byte begin(byte deviceType, byte eepromAddress, int cs_pin);
    // LTC186x Functionality
    byte ltc186xChangeChannel(byte nextChannel);
    byte ltc186xChangeChannel(byte nextChannel, byte unipolar);
    unsigned int ltc186xRead();
    unsigned int ltc186xReadAndChangeChannel(byte nextChannel);
    unsigned int ltc186xReadAndChangeChannel(byte nextChannel, byte unipolar);
    int ltc186xReadBipolar();
    int ltc186xReadBipolarAndChangeChannel(byte nextChannel);
    int ltc186xReadBipolarAndChangeChannel(byte nextChannel, byte unipolar);
    // EEPROM functionality
    const char* eui48Get();
    byte eepromRead(int address);
    byte eepromRead(int address, byte defaultOnError);
    byte eepromWrite(int address, byte value);
    byte eepromWrite(int address, byte value, byte blocking);
};

Ard186x Class Public Methods / Functions

Ard186x::Ard186x()

The Ard186x::Ard186x() constructor takes no arguments, and will initialize the Ard186x object upon creation.


void Ard186x::begin(byte deviceType, byte eepromAddress, int cs_pin)

The Ard186x::begin() function should be called within the setup() function of your sketch. It requires the device type (DEVICE_LTC1863 for the ARD-LTC1863 board, or DEVICE_LTC1867 if you have it wired to an LTC1867) and EEPROM address on the ARD-LTC1863 to initialize both parts. The EEPROM address can be passed in directly as a number, or by using the address macros. Optionally, if using the ARD-LTC1863 / ARD-LTC1867 on an Arduino where the I2C pins conflict with the chip select line on D3, the EEPROM can be disabled by using address macro ARD186X_EEP_DISABLE.

The cs_pin argument is optional if you're using digital I/O line D3 for the chip select. However, if you're using any other digital IO to provide chip select to the LTC1863 / LTC1867 (such as D8, the other directly selectable option via JP6), you need to put that in here.

Returns:

Ard186x::begin() will return a byte corresponding to a bitmast of errors, with 0 corresponding with complete success.

  • ARD186X_SUCCESS (0x00) upon both devices being initialized successfully
  • ARD186X_LTC186X_ERR (0x01) if the LTC186x is not initialized successfully
  • ARD186X_EEPROM_ERR (0x02) if the EEPROM is not initialized successfully


byte Ard186x::ltc186xChangeChannel(byte channel)
byte Ard186x::ltc186xChangeChannel(byte channel, byte unipolar)

The Ard186x::ltc186xChangeChannel() function will change the LTC1863 / LTC1867's input multiplexer to the channel specified in channel and start a new conversion. The value in channel corresponds the five highest order bits sent out as the device's next conversion configuration (SD, ODD, S1, S0, and COM from the datasheet). In addition to computing values for channel yourself, you can use the channel macros.

An optional flag, unipolar, specifies how the converter should represent the next resulting value. If omitted or set to a non-zero value, the ADC read value will range from 0-4095. If set to zero, the ADC read value will range from -2048 to 2047.


unsigned int Ard186x::ltc186xRead()

The Ard186x::ltc186xRead() function will read the last conversion value as an unsigned number between 0-4095 (LTC1863) and 0-65535 (LTC1867), and also starts a new conversion on the same channel. This function should be used if the last channel change (either through ltc186xChangeChannel(), ltc186xReadAndChangeChannel(), or ltc186xReadBipolarAndChangeChannel()) had the unipolar attribute omitted or set to a non-zero value.

Returns:

  • 0 to 4095/65535 - result of last ADC conversion


unsigned int Ard186x:: ltc186xReadAndChangeChannel(byte nextChannel)
unsigned int Ard186x:: ltc186xReadAndChangeChannel(byte nextChannel, byte unipolar)

The Ard186x::ltc186xReadAndChangeChannel() function will read an unsigned number corresponding to the value of the last conversion and change the channel to be used in the next conversion at the same time. This is useful for not wasting time if high speed reads are important. A normal read followed by a channel change will waste the conversion triggered by the read. This function should be used if the last channel change (either through ltc186xChangeChannel(), ltc186xReadAndChangeChannel(), or ltc186xReadBipolarAndChangeChannel()) had the unipolar attribute omitted or set to a non-zero value. It doesn't matter if the next channel is configured to be unipolar or bipolar.

Channel change behaviour works exactly like Ard186x::ltc186xChangeChannel(). Read and return behaviour works exactly like Ard186x:: ltc186xRead().


int Ard186x::ltc186xReadBipolar()

The Ard186x::ltc186xReadBipolar() function will read the last conversion value as a signed 16 bit number between -2048 and 2047 (LTC1863) or -32768 and 32767 (LTC1867), and also starts a new conversion on the same channel. This function should be used if the last channel change (either through ltc186xChangeChannel(), ltc186xReadAndChangeChannel(), or ltc186xReadBipolarAndChangeChannel()) had the unipolar attribute set to zero.

Returns:

  • -2048 to 2047 (LTC1863) or -32768 to 32767 (LTC1867) - result of last ADC conversion


int Ard186x:: ltc186xReadBipolarAndChangeChannel(byte nextChannel)
int Ard186x:: ltc186xReadBipolarAndChangeChannel(byte nextChannel, byte unipolar)

The Ard186x::ltc186xReadBipolarAndChangeChannel() function will read a signed number corresponding to the value of the last conversion and change the channel to be used in the next conversion at the same time. This is useful for not wasting time if high speed reads are important. A normal read followed by a channel change will waste the conversion triggered by the read. This function should be used if the last channel change (either through ltc186xChangeChannel(), ltc186xReadAndChangeChannel(), or ltc186xReadBipolarAndChangeChannel()) had the unipolar attribute omitted or set to a non-zero value. It doesn't matter if the next channel is configured to be unipolar or bipolar.

Channel change behaviour works exactly like Ard186x::ltc186xChangeChannel(). Read and return behaviour works exactly like Ard186x:: ltc186xBipolarRead().


const char* Ard186x::eui48Get()

The Ard186x::eui48Get() function will retrieve the board's 48-bit, globally unique, EUI-48TM-compatible identification number as a string.

Returns:

Ard186x::eui48Get() will return a character pointer to a constant, NULL-terminated string. The value will be either 12 characters of hexadecimal number, or "Unknown" if the Ard186x::begin() failed to find the EEPROM. (Ard186x::begin() would have returned a value with the ARD186X_EEPROM_ERR bit set.)


byte Ard186x::eepromRead(int address)
byte Ard186x::eepromRead(int address, byte defaultOnError)

The Ard186x::eepromRead() function will retrieve a byte from the ARD-LTC1863 / ARD-LT1867's onboard EEPROM at the location specified by address. Valid values for address are 0x00-0x7F.

Optionally, the function can take a second argument - defaultOnError - of the value to be returned if the EEPROM is not initialized or is not accessible when the function is called. If the defaultOnError parameter is omitted, it will default to returning 0x00 on failure.


byte Ard186x::eepromWrite(int address, byte value)
byte Ard186x::eepromWrite(int address, byte value, byte blocking)

The Ard186x::eepromWrite() function will write a byte of value value to the ARD-LTC1863's onboard EEPROM at the location specified by address. Valid values for address are 0x00-0x7F, and value can be 0x00-0xFF.

Optionally, the function can take a third argument - blocking. The Microchip 24AA025E48 EEPROM used on the ARD-LTC1863 / ARD-LTC1867 can take up to 5 milliseconds to actually commit a write to EEPROM. If blocking is non-zero or omitted, the eepromWrite() function will block until it can confirm that the write is completed or until it times out after 10 millseconds.

Note that blocking will not cause the value to be verified - it merely causes the function to block until the part begins acknowledging I2C/TWI transactions once again, indicating that the write cycle is complete.

Returns:

  • * ARD186X_SUCCESS (0x00) if the write completed
  • ARD186X_EEPROM_ERR (0x02) if the write failed

Address Macros

EEPROM Address Macros

The address for the EEPROM is configurable on the ARD-LTC1863 / ARD-LTC1867 using jumpers JP5-JP6. You can either use the datasheet and directly enter the 24AA025E48's address into the Ard186x::begin() function, or use some convenient macros.

The macros are all in the form of ARD186X_EEP_ADDR_ba, where a and b can take on the value of '0' or 'Z'. Placeholder 'a' represents jumper JP5 and 'b' represents JP6. '0' indicates that a jumper has been placed across those pins, and 'Z' indicates that it's left floating (no jumper).

So, if both were left open, you'd use ARD186X_EEP_ADDR_ZZ. Likewise, for JP5 jumpered and JP6 open ARD186X_EEP_ADDR_Z0.

To disable EEPROM functionality, use ARD186X_EEP_DISABLED.

Channel Macros

Bit position macros are provided corresponding to the bits used to define the LTC1863/LTC1867 multiplexer channel in the configuration byte:

  • LTC186X_CONFIG_SINGLE_END
  • LTC186X_CONFIG_ODD
  • LTC186X_CONFIG_S1
  • LTC186X_CONFIG_S0

These can be combined into a channel value by an expression such as:

(_BV(LTC186X_CONFIG_S1) | _BV(LTC186X_CONFIG_SINGLE_END))

Please see the LTC1863 / LTC1867 datasheet, page 9, tables 1 & 2, to see how these are used directly.

Additionally, the library conveniently turns these combinations into formulaic macros. Differential configurations take the form LTC186X_CHAN_DIFF_aP_bN, where 'a' represents the channel number of the positive input (IN+ in the LTC1863/1867 datasheet) and 'b' represents the channel number of the negative input (IN-). For differential configurations using channel 7 as a common negative input (IN-), the bN part is replaced with 7COM.

Single-ended configurations are in the form LTC186X_CHAN_SINGLE_aP, where again 'a' represents the channel number of the positive (IN+) input.

Some examples:

  • LTC186X_CHAN_DIFF_2P_3N - Differential, input 2 is IN+, input 3 is IN-
  • LTC186X_CHAN_DIFF_2P_7COM - Differential, input 2 is IN+, input 7 is common IN-
  • LTC186X_CHAN_SINGLE_2P - Single ended, input 2 as IN+

For a complete list, look in the Ard1863.h header file in the Arduino Ard1863 library directory.