/ Home Automation

Monitoring an APC Back-UPS With openHAB 2

openHAB doesn’t have a binding for APC UPS devices. Luckily, there are other ways to integrate them into your openHAB setup.

In the following, I’m describing how the exec binding can be used to regularly poll the UPS status using the apcaccess command-line utility.

The result will look somehow like this:

I’m using a APC Back-UPS BX 700VA here—a relatively cheap model with Schuko outlets and a USB connector.

Prerequisites

  • APC Back-UPS connected and configured (the apcaccess command needs to work)
  • Working openHAB 2 installation

Configuration

We’ll need to add a binding, a thing, various items, and finally an entry in the sitemap.

Bindings

As aforementioned, I’m using the exec binding to poll the status of the apcaccess command-line utility on a regular basis. To install the exec binding, add exec to the binding list in services/addons.cfg.

Example:

# A comma-separated list of bindings to install (e.g. "sonos,knx,zwave")
binding = exec

Things

To make the UPS status available to openHAB, create a new file called apc.things in your things directory and insert the following line:

Thing exec:command:apc [command="/sbin/apcaccess -u", interval=5, timeout=2, autorun=false]

The -u parameter will suppress any units (volts, percent, seconds, etc.) This makes parsing of the output much easier.

Note: The command above assumes that the apcaccess command-line utility is located in /sbin/. Adjust this path if necessary.

Items

Create a new file called apc.items in your items directory and insert the following contents:

String APC_Raw { channel="exec:command:apc:output" }

Group gAPC

String      APC_APC         (gAPC)
DateTime    APC_DATE        (gAPC)
String      APC_HOSTNAME    (gAPC)
String      APC_VERSION     (gAPC)
String      APC_UPSNAME     (gAPC)
String      APC_CABLE       (gAPC)
String      APC_DRIVER      (gAPC)
String      APC_UPSMODE     (gAPC)
DateTime    APC_STARTTIME   (gAPC)
String      APC_MODEL       (gAPC)
String      APC_STATUS      (gAPC)
Number      APC_LINEV       (gAPC)
Number      APC_LOADPCT     (gAPC)
Number      APC_BCHARGE     (gAPC)
Number      APC_TIMELEFT    (gAPC)
Number      APC_MBATTCHG    (gAPC)
Number      APC_MINTIMEL    (gAPC)
Number      APC_MAXTIME     (gAPC)
String      APC_SENSE       (gAPC)
Number      APC_LOTRANS     (gAPC)
Number      APC_HITRANS     (gAPC)
Number      APC_ALARMDEL    (gAPC)
Number      APC_BATTV       (gAPC)
String      APC_LASTXFER    (gAPC)
Number      APC_NUMXFERS    (gAPC)
DateTime    APC_XONBATT     (gAPC)
Number      APC_TONBATT     (gAPC)
Number      APC_CUMONBATT   (gAPC)
DateTime    APC_XOFFBATT    (gAPC)
String      APC_SELFTEST    (gAPC)
String      APC_STATFLAG    (gAPC)
String      APC_SERIALNO    (gAPC)
DateTime    APC_BATTDATE    (gAPC)
Number      APC_NOMINV      (gAPC)
Number      APC_NOMBATTV    (gAPC)
Number      APC_NOMPOWER    (gAPC)
String      APC_FIRMWARE    (gAPC)

The first item called APC_Raw holds the full output of the apcaccess utility. The other items don’t do anything yet—in the next step, we will create a rule to parse the output and assign values the individual items. The group gAPC is required by the rule, so don’t forget to specify it here.

Note: If you have a different model than I have, this list might not be 100% correct. Run apcaccess to get a list of parameters available for your UPS, and adjust the list accordingly.

Rules

Create a new file called apc.rules in your rules directory and insert the following contents:

import java.io.BufferedReader
import java.io.StringReader
import java.util.Calendar
import java.text.SimpleDateFormat
import java.text.ParseException

rule "APC: Parse raw output from command-line tool"
when
	Item APC_Raw changed
then
	var output = APC_Raw.state.toString
	var String line
	var String[] buffer
	var String value
	var bufReader = new BufferedReader(new StringReader(output))
	var Calendar cal = Calendar.getInstance()
	var formatStrings = newArrayList('yyyy-MM-dd HH:mm:ss Z', 'yyyy-MM-dd')
		
	while((line = bufReader.readLine()) != null) {
		buffer = line.split(':', 2)
		for (var i = 0; i < 2; i++) {
			buffer.set(i, buffer.get(i).trim())
    	}
    	
    	// check if there’s an item for this key (e.g. APC_STARTTIME)
    	var item = gAPC.members.findFirst[name.equals("APC_" + buffer.get(0))]

		if (item != null) {
			value = buffer.get(1)
			
			// DateTime item: try to parse date
			if (item.type == 'DateTime') {
				var succeeded = false
				for (String formatString : formatStrings) {
					try {
						if (!succeeded) { // no `break` statement in openHAB :(
							cal.setTime(new SimpleDateFormat(formatString).parse(value))
							item.postUpdate(new DateTimeType(cal).toString)
							succeeded = true
						}
					} catch (ParseException e) { }
				}
			// String or Number: just update the value
			} else {
				item.postUpdate(value)	
			}
		}
	}
	
end

Whenever APC_Raw changes, this rule will process the command’s output and will fill in the individual items with the correctly parsed values (these can be of type String, Number, or DateTime).

Sitemap

Finally, to expose these values, create an additional entry in your sitemap. If you’re using the default sitemap, open the file sitemaps/default.sitemap and add the following:

sitemap default label="Home" {

	// …

	Frame label="System Status" {
		Text label="UPS [%s]" item=APC_STATUS valuecolor=[APC_STATUS=="ONBATT"="#FF0000",APC_STATUS=="ONLINE"="#008000"] {
			Text item=APC_MODEL label="Model [%s]"
			Text item=APC_STATUS label="Status [%s]" valuecolor=[APC_STATUS=="ONBATT"="#FF0000",APC_STATUS=="ONLINE"="#008000"]
			Text item=APC_STARTTIME label="Start Time [%1$td/%1$tm/%1$ty %1$tH:%1$tM]"
			Text item=APC_LOADPCT label="Load [%.1f %%]"
			Text item=APC_TIMELEFT label="Time Left [%.1f min]"
			Text item=APC_LINEV label="Line Voltage [%.1f V]"
			Text item=APC_BATTV label="Battery Voltage [%.1f V]"
			Text item=APC_BATTDATE label="Battery Date [%1$td/%1$tm/%1$ty]"
		}
	}
}

As you can see, I haven’t added all available values here. Adjust this to your needs.

That’s it!

Bonus: Push Notification On Power Outage

To get a notification on your mobile device whenever the power fails (and also when it returns), configure the pushover binding and add the following rule to your apc.rules:

rule "APC: Notify power outage/return"
when
	Item APC_STATUS changed
then

	var msg = ''

	if (APC_STATUS.state == "ONLINE") {
		msg = "Power has returned"
	} else if (APC_STATUS.state == "ONBATT") {
		msg = "Power outage detected, remaining battery life: " + APC_TIMELEFT.state + " min"
	}
	
	if (msg != '') {
		logInfo("APC", msg)
		pushover(msg)
	}
end

Further Reading

Monitoring an APC Back-UPS With openHAB 2
Share this