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.

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.

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.

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.

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.

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.

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.

int	ph_oem_clear_calibration (const ph_oem_t *dev)
	Clears all calibrations previously done.

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.

int	ph_oem_read_calibration_state (const ph_oem_t dev, uint16_t calibration_state)
	Read the PH_OEM_REG_CALIBRATION_CONFIRM register.

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.

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.

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.

Typedef Documentation

◆ ph_oem_interrupt_pin_cb_t

typedef void(* ph_oem_interrupt_pin_cb_t) (void *)

pH OEM interrupt pin callback

Definition at line 122 of file ph_oem.h.

Enumeration Type Documentation

◆ ph_oem_calibration_option_t

enum 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

enum 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

enum 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

enum 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

enum 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] dev device 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]	dev	device descriptor
[in]	cb	callback called when the pH OEM interrupt pin fires
[in]	arg	callback 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]	dev	device descriptor
[in]	params	device 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]	dev	device descriptor
[out]	calibration_state	calibration 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]	dev	device descriptor
[out]	temperature_compensation	raw 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]	dev	device descriptor
[out]	ph_value	raw 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] dev device 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]	dev	device descriptor
[in]	calibration_value	pH value multiplied by 1000 e.g 7,002 * 1000 = 7002
[in]	option	ph_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]	dev	device descriptor
[in]	temperature_compensation	valid 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]	dev	device descriptor
[in]	state	ph_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]	dev	device descriptor
[in]	addr	new 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]	dev	device descriptor
[in]	state	ph_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] dev device 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

Detailed Description

Files

Data Structures

Typedefs

Enumerations

Functions

Typedef Documentation

◆ ph_oem_interrupt_pin_cb_t

Enumeration Type Documentation

◆ ph_oem_calibration_option_t

◆ ph_oem_device_state_t

◆ ph_oem_irq_option_t

◆ ph_oem_led_state_t

◆ ph_oem_named_returns_t

Function Documentation

◆ ph_oem_clear_calibration()

◆ ph_oem_enable_interrupt()

◆ ph_oem_init()

◆ ph_oem_read_calibration_state()

◆ ph_oem_read_compensation()

◆ ph_oem_read_ph()

◆ ph_oem_reset_interrupt_pin()

◆ ph_oem_set_calibration()

◆ ph_oem_set_compensation()

◆ ph_oem_set_device_state()

◆ ph_oem_set_i2c_address()

◆ ph_oem_set_led_state()

◆ ph_oem_start_new_reading()