/* * Copyright (C) 2019 HAW Hamburg * * This file is subject to the terms and conditions of the GNU Lesser * General Public License v2.1. See the file LICENSE in the top level * directory for more details. */ /** * @defgroup drivers_ad7746 AD7746 Capacitance-to-digital converter driver * @ingroup drivers_sensors * @ingroup drivers_saul * @brief I2C Capacitance-to-digital converter with temperature and voltage * sensors. The devices has two main channels: capacitance channel * and voltage / temperature channel. * * The capacitance channel can measure from two different inputs * (CIN1 and CIN2), selected using @ref ad7746_set_cap_ch_input. * * The voltage / temperature channel can measure from five different * sources: Voltage from VIN pins, internal VCC, internal * temperature sensor and external temperature sensor * (see datasheet for proper setup). The mode of this channel can be * set using @ref ad7746_set_vt_ch_mode or will directly be set * when trying to read from a specific source which is not the * currently selected one. This mode change may lead to data not * being available right away (in which case the reading function * will return @ref AD7746_NODATA error code). * * @note Constantly switching between modes in the voltage / temperature * channel may lead to invalid data, for what it seems to be a * device limitation. * * This driver provides @ref drivers_saul capabilities. * @{ * * @file * @brief AD7746 Capacitance-to-digital converter with temperature * sensor driver * * @author Leandro Lanzieri */ #ifndef AD7746_H #define AD7746_H #ifdef __cplusplus extern "C" { #endif #include "periph/i2c.h" #include "periph/gpio.h" /** * @brief 0 fF capacitance code */ #define AD7746_ZERO_SCALE_CODE (0x800000LL) /** * @brief Interval voltage reference expressed in mV */ #define AD7746_INTERNAL_VREF (1170) /** * @brief Maximum value that can be configured into the DACs. */ #define AD7746_DAC_MAX (0x7F) /** * @brief Channel numbers for reading */ enum { AD7746_READ_CAP_CH = 0, /**< read capacitive channel */ AD7746_READ_VT_CH = 1 /**< read voltage / temperature channel */ }; /** * @brief Named return values */ enum { AD7746_OK = 0, /**< everything was fine */ AD7746_NOI2C = -1, /**< I2C communication failed */ AD7746_NODEV = -2, /**< no AD7746 device found on the bus */ AD7746_NODATA = -3 /**< no data available */ }; /** * @brief Voltage / Temperature channel sample rates */ typedef enum { AD7746_VT_SR_498 = 0, /**< 49.8 Hz */ AD7746_VT_SR_312 = 1, /**< 31.2 Hz */ AD7746_VT_SR_161 = 2, /**< 16.1 Hz */ AD7746_VT_SR_082 = 3 /**< 8.2 Hz */ } ad7746_vt_sample_rate_t; /** * @brief Voltage / Temperature channel modes */ typedef enum { AD7746_VT_MD_DIS = -1, /**< channel disabled */ AD7746_VT_MD_TEMP = 0, /**< internal temperature sensor */ AD7746_VT_MD_ETEMP = 1, /**< external temperature sensor (see datasheet) */ AD7746_VT_MD_VDD = 2, /**< Vdd voltage monitor */ AD7746_VT_MD_VIN = 3 /**< external voltage input (Vin) */ } ad7746_vt_mode_t; /** * @brief Capacitance channel input */ typedef enum { AD7746_CAP_IN_1 = 0, /**< CIN1 input */ AD7746_CAP_IN_2 /**< CIN2 input */ } ad7746_cap_input_t; /** * @brief Capacitive channel sample rate */ typedef enum { AD7746_CAP_SR_909 = 0, /**< 90.9 Hz */ AD7746_CAP_SR_838 = 1, /**< 83.8 Hz */ AD7746_CAP_SR_500 = 2, /**< 50.0 Hz */ AD7746_CAP_SR_263 = 3, /**< 26.3 Hz */ AD7746_CAP_SR_161 = 4, /**< 16.1 Hz */ AD7746_CAP_SR_130 = 5, /**< 13.0 Hz */ AD7746_CAP_SR_109 = 6, /**< 10.9 Hz */ AD7746_CAP_SR_091 = 7 /**< 9.1 Hz */ } ad7746_cap_sample_rate_t; /** * @brief Excitation signal output configuration */ typedef enum { AD7746_EXC_A = 0x06, /**< enable only exc A output */ AD7746_EXC_B = 0x09, /**< enable only exc B output */ AD7746_EXC_AB = 0x0A /**< enable exc A and B outputs */ } ad7746_exc_config_t; /** * @brief AD7746 params */ typedef struct ad7746_params { i2c_t i2c; /**< i2c device */ uint8_t addr; /**< i2c address */ uint8_t dac_a_cap; /**< DAC A capacitance */ uint8_t dac_b_cap; /**< DAC B capacitance */ ad7746_exc_config_t exc_config; /**< excitation signal config */ ad7746_cap_sample_rate_t cap_sample_rate; /**< capacitance sample rate */ ad7746_vt_sample_rate_t vt_sample_rate; /**< voltage/temp sample rate */ ad7746_vt_mode_t vt_mode; /**< mode of the voltage/temp ch */ ad7746_cap_input_t cap_input; /**< selected capacitance input*/ } ad7746_params_t; /** * @brief AD7746 device descriptor */ typedef struct ad7746 { ad7746_params_t params; /**< device driver configuration */ } ad7746_t; /** * @brief Initializes an AD7746 device * * @param[in,out] dev device descriptor * @param[in] params device configuration * * @return AD7746_OK on success * @return AD7746_NODEV if no device is found on the bus * @return AD7746_NOI2C if other error occurs */ int ad7746_init(ad7746_t *dev, const ad7746_params_t *params); /** * @brief Reads the capacitance from the input 1 (CIN1). Returns the value in * fF. * * @note If the currently selected input does not match @ref AD7746_CAP_IN_1 it * will be changed to it. This may cause data not to be available right * away. The time until new data is available will depend on the * @ref ad7746_params_t::cap_sample_rate "sample rate" of the channel. * * @param[in, out] dev device descriptor * @param[out] value read value in fF * * @return AD7746_OK on success * @return AD7746_NODATA if there is no data available in the channel * @return AD7746_I2C if other error occurs */ int ad7746_read_capacitance_1(ad7746_t *dev, int *value); /** * @brief Reads the capacitance from the input 2 (CIN2). Returns the value in * fF. * * @note If the currently selected input does not match @ref AD7746_CAP_IN_2 it * will be changed to it. This may cause data not to be available right * away. The time until new data is available will depend on the * @ref ad7746_params_t::cap_sample_rate "sample rate" of the channel. * * @param[in, out] dev device descriptor * @param[out] value read value in fF * * @return AD7746_OK on success * @return AD7746_NODATA if there is no data available in the channel * @return AD7746_I2C if other error occurs */ int ad7746_read_capacitance_2(ad7746_t *dev, int *value); /** * @brief Reads the voltage from the external voltage input (VIN). Returns the * value in mV. * * @note If the current mode of the voltage / temperature channel does not match * @ref AD7746_VT_MD_VIN it will be changed to this mode, causing data not * to be available right away. The time until new data is available will * depend on the @ref ad7746_params_t::vt_sample_rate "sample rate" of the * channel. * * @param[in, out] dev device descriptor * @param[out] value read value in mV * * @return AD7746_OK on success * @return AD7746_NODATA if there is no data available in the channel * @return AD7746_I2C if other error occurs */ int ad7746_read_voltage_in(ad7746_t *dev, int *value); /** * @brief Reads the voltage from the VDD pin. Returns the value in mV. * * @note If the current mode of the voltage / temperature channel does not match * @ref AD7746_VT_MD_VDD it will be changed to this mode, causing data not * to be available right away. The time until new data is available will * depend on the @ref ad7746_params_t::vt_sample_rate "sample rate" of the * channel. * * @param[in, out] dev device descriptor * @param[out] value read value in mV * * @return AD7746_OK on success * @return AD7746_NODATA if there is no data available in the channel * @return AD7746_I2C if other error occurs */ int ad7746_read_voltage_vdd(ad7746_t *dev, int *value); /** * @brief Reads the temperature from the internal sensor. * * @note If the current mode of the voltage / temperature channel does not match * @ref AD7746_VT_MD_TEMP it will be changed to this mode, causing data * not to be available right away. The time until new data is available * will depend on the @ref ad7746_params_t::vt_sample_rate "sample rate" * of the channel. * * @param[in, out] dev device descriptor * @param[out] value read value in celsius * * @return AD7746_OK on success * @return AD7746_NODATA if there is no data available in the channel * @return AD7746_I2C if other error occurs */ int ad7746_read_temperature_int(ad7746_t *dev, int *value); /** * @brief Reads the temperature from the external sensor (see datasheet). * * @note If the current mode of the voltage / temperature channel does not match * @ref AD7746_VT_MD_ETEMP it will be changed to this mode, causing data * not to be available right away. The time until new data is available * will depend on the @ref ad7746_params_t::vt_sample_rate "sample rate" * of the channel. * * @param[in, out] dev device descriptor * @param[out] value read value in celsius * * @return AD7746_OK on success * @return AD7746_NODATA if there is no data available in the channel * @return AD7746_I2C if other error occurs */ int ad7746_read_temperature_ext(ad7746_t *dev, int *value); /** * @brief Sets the current input for the capacitive measurement.If not configured manually, the driver sets the correct mode within the dedicated read function. * * @param[in] dev device descriptor * @param[in] input selected input - 0 for CIN1, 1 for CIN2 * * @return AD7746_OK on success * @return AD7746_NOI2C on error */ int ad7746_set_cap_ch_input(const ad7746_t *dev, ad7746_cap_input_t input); /** * @brief Sets the mode for the voltage / temperature channel and updates the * descriptor with the new configuration. If not configured manually, the driver sets the correct mode within the dedicated read function. * * @param[in, out] dev device descriptor * @param[in] mode mode to which the channel has to be set * * @return AD7746_OK on success * @return AD7746_NOI2C on error */ int ad7746_set_vt_ch_mode(ad7746_t *dev, ad7746_vt_mode_t mode); /** * @brief Sets the sample rate for the voltage / temperature channel * * @param[in] dev device descriptor * @param[in] sr sample rate * * @return AD7746_OK on success * @return AD7746_NOI2C on error */ int ad7746_set_vt_sr(const ad7746_t *dev, ad7746_vt_sample_rate_t sr); /** * @brief Sets the sample rate for the capacitance channel * * @param[in] dev device descriptor * @param[in] sr sample rate * * @return AD7746_OK on success * @return AD7746_NOI2C on error */ int ad7746_set_cap_sr(const ad7746_t *dev, ad7746_cap_sample_rate_t sr); #ifdef __cplusplus } #endif #endif /* AD7746_H */ /** @} */