Skip to main content

Python driver for TrippLite UPS battery backups.

Project description

tripplite

Python USB interface and command-line tool for TrippLite UPS battery backups.

Background

TrippLite offers UI software for monitoring its batteries. However, most of its batteries don't have network access, and the existing TrippLite software requires a local install.

I wanted to monitor the UPS from a remote headless Linux server, so I wrote this tool.

Supported Hardware

This has been exclusively tested on the TrippLite SMART1500LCD UPS. It will likely work on similar firmware but there is a known communication issue with some other TrippLite models (see numat/tripplite#3).

Use lsusb to check. 09ae:2012 should work, while 09ae:3016 may not.

Installation

apt install gcc libusb-1.0-0-dev libudev-dev
pip install tripplite

Connect a USB cable from the UPS to your headless server, and you should be ready to run. If you don't want to run as root, see Note on Permissions below.

Command Line

$ tripplite
{
    "config": {
        "frequency": 60,  # Hz
        "power": 1500,  # VA
        "voltage": 120  # V
    },
    "health": 100,  # %
    "input": {
        "frequency": 59.7,  # Hz
        "voltage": 117.2  # V
    },
    "output": {
        "power": 324,  # W
        "voltage": 117.2  # V
    },
    "status": {
        "ac present": true,
        "below remaining capacity": true,
        "charging": false,
        "discharging": false,
        "fully charged": true,
        "fully discharged": false,
        "needs replacement": false,
        "shutdown imminent": false
    },
    "time to empty": 1004  # s
}

To use in shell scripts, parse the json output with something like jq. For example, tripplite | jq '.status."ac present"' will return whether or not the unit detects AC power.

Python

If you'd like to link this to more complex behavior (e.g. data logging, text alerts), consider using a Python script.

from tripplite import Battery
with Battery() as battery:
    print(battery.get())

The state variable will contain an object with the same format as above. Use state['status']['ac present'] and state['status']['shutdown imminent'] for alerts, and consider logging voltage, frequency, and power.

If you are logging multiple batteries, you will need to handle each connection separately.

from tripplite import Battery, battery_paths
for path in battery_paths:
    with Battery(path) as battery:
        print(battery.get())

These paths are unfortunately non-deterministic and will change on each iteration. For long running processes please prefer to keep an open Battery object and open + close on read errors. For example:

    def check_batteries(
        self, battery_paths: List[str], check_period: float = 30.0
    ) -> None:
        """Read batteries and reopen in error"""
        self.batteries = [Battery(path) for path in battery_paths]
        for battery in self.batteries:
            battery.open()
        while True:
            time.sleep(check_period)
            for state, battery in zip(self.state, self.batteries):
                try:
                    state.update(battery.get())
                except OSError:
                    logger.exception(f"Could not read battery {battery}.")
                    battery.close()

Note on Permissions

To read the TrippLite, you need access to the USB port. You have options:

  • Run everything as root
  • Add your user to the dialout group to access all serial ports
  • Create a group restricted to accessing TrippLite USB devices through udev

For the last option, the rule looks like:

echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="09ae", GROUP="tripplite"' > /etc/udev/rules.d/tripplite.rules
udevadm control --reload-rules

Prometheus Exporter

This package offers an extra install to include a Prometheus Exporter which allows for data collection into a prometheus time series database. Esentially it's a small HTTP server that allows Prometheus to scrape grabbing metrics at a configurable period.

Install

pip install tripplite[exporter]

You can then manually run the triplite-exporter cli or use the tripplite_exporter.service systemd unit file to have systemd run and supervise the process.

Failure Mode

The script will try to close and reopen the USB serial connection to the device on an OSError. If an open fails, the script will exit with the return code of 2.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for tripplite, version 0.3.0
Filename, size File type Python version Upload date Hashes
Filename, size tripplite-0.3.0-py2.py3-none-any.whl (15.0 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size tripplite-0.3.0.tar.gz (7.0 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page