sfDevAS7331.h

Go to the documentation of this file.

 
#pragma once
 
#include <stdint.h>
 
// include the sparkfun toolkit headers
#include <sfTk/sfToolkit.h>
 
// Bus interfaces
#include <sfTk/sfTkII2C.h>
// I2C Addressing
// 7-bit address defined as [1, 1, 1, 0, 1, A1, A0] where A1/A0 are the
// physical address pins tied high or low
const uint8_t kDefaultAS7331Addr = 0x74;    // A1 = 0, A0 = 0
const uint8_t kSecondaryAS7331Addr = 0x75;  // A1 = 0, A1 = 1
const uint8_t kTertiaryAS7331Addr = 0x76;   // A1 = 1, A0 = 0
const uint8_t kQuaternaryAS7331Addr = 0x77; // A1 = 1, A0 = 1
 
const uint8_t kDefaultAS7331DeviceID = 0x21;  // When polling the AGEN register, this should be returned on boot.
const uint8_t kAS7331DeviceIDTopNibble = 0x2; // Top nibble of the AGEN byte, always the same.
 
// Enum Definitions
 
// Device Operating Mode
typedef enum
{
    // 0b00X invalid
    DEVICE_MODE_CFG = 0x2,
    DEVICE_MODE_MEAS = 0x3
    // 0b1XX invalid
} as7331_dev_op_state_t;
 
// Sensor gain, able to be read as (1 << (11 - gain)) aka 2^(11-gain).
typedef enum
{
    GAIN_2048 = 0x0000,
    GAIN_1024,
    GAIN_512,
    GAIN_256,
    GAIN_128,
    GAIN_64,
    GAIN_32,
    GAIN_16,
    GAIN_8,
    GAIN_4,
    GAIN_2,
    GAIN_1
} as7331_gain_t;
 
// Conversion Clock Frequency available settings, read as (1024 * (1 << cclk))
// aka 1024*2^cclk.
typedef enum
{
    CCLK_1_024_MHZ = 0x00,
    CCLK_2_048_MHZ,
    CCLK_4_096_MHZ,
    CCLK_8_192_MHZ
} as7331_conv_clk_freq_t;
 
// Measurement Mode types
typedef enum
{
    MEAS_MODE_CONT = 0x0, // Continuous mode
    MEAS_MODE_CMD,        // Command/OneShot mode
    MEAS_MODE_SYNS,       // SYNchronous Start mode
    MEAS_MODE_SYND        // SYNchronous start and enD mode
} as7331_meas_mode_t;
 
// Time conversion values in CONT, CMD, SYNS modes. Read as (1 << tconv) aka
// 2^tconv.
typedef enum
{
    TIME_1MS = 0x0,
    TIME_2MS,
    TIME_4MS,
    TIME_8MS,
    TIME_16MS,
    TIME_32MS,
    TIME_64MS,
    TIME_128MS,
    TIME_256MS,
    TIME_512MS,
    TIME_1024MS,
    TIME_2048MS,
    TIME_4096MS,
    TIME_8192MS,
    TIME_16384MS
} as7331_conv_time_t;
 
// Predivider values. Read as (1 << (1+div)) aka 2^(1+div).
typedef enum
{
    DIV_2 = 0x0,
    DIV_4,
    DIV_8,
    DIV_16,
    DIV_32,
    DIV_64,
    DIV_128,
    DIV_256
} as7331_divider_val_t;
 
// Type of UV to pick.
typedef enum
{
    AS7331_UVA,
    AS7331_UVB,
    AS7331_UVC
} as7331_uv_type;
 
// Configuration Register Descriptions
//
// Can only be accessed in the Configuration operation state. All 8 bits long.
//
// The following registers map to the underlying registers of the device.
 
const uint8_t kSfeAS7331RegCfgOsr = 0x00; // Register address
 
// A union is used here so that individual values from the register can be
// accessed or the whole register can be accessed.
typedef union {
    struct
    {
        uint8_t dos : 3;      // Device Operating State   - OSR[2:0]
        uint8_t sw_res : 1;   // Software Reset           - OSR[3]
        uint8_t reserved : 2; // Reserved, don't write.   - OSR[4:5]
        uint8_t pd : 1;       // Power Down Enabled       - OSR[6]
        uint8_t ss : 1;       // Start State              - OSR[7]
    };
    uint8_t byte;
} sfe_as7331_reg_cfg_osr_t;
 
const uint8_t kSfeAS7331RegCfgAgen = 0x02; // Register address
 
