Device driver for Atlas Scientific pH OEM sensor with SMBus/I2C interface. More...

Detailed Description

Device driver for Atlas Scientific pH OEM sensor with SMBus/I2C interface.

The Atlas Scientific pH OEM sensor can be used with or without the interrupt pin. Per default this pin is mapped to GPIO_UNDEF if not otherwise defined in your makefile.

If you use an electrical isolation for most accurate readings e.g. with the ADM3260, keep in mind that its not recommended to use the interrupt pin without also isolating it somehow. The preferred method, if not using an isolation on the interrupt line, would be polling. In this case leave the interrupt pin undefined.

The Sensor has no integrated temperature sensor and for the highest possible precision it requires another device to provide the temperature for error compensation.

Once the pH OEM is powered on it will be ready to receive commands and take readings after 1ms.

Note
This driver provides [S]ensor [A]ctuator [U]ber [L]ayer capabilities. Reading (saul_driver_t::read) from the device returns the current pH value. Writing (saul_driver_t::write) a temperature value in celsius to the device sets the temperature compensation. A valid temperature range is 1 - 20000 (0.01 °C to 200.0 °C)
Communication is done using SMBus/I2C protocol at speeds of 10-100 kHz. Set your board I2C speed to I2C_SPEED_LOW or I2C_SPEED_NORMAL

Files

file  ph_oem.h
 Device driver for Atlas Scientific pH OEM Sensor with SMBus/I2C interface.
 
file  ph_oem_params.h
 Default configuration for Atlas Scientific pH OEM sensors.
 
file  ph_oem_regs.h
 Register definitions for the Atlas Scientific pH OEM sensor.
 

Data Structures

struct  ph_oem_params
 pH OEM sensor params More...
 
struct  ph_oem
 pH OEM device descriptor More...
 

Typedefs

typedef struct ph_oem_params ph_oem_params_t
 pH OEM sensor params
 
typedef void(* ph_oem_interrupt_pin_cb_t) (void *)
 pH OEM interrupt pin callback
 
typedef struct ph_oem ph_oem_t
 pH OEM device descriptor
 

Enumerations

enum  ph_oem_named_returns_t {
  PH_OEM_OK = 0, PH_OEM_NODEV = -1, PH_OEM_READ_ERR = -2, PH_OEM_WRITE_ERR = -3,
  PH_OEM_NOT_PH = -4, PH_OEM_INTERRUPT_GPIO_UNDEF = -5, PH_OEM_GPIO_INIT_ERR = -6, PH_OEM_TEMP_OUT_OF_RANGE = -7
}
 Named return values. More...
 
enum  ph_oem_led_state_t { PH_OEM_LED_ON = 0x01, PH_OEM_LED_OFF = 0x00 }
 LED state values. More...
 
enum  ph_oem_device_state_t { PH_OEM_TAKE_READINGS = 0x01, PH_OEM_STOP_READINGS = 0x00 }
 Device state values. More...
 
enum  ph_oem_irq_option_t { PH_OEM_IRQ_RISING = 0x02, PH_OEM_IRQ_FALLING = 0x04, PH_OEM_IRQ_BOTH = 0x08 }
 Interrupt pin option values. More...
 
enum  ph_oem_calibration_option_t { PH_OEM_CALIBRATE_LOW_POINT = 0x02, PH_OEM_CALIBRATE_MID_POINT = 0x03, PH_OEM_CALIBRATE_HIGH_POINT = 0x04 }
 Calibration option values. More...
 

Functions

int ph_oem_init (ph_oem_t *dev, const ph_oem_params_t *params)
 Initialize a pH OEM sensor. More...
 
int ph_oem_set_i2c_address (ph_oem_t *dev, uint8_t addr)
 Sets a new address to the pH OEM device by unlocking the PH_OEM_REG_UNLOCK register and writing a new address to the PH_OEM_REG_ADDRESS register. More...
 
int ph_oem_enable_interrupt (ph_oem_t *dev, ph_oem_interrupt_pin_cb_t cb, void *arg)
 Enable the pH OEM interrupt pin if ph_oem_params_t::interrupt_pin is defined. More...
 
