Created by gh-md-toc
This is a software plugin for the Indigo Home Automation Server. The plugin allows access to the current state information for many models of APC UPSes that can be physically attached to a computer via USB or a special networking cable.
Because of the volatile nature of individual components within GitHub repositories such as this one, please only download actual releases. Any other downloads may result in an incomplete plugin, repeated errors in the Indigo log and/or incorrect behavior of the plugin.
Note: This plugin requires a separate apcupsd software package (http://www.apcupsd.org) to be installed and running on whatever computer your APC UPS is physically connected to (not limited to Macs). While this separate package offers lots of configuration options, its default installation usually results in a perfectly usable setup for this plugin.
Unless otherwise noted, this plugin's releases should work without modifications with Indigo 6 and higher. With Indigo 5, minor steps after the plugin has been installed must be performed first—see below. It is possible the plugin might work in earlier versions of Indigo but no testing has been done on them.
If you are running a previous version of the plugin lower than 0.5.0 you will need to take some extra steps to migrate to the newer version. This should be a one-time activity, although future versions may have their own set of migration steps.
In the Finder:
Select the Go —> Go to Folder... menu option and enter the following path:
/Library/Application Support/Perceptive Automation/Indigo 7/Plugins (Disabled)
(change Indigo 7 to Indigo 6 or Indigo 5 as appropriate to match your version of Indigo)
This should refresh your Indigo apcupsd UPS device states, while retaining associated triggers, state condition tests, etc. Should these steps not work you will need to delete the apcupsd UPS device(s) and recreate them.
After you install the plugin you will need to configure it. These settings apply to all UPS devices monitored by this plugin. You may need to scroll the dialog's contents to see all the settings. In the Configure apcupsd dialog (Plugins —> apcupsd —> Configure... menu option) you:
All items on the Configure apcupsd dialog include tooltips—just hover over an item of interest for a quick reminder of its purpose.
Once configured, the plugin will allow you to create an Indigo device for each apcupsd instance (IP address and port) you have for your attached UPSes.
When creating an APCUPSD plugin device, you:
On the resulting Configure apcupsd UPS dialog (you may need to scroll to see all the settings):
All items on the Configure apcupsd UPS dialog include tooltips—just hover over an item of interest for a quick reminder of its purpose.
If you have setup one or more of the /etc/apcupsd/filename handler files (see Event Notifications, you can create Indigo triggers for the matching event(s) to allow near-realtime reaction to status changes in the UPS.
Even without Event Notifications, you can create triggers based upon device state value changes. These state changes are only updated as frequently as you have configured the plugin to poll the UPS devices so there may be some delay in the trigger event being activated by Indigo. For example, if you have a trigger set to watch for changes to a UPS device's TIMELEFT value and your polling frequency is every 5 minutes, the trigger can still test for values but should take note that if TIMELEFT is less than 5 (minutes) that another trigger may not occur before the UPS has shutdown. Testing against a value of less than 10 should still give the trigger a chance to take appropriate actions.
A set of commands are available in the Plugins —> apcupsd menu that can be used for specific on-demand features.
The separate apcupsd package provides a mechanism to perform site-specific steps when certain events are detected on a monitored UPS. One such step can be to send a notification to the Indigo server. This plugin contains an event notification server to receive those event notifications from the local apcupsd process, via its /etc/apcupsd/apccontrol shell script, and from instances of apcupsd running on remote systems via the same mechanism. This event server is not required to be used unless you plan to have the Indigo server react to UPS changes via triggers.
To enable the event server in the Plugins —> apcupsd —> Configure... dialog:
The screenshot in the Plugin Configuration section shows this feature enabled.
To send these external events to the plugin's event server, you need to edit the desired event handler files in /etc/apcupsd/filename. The following handlers (filename must match these names) are supported (create them if they do not exist and you want to receive that event in Indigo):
Add the following text to each handler file you wish to have send events to the Indigo APCUPSD plugin:
#!/bin/sh
source /etc/apcupsd/tell_indigo $(basename $0) "$1"
Open a Terminal (/Applications/Utilities/Terminal) window and issue this command (please Copy from this document and Paste the entire line into the Terminal window):
sudo cp -p "/Library/Application Support/Perceptive Automation/Indigo 7/Plugins"/apcupsd.indigoPlugin/Contents/Resources/tell_indigo /etc/apcupsd/
(change Indigo 7 to Indigo 6 or Indigo 5 as appropriate to match your version of Indigo)
Review and edit /etc/apcupsd/tell_indigo as needed to set the proper INDIGO_SERVER and INDIGO_PORT values. Note that if your Indigo device name contains a colon (:) or unicode characters then the /etc/apcupsd/tell_indigo script must use the matching numeric device ID. That can be accomplished within the example case statement in the script.
If you are comfortable with the command line interface of your Mac, you may wish to delete all but one of the handler files and then create them all again but as symlinks (not Finder aliases) to the one file you saved. In that way, you only need to edit one file to change all of the handlers.
Because Indigo 5 uses an older version of Python for its plugin execution, some minor code changes must be made to the plugin distribution to work with that older version of Python. These changes must be made any time the plugin is updated on your Indigo 5 system. Without making these code changes the plugin will not function properly and will log errors to the Indigo log on an on-going basis.
Open a Terminal (/Applications/Utilities/Terminal) window and issue this command (please Copy from this document and Paste the entire line into the Terminal window):
/Library/Application\ Support/Perceptive\ Automation/Indigo\ 5/Plugins\ \(Disabled\)/apcupsd.indigoPlugin/Contents/Resources/use_on_Indigo5
If you get a "No such file or directory" error and no "Starting" message, you do not have the plugin disabled.
Please use the APCUPSD Plugin discussion forum thread to post any issues, questions, ideas, etc.
Here is the plugin ID in case you need to programmatically restart the plugin:
com.martys.apcupsd
If you find that you do need to restart the plugin in this way, perhaps there is something that can be done in the code to lessen that need. Please bring it up in the forum.
This project is licensed using Unlicense. All mentioned software other than the plugin itself may be covered by different licenses.