Feature: Add peaNUT Widget

[Brandawg93]

Proposed change

Add support for https://github.com/Brandawg93/PeaNUT.

Type of change

• New service widget
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Documentation only
• Other (please explain)

Checklist:

• If applicable, I have added corresponding documentation changes.
• If applicable, I have reviewed the feature and / or service widget guidelines.
• I have checked that all code style checks pass using pre-commit hooks and linting checks.
• If applicable, I have tested my code for new features & regressions on both mobile & desktop devices, using the latest version of major browsers.

[shamoon]

Ha, recognize you from the homebridge ecosystem 👍

Thanks for the PR. The only thing is, our guidelines require PRs be linked to an open request, I'd be happy to link this to #1317 but do you have any idea what the adoption of your tool is? Again, I'd be fine with it but we've had this kinda thing before and we get a lot of complaints when a widget requires a tool that most people dont have (which TBH, Im guessing is the case here, but I dont know)...

[Brandawg93]

Nice! I guess I have a reputation that precedes me. 😅

Sure. Feel free to link it to #1317. I don't have hard stats on tool adoption, but it's been steadily gaining traction. It was also featured in selfh.st which was pretty neat.

I mainly created this PR for others to be able to vote on it and noticed that a generic UPS issue was already created so wasn't sure what best to do.

P.S. I need to finish documentation. You responded must faster than I anticipated. 😂

[Brandawg93]

Ok. Should be good to go. Just something for people to vote on if they want it.

[shamoon]

Yea, we'll see what people say, this seems pretty straightforward so Im inclined to merge it unless theres something compelling there.

Tiny change, and would you mind supplying a sample of API output?

[mordilloSan]

Nice proposal! Would like to see that

[vladaurosh]

Is it possible to have native support for Nut, so we don't need peaNut running?

[Brandawg93]

@shamoon Here is a sample of /api/v1/devices/ups

{
"battery_charge": "100",
"battery_charge_low": "10",
"battery_charge_warning": "20",
"battery_mfr_date": "CPS",
"battery_runtime": "23460",
"battery_runtime_low": "300",
"battery_type": "PbAcid",
"battery_voltage": "24.0",
"battery_voltage_nominal": "24",
"device_mfr": "CPS",
"device_model": "REDACTED",
"device_serial": "REDACTED",
"device_type": "ups",
"driver_name": "usbhid-ups",
"driver_parameter_pollfreq": "30",
"driver_parameter_pollinterval": "2",
"driver_parameter_port": "auto",
"driver_parameter_synchronous": "auto",
"driver_version": "2.8.0",
"driver_version_data": "CyberPower HID 0.6",
"driver_version_internal": "0.47",
"driver_version_usb": "libusb-1.0.26 (API: 0x1000109)",
"input_voltage": "122.0",
"input_voltage_nominal": "120",
"output_voltage": "122.0",
"ups_beeper_status": "enabled",
"ups_delay_shutdown": "20",
"ups_delay_start": "30",
"ups_load": "3",
"ups_mfr": "CPS",
"ups_model": "REDACTED",
"ups_productid": "0501",
"ups_realpower_nominal": "810",
"ups_serial": "REDACTED",
"ups_status": "OL",
"ups_test_result": "No test initiated",
"ups_timer_shutdown": "-60",
"ups_timer_start": "-60",
"ups_vendorid": "0764"
}

[Brandawg93]

Is it possible to have native support for Nut, so we don't need peaNut running?

Native support would probably be outside the scope of Homepage. There was discussion of a different approach on #1317, but either way will require intermediary code to translate NUT to a REST API. Although PeaNUT has a UI attached to it, it's the simplest way I've found so far to be able to monitor a UPS.

[vladaurosh]

Is it possible to have native support for Nut, so we don't need peaNut running?

Native support would probably be outside the scope of Homepage. There was discussion of a different approach on #1317, but either way will require intermediary code to translate NUT to a REST API. Although PeaNUT has a UI attached to it, it's the simplest way I've found so far to be able to monitor a UPS.

What about using this module? Would it help to have native support for Nut?
https://github.com/skarcha/node-nut/tree/master

[shamoon]

That last one is a node-client, so it could be used by a homepage widget but it would require a custom proxy, etc. which is something we generally try to avoid.

The more I've looked at this, I think the simple answer is to include a note in the docs about all this.

[shamoon]

@Brandawg93 This works great, thanks.

