Skip to content

Commit 16a2465

Browse files
yuxincsyuxincs
authored
Provide detailed functionality description for APCUPSD (#38876)
1 parent 8590c4c commit 16a2465

File tree

1 file changed

+300
-72
lines changed

1 file changed

+300
-72
lines changed

‎source/_integrations/apcupsd.markdown

+300-72
Original file line numberDiff line numberDiff line change
@@ -50,89 +50,317 @@ Port:
5050
description: "The port of the APC UPS Daemon configured above."
5151
{% endconfiguration_basic %}
5252

53-
## Binary sensor
53+
## Supported functionality
5454

55-
This integration provides a binary sensor for the following information from apcupsd:
55+
### Entities
5656

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

59-
## Sensors
59+
#### Binary sensors
6060

61-
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`.
61+
- **Online Status**
62+
- **Description**: Indicates whether the UPS is online, supplying power to connected devices from utility line, not the battery.
63+
- **Available for machines**: all
64+
65+
#### Sensors
6266

6367
{% note %}
6468

6569
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.
6670

6771
{% endnote %}
6872

69-
- UPS Alarm Delay (ALARMDEL)
70-
- UPS Ambient Temperature (AMBTEMP)
71-
- UPS Status Data (APC)
72-
- UPS Model (APCMODEL)
73-
- UPS Bad Batteries (BADBATTS)
74-
- UPS Battery Replaced (BATTDATE)
75-
- UPS Battery Status (BATTSTAT)
76-
- UPS Battery Voltage (BATTV)
77-
- UPS Battery (BCHARGE)
78-
- UPS Cable Type (CABLE)
79-
- UPS Total Time on Battery (CUMONBATT)
80-
- UPS Status Date (DATE)
81-
- UPS Dip Switch Settings (DIPSW)
82-
- UPS Low Battery Signal (DLOWBATT)
83-
- UPS Driver (DRIVER)
84-
- UPS Shutdown Delay (DSHUTD)
85-
- UPS Wake Delay (DWAKE)
86-
- UPS Date and Time (END APC)
87-
- UPS External Batteries (EXTBATTS)
88-
- UPS Firmware Version (FIRMWARE)
89-
- UPS Transfer High (HITRANS)
90-
- UPS Hostname (HOSTNAME)
91-
- UPS Ambient Humidity (HUMIDITY)
92-
- UPS Internal Temperature (ITEMP)
93-
- UPS Last Transfer (LASTXFER)
94-
- UPS Input Voltage Status (LINEFAIL)
95-
- UPS Line Frequency (LINEFREQ)
96-
- UPS Input Voltage (LINEV)
97-
- UPS Load (LOADPCT)
98-
- UPS Load Apparent Power (LOADAPNT)
99-
- UPS Transfer Low (LOTRANS)
100-
- UPS Manufacture Date (MANDATE)
101-
- UPS Master Update (MASTERUPD)
102-
- UPS Input Voltage High (MAXLINEV)
103-
- UPS Battery Timeout (MAXTIME)
104-
- UPS Battery Shutdown (MBATTCHG)
105-
- UPS Input Voltage Low (MINLINEV)
106-
- UPS Shutdown Time (MINTIMEL)
107-
- UPS Model (MODEL)
108-
- UPS Battery Nominal Voltage (NOMBATTV)
109-
- UPS Nominal Input Voltage (NOMINV)
110-
- UPS Nominal Output Voltage (NOMOUTV)
111-
- UPS Nominal Output Power (NOMPOWER)
112-
- UPS Nominal Apparent Power (NOMAPNT)
113-
- UPS Transfer Count (NUMXFERS)
114-
- UPS Output Current (OUTCURNT)
115-
- UPS Output Voltage (OUTPUTV)
116-
- UPS Register 1 Fault (REG1)
117-
- UPS Register 2 Fault (REG2)
118-
- UPS Register 3 Fault (REG3)
119-
- UPS Restore Requirement (RETPCT)
120-
- UPS Last Self Test (LASTSTEST)
121-
- UPS Self Test Result (SELFTEST)
122-
- UPS Sensitivity (SENSE)
123-
- UPS Serial Number (SERIALNO)
124-
- UPS Startup Time (STARTTIME)
125-
- UPS Status Flag (STATFLAG)
126-
- UPS Status (STATUS)
127-
- UPS Self Test Interval (STESTI)
128-
- UPS Time Left (TIMELEFT)
129-
- UPS Time on Battery (TONBATT)
130-
- UPS Mode (UPSMODE)
131-
- UPS Name (UPSNAME)
132-
- UPS Daemon Info (VERSION)
133-
- UPS Transfer from Battery (XOFFBAT)
134-
- UPS Transfer from Battery (XOFFBATT)
135-
- UPS Transfer to Battery (XONBATT)
73+
- **Alarm Delay**
74+
- **Description**: The delay period for the UPS alarm.
75+
- **Available for machines**: all
76+
77+
- **Battery Replaced**
78+
- **Description**: The date that batteries were last replaced.
79+
- **Available for machines**: all
80+
81+
- **Battery Voltage**
82+
- **Description**: Battery voltage as supplied by the UPS.
83+
- **Available for machines**: all
84+
85+
- **Battery**
86+
- **Description**: The percentage charge on the batteries.
87+
- **Available for machines**: all
88+
89+
- **Total Time on Battery**
90+
- **Description**: Total (cumulative) time on batteries in seconds since apcupsd startup.
91+
- **Available for machines**: all
92+
93+
- **Date and Time**
94+
- **Description**: The time and date that the STATUS record was written.
95+
- **Available for machines**: all
96+
97+
- **Transfer High**
98+
- **Description**: The line voltage above which the UPS will switch to batteries.
99+
- **Available for machines**: all
100+
101+
- **Input Voltage**
102+
- **Description**: The current line voltage as returned by the UPS.
103+
- **Available for machines**: all
104+
105+
- **Load**
106+
- **Description**: The percentage of load capacity as estimated by the UPS.
107+
- **Available for machines**: all
108+
109+
- **Transfer Low**
110+
- **Description**: The line voltage below which the UPS will switch to batteries.
111+
- **Available for machines**: all
112+
113+
- **Battery Timeout**
114+
- **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).
115+
- **Available for machines**: all
116+
117+
- **Battery Shutdown**
118+
- **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).
119+
- **Available for machines**: all
120+
121+
- **Shutdown Time**
122+
- **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).
123+
- **Available for machines**: all
124+
125+
- **Battery Nominal Voltage**
126+
- **Description**: The nominal battery voltage.
127+
- **Available for machines**: all
128+
129+
- **Nominal Input Voltage**
130+
- **Description**: The input voltage that the UPS is configured to expect.
131+
- **Available for machines**: all
132+
133+
- **Nominal Output Power**
134+
- **Description**: The maximum power in Watts that the UPS is designed to supply.
135+
- **Available for machines**: all
136+
137+
- **Transfer Count**
138+
- **Description**: The number of transfers to batteries since apcupsd startup.
139+
- **Available for machines**: all
140+
141+
- **Last Self-test**
142+
- **Description**: The date and time of the last self-test performed by the UPS.
143+
- **Available for machines**: all
144+
- **Remarks**: This only becomes available when a self-test (either automatic or manual) is performed.
145+
146+
- **Self Test Result**
147+
- **Description**: The results of the last self test, and may have the following values:
148+
- OK: self test indicates good battery
149+
- BT: self test failed due to insufficient battery capacity
150+
- NG: self test failed due to overload
151+
- NO: No results
152+
- **Available for machines**: all
153+
154+
- **Startup Time**
155+
- **Description**: The time/date that apcupsd was started.
156+
- **Available for machines**: all
157+
158+
- **Status**
159+
- **Description**: The current status of the UPS (ONLINE, CHARGING, ONBATT, etc.)
160+
- **Available for machines**: all
161+
162+
- **Time Left**
163+
- **Description**: The remaining runtime left on batteries as estimated by the UPS.
164+
- **Available for machines**: all
165+
166+
- **Time on Battery**
167+
- **Description**: Time in seconds currently on batteries, or 0.
168+
- **Available for machines**: all
169+
170+
- **Mode**
171+
- **Description**: The mode in which apcupsd is operating as specified in the configuration file (UPSMODE)
172+
- **Available for machines**: all
173+
174+
- **Transfer from Battery**
175+
- **Description**: Time and date of last transfer from batteries.
176+
- **Available for machines**: all
177+
178+
- **Transfer to Battery**
179+
- **Description**: Time and date of last transfer to batteries.
180+
- **Available for machines**: all
181+
- **Remarks**: This entity only becomes available after a tranfer to battery event happens.
182+
183+
- **Battery Status**
184+
- **Description**: The status of the batteries.
185+
- **Available for machines**: Back-UPS Pro and Smart-UPS
186+
187+
- **Line Frequency**
188+
- **Description**: Line frequency in hertz as given by the UPS.
189+
- **Available for machines**: Back-UPS Pro and Smart-UPS
190+
191+
- **Load Apparent Power**
192+
- **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.
193+
- **Available for machines**: Back-UPS Pro and Smart-UPS
194+
195+
- **Output Voltage**
196+
- **Description**: The voltage the UPS is supplying to your equipment
197+
- **Available for machines**: Back-UPS Pro and Smart-UPS
198+
199+
- **Bad Batteries**
200+
- **Description**: The number of bad battery packs.
201+
- **Available for machines**: Smart-UPS
202+
203+
- **Dip Switch Settings**
204+
- **Description**: The current dip switch settings on UPSes that have them.
205+
- **Available for machines**: Smart-UPS
206+
207+
- **Low Battery Signal**
208+
- **Description**: The remaining runtime below which the UPS sends the low battery signal. At this point apcupsd will force an immediate emergency shutdown.
209+
- **Available for machines**: Smart-UPS
210+
211+
- **Shutdown Delay**
212+
- **Description**: The grace delay that the UPS gives after receiving a power down command from apcupsd before it powers off your equipment.
213+
- **Available for machines**: Smart-UPS
214+
215+
- **Wake Delay**
216+
- **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.
217+
- **Available for machines**: Smart-UPS
218+
219+
- **External Batteries**
220+
- **Description**: The number of external batteries as defined by the user. A correct number here helps the UPS compute the remaining runtime more accurately.
221+
- **Available for machines**: Smart-UPS
222+
223+
- **Internal Temperature**
224+
- **Description**: Internal UPS temperature as supplied by the UPS.
225+
- **Available for machines**: Smart-UPS
226+
227+
- **Input Voltage Status**
228+
- **Description**: The input line voltage status. "OK" indicates normal operation.
229+
- **Available for machines**: Smart-UPS
230+
231+
- **Master Update**
232+
- **Description**: The last time the master sent an update to the device.
233+
- **Available for machines**: Smart-UPS
234+
235+
- **Input Voltage High**
236+
- **Description**: The maximum line voltage since the UPS was started, as reported by the UPS.
237+
- **Available for machines**: Smart-UPS
238+
239+
- **Input Voltage Low**
240+
- **Description**: The minimum line voltage since the UPS was started, as returned by the UPS.
241+
- **Available for machines**: Smart-UPS
242+
243+
- **Nominal Output Voltage**
244+
- **Description**: The output voltage that the UPS will attempt to supply when on battery power.
245+
- **Available for machines**: Smart-UPS
246+
247+
- **Nominal Apparent Power**
248+
- **Description**: The rated apparent power capacity.
249+
- **Available for machines**: Smart-UPS
250+
251+
- **Output Current**
252+
- **Description**: The output current being supplied by the UPS to the connected devices
253+
- **Available for machines**: Smart-UPS
254+
255+
- **Restore Requirement**
256+
- **Description**: The percentage charge that the batteries must have after a power off condition before the UPS will restore power to your equipment.
257+
- **Available for machines**: Smart-UPS
258+
259+
- **Self Test Interval**
260+
- **Description**: The interval in hours between automatic self tests.
261+
- **Available for machines**: Smart-UPS
262+
263+
- **Transfer from Battery**
264+
- **Description**: The date and time of last transfer off battery since apcupsd startup.
265+
- **Available for machines**: Smart-UPS
266+
267+
- **Ambient Humidity**
268+
- **Description**: The humidity as measured by the UPS.
269+
- **Available for machines**: Smart-UPS with optional accessories (e.g., temperature/humidity sensors or SNMP network cards).
270+
271+
- **Ambient Temperature**
272+
- **Description**: The ambient temperature as measured by the UPS.
273+
- **Available for machines**: Smart-UPS with optional accessories (e.g., temperature/humidity sensors or SNMP network cards).
274+
275+
- **Status Data**
276+
- **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.
277+
- **Available for machines**: all
278+
- **Remarks**: Disabled by default for advanced uses.
279+
280+
- **Model**
281+
- **Description**: The old APC model identification code.
282+
- **Available for machines**: Smart-UPS
283+
- **Remarks**: Disabled by default for advanced uses.
284+
285+
- **Cable Type**
286+
- **Description**: The cable as specified in the configuration file (UPSCABLE).
287+
- **Available for machines**: all
288+
- **Remarks**: Disabled by default for advanced uses.
289+
290+
- **Status Date**
291+
- **Description**: The date and time that the information was last obtained from the UPS.
292+
- **Available for machines**: all
293+
- **Remarks**: Disabled by default for advanced uses.
294+
295+
- **Driver**
296+
- **Description**: The driver used to communicate with the UPS.
297+
- **Available for machines**: all
298+
- **Remarks**: Disabled by default for advanced uses.
299+
300+
- **Firmware Version**
301+
- **Description**: The firmware revision number as reported by the UPS.
302+
- **Available for machines**: all
303+
- **Remarks**: Disabled by default for advanced uses.
304+
305+
- **Hostname**
306+
- **Description**: The name of the machine that collected the UPS data.
307+
- **Available for machines**: all
308+
- **Remarks**: Disabled by default for advanced uses.
309+
310+
- **Last Transfer**
311+
- **Description**: The reason for the last transfer to batteries.
312+
- **Available for machines**: all
313+
- **Remarks**: Disabled by default for advanced uses.
314+
315+
- **Manufacture Date**
316+
- **Description**: The date the UPS was manufactured.
317+
- **Available for machines**: Smart-UPS
318+
- **Remarks**: Disabled by default for advanced uses.
319+
320+
- **Model**
321+
- **Description**: The UPS model as derived from information from the UPS.
322+
- **Available for machines**: all
323+
- **Remarks**: Disabled by default for advanced uses.
324+
325+
- **Register 1 Fault**
326+
- **Description**: The value from the UPS fault register 1.
327+
- **Available for machines**: Smart-UPS
328+
- **Remarks**: Disabled by default for advanced uses.
329+
330+
- **Register 2 Fault**
331+
- **Description**: The value from the UPS fault register 2.
332+
- **Available for machines**: Smart-UPS
333+
- **Remarks**: Disabled by default for advanced uses.
334+
335+
- **Register 3 Fault**
336+
- **Description**: The value from the UPS fault register 3.
337+
- **Available for machines**: Smart-UPS
338+
- **Remarks**: Disabled by default for advanced uses.
339+
340+
- **Sensitivity**
341+
- **Description**: The sensitivity level of the UPS to line voltage fluctuations.
342+
- **Available for machines**: all
343+
- **Remarks**: Disabled by default for advanced uses.
344+
345+
- **Serial Number**
346+
- **Description**: The UPS serial number.
347+
- **Available for machines**: all
348+
- **Remarks**: Disabled by default for advanced uses.
349+
350+
- **Status Flag**
351+
- **Description**: Status flag. English version is given by STATUS.
352+
- **Available for machines**: all
353+
- **Remarks**: Disabled by default for advanced uses.
354+
355+
- **Name**
356+
- **Description**: The name of the UPS as stored in the EEPROM or in the UPSNAME directive in the configuration file.
357+
- **Available for machines**: all
358+
- **Remarks**: Disabled by default for advanced uses.
359+
360+
- **Daemon Info**
361+
- **Description**: The apcupsd release number, build date, and platform.
362+
- **Available for machines**: all
363+
- **Remarks**: Disabled by default for advanced uses.
136364

137365
## Examples
138366

0 commit comments

Comments
 (0)