Skip to content

Provide detailed functionality description for APCUPSD #38876

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 5, 2025
Merged

Provide detailed functionality description for APCUPSD #38876

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
97d793e
Provide detailed functionality description for APCUPSD
yuxincs May 4, 2025
0fedd75
Update apcupsd.markdown
yuxincs May 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
372 changes: 300 additions & 72 deletions source/_integrations/apcupsd.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,89 +50,317 @@ Port:
description: "The port of the APC UPS Daemon configured above."
{% endconfiguration_basic %}

## Binary sensor
## Supported functionality

This integration provides a binary sensor for the following information from apcupsd:
### Entities

- UPS status
The APC UPS Daemon integration provides the following entities.

## Sensors
#### Binary sensors

This integration provides sensors for the following information from apcupsd based on their availability. Each sensor is listed here along with their corresponding resource name obtained from `apcaccess`.
- **Online Status**
- **Description**: Indicates whether the UPS is online, supplying power to connected devices from utility line, not the battery.
- **Available for machines**: all

#### Sensors

{% note %}

Some sensors are disabled by default, since they provide information that is only useful for advanced users. You can manually enable them in **{% my entities title="Settings -> Devices & Services -> Entities" %}** -> the sensor entity you want to enable -> Advanced settings -> Enabled.

{% endnote %}

- UPS Alarm Delay (ALARMDEL)
- UPS Ambient Temperature (AMBTEMP)
- UPS Status Data (APC)
- UPS Model (APCMODEL)
- UPS Bad Batteries (BADBATTS)
- UPS Battery Replaced (BATTDATE)
- UPS Battery Status (BATTSTAT)
- UPS Battery Voltage (BATTV)
- UPS Battery (BCHARGE)
- UPS Cable Type (CABLE)
- UPS Total Time on Battery (CUMONBATT)
- UPS Status Date (DATE)
- UPS Dip Switch Settings (DIPSW)
- UPS Low Battery Signal (DLOWBATT)
- UPS Driver (DRIVER)
- UPS Shutdown Delay (DSHUTD)
- UPS Wake Delay (DWAKE)
- UPS Date and Time (END APC)
- UPS External Batteries (EXTBATTS)
- UPS Firmware Version (FIRMWARE)
- UPS Transfer High (HITRANS)
- UPS Hostname (HOSTNAME)
- UPS Ambient Humidity (HUMIDITY)
- UPS Internal Temperature (ITEMP)
- UPS Last Transfer (LASTXFER)
- UPS Input Voltage Status (LINEFAIL)
- UPS Line Frequency (LINEFREQ)
- UPS Input Voltage (LINEV)
- UPS Load (LOADPCT)
- UPS Load Apparent Power (LOADAPNT)
- UPS Transfer Low (LOTRANS)
- UPS Manufacture Date (MANDATE)
- UPS Master Update (MASTERUPD)
- UPS Input Voltage High (MAXLINEV)
- UPS Battery Timeout (MAXTIME)
- UPS Battery Shutdown (MBATTCHG)
- UPS Input Voltage Low (MINLINEV)
- UPS Shutdown Time (MINTIMEL)
- UPS Model (MODEL)
- UPS Battery Nominal Voltage (NOMBATTV)
- UPS Nominal Input Voltage (NOMINV)
- UPS Nominal Output Voltage (NOMOUTV)
- UPS Nominal Output Power (NOMPOWER)
- UPS Nominal Apparent Power (NOMAPNT)
- UPS Transfer Count (NUMXFERS)
- UPS Output Current (OUTCURNT)
- UPS Output Voltage (OUTPUTV)
- UPS Register 1 Fault (REG1)
- UPS Register 2 Fault (REG2)
- UPS Register 3 Fault (REG3)
- UPS Restore Requirement (RETPCT)
- UPS Last Self Test (LASTSTEST)
- UPS Self Test Result (SELFTEST)
- UPS Sensitivity (SENSE)
- UPS Serial Number (SERIALNO)
- UPS Startup Time (STARTTIME)
- UPS Status Flag (STATFLAG)
- UPS Status (STATUS)
- UPS Self Test Interval (STESTI)
- UPS Time Left (TIMELEFT)
- UPS Time on Battery (TONBATT)
- UPS Mode (UPSMODE)
- UPS Name (UPSNAME)
- UPS Daemon Info (VERSION)
- UPS Transfer from Battery (XOFFBAT)
- UPS Transfer from Battery (XOFFBATT)
- UPS Transfer to Battery (XONBATT)
- **Alarm Delay**
- **Description**: The delay period for the UPS alarm.
- **Available for machines**: all

- **Battery Replaced**
- **Description**: The date that batteries were last replaced.
- **Available for machines**: all

- **Battery Voltage**
- **Description**: Battery voltage as supplied by the UPS.
- **Available for machines**: all

- **Battery**
- **Description**: The percentage charge on the batteries.
- **Available for machines**: all

- **Total Time on Battery**
- **Description**: Total (cumulative) time on batteries in seconds since apcupsd startup.
- **Available for machines**: all

- **Date and Time**
- **Description**: The time and date that the STATUS record was written.
- **Available for machines**: all

