Accum-Tester/inc/INA3221.h

/*

	Arduino library for INA3221 current and voltage sensor.

	MIT License

	Copyright (c) 2020 Beast Devices, Andrejs Bondarevs

	Permission is hereby granted, free of charge, to any person obtaining a copy
	of this software and associated documentation files (the "Software"), to deal
	in the Software without restriction, including without limitation the rights
	to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
	copies of the Software, and to permit persons to whom the Software is
	furnished to do so, subject to the following conditions:

	The above copyright notice and this permission notice shall be included in all
	copies or substantial portions of the Software.

	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
	AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
	OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
	SOFTWARE.

*/

#ifndef BEASTDEVICES_INA3221_H
#define BEASTDEVICES_INA3221_H

#include <ch.h>
#include <hal.h>

typedef enum {
    INA3221_ADDR40_GND = 0b1000000, // A0 pin -> GND
    INA3221_ADDR41_VCC = 0b1000001, // A0 pin -> VCC
    INA3221_ADDR42_SDA = 0b1000010, // A0 pin -> SDA
    INA3221_ADDR43_SCL = 0b1000011  // A0 pin -> SCL
} ina3221_addr_t;

// Channels
typedef enum {
    INA3221_CH1 = 0,
    INA3221_CH2 = 1,
    INA3221_CH3 = 2,
    INA3221_CH_NUM = 3
} ina3221_ch_t;

// Registers
typedef enum {
    INA3221_REG_CONF = 0,
    INA3221_REG_CH1_SHUNTV,
    INA3221_REG_CH1_BUSV,
    INA3221_REG_CH2_SHUNTV,
    INA3221_REG_CH2_BUSV,
    INA3221_REG_CH3_SHUNTV,
    INA3221_REG_CH3_BUSV,
    INA3221_REG_CH1_CRIT_ALERT_LIM,
    INA3221_REG_CH1_WARNING_ALERT_LIM,
    INA3221_REG_CH2_CRIT_ALERT_LIM,
    INA3221_REG_CH2_WARNING_ALERT_LIM,
    INA3221_REG_CH3_CRIT_ALERT_LIM,
    INA3221_REG_CH3_WARNING_ALERT_LIM,
    INA3221_REG_SHUNTV_SUM,
    INA3221_REG_SHUNTV_SUM_LIM,
    INA3221_REG_MASK_ENABLE,
    INA3221_REG_PWR_VALID_HI_LIM,
    INA3221_REG_PWR_VALID_LO_LIM,
    INA3221_REG_MANUF_ID = 0xFE,
    INA3221_REG_DIE_ID = 0xFF
} ina3221_reg_t;

// Conversion times
typedef enum {
    INA3221_REG_CONF_CT_140US = 0,
    INA3221_REG_CONF_CT_204US,
    INA3221_REG_CONF_CT_332US,
    INA3221_REG_CONF_CT_588US,
    INA3221_REG_CONF_CT_1100US,
    INA3221_REG_CONF_CT_2116US,
    INA3221_REG_CONF_CT_4156US,
    INA3221_REG_CONF_CT_8244US
} ina3221_conv_time_t;

// Averaging modes
typedef enum {
    INA3221_REG_CONF_AVG_1 = 0,
    INA3221_REG_CONF_AVG_4,
    INA3221_REG_CONF_AVG_16,
    INA3221_REG_CONF_AVG_64,
    INA3221_REG_CONF_AVG_128,
    INA3221_REG_CONF_AVG_256,
    INA3221_REG_CONF_AVG_512,
    INA3221_REG_CONF_AVG_1024
} ina3221_avg_mode_t;

typedef struct Beastdevices_INA3221 {
    ina3221_addr_t i2c_addr; /**< I2C address */
    I2CDriver *i2cd; /**< I2C driver */
    uint32_t shuntRes[INA3221_CH_NUM]; /**< Shunt resistance in mOhm */
    uint32_t filterRes[INA3221_CH_NUM]; /**< Series filter resistance in Ohm */
} ina3221_t;

// Gets a register value.
uint16_t INA3221_getReg(ina3221_t * ina, const ina3221_reg_t reg);

// Resets INA3221
void INA3221_reset(ina3221_t * ina);

// Sets operating mode to power-down
void INA3221_setModePowerDown(ina3221_t * ina);

// Sets operating mode to continious
void INA3221_setModeContinious(ina3221_t * ina);

// Sets operating mode to triggered (single-shot)
void INA3221_setModeTriggered(ina3221_t * ina);

// Enables shunt-voltage measurement
void INA3221_setShuntMeasEnable(ina3221_t * ina);

// Disables shunt-voltage mesurement
void INA3221_setShuntMeasDisable(ina3221_t * ina);

// Enables bus-voltage measurement
void INA3221_setBusMeasEnable(ina3221_t * ina);

// Disables bus-voltage measureement
void INA3221_setBusMeasDisable(ina3221_t * ina);

// Sets averaging mode. Sets number of samples that are collected
// and averaged togehter.
void INA3221_setAveragingMode(ina3221_t * ina, ina3221_avg_mode_t mode);