int ph_oem_reset_interrupt_pin (const ph_oem_t *dev)
 The interrupt pin will not auto reset on option PH_OEM_IRQ_RISING and PH_OEM_IRQ_FALLING after interrupt fires, so call this function again to reset the pin state. More...
 
int ph_oem_set_led_state (const ph_oem_t *dev, ph_oem_led_state_t state)
 Set the LED state of the pH OEM sensor by writing to the PH_OEM_REG_LED register. More...
 
int ph_oem_set_device_state (const ph_oem_t *dev, ph_oem_device_state_t state)
 Sets the device state (active/hibernate) of the pH OEM sensor by writing to the PH_OEM_REG_HIBERNATE register. More...
 
int ph_oem_start_new_reading (const ph_oem_t *dev)
 Starts a new reading by setting the device state to PH_OEM_TAKE_READINGS. More...
 
int ph_oem_clear_calibration (const ph_oem_t *dev)
 Clears all calibrations previously done. More...
 
int ph_oem_set_calibration (const ph_oem_t *dev, uint16_t calibration_value, ph_oem_calibration_option_t option)
 Sets the PH_OEM_REG_CALIBRATION_BASE register to the calibration_value which the pH OEM sensor will be calibrated to. More...
 
int ph_oem_read_calibration_state (const ph_oem_t *dev, uint16_t *calibration_state)
 Read the PH_OEM_REG_CALIBRATION_CONFIRM register. More...
 
int ph_oem_set_compensation (const ph_oem_t *dev, uint16_t temperature_compensation)
 Sets the PH_OEM_REG_TEMP_COMPENSATION_BASE register to the temperature_compensation value which the pH OEM sensor will use to compensate the reading error. More...
 
int ph_oem_read_compensation (const ph_oem_t *dev, uint16_t *temperature_compensation)
 Reads the PH_OEM_REG_TEMP_CONFIRMATION_BASE register to verify the temperature compensation value that was used to take the pH reading is set to the correct temperature. More...
 
int ph_oem_read_ph (const ph_oem_t *dev, uint16_t *ph_value)
 Reads the PH_OEM_REG_PH_READING_BASE register to get the current pH reading. More...
 

Enumeration Type Documentation

◆ ph_oem_calibration_option_t

Calibration option values.

Enumerator
PH_OEM_CALIBRATE_LOW_POINT 

Low point calibration option.

PH_OEM_CALIBRATE_MID_POINT 

Mid point calibration option.

PH_OEM_CALIBRATE_HIGH_POINT 

High point calibration option.

Definition at line 102 of file ph_oem.h.

◆ ph_oem_device_state_t

Device state values.

Enumerator
PH_OEM_TAKE_READINGS 

Device active state.

PH_OEM_STOP_READINGS 

Device hibernate state.

Definition at line 86 of file ph_oem.h.

◆ ph_oem_irq_option_t

Interrupt pin option values.

Enumerator
PH_OEM_IRQ_RISING 

Pin high on new reading (manually reset)

PH_OEM_IRQ_FALLING 

Pin low on new reading (manually reset)

PH_OEM_IRQ_BOTH 

Invert state on new reading (automatically reset)

Definition at line 93 of file ph_oem.h.

◆ ph_oem_led_state_t

LED state values.

Enumerator
PH_OEM_LED_ON 

LED on state.

PH_OEM_LED_OFF 

LED off state.

Definition at line 78 of file ph_oem.h.

◆ ph_oem_named_returns_t

Named return values.

Enumerator
PH_OEM_OK 

Everything was fine.

PH_OEM_NODEV 

No device found on the bus.

PH_OEM_READ_ERR 

Reading to device failed.

PH_OEM_WRITE_ERR 

Writing to device failed.

PH_OEM_NOT_PH 

Not an Atlas Scientific pH OEM device.

PH_OEM_INTERRUPT_GPIO_UNDEF 

Interrupt pin is GPIO_UNDEF.

PH_OEM_GPIO_INIT_ERR 

Error while initializing GPIO PIN.

PH_OEM_TEMP_OUT_OF_RANGE 

Temperature is out of range.

Definition at line 64 of file ph_oem.h.

Function Documentation

◆ ph_oem_clear_calibration()

int ph_oem_clear_calibration ( const ph_oem_t dev)

Clears all calibrations previously done.

