add NUT Network UPS Tools

[mstormi]

Looking for anyone to provide NUT templates and menu-driven configuration to add a Uninterruptible Power Supply to an openHABian system, be it a RPi HAT (like Waveshare) or an external UPS to communicate to via serial or IP.
Primary demand is to properly shut down openHABian to save ZRAM contents to disk in case of an ongoing power outage.

[rkoshak]

Starting some preliminary searching and the Waveshare UPS HAT is not supported by NUT as far as I can tell. BUT does have an I2C driver but it's not clear whether it will work out of the box or not. I can't find anything that mentions Waveshare and NUT on the same page.

Is this worth doing if we only support configuration of a couple of UPS devices? I can't afford to be buying dozens of these things to see if I can make them work. I have one Cyberpower UPS that I can test with and I'll try to find one or two HATs that NUT supports.

I also won't have as whole lot of time to devote to this in the immediate future but I'm willing to take a stab at it if no one else steps up.

[florian-h05]

Maybe I can provide my configuration files, I have a UPS attached to my Pi.

I have an Eaton 3S 700, currently attached to my Synology NAS and connected to the Pi with IP.
But in the past I also had that UPS attached directly to my Pi with USB.

Generally, there is not much difference in the configuration between using an USB UPS or one over IP (as long as nut is used).

I think the USB configuration should work for most people out of the box, port selection can be done automatically. (I haven‘t tested how this works with multiple USB devices attached, I only had the UPS attached).

[rkoshak]

I think the USB configuration should work for most people out of the box, port selection can be done automatically. (I haven‘t tested how this works with multiple USB devices attached, I only had the UPS attached).

All that's true but the driver selection can't as far as I'm aware and that's the major point I'm concerned with. There's a bunch of drivers and you have to look your UPS up in their big database to see which one is the correct driver for your UPS. Then you have special configuration parameters for each driver.

Once the right driver is selected and configured it's smooth sailing. Maybe we just leave driver selection and configuration as an exercise for the end user, though that's the most complicated part so that feels unsatisfactory. Here's the hardware compatibility list: https://networkupstools.org/stable-hcl.html. Notice the right hand column. If you click on one of the drivers listed there, you can see the extra configuration parameters for that driver.

And of course, the hardware list is not complete. 😭

[florian-h05]

I just checked your link, and unfortunately you are right, there‘s no auto driver selection.

Once the right driver is selected and configured it's smooth sailing. Maybe we just leave driver selection and configuration as an exercise for the end user, though that's the most complicated part so that feels unsatisfactory. Here's the hardware compatibility list: https://networkupstools.org/stable-hcl.html. Notice the right hand column. If you click on one of the drivers listed there, you can see the extra configuration parameters for that driver.

I think that there is no other way than leaving driver selection and configuration to the user. Even though that doesn‘t feel good, I can‘t think of a different solution due to the large number of different drivers. We have to link to this page https://networkupstools.org/stable-hcl.html from the setup wizard and let the user type his ups configuration.

But adding Network UPS Tools would help anyway, as the user wouldn‘t have to configure upssched and upsmon and the other stuff.

What do you think? @mstormi

[mstormi]

Do you think it's possible to provide configs for the 2,3 most popular UPS ? One HAT based (Waveshare?) and one or two external units (the cheapmost APC to have serial? what else?)

[florian-h05]

You mean providing multiple configs the user can choose between in the install wizard?

This should be possible.

