Differences

This shows you the differences between two versions of the page.

--- supported_hardware:apc [2018/11/17 15:13] – [XTension Units] James Sentman
+++ supported_hardware:apc [2023/02/17 13:39] (current) – made list of settings an actual list for better readability James Sentman
@@ Line 1: / Line 1: @@
 ====APC UPS===
-{{:supported_hardware:apcexample.png?direct&300 |}}Monitoring an APC UPS via the [[http://www.apcupsd.org|apcupsd]] daemon. This plugin will connect to the apcupsd daemon and collect the battery state, AC power state, load percentage, time left and other important data even if the UPS in question isn’t physically connected to your Mac. If you wish to talk to a physically connected UPS please have a look at the original [[UPS]] plugin. You probably don’t actually want to have a UPS physically plugged into your Mac server anyway believe it or not, see below, but it can be very useful to be able to monitor the UPS anyway. You may have other computers, DVRs, WiFi access points, or other home automation nodes that are on separate UPS’s and it can be very helpful to be able to monitor those and know their approximate runtime and battery health as well. Installing this plugin and apcupsd on a raspberry pi can give you all that.
+{{:supported_hardware:apcexample.png?direct&300 |}}Monitoring an APC UPS via the [[http://www.apcupsd.org|apcupsd]] daemon. This plugin also works with many CyberPower brand UPS’s as well but you should verify that the UPS you’re considering is supported by the apcupsd app first. This plugin will connect to the apcupsd daemon and collect the battery state, AC power state, load percentage, time left and other important data even if the UPS in question isn’t physically connected to your Mac. If you wish to talk to a physically connected UPS please have a look at the original [[UPS]] plugin. You probably don’t actually want to have a UPS physically plugged into your Mac server anyway believe it or not, see below, but it can be very useful to be able to monitor the UPS anyway. You may have other computers, DVRs, WiFi access points, or other home automation nodes that are on separate UPS’s and it can be very helpful to be able to monitor those and know their approximate runtime and battery health as well. Installing this plugin and apcupsd on a raspberry pi can give you all that.
 There is a rather severe problem with connecting a UPS directly to a Mac OS Server. (not MacOSX Server, but any Mac acting as a server) You might wonder why you wouldn’t want to just connect the UPS to the computer? It will shut it down properly then and all will be well. Except that if you have the energy saver preferences set up to properly shut down your computer then it will not restart when the power comes back. There is a setting for most Macs to “restart after a power failure” but this only works if you let the power actually be pulled and NOT do a proper shutdown. The bug in MacOS is that this doesn’t work if you have a UPS connected to the machine! This has been broken for several major OS versions now. If you are running a Mac server and wish to use a UPS then you don’t actually want the UPS connected to the Mac or it will not restart without you there to push the button.
@@ Line 67: / Line 67: @@
 static ip_address=192.168.0.91/24
 static routers=192.168.0.1
-status domain_name_server=192.168.0.1 8.8.8.8 fd51:42f8:caae:d92e::1
+static domain_name_server=192.168.0.1 8.8.8.8 fd51:42f8:caae:d92e::1
 </code>
@@ Line 87: / Line 87: @@
 To install [[http://www.apcupsd.org|apcupsd]] run the command:
-sudo apt-get install apcupsd
+sudo apt install apcupsd
 to make sure that it is running at startup edit /etc/default/apcupsd via:
@@ Line 93: / Line 93: @@
 sudo nano /etc/default/apcupsd
-and change the single line from “isconfigured=no” to “isconfigured=yet” and save the file.
+and change the single line from “isconfigured=no” to “isconfigured=yes” and save the file.
 ====Configure APCUPSD====
@@ Line 106: / Line 106: @@
 uncomment if necessary and edit the following lines:
-UPSNAME (give it a short meaningful name, like main or myups or office or attic or something)
+  * UPSNAME (give it a short meaningful name, like main or myups or office or attic or something)
-UPSCABLE usb
+  * UPSCABLE usb
-UPSTYPE usb
+  * UPSTYPE usb
-DEVICE (this is the link to the serial port if it’s a serial device, for the USB version this line must be blank. It is not blank in the default settings and will not work for a USB device unless present, uncommented and blank)
+  * DEVICE (this is the link to the serial port if it’s a serial device, for the USB version this line must be blank. It is not blank in the default settings and will not work for a USB device unless present, uncommented and blank)
-POLLTIME 30 (this defaults to 60, I set mine to 30 don’t really know what the effect is as the data seems to change much faster than that anyway)
+  * POLLTIME 30 (this defaults to 60, I set mine to 30 don’t really know what the effect is as the data seems to change much faster than that anyway)
-NETSERVER on (this is important it’s how XTension will connect to it)
+  * NETSERVER on (this is important it’s how XTension will connect to it)
-NISIP 0.0.0.0 (this defaults to the 127.0.0.1 address meaning that it will only accept connections from the local host. If you want to be able to connect to it from XTension you must set it to 0.0.0.0)
+  * NISIP 0.0.0.0 (this defaults to the 127.0.0.1 address meaning that it will only accept connections from the local host. If you want to be able to connect to it from XTension you must set it to 0.0.0.0)
-NISPORT 3551 (this is the default, don’t change it, If you have to change it you can enter the port in XTension’s setup for this interface)
+  * NISPORT 3551 (this is the default, don’t change it, If you have to change it you can enter the port in XTension’s setup for this interface)
@@ Line 223: / Line 223: @@
 **Humidity**: The humidity of the room.
+====Interface Script====
+If you have installed the user scripts above then you can trap all broadcast events from the UPS inside the Interface Script. In the Edit Interface window click the “Edit” button for the interface script. Then use the “Insert...” toolbar button to insert the “UPS Event Handler” The AppleScript code that is inserted will give you a full list of the known events though depending on your model there may be others that could be sent as well.
+Some of the events are also reflected as Unit changes such as the power fail and error messages. Others can only be caught by installing this handler.
+<code>
+(*
+		U P S   E V E N T   H A N D L E R
+	Called when the UPS sends a broadcast event. This is where you
+	can trap events other than those that have units associated
+	with them. In order to receive these you must have installed the
+	xtevent script on the raspberry pi.
+	EventName will be one of the following:
+	annoyme
+		If we were letting the UPS shutdown our machine this is the alert that it is about
+		to happen. The events scripts stop the shutdown from happening however.
+	changeme
+		The battery needs changing. If we were allowing system shutdown that would happen next.
+		This event also turns on the ERROR unit.
+	commfailure
+		The UPS is no longer responding, possibly unplugged the USB cable?
+		This event also turns on the ERROR unit.
+	commok
+		Only sent after a commfailure event, the UPS is now responding.
+	doshutdown
+		When the config time limits or battery levels have dropped to the point that if it
+		were automatically going to shutdown it would now be doing so.
+	emergency
+		While in the software, nobody knows what would generate an emergency shutdown.
+	failing
+		The batteries are exhausted. The next event will be doshutdown.
+	loadlimit
+		The battery charge is below the low limit set in the config file.
+		The next event will be doshutdown
+	powerout
+		This is sent immediately when the power fails. It can also be generated during
+		a self test of the UPS.
+	onbattery
+		Send 5 or 6 seconds after the powerout event if the power has not returned.
+		This could be used to filter self test events. The timing of this can be set
+		in the config file.
+	offbattery
+		Send when power returns but only if the power has been off long enough to generate
+		the onbattery event.
+	mainsback
+		The power has returned
+	runlimit
+		The Time Left property of the battery has fallen below the configured value.
+	timeout
+		The maximum time on battery value in the configuration has expired.
+	startselftest
+		A self test has been detected. This may not be reliable depending on the onbattery timing
+	endselftest
+		The end of a self test has been detected.
+	battdetatch
+		The batteries have been disconnected
+	battattach
+		The batteries are reconnected
+*)
+on UPSEvent( EventName)
+  write log "UPS Event Received: " & EventName
+end UPSEvent
+</code>
 ====History====
   * The apcupsd plugin first appeared in XTension 9.4.12 on Oct 2nd 2018 and is written by James Sentman
   * Version 2.0 of the plugin added support for realtime event reception of power fails and other messages. It also stops the ups software from shutting down the pi and killing the power from the UPS early. It was released in XTension version 9.4.13 in November of 2018.