Parameters
[in]devdevice descriptor
Returns
PH_OEM_OK on success
PH_OEM_WRITE_ERR if writing to the device failed
PH_OEM_READ_ERR if reading from the device failed

◆ ph_oem_enable_interrupt()

int ph_oem_enable_interrupt ( ph_oem_t dev,
ph_oem_interrupt_pin_cb_t  cb,
void *  arg 
)

Enable the pH OEM interrupt pin if ph_oem_params_t::interrupt_pin is defined.

Note
ph_oem_reset_interrupt_pin needs to be called in the callback if you use PH_OEM_IRQ_FALLING or PH_OEM_IRQ_RISING
Provide the PH_OEM_PARAM_INTERRUPT_OPTION flag in your makefile. Valid options see: ph_oem_irq_option_t. The default is PH_OEM_IRQ_BOTH.
Also provide the gpio_mode_t as a CFLAG in your makefile. Most likely GPIO_IN. If the pin is to sensitive use GPIO_IN_PU for PH_OEM_IRQ_FALLING or GPIO_IN_PD for PH_OEM_IRQ_RISING and PH_OEM_IRQ_BOTH. The default is GPIO_IN_PD
Parameters
[in]devdevice descriptor
[in]cbcallback called when the pH OEM interrupt pin fires
[in]argcallback argument
Returns
PH_OEM_OK on success
PH_OEM_WRITE_ERR if writing to the device failed
PH_OEM_INTERRUPT_GPIO_UNDEF if the interrupt pin is undefined
PH_OEM_GPIO_INIT_ERR if initializing the interrupt gpio pin failed

◆ ph_oem_init()

int ph_oem_init ( ph_oem_t dev,
const ph_oem_params_t params 
)

Initialize a pH OEM sensor.

Parameters
[in,out]devdevice descriptor
[in]paramsdevice configuration
Returns
PH_OEM_OK on success
PH_OEM_NODEV if no device is found on the bus
PH_OEM_NOT_PH if the device found at the address is not a pH OEM device

◆ ph_oem_read_calibration_state()

int ph_oem_read_calibration_state ( const ph_oem_t dev,
uint16_t *  calibration_state 
)

Read the PH_OEM_REG_CALIBRATION_CONFIRM register.

After a calibration event has been successfully carried out, the calibration confirmation register will reflect what calibration has been done, by setting bits 0 - 2.

Parameters
[in]devdevice descriptor
[out]calibration_statecalibration state reflected by bits 0 - 2
(0 = low, 1 = mid, 2 = high)
Returns
PH_OEM_OK on success
PH_OEM_READ_ERR if reading from the device failed

◆ ph_oem_read_compensation()

int ph_oem_read_compensation ( const ph_oem_t dev,
uint16_t *  temperature_compensation 
)

Reads the PH_OEM_REG_TEMP_CONFIRMATION_BASE register to verify the temperature compensation value that was used to take the pH reading is set to the correct temperature.

Parameters
[in]devdevice descriptor
[out]temperature_compensationraw temperature compensation value.
Divide by 100 for floating point
e.g 3426 / 100 = 34.26
Returns
PH_OEM_OK on success
PH_OEM_READ_ERR if reading from the device failed

◆ ph_oem_read_ph()

int ph_oem_read_ph ( const ph_oem_t dev,
uint16_t *  ph_value 
)

Reads the PH_OEM_REG_PH_READING_BASE register to get the current pH reading.

Parameters
[in]devdevice descriptor
[out]ph_valueraw pH value
divide by 1000 for floating point
e.g 8347 / 1000 = 8.347
Returns
PH_OEM_OK on success
PH_OEM_READ_ERR if reading from the device failed

◆ ph_oem_reset_interrupt_pin()

int ph_oem_reset_interrupt_pin ( const ph_oem_t dev)

The interrupt pin will not auto reset on option PH_OEM_IRQ_RISING and PH_OEM_IRQ_FALLING after interrupt fires, so call this function again to reset the pin state.

Note
The interrupt settings are not retained if the power is cut, so you have to call this function again after powering on the device.
Parameters
[in]devdevice descriptor
Returns
PH_OEM_OK on success
PH_OEM_WRITE_ERR if writing to the device failed

◆ ph_oem_set_calibration()