// A union is used here so that individual values from the register can be
// accessed or the whole register can be accessed.
typedef union {
    struct
    {
        uint8_t mut : 4;   // Increments when changes are made to the control
                           // registers. Defaults to 0b0001 aka 0x1.
        uint8_t devid : 4; // Always equals 0b0010 aka 0x2.
    };
    uint8_t byte;
} sfe_as7331_reg_cfg_agen_t;
 
const uint8_t kSfeAS7331RegCfgCreg1 = 0x06; // Register address
 
// A union is used here so that individual values from the register can be
// accessed or the whole register can be accessed.
typedef union {
    struct
    {
        uint8_t time : 4; // Conversion time  - CREG1[3:0]
        uint8_t gain : 4; // Sensor gain      - CREG1[7:4]
    };
    uint8_t byte;
} sfe_as7331_reg_cfg_creg1_t;
 
const uint8_t kSfeAS7331RegCfgCreg2 = 0x07; // Register address
 
// A union is used here so that individual values from the register can be
// accessed or the whole register can be accessed.
typedef union {
    struct
    {
        uint8_t div : 3;       // Digital Divider value                            - CREG2[2:0]
        uint8_t en_div : 1;    // Whether the digital divider is enabled           - CREG2[3]
        uint8_t reserved : 2;  // Reserved, don't write.                           - CREG2[5:4]
        uint8_t en_tm : 1;     // Whether temperature is calculated in SYND mode.  - CREG2[6]
        uint8_t reserved1 : 1; // Reserved, don't write.                           - CREG2[7]
    };
    uint8_t byte;
} sfe_as7331_reg_cfg_creg2_t;
 
const uint8_t kSfeAS7331RegCfgCreg3 = 0x08; // Register Address
 
// A union is used here so that individual values from the register can be
// accessed or the whole register can be accessed.
typedef union {
    struct
    {
        uint8_t cclk : 2;      // Conversion clock selection.      - CREG3[1:0]
        uint8_t reserved : 1;  // Reserved, don't write.           - CREG3[2]
        uint8_t rdyod : 1;     // Output mode of the ready pin.    - CREG3[3]
        uint8_t sb : 1;        // Standby mode bit.                - CREG3[4]
        uint8_t reserved1 : 1; // Reserved, don't write.           - CREG3[5]
        uint8_t mmode : 2;     // Measurement mode selection.      - CREG3[7:6]
    };
    uint8_t byte;
} sfe_as7331_reg_cfg_creg3_t;
 
const uint8_t kSfeAS7331RegCfgBreak = 0x09; // Register address, register is a single uint8_t.
 
const uint8_t kSfeAS7331RegCfgEdges = 0x0A; // Register address, register is a single uint8_t.
 
const uint8_t kSfeAS7331RegCfgOptReg = 0x0B; // Register address
 
// A union is used here so that individual values from the register can be
// accessed or the whole register can be accessed.
typedef union {
    struct
    {
        uint8_t init_idx : 1; // I2C repeat start mode flag.  - OPTREG[0]
        uint8_t reserved : 7; // Reserved, don't write.       - OPTREG[7:1]
    };
    uint8_t byte;
} sfe_as7331_reg_cfg_optreg_t;
 
// Measurement Register Descriptions
//
// Can only be accessed in the Measure operation state. All 16 bits long. They
// are all read-only except the bottom byte of the OSR/STATUS register.
//
// The following registers map to the underlying registers of the device.
 
const uint8_t kSfeAS7331RegMeasOsrStatus = 0x00; // Register address
 
// A union is used here so that individual values from the register can be
// accessed or the whole register can be accessed.
typedef union {
    struct
    {
        sfe_as7331_reg_cfg_osr_t osr; // See OSR configuration register above.        - OSRSTAT[7:0]
        uint8_t powerstate : 1;       // Power down state.                            - OSRSTAT[8]
        uint8_t standbystate : 1;     // Standby mode state.                          - OSRSTAT[9]
        uint8_t notready : 1;         // Inverted value of the ready pin.             - OSRSTAT[10]
        uint8_t ndata : 1;            // Indicates new data available.                - OSRSTAT[11]
        uint8_t ldata : 1;            // Indicates data overwrite prior to retrieval. - OSRSTAT[12]
        uint8_t adcof : 1;            // OVF of at least one ADC channel.             - OSRSTAT[13]
        uint8_t mresof : 1;           // OVF of at least one of the MRES registers.   - OSRSTAT[14]
        uint8_t outconvof : 1;        // OVF of the internal 24-bit time reference.   - OSRSTAT[15]
    };
    uint16_t word;
} sfe_as7331_reg_meas_osr_status_t;
 
