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.