I fixed a missing docs link but as you can see, also added a note about all of the above. Let me know your thoughts, certainly feel free to change the wording or whatever.

Otherwise Im good with this, but will await your thoughts.

[Brandawg93]

Looks good to me! That's the best part of opensource projects - users get to decide what they want to use.

The other tool looks really neat too and serves a slightly different purpose than PeaNUT. NUTCase looks to be for power users looking to examine data over time. It's perfect for something like grafana. PeaNUT, on the other hand, is meant to be a path of least resistance to monitoring a UPS.

Both are great for Homepage! It's up to the end user to decide what works best for them.

[samborambo]

I used https://github.com/dietah/nut-http instead of peaNUT. Similar default payload but with period delimiter instead of underscore in the JSON keys. Maybe add a switch for that.

[Brandawg93]

I used https://github.com/dietah/nut-http instead of peaNUT. Similar default payload but with period delimiter instead of underscore in the JSON keys. Maybe add a switch for that.

The next release of peanut will use the period in JSON instead of underscore. GraphQL isn't happy with period, so I had to change it initially.

https://github.com/Brandawg93/PeaNUT/tree/next

[augustozanellato]

The next release of peanut will use the period in JSON instead of underscore.

It has been since released, so the widget is now broken 😢

[Brandawg93]

Whoops...I was hoping to squeeze that fix in before the release! For now you can use the template in peanut's README.

[Brandawg93]

#2526 should fix it. Just polishing it up now.

[Brandawg93]

Looks like it has been merged.

P.S. I blame homepage for getting me too excited about NextJS and Tailwind. 😜

[Magelo]

With Homepage v0.8.4 it's not usable in this simple form:

widget:
type: peanut
url: http://peanut.host.or.ip:port
key: nameofyourups

I have to use the customapi syntax, simply because a call to the api : http://host:port/api/v1/devices/[ups] is not using underscore in labels, but a period.

 widget:
      type: customapi
      url: http://host:port/api/v1/devices/[ups]
      mappings:
        - field: battery.charge
          label: UPS Charge
          format: percent
        - field: ups.load
          label: UPS Load
          format: percent
        - field: battery.runtime
          label: Runtime
          format: float
          scale: 1/60
          suffix: Min
        - field: ups.status
          label: UPS Status
          format: text
          remap:
            - value: OL
              to: Online
            - value: OB
              to: On Battery
            - value: LB
              to: Low Battery
            - any: true
              to: Unknown

I'm a bit confused with the last comments here, was it or was it not part of the official merge? Changing the default back to a period? My experience tells me it's not part of 0.8.4.

[shamoon]

#2526 was merged but is currently only in the main image, it will be in the next versioned release (e.g. 0.8.5 presumably) but is not in 0.8.4

[Magelo]

Thank you @shamoon for this clarification. By the way, nice addition to the ever growing list of widget!

[vampywiz17]

It not working on my UPS... somebody any idea, what the problem?

my config:

    - PeaNUT:
        icon: https://raw.githubusercontent.com/Brandawg93/PeaNUT/main/src/app/icon.svg
        href: http://192.168.31.105:8084
        description: UPS státusz
        server: my-docker
        container: PeaNUT
        widget:
          type: peanut
          url: http://192.168.31.105:8084
          key: kstar

The PeaNUT work well, also. The api/v1/devices/kstar output are:

{"battery.charge":"100","battery.voltage":"27.40","battery.voltage.high":"26.00","battery.voltage.low":"20.80","battery.voltage.nominal":"24.0","device.mfr":"","device.model":"2000VA","device.type":"ups","driver.name":"blazer_usb","driver.parameter.pollinterval":"2","driver.parameter.port":"auto","driver.parameter.synchronous":"auto","driver.version":"2.8.0","driver.version.internal":"0.14","driver.version.usb":"libusb-1.0.24 (API: 0x1000108)","input.current.nominal":"8.0","input.frequency":"50.0","input.frequency.nominal":"50","input.voltage":"230.6","input.voltage.fault":"207.1","input.voltage.nominal":"230","output.voltage":"230.6","ups.beeper.status":"enabled","ups.delay.shutdown":"30","ups.delay.start":"180","ups.firmware":"","ups.load":"22","ups.mfr":"","ups.model":"2000VA","ups.productid":"0000","ups.status":"OL","ups.type":"offline / line interactive","ups.vendorid":"0001"}

[Brandawg93]

@vampywiz17 It will work when homepage v0.8.5 is released.

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new discussion or issue for related concerns.