UPS Card

Features

• Two cards: a full UPS Card (custom:ups-card) and a compact UPS Mini Card (custom:ups-mini-card)
• State of the UPS — on mains, charging, on battery, low battery, overload, bypass, calibration, battery test, forced shutdown, offline — as a status chip and as the color of the header icon (green on the mains, blue charging, orange on battery, red when low, overloaded or offline)
• A drawn UPS animated by its state: power flowing from the wall plug to the computer, the battery gauge filling while charging, the plug cut off and the gauge draining on battery, a blinking LED when something is wrong, the UPS shaking when overloaded (see Animations)
• Battery charge, runtime left (in the units of your language), load in percent and power
• Power section: input and output voltage, real power against the nominal power, apparent power against the VA rating (both estimated from the load when the UPS does not report them), load, frequency, temperature
• Battery section: charge, runtime, battery voltage and temperature, date the battery was installed, date it should be replaced (battery_life, 4 years by default), result of the last self-test
• Outage history from the Home Assistant history: number of outages and time on battery over the last history_days days, the longest one and the latest ones with their date and duration, the one going on included; the transfers counted by APC UPS Daemon and the reason of its last transfer
• Alerts: on battery (for how long and the runtime left), low battery, overload, high load, battery to replace (flag of the UPS or replacement date reached), no communication with the UPS, UPS output off, no battery, alarm raised by the UPS, forced shutdown
• Collapsible sections (chevron to the right when folded, down when unfolded), folded back as they were by a click anywhere else
• Detail button on the mini card (top right): it switches the mini card to the full card's content and back; a click anywhere outside the card brings the compact view back
• Click any value to open its Home Assistant history (more-info dialog)
• Visual editor in the dashboard UI for both cards (no YAML needed)
• Sections view: the full card takes 12 columns by default and at least 6, the mini card 6; narrow widths get their own layout
• Light and dark mode, prefers-reduced-motion, English, French, German, Spanish, Italian, Dutch, European Portuguese, Polish, Serbian (Cyrillic and Latin), Romanian, Danish, Swedish, Bulgarian, Russian, Ukrainian, Hungarian, Slovak, Czech, Slovenian, Latvian and Greek
• Single file, no external dependency, the logos are embedded

Supported integrations

Integration	What the cards read
Network UPS Tools (core, nut)	Status (ups.status and its readable form), battery charge, runtime, load, input and output voltage, real power and nominal power, apparent power and nominal apparent power, UPS and battery temperature, battery voltage, input frequency, battery date (or manufacturing date), self-test result, low battery threshold
APC UPS Daemon (core, apcupsd)	Status and online status, battery charge, time left, load, line and output voltage, nominal output power and nominal apparent power (power estimated from the load), internal temperature, battery voltage, line frequency, battery replacement date, self-test result, transfer count, last transfer reason, time on battery, time of the last transfer from battery
Generic sensors	Any sensor given in the entities option: status (text), mains binary sensor, battery, runtime, load, voltages, power, temperature, battery voltage, frequency, battery date (see Generic sensors)

Many sensors are disabled by default in Home Assistant — for NUT the runtime, real and apparent power and their nominal values, temperatures, battery voltage and date, input frequency, self-test result and low battery threshold; for apcupsd the last transfer reason and the manufacturing date: enable the ones you want in the device page of the UPS, the cards show them as soon as they are there. Details in How it works.

Prerequisites

Home Assistant 2024.8 or later, with the Network UPS Tools or APC UPS Daemon integration configured, or sensors of your own for the UPS. The outage history needs the Recorder (on by default).

Configuration

Card types#

Visual editor#

Edit a dashboard, click Add card and search for UPS Card or UPS Mini Card. The first UPS is preselected; pick another one in the list if you have several (or None for generic sensors only), set an optional title, choose the sections, the folded sections, the history length and the battery life, and fill the Entities part for generic sensors. The preview updates live, and options left at their default are kept out of the generated YAML.

Minimal#

type: custom:ups-card

type: custom:ups-mini-card

Full options#

type: custom:ups-card
device: Office UPS
title: Office
show_title: true
show_subtitle: true
show_alerts: true
show_power: true
show_battery: true
show_outages: true
collapsed:
  - power
history_days: 30
max_outages: 5
low_runtime: 10
battery_life: 4
battery_replaced: "2024-03-14"
entities:
  temperature: sensor.office_ups_room_temperature
language: fr

type: custom:ups-mini-card
device: Rack UPS
title: Rack
show_alerts: true
low_runtime: 10
zoom: true
language: fr

Options reference#

Generic sensors#

