Skip to content

Commit

Permalink
improve API + documentation (#12)
Browse files Browse the repository at this point in the history 
- add **bool setBusResolution(bits)**
- add **bool setBusSamples(value)**
- add **bool setShuntResolution(bits)**
- add **bool setShuntSamples(value)**
- improve error checking several functions
  - calls to **writeRegister()** should return 0.
  - error handling needs improvement, this is a first step.
- improve **INA219_get_settings.ino**
- update keywords.txt
- update readme.md
  • Loading branch information
@RobTillaart
RobTillaart authored Jan 18, 2024
1 parent 7fa38ef commit 5af0714
Show file tree
Hide file tree
Showing 13 changed files with 263 additions and 82 deletions.
13 changes: 13 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,19 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
and this project adheres to [Semantic Versioning](http://semver.org/).


## [0.2.1] - 2024-01-17
- add **bool setBusResolution(bits)**
- add **bool setBusSamples(value)**
- add **bool setShuntResolution(bits)**
- add **bool setShuntSamples(value)**
- improve error checking several functions
- calls to **writeRegister()** should return 0.
- error handling needs improvement, this is a first step.
- improve **INA219_get_settings.ino**
- update keywords.txt
- update readme.md


## [0.2.0] - 2023-12-04
- Fix #8, refactor API - support ESP32-S3
- update readme.md
Expand Down
120 changes: 93 additions & 27 deletions INA219.cpp
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// FILE: INA219.h
// AUTHOR: Rob Tillaart
// VERSION: 0.2.0
// VERSION: 0.2.1
// DATE: 2021-05-18
// PURPOSE: Arduino library for INA219 voltage, current and power sensor
// URL: https://github.com/RobTillaart/INA219
Expand Down Expand Up @@ -124,15 +124,16 @@ bool INA219::getConversionFlag()
//
// CONFIGURATION
//
void INA219::reset()
bool INA219::reset()
{
uint16_t config = _readRegister(INA219_CONFIGURATION);
config |= 0x8000;
_writeRegister(INA219_CONFIGURATION, config);
uint16_t wrrv = _writeRegister(INA219_CONFIGURATION, config);
// reset calibration
_current_LSB = 0;
_maxCurrent = 0;
_shunt = 0;
return (wrrv == 0);
}


Expand All @@ -144,8 +145,9 @@ bool INA219::setBusVoltageRange(uint8_t voltage)
uint16_t config = _readRegister(INA219_CONFIGURATION);
config &= ~INA219_CONF_BUS_RANGE_VOLTAGE;
if (voltage == 32) config |= INA219_CONF_BUS_RANGE_VOLTAGE;
_writeRegister(INA219_CONFIGURATION, config);
return true;

uint16_t wrrv = _writeRegister(INA219_CONFIGURATION, config);
return (wrrv == 0);
}


Expand All @@ -168,8 +170,9 @@ bool INA219::setGain(uint8_t factor)
if (factor == 2) config |= (1 << 11);
else if (factor == 4) config |= (2 << 11);
else if (factor == 8) config |= (3 << 11);
_writeRegister(INA219_CONFIGURATION, config);
return true;

uint16_t wrrv = _writeRegister(INA219_CONFIGURATION, config);
return (wrrv == 0);
}


Expand All @@ -184,21 +187,49 @@ uint8_t INA219::getGain()
}


////////////////////////////////////////////////////////
//
// BUS
//
bool INA219::setBusResolution(uint8_t bits)
{
if ((bits < 9) || (bits > 12)) return false;
bits -= 9;

uint16_t config = _readRegister(INA219_CONFIGURATION);
config &= ~INA219_CONF_BUS_ADC;
config |= (bits << 7);

uint16_t wrrv = _writeRegister(INA219_CONFIGURATION, config);
return (wrrv == 0);
}


// value = 0..7, always 12 bit resolution,
bool INA219::setBusSamples(uint8_t value)
{
if (value > 7) return false;
value |= 8;

uint16_t config = _readRegister(INA219_CONFIGURATION);
config &= ~INA219_CONF_BUS_ADC;
config |= (value << 7);

uint16_t wrrv = _writeRegister(INA219_CONFIGURATION, config);
return (wrrv == 0);
}


bool INA219::setBusADC(uint8_t mask)
{
if (mask > 0x0F) return false;

// TODO improve this one. datasheet.
// two functions
// setBusResolution + setBusSamples()
uint16_t config = _readRegister(INA219_CONFIGURATION);
config &= ~INA219_CONF_BUS_ADC;
config |= (mask << 7);
// if (bits == 10) config |= (1 << 7);
// else if (bits == 11) config |= (2 << 7);
// else if (bits == 12) config |= (3 << 7);
_writeRegister(INA219_CONFIGURATION, config);
return true;

uint16_t wrrv = _writeRegister(INA219_CONFIGURATION, config);
return (wrrv == 0);
}


Expand All @@ -210,18 +241,49 @@ uint8_t INA219::getBusADC()
}


////////////////////////////////////////////////////////
//
// SHUNT
//
bool INA219::setShuntResolution(uint8_t bits)
{
if ((bits < 9) || (bits > 12)) return false;
bits -= 9;

uint16_t config = _readRegister(INA219_CONFIGURATION);
config &= ~INA219_CONF_SHUNT_ADC;
config |= (bits << 3);

uint16_t wrrv = _writeRegister(INA219_CONFIGURATION, config);
return (wrrv == 0);
}


