From 533ada693e54caecffc2b1898a7a4ed00248cb0d Mon Sep 17 00:00:00 2001 From: Yuxin Wang Date: Wed, 28 Sep 2022 03:18:26 -0400 Subject: [PATCH] Update apcupsd docs to reflect support for config flow. (#24255) --- source/_integrations/apcupsd.markdown | 203 +++++++++++--------------- 1 file changed, 82 insertions(+), 121 deletions(-) diff --git a/source/_integrations/apcupsd.markdown b/source/_integrations/apcupsd.markdown index 6fade1a6494..a005b67204b 100644 --- a/source/_integrations/apcupsd.markdown +++ b/source/_integrations/apcupsd.markdown @@ -1,7 +1,6 @@ --- title: apcupsd description: Instructions on how to integrate apcupsd status with Home Assistant. -logo: apcupsd.png ha_category: - Binary Sensor - Sensor @@ -9,18 +8,21 @@ ha_category: ha_release: 0.13 ha_iot_class: Local Polling ha_domain: apcupsd +ha_config_flow: true +ha_codeowners: + - '@yuxincs' ha_platforms: - binary_sensor - sensor ha_integration_type: integration --- -[Apcupsd](http://www.apcupsd.org/) status information can be integrated into Home Assistant when the Network Information Server (NIS) [is configured](http://www.apcupsd.org/manual/manual.html#nis-server-client-configuration-using-the-net-driver) on the APC device. +[apcupsd](http://www.apcupsd.org/) status information can be integrated into Home Assistant when the Network Information Server (NIS) [is configured](http://www.apcupsd.org/manual/manual.html#nis-server-client-configuration-using-the-net-driver) on the APC device. There is currently support for the following device types within Home Assistant: - [Binary Sensor](#binary-sensor) -- [Sensor](#sensor) +- [Sensor](#sensors) ## Home Assistant add-on installation @@ -28,136 +30,95 @@ Install this [unofficial add-on](https://github.com/korylprince/hassio-apcupsd/) After installation, follow the instructions on the GitHub page to configure the plugin. Then continue to follow the integration configurations below. -## Configuration - -To enable this sensor, add the following lines to your `configuration.yaml`: - -```yaml -# Example configuration.yaml entry -apcupsd: -``` - -{% configuration %} -host: - description: The hostname/IP address on which the apcupsd NIS is being served. - required: false - type: string - default: localhost -port: - description: The port on which the apcupsd NIS is listening. - required: false - type: integer - default: 3551 -{% endconfiguration %} +{% include integrations/config_flow.md %}
-If you get `ConnectionRefusedError: Connection refused` errors in the Home Assistant logs, ensure the [Apcupsd](http://www.apcupsd.org/) configuration directives used by its Network Information Server is set to permit connections from all addresses [NISIP 0.0.0.0](http://www.apcupsd.org/manual/manual.html#configuration-directives-used-by-the-network-information-server), else non-local addresses will not connect. +If you get `ConnectionRefusedError: Connection refused` errors in the Home Assistant logs, ensure the [apcupsd](http://www.apcupsd.org/) configuration directives used by its Network Information Server is set to permit connections from all addresses [NISIP 0.0.0.0](http://www.apcupsd.org/manual/manual.html#configuration-directives-used-by-the-network-information-server), else non-local addresses will not connect. + +
- ## Binary sensor -In addition to the [Apcupsd Sensor](#sensor) devices, you may also create a device which is simply "on" when the UPS status is online and "off" at all other times. +This integration provides a binary sensor for the following information from apcupsd: -### Configuration +- UPS status -To enable this sensor, you first have to set up apcupsd integration (above), and add the following lines to your `configuration.yaml` file: +## Sensors -```yaml -# Example configuration.yaml entry -binary_sensor: - - platform: apcupsd -``` +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`. -{% configuration %} -name: - description: Name to use in the frontend. - required: false - type: string - default: UPS Online Status -{% endconfiguration %} +
-## Sensor +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. - The `apcupsd` sensor platform allows you to monitor a UPS (battery backup) by using data from the [apcaccess](https://linux.die.net/man/8/apcaccess) command. +
-### Configuration +- 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 (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) -To use this sensor platform, you first have to set up apcupsd integration (above), and add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -sensor: - - platform: apcupsd - resources: - - bcharge - - linev -``` - -{% configuration %} -resources: - description: Contains all entries to display. - required: true - type: list -{% endconfiguration %} - -### Example - -Given the following output from `apcaccess`: - -```yaml -APC : 001,051,1149 -DATE : 2016-02-09 17:13:31 +0000 -HOSTNAME : localhost -VERSION : 3.14.12 (29 March 2014) redhat -UPSNAME : netrack -CABLE : Custom Cable Smart -DRIVER : APC Smart UPS (any) -UPSMODE : Stand Alone -STARTTIME: 2016-02-09 16:06:47 +0000 -MODEL : SMART-UPS 1400 -STATUS : TRIM ONLINE -LINEV : 247.0 Volts -LOADPCT : 13.0 Percent -BCHARGE : 100.0 Percent -TIMELEFT : 104.0 Minutes -MBATTCHG : 5 Percent -MINTIMEL : 3 Minutes -MAXTIME : 0 Seconds -MAXLINEV : 249.6 Volts -MINLINEV : 244.4 Volts -OUTPUTV : 218.4 Volts -[...] -``` - -Use the values from the left hand column (lower case required). - -Full Example Configuration: - -```yaml -sensor: - - platform: apcupsd - resources: - - apc - - date - - hostname - - version - - upsname - - cable - - driver - - upsmode - - starttime - - model - - status - - linev - - loadpct - - bcharge - - timeleft - - mbattchg - - mintimel - - maxtime - - maxlinev - - minlinev - - outputv -```