// Output result registers. 16-bit values unless noted otherwise.
const uint8_t kSfeAS7331RegMeasTemp = 0x01; // 12-bit temperature, MS 4-bits 0.
const uint8_t kSfeAS7331RegMeasMres1 = 0x02;
const uint8_t kSfeAS7331RegMeasMres2 = 0x03;
const uint8_t kSfeAS7331RegMeasMres3 = 0x04;
const uint8_t kSfeAS7331RegMeasOutConvL = 0x05; // First 16-bits of 24-bit OUTCONV.
const uint8_t kSfeAS7331RegMeasOutConvH = 0x06; // LSB is MSB of OUTCONV, MSB is 0.
 
 
class sfDevAS7331
{
  public:
    // Default initialization values based on the datasheet. See SfeAS7331Driver::setDefaultSettings for
    // an explanation of the values.
    sfDevAS7331()
        : _theBus{nullptr}, _breakTime{25}, _numEdges{1}, _readyPinMode{false}, _dividerEnabled{false},
          _tempConvEnabled{true}, _indexMode{true}, _standbyState{false}, _startState{false},
          _powerDownEnableState{true}, _opMode{DEVICE_MODE_CFG}, _sensorGain{GAIN_2}, _cclk{CCLK_1_024_MHZ},
          _mmode{MEAS_MODE_CMD}, _conversionTime{TIME_64MS}, _dividerRange{DIV_2}, _uva{0.0f}, _uvb{0.0f}, _uvc{0.0f},
          _temperature{0.0f}, _outputConversionTime{0U}, _conversionA{0.0f}, _conversionB{0.0f}, _conversionC{0.0f}
    {
    }
 
    bool begin(sfTkIBus *theBus = nullptr);
 
    uint8_t getDeviceID(void);
 
    void setCommunicationBus(sfTkIBus *theBus);
 
    bool runDefaultSetup(const bool &runSoftReset = false);
 
    bool prepareMeasurement(const as7331_meas_mode_t &measMode = MEAS_MODE_CONT, const bool &startMeasure = false);
 
    bool reset(void);
 
    sfTkError_t readTemp(void);
 
    sfTkError_t readUVA(void);
 
    sfTkError_t readUVB(void);
 
    sfTkError_t readUVC(void);
 
    sfTkError_t readAllUV(void);
 
    sfTkError_t readAll(void);
 
    sfTkError_t readOutConv(void);
 
    float getUVA(void);
 
    float getUVB(void);
 
    float getUVC(void);
 
    float getTemp(void);
 
    uint32_t getOutConv(void);
 
    as7331_gain_t getGainRaw(void);
 
    uint16_t getGainValue(void);
 
    sfTkError_t setGain(const as7331_gain_t &gain);
 
    as7331_conv_clk_freq_t getCClkRaw(void);
 
    uint16_t getCClkKHz(void);
 
    sfTkError_t setCClk(const as7331_conv_clk_freq_t &cclk);
 
    as7331_conv_time_t getConversionTimeRaw(void);
 
    uint16_t getConversionTimeMillis(void);
 
    sfTkError_t setConversionTime(const as7331_conv_time_t &convTime);
 
    bool getReadyPinMode(void);
 
    sfTkError_t setReadyPinMode(const bool &pinMode);
 
    bool getDigitalDividerEnabled(void);
 
    sfTkError_t setDigitalDividerEnabled(const bool &isEnabled);
 
    as7331_divider_val_t getDigitalDividerRange(void);
 
    sfTkError_t setDigitalDividerRange(const as7331_divider_val_t &divider, const bool &enableDiv = true);
 
    bool getSyndTempConversionEnabled(void);
 
    sfTkError_t setSyndTempConversionEnabled(const bool &isEnabled);
 
    bool getIndexMode(void);
 
    sfTkError_t setIndexMode(const bool &indexMode);
 
    uint8_t getBreakTime(void);
 
    sfTkError_t setBreakTime(const uint8_t &breakTime);
 
    uint8_t getNumEdges(void);
 
    sfTkError_t setNumEdges(const uint8_t &numEdges);
 
    bool getPowerDownState(void);
 
    sfTkError_t setPowerDownState(const bool &pd);
 
    as7331_dev_op_state_t getOperationMode(void);
 
    sfTkError_t setOperationMode(const as7331_dev_op_state_t &opMode);
 
    as7331_meas_mode_t getMeasurementMode(void);
 
