User Tools

Site Tools


supported_hardware:apc

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
Next revisionBoth sides next revision
supported_hardware:apc [2018/11/14 12:29] James Sentmansupported_hardware:apc [2019/11/21 13:52] – [Give Your Pi a Static IP] fixed incorect “static” written incorrectly as “status” in the example wlan0 setup James Sentman
Line 67: Line 67:
 static ip_address=192.168.0.91/24 static ip_address=192.168.0.91/24
 static routers=192.168.0.1 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> </code>
  
Line 182: Line 182:
 ====XTension Setup==== ====XTension Setup====
  
-{{:supported_hardware:apcsetup.png?direct&400 |}} Create a new interface in XTension and select “APC UPS Status” from the Device popup. Enter the static IP address you just gave to your Pi above and then the port. If you didn’t change it in the configuration file then it’s running on port 3551. Give the interface a descriptive name so that you can tell all your UPS’s apart. Click the save button, find the new interface in the Interface Status window and check it’s enabled checkbox to start it up.+{{:supported_hardware:apcsetup.png?direct&425 |}} Create a new interface in XTension and select “APC UPS Status” from the Device popup. Enter the static IP address you just gave to your Pi above and then the port. If you didn’t change it in the configuration file then it’s running on port 3551. Give the interface a descriptive name so that you can tell all your UPS’s apart.
  
 +Set the polling times. You can set separate polling times for when the power is on and then the power is off. I don’t need to see every single change in load when things are working fine and so the default for AC On Polling time is 30 seconds. Once the power goes off though I want to see updates to the battery charge and time left more often so the default for polling times when the power is off is every 10 seconds. When the interface is running you can manually poll it for new information with the Poll Now button.
 +
 +The Event Broadcast Port is set by the xtevent.py script you installed above. Immediate events are sent to XTension via a UDP broadcast on this port. If you change this port in XTension then you must edit the xtevent.py script on your raspberry pi to match or you won’t receive any realtime events.
 +
 +Click the save button, find the new interface in the Interface Status window and check it’s enabled checkbox to start it up.
 ====XTension Units==== ====XTension Units====
 {{ :supported_hardware:apcunits.png?direct&650|}} Once the interface is enabled and running you will be presented with a list of units created automatically by the interface. They will be given a default name that is based on the name you gave the interface and then the function. {{ :supported_hardware:apcunits.png?direct&650|}} Once the interface is enabled and running you will be presented with a list of units created automatically by the interface. They will be given a default name that is based on the name you gave the interface and then the function.
    
-**AC Power**: shows online and is in an on state as long as the AC power is available. Since I’m polling the UPS relatively slowly it may not catch very short interruptions in power. If you need an immediate event about the loss and restoration of power let me know as that can probably be done through further software on the Pi. You may wish to change the default colors for this unit so that it displays green when the power is on and red when the power is off as it’s the off state that is the warning state.+**AC Power**: shows online and is in an on state as long as the AC power is available. This is updated by the realtime user scripts we installed on the pi and also from polling. This way you can catch very short power failures that would not have been caught due to the normal intermittent polling. Note that in order to receive these real time events XTension and your UPS monitor Pi must be on the same subnet. You may wish to change the default colors for this unit so that it displays green when the power is on and red when the power is off as it’s the off state that is the warning state.
  
 **Error**: sometimes the software will append an error message to the status line. I have seen “LOWBATT” when my ups battery wasn’t going to be able to service the high load. This unit will display either “none” or the message sent. It will be off as long as there is no error and will turn on to alert you that the UPS has sent some error message. Use the On script to notify yourself of an error message from the UPS. Note that this is not the same as a failed battery self test, that message handled separately see the “Self Test Failure” unit below. **Error**: sometimes the software will append an error message to the status line. I have seen “LOWBATT” when my ups battery wasn’t going to be able to service the high load. This unit will display either “none” or the message sent. It will be off as long as there is no error and will turn on to alert you that the UPS has sent some error message. Use the On script to notify yourself of an error message from the UPS. Note that this is not the same as a failed battery self test, that message handled separately see the “Self Test Failure” unit below.
Line 204: Line 209:
  
 **Self Test Failure**: If no self test has been run since the program connected then this unit will be in an off state and show “none”. Once a test has been run while it’s watching the unit label will change to “OK” unless there is a problem. If a self test failure of the battery or the load or whatever happens the label will change to the error message and the unit will turn on. Use the on script to notify yourself of a failed self test. **Self Test Failure**: If no self test has been run since the program connected then this unit will be in an off state and show “none”. Once a test has been run while it’s watching the unit label will change to “OK” unless there is a problem. If a self test failure of the battery or the load or whatever happens the label will change to the error message and the unit will turn on. Use the on script to notify yourself of a failed self test.
 +
 +**On Battery**: When the power has been out long enough for the UPS to be sure it isn’t a self test this unit will turn on. This is usually 5 or 6 seconds after a power failure. This will not turn on for power failure events shorter than that duration. This could be useful as you might turn off loads that are plugged into the UPS that are not necessary in a long term power failure condition to reduce the load and increase the runtime.
 +
 +**Charging**: Once power has returned and the UPS has switched off the On Battery unit this unit will turn on until the batteries are fully charged.
  
 If your device supports these additional readings then units to create them will be setup as well. Most simpler units do not support these. If your device supports these additional readings then units to create them will be setup as well. Most simpler units do not support these.
Line 215: Line 224:
 **Humidity**: The humidity of the room. **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==== ====History====
-The apcupsd plugin first appeared in XTension 9.4.12 on Oct 2nd 2018 and is written by James Sentman+  * 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. 
supported_hardware/apc.txt · Last modified: 2023/02/17 13:39 by James Sentman