- **Transfer High**
- **Description**: The line voltage above which the UPS will switch to batteries.
- **Available for machines**: all

- **Input Voltage**
- **Description**: The current line voltage as returned by the UPS.
- **Available for machines**: all

- **Load**
- **Description**: The percentage of load capacity as estimated by the UPS.
- **Available for machines**: all

- **Transfer Low**
- **Description**: The line voltage below which the UPS will switch to batteries.
- **Available for machines**: all

- **Battery Timeout**
- **Description**: apcupsd will shut down your system if the time on batteries exceeds this value. A value of zero disables the feature. Value is set in the configuration file (TIMEOUT).
- **Available for machines**: all

- **Battery Shutdown**
- **Description**: If the battery charge percentage (BCHARGE) drops below this value, apcupsd will shut down your system. Value is set in the configuration file (BATTERYLEVEL).
- **Available for machines**: all

- **Shutdown Time**
- **Description**: apcupsd will shut down your system if the remaining runtime equals or is below this point. Value is set in the configuration file (MINUTES).
- **Available for machines**: all

- **Battery Nominal Voltage**
- **Description**: The nominal battery voltage.
- **Available for machines**: all

- **Nominal Input Voltage**
- **Description**: The input voltage that the UPS is configured to expect.
- **Available for machines**: all

- **Nominal Output Power**
- **Description**: The maximum power in Watts that the UPS is designed to supply.
- **Available for machines**: all

- **Transfer Count**
- **Description**: The number of transfers to batteries since apcupsd startup.
- **Available for machines**: all

- **Last Self-test**
- **Description**: The date and time of the last self-test performed by the UPS.
- **Available for machines**: all
- **Remarks**: This only becomes available when a self-test (either automatic or manual) is performed.

- **Self Test Result**
- **Description**: The results of the last self test, and may have the following values:
- OK: self test indicates good battery
- BT: self test failed due to insufficient battery capacity
- NG: self test failed due to overload
- NO: No results
- **Available for machines**: all

- **Startup Time**
- **Description**: The time/date that apcupsd was started.
- **Available for machines**: all

- **Status**
- **Description**: The current status of the UPS (ONLINE, CHARGING, ONBATT, etc.)
- **Available for machines**: all

- **Time Left**
- **Description**: The remaining runtime left on batteries as estimated by the UPS.
- **Available for machines**: all

- **Time on Battery**
- **Description**: Time in seconds currently on batteries, or 0.
- **Available for machines**: all

- **Mode**
- **Description**: The mode in which apcupsd is operating as specified in the configuration file (UPSMODE)
- **Available for machines**: all

- **Transfer from Battery**
- **Description**: Time and date of last transfer from batteries.
- **Available for machines**: all

- **Transfer to Battery**
- **Description**: Time and date of last transfer to batteries.
- **Available for machines**: all
- **Remarks**: This entity only becomes available after a tranfer to battery event happens.

- **Battery Status**
- **Description**: The status of the batteries.
- **Available for machines**: Back-UPS Pro and Smart-UPS

- **Line Frequency**
- **Description**: Line frequency in hertz as given by the UPS.
- **Available for machines**: Back-UPS Pro and Smart-UPS

- **Load Apparent Power**
- **Description**: An "apparent load" condition, indicating the calculated load on the UPS based on the voltage and current. This is a measure of how much power the UPS is supplying to connected devices, often reported as a percentage of its capacity.
- **Available for machines**: Back-UPS Pro and Smart-UPS

- **Output Voltage**
- **Description**: The voltage the UPS is supplying to your equipment
- **Available for machines**: Back-UPS Pro and Smart-UPS

- **Bad Batteries**
- **Description**: The number of bad battery packs.
- **Available for machines**: Smart-UPS

- **Dip Switch Settings**
- **Description**: The current dip switch settings on UPSes that have them.
- **Available for machines**: Smart-UPS

- **Low Battery Signal**
- **Description**: The remaining runtime below which the UPS sends the low battery signal. At this point apcupsd will force an immediate emergency shutdown.
- **Available for machines**: Smart-UPS

- **Shutdown Delay**
- **Description**: The grace delay that the UPS gives after receiving a power down command from apcupsd before it powers off your equipment.
- **Available for machines**: Smart-UPS

- **Wake Delay**
- **Description**: The amount of time the UPS will wait before restoring power to your equipment after a power off condition when the power is restored.
- **Available for machines**: Smart-UPS

- **External Batteries**
- **Description**: The number of external batteries as defined by the user. A correct number here helps the UPS compute the remaining runtime more accurately.
- **Available for machines**: Smart-UPS

- **Internal Temperature**
- **Description**: Internal UPS temperature as supplied by the UPS.
- **Available for machines**: Smart-UPS

- **Input Voltage Status**
- **Description**: The input line voltage status. "OK" indicates normal operation.
- **Available for machines**: Smart-UPS

- **Master Update**
- **Description**: The last time the master sent an update to the device.
- **Available for machines**: Smart-UPS

- **Input Voltage High**
- **Description**: The maximum line voltage since the UPS was started, as reported by the UPS.
- **Available for machines**: Smart-UPS