    sfTkError_t setMeasurementMode(const as7331_meas_mode_t &measMode);
 
    bool getStandbyState(void);
 
    sfTkError_t setStandbyState(const bool &standby);
 
    bool getStartState(void);
 
    sfTkError_t setStartState(const bool &startState);
 
    sfTkError_t getStatus(sfe_as7331_reg_meas_osr_status_t &statusReg);
 
    sfTkError_t getOSR(sfe_as7331_reg_cfg_osr_t &osrReg);
 
    sfTkError_t setOSR(const sfe_as7331_reg_cfg_osr_t &osrReg);
 
    sfTkError_t getCReg1(sfe_as7331_reg_cfg_creg1_t &creg1);
 
    sfTkError_t setCReg1(const sfe_as7331_reg_cfg_creg1_t &creg1);
 
    sfTkError_t getCReg2(sfe_as7331_reg_cfg_creg2_t &creg2);
 
    sfTkError_t setCReg2(const sfe_as7331_reg_cfg_creg2_t &creg2);
 
    sfTkError_t getCReg3(sfe_as7331_reg_cfg_creg3_t &creg3);
 
    sfTkError_t setCReg3(const sfe_as7331_reg_cfg_creg3_t &creg3);
 
    sfTkError_t getBreak(uint8_t &breakReg);
 
    sfTkError_t setBreak(const uint8_t &breakReg);
 
    sfTkError_t getEdges(uint8_t &edgesReg);
 
    sfTkError_t setEdges(const uint8_t &edgesReg);
 
    sfTkError_t getOptIndex(sfe_as7331_reg_cfg_optreg_t &optReg);
 
    sfTkError_t setOptIndex(const sfe_as7331_reg_cfg_optreg_t &optReg);
 
  private:
    sfTkError_t readRawUV(const as7331_uv_type &uv_type);
 
    float convertRawTempToTempC(const uint16_t &inputVal);
 
    float convertRawUVVal(const uint16_t &rawVal, const float &convFactor);
 
    void calculateConversionFactors(void);
 
    void setDefaultSettings(void);
 
    sfTkIBus *_theBus; // Pointer to bus device.
 
    uint8_t _breakTime; // Local config value. Value is in us/8. EX: _breakTime = 20 means 20*8 = 160us.
    uint8_t _numEdges;  // Local config value. Edges seen on SYN pin before ending conversion in SYND mode.
 
    bool _readyPinMode;         // Local config value. False is Push/Pull True is Open/Drain.
    bool _dividerEnabled;       // Local config value. False is disabled, True is enabled.
    bool _tempConvEnabled;      // Local config value. False is disabled, True is enabled.
    bool _indexMode;            // Local config value. False is for controllers without repeat start.
    bool _standbyState;         // Local state value. False means the device is not in standby mode.
    bool _startState;           // Local state value. False means the device is not allowed to measure.
    bool _powerDownEnableState; // Local state value. False means the device is NOT POWERED DOWN. This is inverse.
 
    as7331_dev_op_state_t _opMode; // Local state value. Configuration or Measure operating mode.
    as7331_gain_t _sensorGain;     // Local config value. Sensor gain stored as (1 << (11 - gain)).
    as7331_conv_clk_freq_t _cclk;  // Local config value. Sensor's conversion clock stored as 1024*(1 << cclk) kHz.
    as7331_meas_mode_t _mmode; // Local state value. Details the device's measurement mode as CONT, CMD, SYNS, or SYND.
    as7331_conv_time_t _conversionTime; // Local config value. Contains the conversion time stored as (1 << time) ms.
    as7331_divider_val_t _dividerRange; // Local config value. Contains the predivider value stored as (1 << 1 + range).
 
    float _uva;         // Last valid UVA result in uW/cm2.
    float _uvb;         // Last valid UVB result in uW/cm2.
    float _uvc;         // Last valid UVC result in uW/cm2.
    float _temperature; // Last valid temperature result in degC.
 
    uint32_t _outputConversionTime; // Last valid output conversion time result in of clock cycle count.
 
    float _conversionA; // Internal conversion factor for the UVA sensor.
    float _conversionB; // Internal conversion factor for the UVB sensor.
    float _conversionC; // Internal conversion factor for the UVC sensor.
 
    const float _fsrA = 348160.0; // Full Scale Resolution for the UVA sensor.
    const float _fsrB = 387072.0; // Full Scale Resolution for the UVB sensor.
    const float _fsrC = 169984.0; // Full Scale Resolution for the UVC sensor.
};