eaton-ups-companion

A lightweight async Python client that communicates with the Eaton UPS Companion desktop application over its local HTTP API — perfect for monitoring your UPS status or building custom dashboards.

Key Features

• Fully async — built on aiohttp, integrates cleanly into asyncio applications

• Typed models — all responses are parsed into structured Python dataclasses

• Patch support — fetch only incremental updates since your last read for efficient polling

• Zero dependencies beyond aiohttp — small and simple to install

Installation

pip install eaton-ups-companion

Prerequisites

The Eaton UPS Companion desktop application must be installed and running on your machine. The library communicates with its local endpoint at http://localhost:4679/euc-data.js.

Quick Start

import asyncio
from eaton_ups_companion import EUCClient

async def main():
    client = EUCClient()
    response = await client.fetch_data()

    print(f"AC present:        {response.status.acPresent}")
    print(f"Battery capacity:  {response.status.batteryCapacity}%")
    print(f"Output load level: {response.status.outputLoadLevel}%")
    print(f"Product:           {response.deviceInfo.product}")

asyncio.run(main())

Real-Time Monitoring

Poll for incremental updates without re-fetching the entire payload:

import asyncio
from eaton_ups_companion import EUCClient

async def monitor():
    client = EUCClient()
    response = await client.fetch_data()

    while True:
        if not response.status.acPresent:
            print("⚠️  AC power lost! Running on battery.")
        if response.status.batteryCapacity < 20:
            print(f"🔋 Battery low: {response.status.batteryCapacity}%")
        if response.status.shutdownImminent:
            print("🛑 Shutdown imminent!")

        # Apply incremental patch in-place
        await client.update_data(response)
        await asyncio.sleep(10)

asyncio.run(monitor())

Data Models

The response object gives you access to a complete picture of your UPS:

• Status — real-time operational data: AC presence, battery capacity & runtime, charging state, overload indicators

• DeviceInfo — product name, model number, EcoControl settings

• PowerSourceCfg — configured output voltage, sensitivity mode, audible alarm

• ShutdownCfg — shutdown behavior, runtime limits, shutdown scripts

• SystemCfg — auto-update intervals, energy cost tracking

• Logs — event log entries with timestamps and severity levels