rickslab-ups-utils 1.3.0

Description:

rickslabupsutils 1.3.0

rickslab-ups-utils
A set of utilities to monitor and react to the status of a set of supported UPSs.
Installation
There are currently 3 possible ways of installing rickslab-ups-utils as summarized here:


Repository -
You can always clone the repository and run that version. This is useful if you want to contribute to the project.



PyPI -
Meant for users wanting to run the very latest version. All PATCH level versions are released
here first. This installation method is also meant for users not on a Debian distribution.




Rickslab.com Debian -
Lags the PyPI release in order to assure robustness. May not include every PATCH version.




User Guide
For a detailed introduction, a community sourced
User Guide
is available. All tools are demonstrated and use cases are presented. Additions
to the guide are welcome. Please submit a pull request with your suggested additions!
Commands
ups-ls
This utility displays most relevant parameters for installed and compatible
UPSs listed in the ups-config.json file. By default, all available parameters
are displayed. The --input and --output options can be used to get relevant
UPS input and output parameters. With the --list_commands option, the
utility will list all available SNMP commands for the configured UPS. With
the --list_params option, the daemon configuration parameters will be listed.
The --list_decoders option will display list of all MiB decoders available
for the UPS defined as daemon target. The --verbose will cause informational
messages to be displayed and --no_markup option will result in plain text
output instead of color coded text. The logger is enabled with the --debug
option.
ups-daemon
With no options specified, the utility will give the current status of the
UPS configured with daemon = true in the ups-config.json file. With the
--daemon option, ups-daemon will continuously check the status of the
UPS. When it detects that the UPS is sourcing powering from the battery,
it will check the amount of time it has been running on battery and run
the specified suspend script when the specified threshold is exceeded. It
will execute the specified resume script when it detects power has resumed.
When the utility detects a Battery Low event from the UPS or that time
remaining for battery or the battery charge is below specified thresholds,
then the shutdown script will be executed. If ups-daemon detects a return
to line power has occurred before the shutdown has completed, it will
execute the cancel shutdown script. With the --verbose option set,
event update messages will be output, otherwise, only events are output.
The --no_markup option will cause the output to be in plain text, with
no color markup codes. The --logfile filename option is used to specify
a logfile, but is not implemented at this time. The threshold and script
definitions must be made in the ups-utils.ini file using
ups-utils.ini.template as a template. The logger is enabled with the
--debug option. The --ltz option will result in the use of the local
time zone in the monitor window and logs. This will be the local time of
where the app is running, not the location of the UPS. The default is UTC.
ups-mon
A utility to give the current state of all compatible UPSs. The default
behavior is to continuously update a text based table in the current window
until Ctrl-C is pressed. With the --gui option, a table of relevant
parameters will be updated in a Gtk window. You can specify the delay
between updates with the --sleep N option where N is an integer > 10 that
specifies the number of seconds to sleep between updates. The threshold for
color coding definitions read from the ups-utils.ini file. This can be
created from a template ups-utils.ini.template, that is part of the
installation package. ups-utils.ini.template as a template. The --log
option is used to write all monitor data to a psv log file. When writing
to a log file, the utility will indicate this in red at the top of the
window with a message that includes the log file name. The --status
option will output a table of the current status. By default, unresponsive
UPSs will not be displayed, but the --show_unresponsive can be used to
force their display. The logger is enabled with the --debug option. The
--ltz option will result in the use of the local time zone in the
monitor window and logs. This will be the local time of where the app is
running, not the location of the UPS. The default is UTC.
New in Current Release - v1.3.0

Implemented Enum objects as keys.
Defaults to text ups-mon window when Gtk is not available.
Code clean up.

Known Issues
The utility currently supports:

APC UPS with AP9630 and AP9641 NMC
EATON UPS with PowerWalker NMC. I had an issue with voltage interpretation, and
found that PowerWalker does not support the use of their NMC with Eaton UPS. But it
mostly works anyway. I no longer have any Eaton UPSs for testing.

It monitors the specified UPSs using snmp v2c. I have not implemented the
ability to listen to snmp traps yet, as I still have some research to do.
If you have different UPS and would like to extend the dictionary in this
code
to support it, feel free to make a pull request.
Reference Material

apc-ups-snmp
Partial List of OIDs for APC UPS
Another Partial List of OIDs for APC UPS
Another Partial List of OIDs for APC UPS
APC Reference
snmp utilities
MIB Browser
Eaton PowerWalker NMC

History
New in Previous Release - v1.2.11

Fix GObject.timeout_add deprecation.
Update repository installation guide and add requirements file.
Many minor changes.

New in Previous Release - v1.2.10

Optimize ups-ls --about output.
Improved messaging to aid new users in configuring new setup.
Detect specification of multiple daemon UPS. Must only be one target daemon UPS.

New in Previous Release - v1.2.9

Fixed error handling for config file reading.
Exit ups-daemon if no daemon ups is defined.
Added details on adding upsutils group and other configuration details.

New in Previous Release - v1.2.8

Improved ups-mon --gui eventual stack overflow. Still hangs after long
runs. I need some help on this one.
Add time of last read to ups-mon header.
Implemented option to display/log in local time. Local time is the time
where the application is running; not the location of the UPS.

New in Previous Release - v1.2.7

Updates to the User Guide.
Cleaned up implementation of GuiComp object.
Fixed an error in the calculation of time on battery and battery remaining
for APC. Now just store time in minutes in data structure and drop the string version.
Include time on battery in color coding logic.
More code optimizations.
Improved LOGGER.debug messages.

New in Previous Release - v1.2.5

Improved message for skipped parameters.
Rewrite daemon configuration reader to make more robust.
Catch errors for json and config readers and handle with feedback to user.
User guide updates.

New in Previous Release - v1.2.4

More robust reading of config file. Missing items will generate a warning
message and defaults will be used.
The PyPI installation still seems to include ups-monitor, so I will print
message and inform user to use ups-mon instead.

New in Previous Release - v1.2.3

Fixed issue in installation instructions that indicated gpu instead of ups.
More error checking. Make APC NMC names backward compatible and more flexible.

New in Previous Release - v1.2.2

Fixed crash when config files are missing and improved feedback to help
user resolve. Update documents to make more clear to user on how to setup.
Modified the --about of ups-ls to aid user in configuring the utility.

New in Previous Release - v1.2.1

Fixed issue in referencing PyPI install resource paths.

New in Previous Release - v1.2.0

Delay sys exit on failure to allow more information to be available for user to troubleshoot.
Check file permissions for security issues and exit if not secure.
Determine installation type (Local Git Repository, PyPI, or Debian), and force use
of Debian location for configuration files if it is a debian installation.
The ups-utils.ini file is now only required for ups-daemon. Other utilities will
use defaults if missing.
Added verbose option to ups-daemon to output status message for normal readings.
Changes in documentation to describe steps necessary to secure snmp shared secret.
Added check of configuration files readability.
Implement code improvements from gpu-utils project.
Move listing like functions from ups-daemon to ups-ls.
Complete rewrite.
USR1 signal will cause ups-mon and ups-daemon to reread daemon ini file.
Moved logic of daemon parameter color coding to the daemon class.

New in Previous Release - v1.0.0

Initial Release - Full functionality and working debian package!