Merge pull request #2430 from jviki/hwmon-ina219

New driver hwmon_ina219

NEWS.adoc

@@ -84,6 +84,13 @@ https://github.com/networkupstools/nut/milestone/11
    reading an empty string or getting a success code `0` from libusb.
    This difference should now be better logged, and not into syslog. [#2399]
 
+ - Introduced a new driver concept for interaction with OS-reported hardware
+   monitoring readings. Currently instantiated as `hwmon_ina219` specifically
+   made for Texas Instruments INA219 chip as exposed in the Linux "hwmon"
+   subsystem of its "sysfs" interface (and talking I2C under the hood), this
+   approach seems to have good potential to expand into covering more devices
+   and perhaps platforms. [#2430]
+
  - upsmon:
    * it was realized that the `POWERDOWNFLAG` must be explicitly set in the
      configuration file, there is no built-in default in the binary program

data/driver.list.in

@@ -248,7 +248,7 @@
 "Cyber Power Systems"	"ups"	"3"	"CP1350AVRLCD"	"USB"	"usbhid-ups"
 "Cyber Power Systems"	"ups"	"3"	"CP1500AVRLCD"	"USB"	"usbhid-ups"
 "Cyber Power Systems"	"ups"	"3"	"CP850PFCLCD"	"USB"	"usbhid-ups"	# https://github.com/networkupstools/nut/issues/605
-"Cyber Power Systems"	"ups"	"3"	"CP1350PFCLCD"	"USB"	"usbhid-ups"	# https://alioth-lists.debian.net/pipermail/nut-upsuser/2023-October/013441.html 
+"Cyber Power Systems"	"ups"	"3"	"CP1350PFCLCD"	"USB"	"usbhid-ups"	# https://alioth-lists.debian.net/pipermail/nut-upsuser/2023-October/013441.html
 "Cyber Power Systems"	"ups"	"3"	"CP1500PFCLCD"	"USB"	"usbhid-ups"	# https://www.cyberpowersystems.com/product/ups/cp1500pfclcd/ https://github.com/networkupstools/nut/issues/520
 "Cyber Power Systems"	"ups"	"3"	"CPJ500"	"USB"	"usbhid-ups"	# https://www.cyberpower.com/jp/ja/product/sku/cpj500#downloads https://github.com/networkupstools/nut/issues/1403
 "Cyber Power Systems"	"ups"	"3"	"CP900AVR"	"USB"	"usbhid-ups"
@@ -1203,6 +1203,8 @@
 "Tecnoware"	"ups"	"2"	"UPS ERA LCD 0.65"	"USB"	"blazer_usb langid_fix=0x409"
 "Tecnoware"	"ups"	"2"	"UPS ERA PLUS 1100"	"USB"	"blazer_usb"	# https://www.tecnoware.com/Prodotti/FGCERAPL1100/ups-era-plus-1100.aspx https://github.com/networkupstools/nut/issues/747
 
+"Texas Instruments"	"ups"	"5"	"INA219"	"hwmon"	"hwmon_ina219"
+
 "Tripp Lite"	"ups"	"1"	"(various)"	"Lan 2.2 interface - black 73-0844 cable"	"genericups upstype=5"
 "Tripp Lite"	"ups"	"3"	"1500 LCD"	"USB"	"usbhid-ups"
 "Tripp Lite"	"ups"	"3"	"AVR550U"	"USB (protocol 2010)"	"usbhid-ups"	# http://www.tripplite.com/en/products/model.cfm?txtSeriesID=930&txtModelID=3090

docs/man/Makefile.am

@@ -711,17 +711,17 @@ HTML_MODBUS_MANS = phoenixcontact_modbus.html \
 endif ! SOME_DRIVERS
 
 # (--with-linux_i2c)
-SRC_LINUX_I2C_PAGES = asem.txt pijuice.txt
+SRC_LINUX_I2C_PAGES = asem.txt pijuice.txt hwmon_ina219.txt
 if ! SOME_DRIVERS
 if WITH_MANS
-MAN_LINUX_I2C_PAGES = asem.8 pijuice.8
+MAN_LINUX_I2C_PAGES = asem.8 pijuice.8 hwmon_ina219.8
 endif WITH_MANS
 
 if WITH_LINUX_I2C
 man8_MANS += $(MAN_LINUX_I2C_PAGES)
 endif WITH_LINUX_I2C
 
-HTML_LINUX_I2C_MANS = asem.html pijuice.html
+HTML_LINUX_I2C_MANS = asem.html pijuice.html hwmon_ina219.html
 endif ! SOME_DRIVERS
 
 # (--with-gpio)

docs/man/hwmon_ina219.txt

@@ -0,0 +1,141 @@
+HWMON_INA219(8)
+===============
+
+NAME
+----
+
+hwmon_ina219 - driver for UPS based on INA219
+
+SYNOPSIS
+--------
+
+*hwmon_ina219* -h
+
+*hwmon_ina219* -a 'UPS_NAME' ['OPTIONS']
+
+NOTE: This man page only documents the specific features of the *hwmon_ina219*
+driver. For information about the core driver, see linkman:nutupsdrv[8].
+
+The driver implements reading of current and voltage from INA219 by using hwmon
+sysfs API of the Linux Kernel. There is no other UPS-like logic in there. Based
+on the measurements of the battery voltage and charging current, the driver
+makes assumptions of the current state of the system.
+
+SUPPORTED HARDWARE
+------------------
+
+The *hwmon_ina219* driver is based on setup with Raspberry PI Compute Module 4
+and its baseboard Waveshare CM4-POE-UPS-BASE.
+
+EXTRA ARGUMENTS
+---------------
+
+The required parameter for this driver:
+
+*port*='hwmon-dir'::
+Path to appropriate /sys/hwmon/hwmonX or 'auto' to detect automatically.
+
+Optional parameters:
+
+*default.battery.charge.low*='low-battery-threshold'::
+Threshold for low battery state (in percent).
+
+*default.battery.voltage.nominal*='voltage-value'::
+Nominal voltage (V) value of utilised batteries, used to derive their low
+and high watermark settings (see below). Default: 3.6.
++
+Known pre-sets include: `3.6`, `3.7`, `3.8`, `3.85`.
+
+*default.battery.voltage.low*='voltage-value'::
+Low voltage (V) value of used batteries. Practically, it denotes depleted
+batteries. If not given, it is derived from the *battery.voltage.nominal*.
+
+*default.battery.voltage.high*='voltage-value'::
+High voltage (V) value of used batteries. Practically, it denotes fully
+charged batteries. If not given, it is derived from the
+*battery.voltage.nominal*.
+
+INSTALLATION
+------------
+
+This driver is specific to the Linux hwmon API.
+
+When using with the Waveshare CM4-POE-UPS-BASE baseboard, there are few steps
+to be done to enable access to the INA219 circuit:
+
+. edit boot/config.txt:
++
+----
+  dtparam=i2c_vc=on
+  dtoverlay=i2c-ina219
+----
+
+. create a new device tree overlay file i2c-ina219.dts:
++
+----
+/dts-v1/;
+/plugin/;
+
+/ {
+    compatible = "brcm,bcm2835";
+
+    fragment@0 {
+        target = <&i2c_csi_dsi>;
+        __overlay__ {
+            #address-cells = <1>;
+            #size-cells = <0>;
+
+            ina219@43 {
+                status = "okay";
+                compatible = "ti,ina219";
+                reg = <0x43>;
+                shunt-resistor = <100000>;  // R100
+            };
+        };
+    };
+};
+----
+
+. convert i2c-ina219.dts to dtbo and place it into /boot/overlays:
++
+----
+$ dtc -@ -I dts -O dtb -o /boot/overlays/i2c-ina219.dtbo i2c-ina219.dts
+----
+
+. configure hwmon_ina219 UPS driver for NUT (ups.conf):
++
+----
+[ina219]
+driver = hwmon_ina219
+port = auto
+----
+
+KNOWN ISSUES AND BUGS
+---------------------
+
+The driver shutdown function is not implemented.
+
+AUTHORS
+-------
+
+Andrew Anderson <aander07@gmail.com>
+
+SEE ALSO
+--------
+
+The core driver:
+~~~~~~~~~~~~~~~~
+
+linkman:nutupsdrv[8]
+
+Internet resources:
+~~~~~~~~~~~~~~~~~~~
+
+* Initial pull requests adding this driver:
+** https://github.com/networkupstools/nut/pull/2430
+** https://github.com/networkupstools/nut/issues/2378
+
+* Baseboard with INA219: https://www.waveshare.com/wiki/CM4-POE-UPS-BASE
+* TI INA219: https://www.ti.com/lit/ds/symlink/ina219.pdf
+
+* The NUT (Network UPS Tools) home page: https://www.networkupstools.org/

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3132 utf-8
+personal_ws-1.1 en 3148 utf-8
 AAC
 AAS
 ABI
@@ -452,6 +452,7 @@ HUPCL
 HV
 HVT
 HW
+HWMON
 Hajduch
 Hanno
 Harnhammar
@@ -1328,6 +1329,7 @@ WTU
 Waldie
 WantedBy
 WatchdogSec
+Waveshare
 WebFreak
 Werror
 Weverything
@@ -1517,6 +1519,7 @@ baudrate
 baytech
 baz
 bcdDevice
+bcm
 bcmxcp
 bd
 belkin
@@ -1546,6 +1549,7 @@ bootable
 bp
 br
 brazil
+brcm
 brotli
 bsd
 bt
@@ -1669,6 +1673,7 @@ crw
 crypto
 csh
 cshdelay
+csi
 css
 cstdint
 ctime
@@ -1768,13 +1773,20 @@ drvpath
 drwxr
 drwxrwx
 ds
+dsi
 dsr
 dsssl
 dstate
 dt
+dtb
+dtbo
+dtc
 dtds
 dtksh
+dtoverlay
+dtparam
 dtr
+dts
 du
 dumbterm
 dummycons
@@ -1973,6 +1985,8 @@ https
 huawei
 hunnox
 hwdb
+hwmon
+hwmonX
 hypervisor
 hypervisors
 iBox
@@ -2005,6 +2019,7 @@ im
 imagesdir
 img
 imv
+ina
 includePath
 includedir
 inductor
@@ -2827,6 +2842,7 @@ sysV
 syscalls
 sysconfdir
 sysconfig
+sysfs
 syslog
 syslogd
 systemctl

drivers/Makefile.am

@@ -68,7 +68,7 @@ SERIAL_USB_DRIVERLIST = \
 NEONXML_DRIVERLIST = netxml-ups
 MACOSX_DRIVERLIST = macosx-ups
 MODBUS_DRIVERLIST = phoenixcontact_modbus generic_modbus huawei-ups2000 socomec_jbus adelsystem_cbi apc_modbus
-LINUX_I2C_DRIVERLIST = asem pijuice
+LINUX_I2C_DRIVERLIST = asem pijuice hwmon_ina219
 POWERMAN_DRIVERLIST = powerman-pdu
 IPMI_DRIVERLIST = nut-ipmipsu
 GPIO_DRIVERLIST = generic_gpio_libgpiod
@@ -329,6 +329,8 @@ asem_LDADD = $(LDADD_DRIVERS) $(LIBI2C_LIBS)
 asem_SOURCES = asem.c
 pijuice_LDADD = $(LDADD_DRIVERS) $(LIBI2C_LIBS)
 pijuice_SOURCES = pijuice.c
+hwmon_ina219_LDADD = $(LDADD_DRIVERS)
+hwmon_ina219_SOURCES = hwmon_ina219.c
 
 # GPIO drivers
 generic_gpio_libgpiod_SOURCES = generic_gpio_common.c generic_gpio_libgpiod.c