- **Input Voltage Low**
- **Description**: The minimum line voltage since the UPS was started, as returned by the UPS.
- **Available for machines**: Smart-UPS

- **Nominal Output Voltage**
- **Description**: The output voltage that the UPS will attempt to supply when on battery power.
- **Available for machines**: Smart-UPS

- **Nominal Apparent Power**
- **Description**: The rated apparent power capacity.
- **Available for machines**: Smart-UPS

- **Output Current**
- **Description**: The output current being supplied by the UPS to the connected devices
- **Available for machines**: Smart-UPS

- **Restore Requirement**
- **Description**: The percentage charge that the batteries must have after a power off condition before the UPS will restore power to your equipment.
- **Available for machines**: Smart-UPS

- **Self Test Interval**
- **Description**: The interval in hours between automatic self tests.
- **Available for machines**: Smart-UPS

- **Transfer from Battery**
- **Description**: The date and time of last transfer off battery since apcupsd startup.
- **Available for machines**: Smart-UPS

- **Ambient Humidity**
- **Description**: The humidity as measured by the UPS.
- **Available for machines**: Smart-UPS with optional accessories (e.g., temperature/humidity sensors or SNMP network cards).

- **Ambient Temperature**
- **Description**: The ambient temperature as measured by the UPS.
- **Available for machines**: Smart-UPS with optional accessories (e.g., temperature/humidity sensors or SNMP network cards).

- **Status Data**
- **Description**: Header record indicating the STATUS format revision level, the number of records that follow the APC statement, and the number of bytes that follow the record.
- **Available for machines**: all
- **Remarks**: Disabled by default for advanced uses.

- **Model**
- **Description**: The old APC model identification code.
- **Available for machines**: Smart-UPS
- **Remarks**: Disabled by default for advanced uses.

- **Cable Type**
- **Description**: The cable as specified in the configuration file (UPSCABLE).
- **Available for machines**: all
- **Remarks**: Disabled by default for advanced uses.

- **Status Date**
- **Description**: The date and time that the information was last obtained from the UPS.
- **Available for machines**: all
- **Remarks**: Disabled by default for advanced uses.

- **Driver**
- **Description**: The driver used to communicate with the UPS.
- **Available for machines**: all
- **Remarks**: Disabled by default for advanced uses.

- **Firmware Version**
- **Description**: The firmware revision number as reported by the UPS.
- **Available for machines**: all
- **Remarks**: Disabled by default for advanced uses.

- **Hostname**
- **Description**: The name of the machine that collected the UPS data.
- **Available for machines**: all
- **Remarks**: Disabled by default for advanced uses.

- **Last Transfer**
- **Description**: The reason for the last transfer to batteries.
- **Available for machines**: all
- **Remarks**: Disabled by default for advanced uses.

- **Manufacture Date**
- **Description**: The date the UPS was manufactured.
- **Available for machines**: Smart-UPS
- **Remarks**: Disabled by default for advanced uses.

- **Model**
- **Description**: The UPS model as derived from information from the UPS.
- **Available for machines**: all
- **Remarks**: Disabled by default for advanced uses.

- **Register 1 Fault**
- **Description**: The value from the UPS fault register 1.
- **Available for machines**: Smart-UPS
- **Remarks**: Disabled by default for advanced uses.

- **Register 2 Fault**
- **Description**: The value from the UPS fault register 2.
- **Available for machines**: Smart-UPS
- **Remarks**: Disabled by default for advanced uses.

- **Register 3 Fault**
- **Description**: The value from the UPS fault register 3.
- **Available for machines**: Smart-UPS
- **Remarks**: Disabled by default for advanced uses.

- **Sensitivity**
- **Description**: The sensitivity level of the UPS to line voltage fluctuations.
- **Available for machines**: all
- **Remarks**: Disabled by default for advanced uses.

- **Serial Number**
- **Description**: The UPS serial number.
- **Available for machines**: all
- **Remarks**: Disabled by default for advanced uses.

- **Status Flag**
- **Description**: Status flag. English version is given by STATUS.
- **Available for machines**: all
- **Remarks**: Disabled by default for advanced uses.

- **Name**
- **Description**: The name of the UPS as stored in the EEPROM or in the UPSNAME directive in the configuration file.
- **Available for machines**: all
- **Remarks**: Disabled by default for advanced uses.

- **Daemon Info**
- **Description**: The apcupsd release number, build date, and platform.
- **Available for machines**: all
- **Remarks**: Disabled by default for advanced uses.
Comment on lines +73 to +363
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Resolve duplicate sensor names and improve grouping
The sensors list includes two entries named Transfer from Battery (lines 174–177 & 263–266) and two named Model (lines 280–283 & 320–323). Duplicate names will confuse users and may not map to unique entity IDs. Please rename or qualify these entries (e.g., "Last Transfer from Battery" vs. "Transfer from Battery (Smart-UPS)", "UPS Model" vs. "Legacy Model") and consider grouping sensors under subheadings by machine type (all, Back-UPS Pro, Smart-UPS) to reduce repetition and improve readability.


## Examples

Expand Down