Arduino library for the I2C INA3221 3 channel voltage and current sensor.
Experimental library for the I2C INA3221. ==> USE WITH CARE
The INA3221 is a 3 channel measuring device to measure voltage. Derived from that voltage and a given shunt, the library calculates current (amperes) and power (watts).
The measurements runs in the background processing the two voltages per channel. (continuous mode assumed). When a measurement is ready the measured value is stored in the appropriate (channel) register. Then the next channel / voltage is measured. As channels can be disabled, the timing of processing / updates per channels might differ.
The core functions read from the (channel) registers, so they are never blocked. They can however return the same value if no new data is available yet.
Some important maxima, see datasheet for all details.
description | max | unit | notes |
---|---|---|---|
channels | 3 | ||
bus voltage | 26 | Volt | unclear for how long. |
shunt voltage | 163 | mVolt | at 0.1 Ohm |
shunt R | 100 | mOhm | typical |
current | 1.63 | Ampere | I = U/R |
Renamed setCriticalCurrect() ==> setCriticalCurrent() to fix typo.
Several functions have been reimplemented after issue #2. This makes pre 0.2.0 versions obsolete.
==> USE WITH CARE
Only tested partially with an Arduino UNO.
Not all functionality is tested and investigated with hardware.
Another point to be tested and verified is negative values in registers.
Read datasheet for details.
As always feedback is welcome, please open an issue on GitHub.
The sensor can have 4 different I2C addresses, which depends on how the A0 address line is connected to the SCL, SDA, GND and VCC pins.
A0 | DEC | HEX | Notes |
---|---|---|---|
GND | 64 | 0x40 | not connected seems to choose this one too. |
VS | 65 | 0x41 | |
SDA | 66 | 0x42 | |
SCL | 67 | 0x43 |
See datasheet - table 1, page 20 - datasheet.
(From Datasheet) The INA3221 supports the transmission protocol for fast mode (1 kHz to 400 kHz) and high-speed mode (1 kHz to 2.94 MHz). All data bytes are transmitted most significant byte first.
(timing in us, Arduino UNO),
indicative by example INA3221_performance.ino
Four most important calls.
Clock | bus V | shunt V | mA | mW |
---|---|---|---|---|
100000 | 568 | 568 | 584 | 1152 |
100000 | 324 | 328 | 340 | 672 |
100000 | 236 | 236 | 260 | 504 |
100000 | 200 | 200 | 220 | 428 |
#include "INA3221.h"
All parameters channels are zero based => so numbered 0 , 1 or 2. Using channels > 2 are not handled (correctly).
Note the power and the current are not meaningful without calibrating the sensor. Also the value is not meaningful if there is no shunt connected.
The parameter channel should always be 0..2
The library has wrapper functions to convert above output to a more appropriate scale of units.
Wrapper functions for the milli scale.
Wrapper functions for the micro scale.
The shunt resistor is typical in the order of 0.100 Ohm.
(not tested) Read datasheet!
The user is responsible to be sure that the critical value >= warning value if he decides to use both. If only one of the two is used, critical might be less than warning.
The parameter channel should always be 0..2
The parameter microVolt should not exceed 163800 µV, will return error -2. NOTE: LSB = 40 uV so microVolt should be >= 40uV
Wrappers using milliAmpere (assuming Shunt is set correctly!). These are often more intuitive from user perspective. NOTE: LSB = 40 uV so milliAmpere should be >= 0.4 mA (assume Shunt = 0.1 Ohm)
(not tested) Read datasheet!
(partially tested) Read datasheet for bit pattern of the mask.
Setting all bits at once with a mask is faster, atomic and uses less code.
The library also provides getters and setters per field.
Average | # samples | notes |
---|---|---|
0 | 1 | default |
1 | 4 | |
2 | 16 | |
3 | 64 | |
4 | 128 | |
5 | 256 | |
6 | 512 | |
7 | 1024 |
BVCT SVCT | time | notes |
---|---|---|
0 | 140 us | |
1 | 204 us | |
2 | 332 us | |
3 | 588 us | |
4 | 1.1 ms | default |
5 | 2.1 ms | |
6 | 4.2 ms | |
7 | 8.3 ms |
Note: times are typical, check datasheet for operational range. (max can be ~10% higher)
Note: In combination with average the total conversion time can take up to 1024 x 8.3 ms almost 9 seconds (+ 10% deviation ==> 10 seconds)
(not tested) See datasheet!
Mode = 4 is not used, is also a shutdown() unknown if there is a difference with mode == 0. The underlying bit pattern (not used).
bit | value | description |
---|---|---|
0 | 0x01 | shunt bit on (0x01) / off (0x00) |
1 | 0x02 | bus bit on (0x02) / off (0x00) |
2 | 0x04 | continuous (0x04) / one shot (0x00) bit. |
Descriptive mode functions (convenience wrappers).
(not tested) See datasheet!
Setting all bits at once with a mask is faster, atomic and uses less code.
TODO: convenience wrappers
(not tested) See datasheet!
To guard the BUS voltage, max value 32760
(tested)
If you appreciate my libraries, you can support the development and maintenance. Improve the quality of the libraries by providing issues and Pull Requests, or donate through PayPal or GitHub sponsors.
Thank you,