Desc: Information about the snmp-ups driver, and SNMP UPSs with NUT
File: snmp-ups.txt
Date: 18 July 2002
Auth: Arnaud Quette <arnaud.quette@free.fr> or <arnaud.quette@mgeups.com>

This driver is an incomplete implementation of the SNMP protocol
for UPSs. It should support any UPS that is RFC 1628 (UPS Mib) compliant.

This driver is sponsored by MGE UPS SYSTEMS <http://www.mgeups.com>.

snmp-ups acts as a bridge from SNMP to NUT, thus allowing to monitor
in NUT any SNMP Agent (embedded or on a host). It doesn't allows the
translation of NUT informations to SNMP, which is part of another
project (UPS Sub-Agent) with UCD SNMP team.

This driver is BETA : it is not built by default, so you should type
"make snmp-ups" in NUT "drivers" directory.
(Un)Success reports are welcomed.

Requirements :
1) You MUST have installed UCD SNMP, also known as Net-SNMP, with
headers and libraries on your machine. See  http://www.net-snmp.org/ for
more informations.
For example, on a Red Hat 7.2, you need those packages :
    ucd-snmp-devel-4.2.3-1
    ucd-snmp-4.2.3-1
    ucd-snmp-utils-4.2.3-1

2) You need an SNMP-UPS-MIB.txt in you MIBs directory (/usr/share/snmp/mibs/
or other directory). 
This file is provided in NUT docs directory, but you may need to rebuild a
newer one by retrieving a recent RFC 1628 file (for example on 
http://www.faqs.org), and cut/paste the whole chapter 4 into a file named
SNMP-UPS-MIB.txt and save it in your MIBs directory.


The snmp-ups driver has the following syntax:

snmp-ups <UPS_unit>:		Start driver in background (normal operation).
				Note that <UPS_unit> is either the IP address
				or the name of the SNMP agent.

Optional parameters, available for "-x" command or in ups.conf, are :
-x community=<value> : Set community name (default=public)
-x snmp_version=<value> : Set SNMP version (default=v1, allowed v2c) 

Example of ups.conf :

[snmp]
        driver = snmp-ups
        port = Evolution
        community = public
        snmp_version = v1


Available NUT values are :

INFO_MFR		UPS Manufacturer
INFO_MODEL		UPS Model
INFO_FIRMREV		Firmware/Software Version
INFO_STATUS		OFF, OL, OB, BOOST, TRIM
INFO_BATTPCT		Battery percentage
INFO_RUNTIME		Predicted runtime on battery
INFO_BATTVOLT		Battery Voltage
INFO_OUTVOLT		Output Voltage

Planned values and commands are :

INFO_UTILITY		Input Voltage
INFO_ACFREQ		AC Frequency
INFO_UPSTEMP		UPS Temperature
INFO_LOADPCT		Load Percentage
CMD_?			Not determined

*****************************************************************************
Development informations :
**************************

This driver has been developed using :

- UCD SNMPD release 4.2.3-1
- a linux box (RH 7.2, kernel 2.4/2.5)
- an MGE UPS SYSTEMS Evolution 500 unit with SNMP card (ref 66245)
  For more information on those devices, see  <http://www.mgeups.com>.

The entry point of the MIB module describing Uninterruptible Power
Supplies is .1.3.6.1.2.1.33.

Translation between SNMP OIDs and NUT values :

NUT Name        | OID                            | SNMP Format details 
----------------+--------------------------------+-------------------------------------
INFO_MFR        | upsIdentManufacturer.0         | The name of the UPS manufacturer.
                | ".1.3.6.1.2.1.33.1.1.1.0"      | 
----------------+--------------------------------+-------------------------------------
INFO_MODEL      | upsIdentModel.0                | The UPS Model designation.
                | ".1.3.6.1.2.1.33.1.1.2.0"      |
----------------+--------------------------------+-------------------------------------
INFO_FIRMREV    | upsIdentAgentSoftwareVersion.0 | The UPS agent software version.
                | ".1.3.6.1.2.1.33.1.1.4.0"      | This variable may or may not have
                |                                | the same value as 
                |                                | upsIdentUPSSoftwareVersion in
                |                                | some implementations.
----------------+--------------------------------+-------------------------------------
INFO_STATUS     | upsOutputSource.0              | The present source of output power.
                | ".1.3.6.1.2.1.33.1.4.1.0"      | The enumeration none(2) indicates
                |                                | that there is no source of output
                |                                | power (and thus no output power).
                |                                | Enumerations: 1 - other, 2 - none,
                |                                | 3 - normal, 4 - bypass, 5 - battery,
                |                                | 6 - booster, 7 - reducer
----------------+--------------------------------+-------------------------------------
INFO_BATTPCT    | upsEstimatedChargeRemaining.0  | An estimate of the battery charge
                | ".1.3.6.1.2.1.33.1.2.4.0"      | remaining expressed as a percent of
                |                                | full charge.
----------------+--------------------------------+-------------------------------------
INFO_RUNTIME    | upsEstimatedMinutesRemaining.0 | An estimate of the time to battery
                | ".1.3.6.1.2.1.33.1.2.3.0"      | charge depletion under the present
                |                                | load conditions (...).
----------------+--------------------------------+-------------------------------------
INFO_BATTVOLT   | upsBatteryVoltage.0            |The magnitude of the present battery
                | ".1.3.6.1.2.1.33.1.2.5.0"      | voltage.
----------------+--------------------------------+-------------------------------------
INFO_UTILITY    | upsConfigOutputVoltage.0       | The magnitude of the nominal output
                | ".1.3.6.1.2.1.33.1.9.3.0"      | voltage.
----------------+--------------------------------+-------------------------------------