For most USB UPS (most Eaton, all MGE, all Dell, some/most APC) the usbhid-ups driver should work (select Connection: USB at https://networkupstools.org/stable-hcl.html to have a view).

For serial UPS, there is no driver that supports such a large amount of the UPSes as usbhid-ups does for USB UPS, but mge-shut seems to support most (Eaton, MGE, Dell).
Regarding APC serial, they all require different drivers/confgurations.

Waveshare doesn‘t seem to work with nut, sorry.

[rkoshak]

Waveshare doesn‘t seem to work with nut, sorry.

It might. Waveshare uses I2C and there is an I2C driver. But without one to test with I can't say for sure it will work. I suspect I2C might be the most common protocol for UPS HATs though. It makes a lot of sense to do it that way. You're already occupying the GPIO pins for it, why force the user to also plug in a USB?

usbhid-ups also works with some CyberPower UPS (it works with my CP1500AVRLCD at least) so it's a great choice. I'd probably offer that and up to three others, including the I2C driver (assuming it actually works with the Waveshare which I need to purchase to verify). We can offer an "other" option that skips setting up any driver and direct the user to some docs on how to choose and configure the driver.

[mstormi]

Waveshare uses I2C and there is an I2C driver. But without one to test with I can't say for sure it will work.

I have one in my production RPi so will be happy to test. I believe there's already options in openHABian to enable the i2c port.

[rkoshak]

There's a good tutorial on how to set it up by hand at https://community.openhab.org/t/beginners-guide-to-network-ups-tools-nut-on-a-raspberry-pi/78443. But we don't need to go through all that just to see if it works.

I think you just need to:

• enable the I2C interface on the RPi
• Install nut using sudo apt install nut
• Open /etc/nut/ups.conf and add a config for the UPS. This is where it gets interesting.
• First we can try to set up the asem driver. I actually don't have much hope that it'll work but it's worth a shot.
• You can tell if it works through the command sudo upsdrvctl start. There will be errors if it doesn't work.

If that doesn't work it would seem that I was wrong. I thought that I read that there is a generic I2C driver but I can't find it and looking through the issues on NUT shows that asem is the only one right now. There is a driver for the PiJuice HAT though but I'm not sure that helps us.

But it seems like we aught to be able to set something up ourselves (see the "RaspberryPi Demo" section https://www.waveshare.com/wiki/UPS_HAT) outside of NUT for this device. Or, if we are really motivated we could submit a new driver for it to the NUT project using the asem driver as a template.

[florian-h05]

I think that I can open a PR to add nut with the usbhid-ups driver (I can test this one) and the mge-shut driver for serial (I can‘t test this, but if I remember right and it requires no special conf, I would add it).

Thanks for the I2C guide Richard.
Regarding Waveshare and I2C, I don‘t have any plans to work on this in my PR; it should be better if @mstormi adds the I2C for Waveshare because he can test it.

[rkoshak]

I'm not sure if it's helpful or not, but here is my Ansible playbook that configures my nut server for my CyberPower CP1500AVRLCD using usbhid-ups.

---
# tasks file for roles/nut-server

- name: Install the NUT server
  apt:
    name: [nut, nut-client, nut-server]
    update_cache: False
  become: True
#  notify:  # Didn't work, it's a problem when run from same machine, we can't reboot.
#  - Reboot if changed

# handler is defined in minwrites

- name: Configure NUT for the CyberPower CP1500AVRLCD
  ini_file:
    path: /etc/nut/ups.conf
    state: present
    section: ups
    option: "{{ item.option }}"
    value: "{{ item.value }}"
  loop:
    - { "option": "driver", "value": "usbhid-ups" }
    - { "option": "port", "value": "auto" }
    - { "option": "desc", "value": "\"CyberPower CP1500AVRLCD\"" }
    - { "option": "pollinterval", "value": "15" }
  become: True
  notify:
    - Cycle the NUT services

- name: Update upsd.conf
  blockinfile:
    path: /etc/nut/upsd.conf
    block: |
      LISTEN 127.0.0.1 3493
      LISTEN {{ nutserver_ip }}
      MAXAGE 25
  become: True
  notify:
    - Cycle the NUT services

- name: Set up the NUT users
  template:
    dest: /etc/nut/upsd.users
    mode: u=rw,g=r
    owner: root
    group: nut
    src: upsd.users
  become: True
  notify:
    - Cycle the NUT services

- name: Configure the server to run
  lineinfile:
    backrefs: True
    line: MODE=netserver
    path: /etc/nut/nut.conf
    regexp: '^MODE=.*'
    state: present
  become: True
  notify:
    - Cycle the NUT services

The "Cycle the nut services" handler is

---
# handlers file for roles/nut-server

- name: Cycle the NUT services
  systemd:
    name: "{{ item }}"
    state: restarted
    daemon_reload: True
    enabled: True
  loop:
    - nut-driver
    - nut-server
    - nut-monitor
  become: True
#  when: (not nut_installed.changed)

Setting up the client:

---
# tasks file for roles/nut-client

- name: Install and configure the nut client
  block:
    - name: Install nut
      apt:
        name: nut
        update_cache: no

    - name: Set up the NUT client
      blockinfile:
        path: /etc/nut/upsmon.conf
        block: |
          MONITOR {{ nut_server }} 1 {{ nut_monuser }} {{ nut_monpass }} slave
          DEADTIME 25
          NOTIFYFLAG ONLINE     SYSLOG+WALL+EXEC
          NOTIFYFLAG ONBATT     SYSLOG+WALL+EXEC
          NOTIFYFLAG LOWBATT    SYSLOG+WALL+EXEC
          NOTIFYFLAG FSD        SYSLOG+WALL+EXEC
          NOTIFYFLAG COMMOK     SYSLOG+WALL+EXEC
          NOTIFYFLAG COMMBAD    SYSLOG+WALL+EXEC
          NOTIFYFLAG SHUTDOWN   SYSLOG+WALL+EXEC
          NOTIFYFLAG REPLBATT   SYSLOG+WALL+EXEC
          NOTIFYFLAG NOCOMM     SYSLOG+WALL+EXEC
          NOTIFYFLAG NOPARENT   SYSLOG+WALL
      register: nutclientconf

    - name: Set the nut mode to netclient
      lineinfile:
        path: /etc/nut/nut.conf
        regexp: '^MODE='
        line: MODE=netclient
      register: nutmode

    - name: Cycle the service
      systemd:
        name: nut-monitor
        state: restarted
      when: nutclientconf.changed or nutmode.changed

  become: true

The client part gets run on all the machines powered by the UPS. The server part only on the machine connected to the UPS itself. I need to spend some time merging these two separate roles but for now they are separate.

[florian-h05]

The Ansible Playbook is a little bit helpful, but I already have my nut conf.
In openHABian, I think we would include all of our nut config files and copy them to the /etc/nut instead of modifying the pre-installed files. That‘s at least the way I think it goes.

[mstormi]

it should be better if @mstormi adds the I2C for Waveshare because he can test it

No sorry I'm busy so all I can offer to contribute is some testing.

[mstormi]

See https://community.openhab.org/t/waveshare-ups-hat-b-python-script-values-display-in-openhab/137886/8

[rkoshak]

I've seen that post and others for Waveshare. I'm left a little wary by the fact that it publishes to OH's REST API to Item names that are known and configured ahead of time. That makes it challenging to add to openHABian I would think, at least in a satisfactory way. It also doesn't do anything to get Waveshare into NUT.

I don't see a generic I2C add-on though several add-ons do support I2C. It might be relatively simply to add a new Waveshare binding or add Waveshare support to the NUT binding, making it expand beyond NUT.

I'm just thinking out loud here.

I just saw https://community.openhab.org/t/geekworm-x728-ups-hat-for-raspberry-pi-over-mqtt/139144. Maybe a simple service that publishes the I2C stuff to MQTT topics would be the way to go. That's simple enough and generic enough. If we follow a standard you could even make them autodiscoverable. Would that be a different issue though?

[florian-h05]

I read a little bit about nut and the Waveshare UPS HAT.
For the Waveshare, we should use the provided Python script from Waveshare, instead of trying anything to make it compatible to nut.
Therefore, nut and Waveshare are two different thing, so I will definitely split those up in two PRs.
I am currently planning to contribute for both, but I need to find the time to so it might take a while to get those two PRs. The PR for nut should be the faster, as I have some experience with nut.

[florian-h05]

@mstormi FYI: I finally started on implementing the nut installation!

Network UPS Tools PR is open: #1759.

[mstormi]

The waveshare python utility and proper i2c config are already part of openHABian.

I've never messed with getting nut to work so you that did will probably be able to get integration of that script done faster than myself. As promised I'd be willing to test any setup.
So any takers ?
Below's the utility output (it keeps producing quad-line output every 2 seconds but I guess you could also fairly simple rewrite it to offer one-shot usage).

admin@mysmarthouse:~ $ python3 /opt/openhabian/includes/INA219.py
Load Voltage:   7.960 V
Current:        0.000000 A

Power:          0.000 W
Percent:       81.7%

Load Voltage:   8.008 V
Current:        0.000000 A
Power:          0.000 W
Percent:       83.7%

[mstormi]

@Larsen-Locke you mentioned you own a Waveshare UPS, too. Would you be willing to have a look at implementing this ?

[Larsen-Locke]

I was thinking about that too, but two problems stopped me:

The different Debian versions need different methods of installation (e.g. different installation of i2c, different requirements for Python libraries). Developing, testing and supporting that is a nightmare (you know the complainers;). As a solution we could restrict the functionality for installations with bookworm and above.

Second: My solution uses a Python script from the Internet. We would have to get permission from the author to use it. I have no idea how this works without legal risks.

[mstormi]

As a solution we could restrict the functionality for installations with bookworm and above.

That's totally fine.

We would have to get permission from the author to use it.

Would we, is there any such copyright or licensing mentioned ? If so why not simply ask him ?

[Larsen-Locke]

What a coincidence. That's what I did.

edit:
I compared the script with the demo from waveshare and they seem to be the same with one additional command for shutting down if under 30%.

[Larsen-Locke]

Why is waveshare only providing a demo and no complete solution?
I guess they don't want to be held responsible for any incidents with Li-Ion-cells. The waveshare UPS is without cells, so you have no control what users might put in: e.g. NCA-cells, old cells, mixtures of cells. Some people handle 18650-cells just like normal rechargeable batteries but they're not ...

The more I think about it the more I don't feel comfortable with the idea....

[mstormi]

• You can tell if it works through the command sudo upsdrvctl start

It doesn't with asem, seems that's no longer part of at least a standard linux nut pkg.

@Larsen-Locke have you had another look at integrating via Python script ?

[Larsen-Locke]

no, actually I don't even use the script myself anymore. The only function I need is to cover some minutes when there is no power. The hardware connection is enough for that.
But it's not difficult: I2C has to be enabled within raspi-config and the script has to be installed as a service. If somebody wants to jump in I can send the files.