Using the JSON returned by NUTCase

Introduction

NUTCase returns JSON containing information about the server followed by the variables for one, or more than one, UPS depending on how many UPS devices are being handled by this particular instance of the UPS tools.

To parse the JSON you will need to know the name (or names) of the UPS devices. If you are unsure what the name(s) are you can use telnet as described in the debugging connectivity page or simply open a browser and put the URL in to load the JSON. Most browsers will give you some type of basic formatting if the receive JSON. You can also run at the command line:

curl --silent "http://<nutcase-ip>:9995/json?target=<nut-server-ip>:3493” | jq .

Example Data

All systems will return slightly different variables and names however a basic example of the JSON output is as follows:

{
    "server_version": "1.2.3",
    "server_address": "10.10.10.9",
    "server_port": 3493,
    "apcmain1":
        {
            "description": "Description unavailable",
            "battery.charge": "100",
            "battery.charge.low": "10",
            "battery.charge.warning": "50",
            "battery.runtime": "3000",
            "battery.voltage": "13.7",
            "battery.voltage.nominal": "12.0",
==== Other variables ====
        }
}

The root level entries server version, address and port are basic information about the server. The name of the UPS device comes next and in this case is apcmain1. In order to access the dat you will need to know the name assigned to the UPS.

If the NUT server is handling multiple UPS devices then at the end of the variable list another UPS device name will be given followed by the variable list for that device.

Filtering The JSON

If you are taking the JSON data into a monitoring tool such as Uptime Kuma then you may want to get only one or two variable values returned in the query. This would be useful if the receiver has only a simple sub-string found test mechanism to check the data.

For example, if the full JSON returned by calling http://(nutcase-ip):(port)/json?addr=(server-ip)&dev=ups is:

{
  "nutcase_version": "NUTCase-UI 0.3.0 Beta 4",
  "server_version": "DSM7-1-1-42930-workplus-version2-repack-42930-220712",
  "server_address": "10.0.10.9",
  "server_port": 3493,
  "ups": {
    "description": "Description unavailable",
    "battery.charge": "100",
    "battery.charge.low": "10",
    "battery.charge.warning": "20",
    "battery.mfr.date": "CPS",
    "battery.runtime": "1500",
    "input.transfer.high": "260",
    "input.transfer.low": "170",
    "input.voltage": "231.0",
    "input.voltage.nominal": "230",
    "ups.load": "20",
    "ups.status": "OL",
    "ups.timer.shutdown": "-60",
    "ups.timer.start": "-60",
    }
  "clients": {
    "count": 3,
    "list": [
      "10.0.10.10", "10.0.10.183", "127.0.0.1"
    ]
  }
}

Then adding an elem parameter thus: http://(nutcase-ip):(port)/json?addr=(server-ip)&dev=ups&elem=ups/ups.status the returned JSON will be:

{
  "ups/ups.status": "OL"
}

The format for elem separates steps in the JSON with / characters and so to get the server_address value you would use &elem=server_address and to get the client count value, &elem=ups/clients/count.

You can also get elements of an array so to get the second IP address in the clients list you can use &dev=ups&elem=ups/clients/list/1 which would return:

{
  "ups/clients/list/1": "10.0.10.183"
}

You can add as many elem parameters as you require, so for example http://(nutcase-ip):(port)/json?addr=(server-ip)&dev=ups&elem=ups/ups.status&elem=ups/ups.load will return:

{
  "ups/ups.status": "OL",
  "ups/ups.load": "20"
}

Using The JSON With HomePage

If you are using the JSON with HomePage then you should use the customapi widget to get and access the JSON data.

I wont duplicate the HomePage documentation here but you can see what is possible from their API. In your services.yaml you can add a customapi widget along the following way. Note that you will need to change this example, particularly the UPS device name, for your system.

Tip

If you want to customise the format of the NUT variables to improve the usefulness of the dispaly then consider re-working the data in to virtual variables and displaying then instead.

- A group name:
    - A sub name:
        href: http://10.10.10.10:9995/log?lines=40
        description: My UPS
        icon: http://10.10.10.10:9995/static/favicon.ico
        widget:
            type: customapi
            url: http://10.10.10.10:9995/json?target=10.10.10.9:3493
            refreshInterval: 60000 # Refresh in milliseconds, don’t overload your server
            method: GET
            mappings:
                - field:
                    apcmain1:
                      input.voltage
                  label: Input
                  format: text
                  suffix: V
                - field:
                    apcmain1: battery.runtime
                  label: Runtime
                  format: float
                  scale: 1/60
                  suffix: Min
                - field:
                    apcmain1:
                      ups.load
                  label: Power
                  format: text
                  suffix: "%"
                - field:
                    apcmain1:
                      ups.status
                  label: Status
                  format: text
                  remap:
                    - value: "OL"
                      to: On-Line
                    - value: "OB"
                      to: Discharge