Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
.idea
build/
deps/
82 changes: 80 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

A Mongoose library for various `I2C` speaking ADCs from Texas Instruments:

* ADS1119 - 16bit, 1000 Samples/sec, 2 differential / 4 single-ended, programmable gain.
* ADS1115 - 16bit, 860 Samples/sec, 2 differential / 4 single-ended, programmable gain
* ADS1114 - 16bit, 860 Samples/sec, 1 differential / 1 single-ended, programmable gain
* ADS1113 - 16bit, 860 Samples/sec, 1 differential / 1 single-ended, no gain
Expand All @@ -17,7 +18,7 @@ The driver takes care of exposing the correct fuctionality based on which `type`
is created. Differential measurements can be taken on all devices, but only
`ADS1x15` has multiple options.

## API Description
## ADS 1013-1115 API

First, create a device using `mgos_ads1x1x_create()` by specifying the type of
chip you're using. Take some measurements using `mgos_ads1x1x_read()`, and
Expand All @@ -43,7 +44,7 @@ the differential voltage between two channels, typically `Chan0` and
`Chan1`. Several channel pairs are allowed, see the include file for
details. Note, that this function is only available on `ADS1X15` chips.

## Example application
#### Example application (!ADS1119)

```
#include "mgos.h"
Expand Down Expand Up @@ -80,6 +81,83 @@ enum mgos_app_init_result mgos_app_init(void) {

```

## ADS 1119 API

TI has simplified the command API and configuration registers during the development of the ADS1119 so it works quite differently to prior chips.

First, create a device using `mgos_ads1119_create()` by specifying the type of
chip you're using. Take some measurements using `mgos_ads1119_read()`, and
clean up the driver by using `mgos_ads1x1x_destroy()`.

#### Creation

During initiation you can specify the settings such as data rate, gain, single shot vs continuous and whether to use the internal 2.048v vREF or an external vREF.

For example: `mgos_ads1119_create(mgos_i2c_get_global(), 0x40, ADC_ADS1119, MGOS_ADS1119_GAIN_1, MGOS_ADS1X1X_SPS_20, MGOS_ADS1119_CM_SS, MGOS_ADS1119_VREF_EXT)`


```
if (!(ads = mgos_ads1119_create(mgos_i2c_get_global(), 0x40, ADC_ADS1119, MGOS_ADS1119_GAIN_1, MGOS_ADS1X1X_SPS_20, MGOS_ADS1119_CM_SS, MGOS_ADS1119_VREF_EXT))) {
LOG(LL_ERROR, ("I2C Could not create ADS1119"));
}
else {
LOG(LL_INFO, ("I2C Have created ADS1119 device successfully"));
}
```

#### Reading values
To read either a single or differential value you need to supply the MUX value per 'Configuration Register Field Descriptions' in the TI datasheet.

The function is of the form `mgos_ads1119_read(struct mgos_ads1x1x* dev, uint8_t mux, int16_t* result)`.

For example to read single ended AIN3 & GND, that corresponds to a mux value of binary 110 / decimal 7, and would have a call like:
`int16_t res; mgos_ads1119_read(ads, 7, &res);`

#### Example application

This example reads all the channels as single ended. As the 5th result element it reads the voltage offset value (AINP and AINN shorted to AVDD / 2) to enable calibration.

```
#include "mgos.h"
#include "mgos_config.h"
#include "mgos_ads1x1x.h"

void timer_cb(void *data) {
struct mgos_ads1x1x *d = (struct mgos_ads1x1x *)data;
int16_t res[5];

if (!d) return;

for(int i=0; i<5; i++) {
if (!mgos_ads1119_read(s_adc, i+3, &res[i])) {
LOG(LL_ERROR, ("Could not read device"));
return;
}
}
LOG(LL_INFO, ("chan={%6d, %6d, %6d, %6d} offset=%d", res[0], res[1], res[2], res[3], res[4]));
}

enum mgos_app_init_result mgos_app_init(void) {
struct mgos_ads1x1x *d = NULL;

if (!(d = mgos_ads1119_create(mgos_i2c_get_global(), 0x40, ADC_ADS1119, MGOS_ADS1119_GAIN_1, MGOS_ADS1X1X_SPS_20, MGOS_ADS1119_CM_SS, MGOS_ADS1119_VREF_EXT))) {
LOG(LL_ERROR, ("Could not create ADS1119"));
return MGOS_APP_INIT_ERROR;
}

mgos_set_timer(100, true, timer_cb, d);

return MGOS_APP_INIT_SUCCESS;
}

```

