Apcupsd

== Using apcupsd to Monitor a USB-Attached APC UPS ==
This wiki page shows how to install and configure the apcupsd package to monitor and report the statistics for an APC branded USB attached Uninterruptible Power Supply (UPS). The UPS model used in the examples is an APC SmartUPS 1000, but any APC or compatible model should work.
The end goal is to make the UPS status available over the network so it can be monitored and used to trigger actions in a home automation system like Home Assistant.
=== Installing and Configuring apcupsd ===
The first step is to add the alpine package for apcupsd. After that, we'll rename the default configuration file and replace them with the parameters needed for our example USB attached APC Smart-UPS.
Installation is by an APK package:
There is one main configuration file called /etc/apcupsd/apcupsd.conf that has all the tunable parameters along with many comments. We'll keep the original as a reference and then edit the parameters to suit.
Now, edit the parameters in using the backup copy of the original file as a reference for comments. Some of the important parameters are listed below in order of appearance.
* UPSNAME - This is to identify your UPS. Exact format is not important, but keep it short and don't use spaces.
* UPSCABLE - For a USB attached UPS, use the value usb
* USBTYPE - Similar to USBCABLE, use usb
* DEVICE - For a USB attached UPS, the parameter is not needed. Comment this line by using a # at the beginning.
These four changes are enough to get started. Everything else can be left as default. Read the comments in the original file to find out what the other parameters do and if you want to use them.
== Starting apcupsd ==
The apcupsd package installs a service that allows you to control apcupsd using the standard tools. The following example shows how to start it and ensure it starts each time the system boots.
 
 alpine:/# rc-service apcupsd start
 * Starting APC UPS daemon ...
 alpine:/# rc-update add apcupsd
 * service apcupsd added to runlevel default
== Checking the Configuration ==
The apcaccess command will communicate with the UPS via the apcupsd daemon's network port and report back what it finds. This is a good way to test your connection and configuration.
A successful test will look similar to what's shown below. 
 
 alpine:/# apcaccess
 APC : 001,043,1022
 DATE : 2024-10-12 15:31:10 +0000
 HOSTNAME : alpine.home
 VERSION : 3.14.14 (31 May 2016) unknown
 UPSNAME : SmartUPS_1000
 CABLE : USB Cable
 DRIVER : USB UPS Driver
 UPSMODE : Stand Alone
 ...
The actual list of reported parameters is much longer, but the first few lines show the ones that have been customized in the configuration thus far. If you see the message Error contacting apcupsd @ localhost:3551: Connection refused, check to ensure the apcupsd service is running.
== Configuring and Testing Email Alerts ==
apcupsd will send alerts for important events using shell scripts in the directory. These scripts and their alert functions are listed below.
* changeme - sends an alert when batteries have reached the end of their useful life
* commfailure - apcupsd cannot communicate with the UPS
* commok - communication with the UPS has been restored after a failure
* offbattery - the UPS is back to running on mains power after running on battery
* onbattery - the ups has switched to battery power
All of the scripts have a similar setup and rely on two environment variables, SYSADMIN and APCUPSD_MAIL, to deliver email alerts. To test the alerts, temporarily export these two variables and run one of the scripts from the command-line. The example below shows how to send a test alert for battery change.
If all goes well, you should receive an email telling you the UPS battery needs changing NOW. If you find you need to use different values for SYSADMIN or APCUPSD_MAIL, be sure to make those changes in . The exported variables used in the test are temporary and will lost after you log out.
== Next Steps ==
Further configuration can be done to initiate automatic shutdown using the parameters in apcupsd.conf (see the original commented file apcupsd.conf~ for details.) You may also monitor the UPS via home automation using Home Assistant and the APC UPS Daemon integration.