int ph_oem_set_calibration ( const ph_oem_t dev,
uint16_t  calibration_value,
ph_oem_calibration_option_t  option 
)

Sets the PH_OEM_REG_CALIBRATION_BASE register to the calibration_value which the pH OEM sensor will be calibrated to.

Multiply the floating point calibration value of your solution by 1000 e.g. pH calibration solution => 7.002 * 1000 = 7002 = 0x00001B5A

The calibration value will be saved based on the given ph_oem_calibration_option_t and retained after the power is cut.

Note
Calibrating with PH_OEM_CALIBRATE_MID_POINT will reset the previous calibrations. Always start with PH_OEM_CALIBRATE_MID_POINT if you doing 2 or 3 point calibration
Parameters
[in]devdevice descriptor
[in]calibration_valuepH value multiplied by 1000 e.g 7,002 * 1000 = 7002
[in]optionph_oem_calibration_option_t
Returns
PH_OEM_OK on success
PH_OEM_WRITE_ERR if writing to the device failed
PH_OEM_READ_ERR if reading from the device failed

◆ ph_oem_set_compensation()

int ph_oem_set_compensation ( const ph_oem_t dev,
uint16_t  temperature_compensation 
)

Sets the PH_OEM_REG_TEMP_COMPENSATION_BASE register to the temperature_compensation value which the pH OEM sensor will use to compensate the reading error.

Multiply the floating point temperature value by 100 e.g. temperature in degree Celsius = 34.26 * 100 = 3426

Note
The temperature compensation will not be retained if the power is cut.
Parameters
[in]devdevice descriptor
[in]temperature_compensationvalid temperature range is 1 - 20000 (0.01 °C to 200.0 °C)
Returns
PH_OEM_OK on success
PH_OEM_WRITE_ERR if writing to the device failed
PH_OEM_TEMP_OUT_OF_RANGE if the temperature_compensation is not in the valid range

◆ ph_oem_set_device_state()

int ph_oem_set_device_state ( const ph_oem_t dev,
ph_oem_device_state_t  state 
)

Sets the device state (active/hibernate) of the pH OEM sensor by writing to the PH_OEM_REG_HIBERNATE register.

Note
Once the device has been woken up it will continuously take readings every 420ms. Waking the device is the only way to take a reading. Hibernating the device is the only way to stop taking readings.
Parameters
[in]devdevice descriptor
[in]stateph_oem_device_state_t
Returns
PH_OEM_OK on success
PH_OEM_WRITE_ERR if writing to the device failed

◆ ph_oem_set_i2c_address()

int ph_oem_set_i2c_address ( ph_oem_t dev,
uint8_t  addr 
)

Sets a new address to the pH OEM device by unlocking the PH_OEM_REG_UNLOCK register and writing a new address to the PH_OEM_REG_ADDRESS register.

The device address will also be updated in the device descriptor so it is still usable.

Settings are retained in the sensor if the power is cut.

The address in the device descriptor will reverse to the default address you provided through PH_OEM_PARAM_ADDR after the microcontroller restarts

Parameters
[in]devdevice descriptor
[in]addrnew address for the device. Range: 0x01 - 0x7f
Returns
PH_OEM_OK on success
PH_OEM_WRITE_ERR if writing to the device failed

◆ ph_oem_set_led_state()

int ph_oem_set_led_state ( const ph_oem_t dev,
ph_oem_led_state_t  state 
)

Set the LED state of the pH OEM sensor by writing to the PH_OEM_REG_LED register.

Parameters
[in]devdevice descriptor
[in]stateph_oem_led_state_t
Returns
PH_OEM_OK on success
PH_OEM_WRITE_ERR if writing to the device failed

◆ ph_oem_start_new_reading()

int ph_oem_start_new_reading ( const ph_oem_t dev)

Starts a new reading by setting the device state to PH_OEM_TAKE_READINGS.

Note
If the ph_oem_params_t::interrupt_pin is GPIO_UNDEF this function will poll every 20ms till a reading is done (~420ms) and stop the device from taking further readings
Parameters
[in]devdevice descriptor
Returns
PH_OEM_OK on success
PH_OEM_WRITE_ERR if writing to the device failed
PH_OEM_READ_ERR if reading from the device failed