Provide detailed functionality description for APCUPSD (#38876)

2025-07-18 23:06:58 +00:00 · 2025-05-05 03:04:14 -04:00 · 2025-05-05 03:04:14 -04:00 · 16a2465e27
commit 16a2465e27
parent 8590c4cb03
1 changed files with 300 additions and 72 deletions
--- a/source/_integrations/apcupsd.markdown
+++ b/source/_integrations/apcupsd.markdown
@ -50,15 +50,19 @@ 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 %}

@ -66,73 +70,297 @@ Some sensors are disabled by default, since they provide information that is onl

 {% 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.

 ## Examples