// value = 0..7, always 12 bit resolution,
bool INA219::setShuntSamples(uint8_t value)
{
if (value > 7) return false;
value |= 8;

uint16_t config = _readRegister(INA219_CONFIGURATION);
config &= ~INA219_CONF_SHUNT_ADC;
config |= (value << 3);

uint16_t wrrv = _writeRegister(INA219_CONFIGURATION, config);
return (wrrv == 0);
}


bool INA219::setShuntADC(uint8_t mask)
{
if (mask > 0x0F) return false;

// TODO improve this one. datasheet.
// two functions
// setShuntResolution + setShuntSamples()
uint16_t config = _readRegister(INA219_CONFIGURATION);
config &= ~INA219_CONF_SHUNT_ADC;
config |= (mask << 3);
_writeRegister(INA219_CONFIGURATION, config);
return true;

uint16_t wrrv = _writeRegister(INA219_CONFIGURATION, config);
return (wrrv == 0);
}


Expand All @@ -233,14 +295,19 @@ uint8_t INA219::getShuntADC()
}


////////////////////////////////////////////////////////
//
// MODE
//
bool INA219::setMode(uint8_t mode)
{
if (mode > 7) return false;
uint16_t config = _readRegister(INA219_CONFIGURATION);
config &= ~INA219_CONF_MODE;
config |= mode;
_writeRegister(INA219_CONFIGURATION, config);
return true;

uint16_t wrrv = _writeRegister(INA219_CONFIGURATION, config);
return (wrrv == 0);
}


Expand All @@ -258,7 +325,7 @@ uint8_t INA219::getMode()
//
bool INA219::setMaxCurrentShunt(float maxCurrent, float shunt)
{
// #define printdebug
// #define PRINTDEBUG
uint16_t calib = 0;

if (maxCurrent < 0.001) return false;
Expand All @@ -269,10 +336,9 @@ bool INA219::setMaxCurrentShunt(float maxCurrent, float shunt)
_maxCurrent = maxCurrent;
_shunt = shunt;
calib = round(0.04096 / (_current_LSB * shunt));
_writeRegister(INA219_CALIBRATION, calib);

uint16_t wrrv = _writeRegister(INA219_CALIBRATION, calib);

#ifdef printdebug
#ifdef PRINTDEBUG
Serial.println();
Serial.print("current_LSB:\t");
Serial.print(_current_LSB, 8);
Expand All @@ -288,7 +354,7 @@ bool INA219::setMaxCurrentShunt(float maxCurrent, float shunt)
Serial.println(" ohm Ω");
#endif

return true;
return (wrrv == 0);
}


Expand Down
23 changes: 16 additions & 7 deletions INA219.h
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,19 @@
#pragma once
// FILE: INA219.h
// AUTHOR: Rob Tillaart
// VERSION: 0.2.0
// VERSION: 0.2.1
// DATE: 2021-05-18
// PURPOSE: Arduino library for INA219 voltage, current and power sensor
// URL: https://github.com/RobTillaart/INA219
//
// Read the datasheet for the details how to connect!
//


#include "Arduino.h"
#include "Wire.h"


#define INA219_LIB_VERSION (F("0.2.0"))
#define INA219_LIB_VERSION (F("0.2.1"))


class INA219
Expand Down Expand Up @@ -52,17 +51,26 @@ class INA219

// CONFIGURATION
// need improvement API wise.
void reset();
bool reset();
// voltage = 16, 32 (values below 32 are rounded to 16 or 32)
bool setBusVoltageRange(uint8_t voltage = 16);
uint8_t getBusVoltageRange(); // returns 16 or 32.
// factor = 1, 2, 4, 8
bool setGain(uint8_t factor = 1);
uint8_t getGain();
// mask
bool setBusADC(uint8_t mask = 0x03);

// configuration BUS
// use one of the next three
bool setBusResolution(uint8_t bits); // 9..12, always 1 sample
bool setBusSamples(uint8_t value); // 0..7, always 12 bits.
bool setBusADC(uint8_t mask = 0x03); // uses a mask, check datasheet
uint8_t getBusADC();
bool setShuntADC(uint8_t mask = 0x03);

// configuration SHUNT
// use one of the next three
bool setShuntResolution(uint8_t bits); // 9..12, always 1 sample
bool setShuntSamples(uint8_t value); // 0..7, always 12 bits.
bool setShuntADC(uint8_t mask = 0x03); // uses a mask, check datasheet
uint8_t getShuntADC();

// Operating mode = 0..7
Expand Down Expand Up @@ -103,6 +111,7 @@ class INA219

uint16_t _readRegister(uint8_t reg);
uint16_t _writeRegister(uint8_t reg, uint16_t value);

float _current_LSB;
float _shunt;
float _maxCurrent;
Expand Down
2 changes: 1 addition & 1 deletion LICENSE
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
MIT License

Copyright (c) 2021-2023 Rob Tillaart
Copyright (c) 2021-2024 Rob Tillaart

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
Loading

0 comments on commit 5af0714

Please sign in to comment.