Notes:
- TI Datasheet: http://www.ti.com/lit/ds/symlink/ads1119.pdf
- Have observed that it will return a negative reading if a thermistor is unplugged, these values are currently simplified to -1.
- TODO: switch the mgos_msleep value between the START/SYNC command and taking the reading based on SPS


# Disclaimer

This project is not an official Google project. It is not supported by Google
Expand Down
51 changes: 47 additions & 4 deletions include/mgos_ads1x1x.h
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@ enum mgos_ads1x1x_type {
ADC_ADS1015,
ADC_ADS1113,
ADC_ADS1114,
ADC_ADS1115
ADC_ADS1115,
ADC_ADS1119
};

enum mgos_ads1x1x_fsr {
Expand All @@ -50,19 +51,41 @@ enum mgos_ads1x1x_dr {
MGOS_ADS1X1X_SPS_MIN = 0, // 8SPS for ADS111X, 128SPS for ADS101X
MGOS_ADS1X1X_SPS_8, // 8SPS, ADS111X only
MGOS_ADS1X1X_SPS_16, // 16SPS, ADS111X only
MGOS_ADS1X1X_SPS_20, // 20SPS, ADS1119 only (default)
MGOS_ADS1X1X_SPS_32, // 32SPS, ADS111X only
MGOS_ADS1X1X_SPS_64, // 64SPS, ADS111X only
MGOS_ADS1X1X_SPS_90, // 90SPS, ADS1119 only
MGOS_ADS1X1X_SPS_128, // 128SPS, both ADS111X and ADS101X
MGOS_ADS1X1X_SPS_250, // 250SPS, both ADS111X and ADS101X
MGOS_ADS1X1X_SPS_330, // 330SPS, ADS1119 only
MGOS_ADS1X1X_SPS_475, // 475SPS, ADS111X only
MGOS_ADS1X1X_SPS_490, // 490SPS, ADS101X only
MGOS_ADS1X1X_SPS_860, // 860SPS, ADS111X only
MGOS_ADS1X1X_SPS_920, // 920SPS, ADS101X only
MGOS_ADS1X1X_SPS_1000, // 1000SPS, ADS1119 only
MGOS_ADS1X1X_SPS_1600, // 1600SPS, ADS101X only
MGOS_ADS1X1X_SPS_2400, // 2400SPS, ADS101X only
MGOS_ADS1X1X_SPS_3300, // 3300SPS, ADS101X only
MGOS_ADS1X1X_SPS_DEFAULT, // 128SPS for ADS111X, 1600SPS for ADS101X
MGOS_ADS1X1X_SPS_MAX, // 860SPS for ADS111X, 3300SPS for ADS101X
MGOS_ADS1X1X_SPS_DEFAULT, // 128SPS for ADS111X, 1600SPS for ADS101X, 20SPS for ADS1119
MGOS_ADS1X1X_SPS_MAX, // 860SPS for ADS111X, 3300SPS for ADS101X, 1000SPS for ADS1119
};

enum mgos_ads1119_gain
{
MGOS_ADS1119_GAIN_1 = 0,
MGOS_ADS1119_GAIN_4
};
Copy link
Collaborator

@pimvanpelt pimvanpelt Aug 26, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, gain exists also in the other chips, so this can be a shared enum, probably hidden behind an ads1x1x_{get,set}_gain() API.


enum mgos_ads1119_conversion_mode
{
MGOS_ADS1119_CM_SS = 0,
MGOS_ADS1119_CM_CONT
};
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

singleshot vs continuous mode exists also in some other versions in the ads1x1x family, so this can be a shared enum, probably hidden behind an ads1x1x_{get,set}_mode() API;


enum mgos_ads1119_vref
{
MGOS_ADS1119_VREF_INT = 0, // Internal 2.048v
MGOS_ADS1119_VREF_EXT
};

/*
Expand All @@ -71,7 +94,20 @@ enum mgos_ads1x1x_dr {
* validity, upon success a new `struct mgos_ads1x1x` is allocated and
* returned. If the device could not be found, NULL is returned.
*/
struct mgos_ads1x1x *mgos_ads1x1x_create(struct mgos_i2c *i2c, uint8_t i2caddr, enum mgos_ads1x1x_type type);
struct mgos_ads1x1x*
mgos_ads1x1x_create(struct mgos_i2c* i2c, uint8_t i2caddr, enum mgos_ads1x1x_type type);

/*
* Initialize a ADS1119 on the I2C bus `i2c` at address specified in `i2caddr`
* parameter (default ADS1X1X is on address 0x48). The device will be polled for
* validity, upon success a new `struct mgos_ads1x1x` is allocated and
* returned. If the device could not be found, NULL is returned.
* Refer to TI product PDF, Configuration Register, for information on what to use for mux/gain/DR/CM/VREF.
* Note, use the decimal value for each, ie AinP = AIN2, AinN=AGND is decimal 5 (101 binary).
* Mux is provided at read time
*/
//struct mgos_ads1x1x* mgos_ads1119_create(struct mgos_i2c* i2c, uint8_t i2caddr, enum mgos_ads1x1x_type type, enum mgos_ads1119_gain gain = MGOS_ADS1119_GAIN_1, enum mgos_ads1x1x_dr dataRate = MGOS_ADS1X1X_SPS_20, enum mgos_ads1119_conversion_mode conversionMode = MGOS_ADS1119_CM_SS, enum mgos_ads1119_vref vRef = MGOS_ADS1119_VREF_INT);
struct mgos_ads1x1x* mgos_ads1119_create(struct mgos_i2c* i2c, uint8_t i2caddr, enum mgos_ads1x1x_type type, enum mgos_ads1119_gain gain, enum mgos_ads1x1x_dr dataRate, enum mgos_ads1119_conversion_mode conversionMode, enum mgos_ads1119_vref vRef);
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(see my comment on abstraction leak in #1)


/*
* Destroy the data structure associated with a ADS1X1X device. The reference
Expand Down Expand Up @@ -108,6 +144,8 @@ bool mgos_ads1x1x_get_dr(struct mgos_ads1x1x *dev, enum mgos_ads1x1x_dr *dr);
*/
bool mgos_ads1x1x_read(struct mgos_ads1x1x *dev, uint8_t chan, int16_t *result);

bool mgos_ads1119_read(struct mgos_ads1x1x* dev, uint8_t mux, int16_t* result);

/* Read a 2-channel differential from the ADC and return the read value in `result`.
* If the channel pair invalid, or an error occurred, false is returned and the
* result cannot be relied upon. Upon success, true is returned.
Expand All @@ -119,6 +157,11 @@ bool mgos_ads1x1x_read(struct mgos_ads1x1x *dev, uint8_t chan, int16_t *result);
*/
bool mgos_ads1x1x_read_diff(struct mgos_ads1x1x *dev, uint8_t chanP, uint8_t chanN, int16_t *result);

/* Centralised helper function to write configuration to an ADS1119
* Sends the command for WREG first
*/
bool mgos_ads1119_write_conf(struct mgos_ads1x1x * dev, uint8_t value);

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

helpers do not go into the public API, as they are not meant to be called by users. This should go into a src/*_internal.h file.

#ifdef __cplusplus
}
#endif
Loading