// Sets bus-voltage conversion time.
void INA3221_setBusConversionTime(ina3221_t * ina, ina3221_conv_time_t convTime);

// Sets shunt-voltage conversion time.
void INA3221_setShuntConversionTime(ina3221_t * ina, ina3221_conv_time_t convTime);

// Sets power-valid upper-limit voltage. The power-valid condition
// is reached when all bus-voltage channels exceed the value set.
// When the powervalid condition is met, the PV alert pin asserts high.
void INA3221_setPwrValidUpLimit(ina3221_t * ina, int16_t voltagemV);

// Sets power-valid lower-limit voltage. If any bus-voltage channel drops
// below the power-valid lower-limit, the PV alert pin pulls low.
void INA3221_setPwrValidLowLimit(ina3221_t * ina, int16_t voltagemV);

// Sets the value that is compared to the Shunt-Voltage Sum register value
// following each completed cycle of all selected channels to detect
// for system overcurrent events.
void INA3221_setShuntSumAlertLimit(ina3221_t * ina, int32_t voltagemV);

// Sets the current value that is compared to the sum all currents.
// This function is a helper for setShuntSumAlertLim(). It onverts current
// value to shunt voltage value.
void INA3221_setCurrentSumAlertLimit(ina3221_t * ina, int32_t currentmA);

// Enables warning alert latch.
void INA3221_setWarnAlertLatchEnable(ina3221_t * ina);

// Disables warning alert latch.
void INA3221_setWarnAlertLatchDisable(ina3221_t * ina);

// Enables critical alert latch.
void INA3221_setCritAlertLatchEnable(ina3221_t * ina);

// Disables critical alert latch.
void INA3221_setCritAlertLatchDisable(ina3221_t * ina);

// Reads flags from Mask/Enable register.
// When Mask/Enable register is read, flags are cleared.
// Use getTimingCtrlAlertFlag(), getPwrValidAlertFlag(),
// getCurrentSumAlertFlag() and getConvReadyFlag() to get flags after
// readFlags() is called.
void INA3221_readFlags(ina3221_t * ina);

// Gets timing-control-alert flag indicator.
bool INA3221_getTimingCtrlAlertFlag(void);

// Gets power-valid-alert flag indicator.
bool INA3221_getPwrValidAlertFlag(void);

// Gets summation-alert flag indicator.
bool INA3221_getCurrentSumAlertFlag(void);

// Gets Conversion-ready flag.
bool INA3221_getConversionReadyFlag(void);

// Gets manufacturer ID.
// Should read 0x5449.
uint16_t INA3221_getManufID(ina3221_t * ina);

// Gets die ID.
// Should read 0x3220.
uint16_t INA3221_getDieID(ina3221_t * ina);

// Enables channel measurements
void INA3221_setChannelEnable(ina3221_t * ina, ina3221_ch_t channel);

// Disables channel measurements
void INA3221_setChannelDisable(ina3221_t * ina, ina3221_ch_t channel);

// Sets warning alert shunt voltage limit
void INA3221_setWarnAlertShuntLimit(ina3221_t * ina, ina3221_ch_t channel, int32_t voltageuV);

// Sets critical alert shunt voltage limit
void INA3221_setCritAlertShuntLimit(ina3221_t * ina, ina3221_ch_t channel, int32_t voltageuV);

// Sets warning alert current limit
void INA3221_setWarnAlertCurrentLimit(ina3221_t * ina, ina3221_ch_t channel, int32_t currentmA);

// Sets critical alert current limit
void INA3221_setCritAlertCurrentLimit(ina3221_t * ina, ina3221_ch_t channel, int32_t currentmA);

// Includes channel to fill Shunt-Voltage Sum register.
void INA3221_setCurrentSumEnable(ina3221_t * ina, ina3221_ch_t channel);

// Excludes channel from filling Shunt-Voltage Sum register.
void INA3221_setCurrentSumDisable(ina3221_t * ina, ina3221_ch_t channel);

// Gets shunt voltage in uV.
int32_t INA3221_getShuntVoltage(ina3221_t * ina, ina3221_ch_t channel);

// Gets warning alert flag.
bool INA3221_getWarnAlertFlag(ina3221_t * ina, ina3221_ch_t channel);

// Gets critical alert flag.
bool INA3221_getCritAlertFlag(ina3221_t * ina, ina3221_ch_t channel);

// Estimates offset voltage added by the series filter resitors
int32_t INA3221_estimateOffsetVoltage(ina3221_t * ina, ina3221_ch_t channel, uint32_t busVoltage);

// Gets current in A.
int32_t INA3221_getCurrent(ina3221_t * ina, ina3221_ch_t channel);

// Gets current compensated with calculated offset voltage.
int32_t INA3221_getCurrentCompensated(ina3221_t * ina, ina3221_ch_t channel);

// Gets bus voltage in V.
uint32_t INA3221_getVoltage(ina3221_t * ina, ina3221_ch_t channel);

#endif