A UPS that neither integration knows (SNMP, Modbus, MQTT, a smart plug's battery pack, template sensors…) is shown from sensors given in entities:

type: custom:ups-card
title: Garage UPS
entities:
  status: sensor.garage_ups_status
  battery: sensor.garage_ups_battery
  runtime: sensor.garage_ups_runtime
  load: sensor.garage_ups_load
  power: sensor.garage_ups_power
battery_replaced: "2025-06-01"

The outage history is read from the status entity, or from online.

How it works

The cards read the Home Assistant entity and device registries instead of entity ids: every sensor of the NUT and apcupsd integrations is matched by its translation_key (ups_status, battery_runtime, time_left, line_voltage…) — or its device class when it has none (the NUT apparent power, the apcupsd battery charge) — and by the UPS device it belongs to. The apcupsd keys are mapped onto the NUT ones, so the same card reads both. Entity ids can therefore be in any language or renamed.

State#

The state comes from the raw NUT status (OL, OB, LB, CHRG, OVER, BYPASS, CAL, TEST, FSD, OFF, RB…), else its readable form, the apcupsd status (ONLINE, ONBATT, LOWBATT, OVERLOAD, COMMLOST, SHUTTING DOWN, REPLACEBATT…) or the words of a generic sensor, else the mains binary sensor. A UPS on battery reads Low battery when the UPS says so, when its charge is under its own low threshold (NUT battery.charge.low, 20 % otherwise) or when its runtime is under low_runtime. A runtime calibration or a battery test (CAL, TEST) reads as such, not as an outage, even though the UPS runs on battery. apcupsd and generic sensors do not report charging: a battery under 100 % on the mains reads Charging for 12 hours after the mains came back (apcupsd's time of the last transfer from battery, else the end of the latest outage of the history, else the last change of the status), then On mains — a battery that settles below 100 % does not read Charging forever. An unavailable status, COMMLOST or NUT OFF (the UPS output is off, with its own alert) read Offline.

Power and battery#

The power is the UPS's real power sensor (NUT ups.realpower), else the load times the nominal power (NUT ups.realpower.nominal, apcupsd nominal output power), shown with "≈"; the same goes for the apparent power (NUT ups.power, else the load times NUT ups.power.nominal or apcupsd nominal apparent power). When there is no real power at all, the hero line shows the apparent power. The load turns orange at 75 % and red at 90 % (with a High load alert). The battery charge turns orange at 50 % and red under the low threshold.

The battery installation date is battery_replaced, else the UPS's battery date (NUT battery.date, apcupsd BATTDATE), else its battery manufacturing date. The replacement date is battery_life years later: orange (and an alert) within 90 days of it, red once passed. A UPS reporting that its battery needs replacing (RB, REPLACEBATT) gets a red alert whatever the date.

Outage history#

The card reads the history of the status entity (history/history_during_period, the last history_days days, states only) when it is shown, again when the status changes and every 15 minutes, and counts the stretches on battery — an overload or a forced shutdown on battery included, a calibration or a battery test left out, a lost communication in the middle of an outage not splitting it: their number, the total time on battery, the longest one and the latest max_outages ones with their start and duration; an outage going on is listed first with ongoing. The history only goes back as far as the Recorder keeps it (purge_keep_days, 10 days by default). The mini card reads it only in its detailed view.

Support

If you find this project useful, you can support its development:

Features

• UPS Card (custom:ups-card): state of the UPS (on mains, charging, on battery, low battery, overload, bypass, calibration, battery test, forced shutdown, offline) as a colored chip and header icon, with a drawn UPS animated by its state; battery charge, runtime left, load and power; power section (input and output voltage, real power against the nominal power, load, apparent power, frequency, temperature); battery section (charge, runtime, battery voltage and temperature, installation date, replacement date, self-test result); outage history read from the Home Assistant history (count, time on battery, longest outage and the latest outages, one going on included), plus the transfers counted by apcupsd and the reason of the last one.
• Alerts: on battery (for how long, runtime left), low battery, overload, high load, battery to replace (UPS flag or replacement date reached), no communication, UPS output off, no battery, UPS alarm, forced shutdown.
• UPS Mini Card (custom:ups-mini-card): state, battery, runtime, load and the main alert, with a detail button that switches to the full card and back.
• Sources: Network UPS Tools (nut) and APC UPS Daemon (apcupsd) found through the Home Assistant registries, whatever the entity ids or language; generic sensors with the entities option, which also replaces any entity of an integration.
• Visual editor for both cards, collapsible sections, Sections view sizes, light and dark themes, prefers-reduced-motion, 22 languages (English in the bundle, the others loaded on demand).