upssched

title: upssched(8)

text:
# upssched(8)

## NAME
upssched - Timer helper for scheduling events from upsmon

## SYNOPSIS
upssched [OPTIONS] [NOTIFYMSG]

Note upssched should be run from upsmon(8) via the NOTIFYCMD. You should never run it directly during normal operations.

upssched -l

List currently tracked timer events, if any. Report as a TAB-separated table of: NAME, TIMEOUT_ABS, TIMEOUT_REL, NOTIFYTYPE, UPSNAME, NOTIFYMSG.

## DESCRIPTION
upssched was created to allow users to execute programs at times relative to events being monitored by upsmon(8). The original purpose was to allow for a shutdown to occur after some fixed period on battery, but there are other uses that are possible.

## COMMON OPTIONS
-h

Show the command-line help message.

-V

Show NUT version banner. More details may be available if you also export NUT_DEBUG_LEVEL=1 or greater verbosity level.

-D

Raise the debugging level. Use this option multiple times for more details.

## OPTIONS
By default upssched processes its configuration file and executes or queues calls to its CMDSCRIPT, or cancels some previously queued item(s), based on configuration and the NOTIFYTYPE it receives. One exception to this is the queue listing mode -l.

-l

List pending timers (if any) and exit.

NOTIFYMSG

Optionally pass a text message (typically originates from upsmon(8) call to upssched as its NOTIFYCMD) as an environment variable named NOTIFYMSG to the CMDSCRIPT launched by upssched immediately or after a timer expires.

## INTEGRATION
upssched needs to be called as the NOTIFYCMD in your upsmon.conf(5). It determines what is happening based on the UPSNAME and NOTIFYTYPE environment variables. You should never have to deal with them directly.

Set the EXEC flag on the events that you want to see in upssched. For example, to make sure that upssched hears about ONLINE, ONBATT and LOWBATT events, the flags would look like this:

```
NOTIFYFLAG ONLINE EXEC
NOTIFYFLAG ONBATT EXEC
NOTIFYFLAG LOWBATT EXEC
```

If you also want to continue writing to the syslog, just add it in:

```
NOTIFYFLAG ONLINE SYSLOG+EXEC
NOTIFYFLAG ONBATT SYSLOG+EXEC
NOTIFYFLAG LOWBATT SYSLOG+EXEC
```

For a full list of notify flags, see the upsmon(8) documentation.

Please note that command execution is synchronous (with the called upssched tool process in case of EXECUTE directive, or with the timer process). Consider using your system shell abilities like & to send long-duration handling to the background and let upssched timer daemon continue. This should not impact upsmon daemon, which handles each notification in a separate sub-process (and so not a problem for immediate EXECUTE events).

## CONFIGURATION
See upssched.conf(5) for information on configuring this program.

## EARLY SHUTDOWNS
To shut down the system early, define a timer that starts due to an ONBATT condition. When it triggers, make your CMDSCRIPT call your shutdown routine. It should finish by calling upsmon -c fsd so that upsmon gets to shut down the slaves in a controlled manner.

Be sure you cancel the timer if power returns (ONLINE).

## EARLY PREPARATION FOR A SHUTDOWN ON UPSMON PRIMARY INSTANCE
The upsmon(8) primary instance is responsible for telling the UPS(es) to power off at the end of emergency shutdown. As such, if there are several clients, the primary instance raises an "FSD" (Forced Shut Down) flag on the data server for each UPS it manages, and waits for secondary instances to log off (or for a timeout to expire). If there are activities that should happen on the primary upsmon’s computer during shutdown which take a long time, you can use the FSD notification to begin those operations while the primary upsmon instance waits for the secondaries to complete their shutdowns.

If you have several UPSes, you may want to combine several notifications with the START-TIMER-SHARED directive (with a short timeout), so you only react once. Alternately, if the needed activity varies by the UPS (e.g. custom remote-device shutdown scripts), you may actually want to use EXECUTE rules right away (and dispatch further work in your CMDSCRIPT).

## DEBOUNCING EVENTS
If your UPS goes on and off battery frequently, you can use this program to reduce the number of pager messages that are sent out. Rather than sending pages directly from upsmon(8), use a short timer here. If the timer triggers with the UPS still on battery, then send the page. If the power returns before then, the timer can be cancelled and no page is necessary.

## BACKGROUND
This program was written primarily to fulfill the requests of users for the early shutdown scenario. The "outboard" design of the program (relative to upsmon) was intended to reduce the load on the average system. Most people don’t have the requirement of shutting down after N seconds on battery, since the usual OB+LB testing is sufficient.

This program was created separately so those people don’t have to spend CPU time and RAM on something that will never be used in their environments.

The design of the timer handler is also geared towards minimizing impact. It will come and go from the process list as necessary. When a new timer is started, a process will be forked to actually watch the clock and eventually start the CMDSCRIPT. When a timer triggers, it is removed from the queue. Cancelling a timer will also remove it from the queue. When no timers are present in the queue, the background process exits.

This means that you will only see upssched running when one of two things is happening:

•There’s a timer of some sort currently running

•upsmon just called it, and you managed to catch the brief instance

The final optimization handles the possibility of trying to cancel a timer when there are none running. If the timer daemon isn’t running, there are no timers to cancel, and furthermore there is no need to start a clock-watcher. So, it skips that step and exits sooner.

## ENVIRONMENT VARIABLES
NUT_DEBUG_LEVEL sets default debug verbosity if no -D arguments were provided on command line, but does not request that the daemon runs in foreground mode.

Note Unlike some other NUT daemons, upssched with enabled debug does not stop reporting on stderr! It forks a background process with the first call as an event handler, which exits soon after all tracked timers have elapsed and were handled (if needed).

UPSNAME and NOTIFYTYPE are required, as detailed above. They are set by upsmon when it calls upssched as its choice of NOTIFYCMD.

NUT_CONFPATH is the path name of the directory that contains upssched.conf and other configuration files. If this variable is not set, upssched uses a built-in default, which is often /usr/local/ups/etc.

## FILES
upssched.conf(5)

## SEE ALSO
upsmon(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


upsimage.cgi

package: nut-cgi

title: upsimage.cgi(8)

summary: Image\-generating helper for upsstats.cgi

text:
# upsimage.cgi(8)

## NAME
upsimage.cgi - Image-generating helper for upsstats.cgi

## SYNOPSIS
upsimage.cgi

Note As a CGI program, this should be invoked through your web server. If you run it from the command line, it will either complain about unauthorized access or spew a PNG at you.

## DESCRIPTION
upsimage.cgi generates the graphical bars that make up the right side of the page generated by upsstats.cgi(8). These represent the current battery charge, utility voltage, and UPS load where available.

The images are in PNG format, and are created by linking to Boutell’s excellent gd library.

For details about configuring some popular web servers to run NUT CGI programs, please see the upsset.conf(5) page.

## ACCESS CONTROL
upsstats will only talk to upsd(8) servers that have been defined in your hosts.conf(5). If it complains about "Access to that host is not authorized", check that file first.

## FILES
hosts.conf(5)

## SEE ALSO
upsd(8), upsstats.cgi(8)

### Internet resources:
•The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/

•The gd home page: http://libgd.bitbucket.org


upsset.cgi

title: upsset.cgi(8)

summary: Web\-based UPS administration program

text:
# upsset.cgi(8)

## NAME
upsset.cgi - Web-based UPS administration program

## SYNOPSIS
upsset.cgi

Note As a CGI program, this should be invoked through your web server. If you run it from the command line, it will sit there until you give it input resembling a POST request.

## DESCRIPTION
upsset.cgi is a read-write NUT client which lets you access many administrative functions within the UPS software from your web browser. You can change settings and invoke instant commands where available.

For details about configuring some popular web servers to run NUT CGI programs, please see the upsset.conf(5) page.

## CHANGING SETTINGS
Some UPS hardware allows you to change certain variables to other values. To see what’s available, pick a UPS from the chooser and select "settings", then select "View" to update the page.

You should see a list of items with the descriptions on the left side and the possible options or input spaces on the right. After changing something, be sure to "Save changes" to update the values in your UPS.

If your UPS doesn’t support any read/write variables, there will be nothing to do on this page.

Setting values in read/write variables can also be done from the command line with upsrw(8).

## INSTANT COMMANDS
Some UPS hardware also has provisions for performing certain actions at the user’s command. These include battery tests, battery calibration, front panel tests (beep!) and more. To access this section, do as above, but pick "Commands" as the function.

If your UPS supports any instant commands, they will be listed in a chooser widget. Pick the one you like and "Issue command" to make it happen.

Note Some dangerous commands like "Turn off load" may not happen right away. This is a feature, not a bug.

The apcsmart(8) driver and some others require that you send this command twice within a short window in order to make it happen. This is to keep you from accidentally killing your systems by picking the wrong one.

To actually turn off the load, you have to send the command once, then send it again after 3 seconds elapse but before 15 seconds pass. If you do it too quickly or slowly, you have to wait at least 3 seconds but not 15 seconds again.

You can also invoke instant commands from the command line with upscmd(8).

## ACCESS CONTROL
It sends commands and settings via the server upsd(8) to your driver, which manages the hardware for you. You must use credentials defined in upsd.users(5) file on that data server with appropriate permissions.

upsset will only talk to upsd(8) servers that have been defined in your hosts.conf(5). If it complains about "Access to that host is not authorized", check your hosts.conf first.

## SECURITY
upsset will not run until you convince it that your CGI directory has been secured. This is due to the possibility of someone using upsset to try password combinations against your upsd(8) server.

See the example upsset.conf file for more information on how you do this. The short explanation is—if you can’t lock it down, don’t try to run it.

## FILES
hosts.conf(5), upsset.conf(5)

## SEE ALSO

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


upsstats.cgi

title: upsstats.cgi(8)

summary: Web\-based UPS status viewer

text:
# upsstats.cgi(8)

## NAME
upsstats.cgi - Web-based UPS status viewer

## SYNOPSIS
upsstats.cgi

Note As a CGI program, this should be invoked through your web server. If you run it from the command line, it will either complain about unauthorized access or spew a bunch of HTML at you.

## DESCRIPTION
upsstats.cgi is a read-only NUT client which uses template files to build web pages containing status information from UPS hardware. It can repeat sections of those template files to monitor several devices simultaneously, or focus on a single UPS.

These templates can also include references to upsimage.cgi(8) for graphical displays of battery charge levels, voltage readings, and the UPS load.

For details about configuring some popular web servers to run NUT CGI programs, please see the upsset.conf(5) page.

Note On platforms with required program file name extensions, like Windows, you may have to use e.g. a *.cgi.exe extension for the programs in HTML template files (UPSSTATSPATH, UPSIMAGEPATH).

## ACCESS CONTROL
upsstats will only talk to upsd(8) servers that have been defined in your hosts.conf(5). If it complains that "Access to that host is not authorized", check that file first.

## TEMPLATES
The web page that is displayed is actually a template containing commands to upsstats which are replaced by status information.

The default file used for the overview of devices is upsstats.html. An alternate template may be provided by &template_list=... CGI query option; relevant file must be allowed via CUSTOM_TEMPLATE_LIST option in hosts.conf(5).

When monitoring a single UPS, the file displayed is upsstats-single.html. An alternate template may be provided by &template_single=... CGI query option; relevant file must be allowed via CUSTOM_TEMPLATE_SINGLE option in hosts.conf(5).

Alternate templates must be structured similarly to default ones, located in the same directory, and contain .htm in the file name. You can specify in the query string part of the URI (for example, in your local index.html and/or added cells of header.html) as e.g.

```
.../cgi-bin/upsstats.cgi?template_single=custom-s.html&template_list=custom-l.html
```

The format of these files, including the possible commands, is documented in upsstats.html(5).

## JSON OUTPUT
In addition to processing HTML templates, upsstats.cgi can be invoked as a JSON API by adding the json parameter to the query string (e.g., ?json or &json).

When this parameter is present, the CGI script bypasses all HTML template parsing and instead returns a JSON object.

The structure of the JSON output depends on whether the host parameter is also provided:

•Multi-host (Default): If no host parameter is specified, the script returns a single JSON object containing an "devices" key. This key holds an array, with each element in the array being a JSON object representing a monitored UPS.

•Single-host Mode: If a host parameter is provided (e.g., ?host=myups@localhost&json), the script returns a single JSON object for that UPS (it will not be wrapped in an "devices" array).

In both modes, each UPS object includes:

•host: The UPS identifier (e.g., "myups@localhost")

•desc: The host description from hosts.conf

•status_raw: The raw status string (e.g., "OL")

•status_parsed: An array of human-readable status strings (e.g., ["Online"])

•vars: An object containing the full tree of all available variables for that UPS (e.g., "battery.charge": "100", "ups.model": "...")

## FILES
hosts.conf(5), upsstats.html(5), upsstats-single.html

## SEE ALSO
upsimage.cgi(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


nut-ipmipsu

package: nut-driver-ipmi

title: nut-ipmipsu(8)

text:
# nut-ipmipsu(8)

## NAME
nut-ipmipsu - Driver for IPMI Power Supply Units (PSU)

## SYNOPSIS
nut-ipmipsu -h

nut-ipmipsu -a PSU_NAME [OPTIONS]

Note This driver is experimental, and still a work-in-progress. Feedback is encouraged.

Note This man page only documents the hardware-specific features of the nut-ipmipsu driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
This driver should support a wide range of PSUs through local IPMI interface.

nut-ipmipsu currently uses the GNU FreeIPMI project, for IPMI implementation.

## EXTRA ARGUMENTS
This driver doesn’t support any optional settings.

## INSTALLATION
This driver may be not built by default. You can build it by installing the libfreeipmi-dev dependencies and using configure --with-ipmi=yes.

You also need to give proper permissions on the local IPMI device file (/dev/ipmi0 for example) to allow the NUT user to access it.

An udev rules file (nut-ipmipsu.rules) is provided and automatically installed on an udev enabled system. This file is generally installed in /etc/udev/rules.d/, or /lib/udev/rules.d/ on newer systems, to address the permission settings problem.

For more information, refer to scripts/udev/README.adoc in NUT sources.

## INSTANT COMMANDS
This driver doesn’t support any instant commands.

## IMPLEMENTATION
The port value is used to identify the PSU. For instance, to target FRU 0x2, use the following in ups.conf:

```
[pdu]

        driver = nut-ipmipsu

        port = id2
```

This driver will report various information related to a PSU, including:

•manufacturer, model, serial and part numbers,

•nominal voltage and frequency,

•actual current and voltage,

•status of the PSU:

•OL means that the PSU is present and providing power,

•OFF means that the PSU is present but not providing power (power cable removed),

•stale (no data) means that the PSU is not present (i.e. physically removed).

Here is an example output for a Dell r610 server:

```
device.mfr: DELL
device.mfr.date: 01/05/11 - 08:51:00
device.model: PWR SPLY,717W,RDNT
device.part: 0RN442A01
device.serial: CN179721130031
device.type: psu
driver.name: nut-ipmipsu
driver.parameter.pollinterval: 2
driver.parameter.port: id2
driver.version: 2.6.1-3139M
driver.version.data: IPMI PSU driver
driver.version.internal: 0.01
input.current: 0.20
input.frequency.high: 63
input.frequency.low: 47
input.voltage: 232.00
input.voltage.maximum: 264
input.voltage.minimum: 90
ups.id: 2
ups.realpower.nominal: 717
ups.status: OL
ups.voltage: 12
```

## KNOWN ISSUES

### Using host names for UPS NMC
An UPS network management card may be assigned a fixed/static IP address or a dynamic one (e.g. by DHCP) in your network. Due to this, you may want or have to use a dynamic naming service to access the UPS. Note that this may become a problem specifically during large outages and shutdowns, when your DHCP/DNS server might already go down while the driver needs to resolve the name involved (especially during late-shutdown hooks, when a new instance of the driver program might start just to tell the UPS to power off or to power-cycle).

It may be wise to ensure your OS name service client can cache the UPS name sufficiently long, or to use fixed IP addressing (and an entry in /etc/hosts for good measure, so you only have one spot to eventually re-configure this).

## AUTHOR
Arnaud Quette <arnaud.quette@free.fr>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
•The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/

•GNU FreeIPMI home page: http://www.gnu.org/software/freeipmi/


snmp-ups

package: nut-driver-snmp

title: snmp-ups(8)

summary: Multi\-MIB Driver for SNMP UPS equipment

text:
# snmp-ups(8)

## NAME
snmp-ups - Multi-MIB Driver for SNMP UPS equipment

## SYNOPSIS
snmp-ups -h

snmp-ups -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the snmp-ups driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
The snmp-ups driver automatically detects and supports a wide range of devices by loading various MIBS, such as:

ietf

UPS that is RFC 1628 (UPS MIB) compliant, e.g. MGE UPS SYSTEMS, Liebert, perhaps others (default)

mge

MGE UPS SYSTEMS and MGE Office Protection Systems devices with SNMP cards (ref 66062, 66045, 66074 and 66244)

apcc

APC AP9605, AP9606, AP9617, and AP9618 APC network management cards, as well as any others supporting the APC POWERNET MIB

netvision

Socomec Sicon UPS with Netvision Web/SNMP management card/external box

eaton_pw_nm2

Powerware devices with ConnectUPS SNMP cards, as well as UPSes with Eaton Gigabit Network Cards (Network-M2) (renamed from pw)

eaton_pxg_ups

Eaton devices with Power Xpert Gateway UPS Card (renamed from pxgx_ups)

aphel_genesisII

Eaton Powerware ePDU Monitored

aphel_revelation

Eaton Powerware ePDU Managed

raritan

Various Raritan PDUs (Dominion PX, PM, RPC)

raritan-px2

Various Raritan PDUs (Dominion PX2)

baytech

Various BayTech PDUs

cpqpower

HP/Compaq AF401A management card, perhaps others

cyberpower

Cyberpower RMCARD201. Should also support RMCARD100 (net version), RMCARD202 and RMCARD301

huawei

Huawei UPS5000-E, perhaps others

tripplite

TrippLite UPSes; at this time this is the IETF MIB mapping with just the Tripplite entry point OID to verify the device vendor, and a real hardware-specific configuration will be added in the future development.

For a complete and up-to-date listing, you can query the driver by passing the mibs=--list argument (see below).

## EXTRA ARGUMENTS
This driver supports the following optional settings in the ups.conf(5):

port=hostname[:port]

Set SNMP hostname, or IP address, and port number of the peer SNMP agent. There is no default for the hostname, but the default port is 161.

mibs=--list

A special option which allows to list the currently known MIB-to-NUT mappings and exit the driver binary, intended for command-line usage like this:

```
:; snmp-ups -a snmp-test -x mibs=--list
```

mibs=name

Set MIB compliance (default=auto, allowed entries: refer to SUPPORTED HARDWARE above). With "auto", the driver will try a select set of SNMP objects until it finds one that the device responds to.

Note that since NUT 2.6.2, snmp-ups has a new method that uses sysObjectID (which is a pointer to the preferred MIB of the device) to detect supported devices. This renders void the requirement to use the "mibs" option.

community=name

Set community name (default is public) for SNMPv1 and SNMPv2c connections. Note that an RW capable community name is required to change UPS settings and send commands (such as for a power-down).

snmp_version=version

Set SNMP version (default = v1, allowed: v2c, v3)

snmp_retries=retries

Specifies the number of Net-SNMP retries to be used in the requests (default=5)

snmp_timeout=timeout

Specifies the Net-SNMP timeout in seconds between retries (default=1)

symmetrathreephase

Enable APCC three phase Symmetra quirks (use on APCC three phase Symmetras): Convert from three phase line-to-line voltage to line-to-neutral voltage (default: not enabled)

pollfreq=num

Set polling interval for full updates, in seconds, to reduce SNMP network traffic relative to the quick updates performed every "pollinterval" (the latter option is described in ups.conf(5)). The default value is 30 (in seconds).

notransferoids

Disable the monitoring of the low and high voltage transfer OIDs in the hardware. This will remove input.transfer.low and input.transfer.high from the list of variables. This should only be used on APCC Symmetra equipment which has strangeness in the three-phase power reporting.

secLevel=value

Set the securityLevel used for SNMPv3 messages (default=noAuthNoPriv, allowed: authNoPriv,authPriv) This parameter is mandatory if you use non-trivial authentication.

secName=value

Set the securityName used for authenticated SNMPv3 messages (no default)

authPassword=value

Set the authentication pass phrase used for authenticated SNMPv3 messages (no default)

privPassword=value

Set the privacy pass phrase used for encrypted SNMPv3 messages (no default)

authProtocol=value

Set the authentication protocol (MD5, SHA, SHA256, SHA384 or SHA512) used for authenticated SNMPv3 messages (default=MD5). Note that the exact protocol list depends on Net-SNMP library capabilities; check help of the snmp-ups binary program for the run-time supported list.

privProtocol=value

Set the privacy protocol (DES, AES, AES192 or AES256) used for encrypted SNMPv3 messages (default=DES). Note that the exact protocol list depends on Net-SNMP library capabilities; check help of the snmp-ups binary program for the run-time supported list.

## REQUIREMENTS
You will need to install the Net-SNMP package from http://www.net-snmp.org/ before building this driver.

SNMP v3 also requires OpenSSL support from http://www.openssl.org.

## LIMITATIONS

### Shutdown
The shutdown sequence should be tested before relying on NUT to send a shutdown command to the UPS. The problem is that the host network stack may have been torn down by the time the driver is invoked to send the shutdown command. The driver attempts to send shutdown.return, shutdown.reboot, and load.off.delay commands to the UPS in sequence, stopping after the first supported command.

### Using host names for UPS NMC
An UPS network management card may be assigned a fixed/static IP address or a dynamic one (e.g. by DHCP) in your network. Due to this, you may want or have to use a dynamic naming service to access the UPS. Note that this may become a problem specifically during large outages and shutdowns, when your DHCP/DNS server might already go down while the driver needs to resolve the name involved (especially during late-shutdown hooks, when a new instance of the driver program might start just to tell the UPS to power off or to power-cycle).

It may be wise to ensure your OS name service client can cache the UPS name sufficiently long, or to use fixed IP addressing (and an entry in /etc/hosts for good measure, so you only have one spot to eventually re-configure this).

## INSTALLATION
This driver is only built if the Net-SNMP development files are present at configuration time. You can also force it to be built by using configure --with-snmp=yes before calling make.

## EXAMPLES
The hostname of the UPS is specified with the "port" value in ups.conf, and may include a non-standard (161) remote peer port:

```
        [snmpv1]

                driver = snmp-ups

                port = snmp-ups.example.com

                community = public

                snmp_version = v1

                pollfreq = 15

                desc = "Example SNMP v1 device"

        [snmpv3]

                driver = snmp-ups

                port = 166.99.224.132:170

                snmp_version = v3

                secLevel = authPriv

                secName = mysecurityname

                authPassword = myauthenticationpassphrase

                privPassword = myprivatepassphrase

                desc = "Example SNMP v3 device, with the highest security level"
```

## AUTHORS
•Arnaud Quette

•Dmitry Frolov

•Jim Klimov

## SEE ALSO

### The core driver:
nutupsdrv(8)

### NUT SNMP Protocols Library
Available at: https://www.networkupstools.org/ups-protocols.html#_snmp

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


package: nut-server

title: al175(8)

text:
# al175(8)

## NAME
al175 - Driver for Eltek UPS models with AL175 alarm module

## SYNOPSIS
al175 -h

al175 -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the al175 driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
The al175 driver is known to work with the following UPSes:

•Eltek MPSU4000 with AL175 alarm module

It may also work with other UPSes equipped with AL175 alarm module, but they have not been tested.

AL175 have to be configured to operate in COMLI mode. See documentation supplied with your hardware on how to do it.

## EXTRA ARGUMENTS
This driver does not support any extra settings in the ups.conf(5).

## INSTANT COMMANDS
This driver supports some extra commands (see upscmd(8)):

test.battery.start

Start a battery test.

test.battery.stop

Stop a battery test.

## VARIABLES
Besides status, this driver reads UPS state into following variables:

•ups.test.result

•output.voltage.nominal

•output.current

•battery.voltage.nominal

•battery.current

•battery.temperature

•input.transfer.boost.low

## KNOWN ISSUES AND BUGS
•Shutdown is not supported. FIXME

•The driver was reworked to meet the project code quality criteria, without testing on real hardware. Some bugs may have crept in.

## AUTHOR
Kirill Smelkov <kirr@mns.spb.ru>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


apcsmart

title: apcsmart(8)

text:
# apcsmart(8)

## NAME
apcsmart - Driver for American Power Conversion Smart Protocol UPS equipment

## SYNOPSIS
apcsmart -h

apcsmart -a UPS_NAME [-x option=value ...]

Note This man page only documents the hardware-specific features of the apcsmart driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
The apcsmart driver should recognize (or at the very least, work with) the majority of Smart-UPS models — which includes Smart-UPS, Matrix-UPS and Back-UPS lineups, among few other ones.

Currently, we can roughly divide APC hardware into four groups (note that the division isn’t strict by any means, and the borders between those are pretty fuzzy):

[very] "old" models

These models usually have old APC logo, white color and no programmable EEPROM; you won’t find them listed anywhere on APC’s site either. The support for those will be usually based on driver’s compatibility tables, or if the model (firmware) is not listed in those — the driver will try to follow the very basic subset of features, while still trying to remain useful. Despite "smart" tagname, they often tend to behave in pretty dumb way (see the section below about shutdown behaviour). Example models:

•Smart-UPS 2000I

•Smart-UPS 900I

"new" models

These models usually come from late 1990s / pre-2009 times. They are often referred to as "3rd. gen". For the most part, they have programmable EEPROM, report supported commands and capabilities, and should work just fine with the apcsmart driver.

"microlink" models

WARNING: These are not natively supported by apcsmart (or as of this writing by apcupsd, for that matter, if you’re wondering). Around 2007, APC (now APC Schneider) decided to go back to its proprietary roots, and all the new models (SMT, SMX, SURTD) use completely different protocol and cables. If you purchased a new APC UPS — that uses cable with RJ45 on the one end, and DB-9 on the other — then you have such model. Your only option to support it through NUT is to purchase a "legacy communications card" — part #AP9620 (google AP9620 for more details). Or if that’s not an option, rely on official software. UPDATE:. Later releases of apcupsd claimed support for new APC protocols, so it is worth checking if apcupsd software would work with your device, and apcupsd-ups NUT driver would handle it as part of NUT-managed ecosystem.

Microsol models

Several Microsol serial models sold in Brazil have been rebranded as APC Back-UPS, and the model numbers tend to start with "BZ". If you have one of these "Nobreaks", they will not work with the apcsmart driver — please see the solis(8) driver instead. Example models:

•Back-UPS BZ1200-BR

•Back-UPS BZ2200BI-BR

Another thing to remember is that Smart protocol is not USB protocol. If you have UPS with both USB and serial ports, then depending on how you connect it, you will need either apcsmart or usbhid-ups driver.

## CABLING
This driver expects to see a 940-0024C cable or a clone by default. You can switch to the 940-0095B dual-mode cable support with the cable= definition described below.

If your 940-xx24X cable is broken or missing, use this diagram to build a clone:

https://www.networkupstools.org/cables.html#_940_0024c_clone

Note The "xx" is either "00" for a short cable, or the number of feet of a longer cable. The "X" is a letter representing the minor revision of the physical cable and its connectors ("C" and "E" are commonly found revisions). All minor revisions should use the same pin-outs and wiring.

You can specify alternate cable in ups.conf(5):

```
*cable*=940-0095B
```

Alternatively, you can also provide it on the command line using:

```
-x *cable*=940-0095B
```

## TTY MODES
By default the driver works in canonical mode, but it proved to be a problem in Windows systems. Furthermore there’s a possibility of some obscure serial cards or serial-USB converters that could cause problems as well. You can use ttymode= option to force non-canonical discipline in ups.conf(5):

```
*ttymode*=raw
```

Alternatively, you can also provide it on the command line using:

```
-x *ttymode*=raw
```

Note Any other value will make the driver work in the canonical mode.

## EXPLANATION OF SHUTDOWN METHODS SUPPORTED BY APC UPSES
APC hardware supports a lot of shutdown methods, that themselves can differ in behaviour quite a bit, depending on the model.

S (soft hibernate)

This is most basic command present in probably all APC models. It will hibernate the UPS, and subsequently wake it up when the mains supply returns. The command doesn’t work if the UPS is running on mains. "old" models:

The behaviour here is unfortunately pretty primitive - when the power returns, the UPS just wakes up. No grace periods, no min. battery charge condition, etc. This is probably not what you want.

"new" models:

The behaviour here is as expected — the power is cut off after the EEPROM defined grace period. The UPS will wake up when the power returns, after the EEPROM defined delay AND if the EEPROM defined min. battery charge level is met. The delay is counted from the power’s return.

CS (aka "force OB hack")

This is a trick to make UPS power down even if it’s running on mains. Immediately before issuing S, "simulate power failure" is issued. The remaining behaviour is as in S case. There’s a delay between "simulate power failure" and S — by default set to 3.5s. You can control it through cshdelay option (allowed values are from 0 to 9.9).

The name came from APC CS models, where such trick was used to power down UPSes in consistent fashion using only S. It’s better to use @nnn command if your UPS supports it (and is not too old, see below).

@nnn (hard hibernate)

This is basic command used to hibernate UPS regardless if it’s running on batteries or on mains. The option takes 3 digits argument which can be used to specify additional wake-up delay (in 6 minute units). "old" models:

The behaviour is — unfortunately — similarly primitive to S. The UPS unconditionally wakes up after nnn*6 minutes: it doesn’t care if the power returned !

Note

If nnn = 000, then UPS will do precisely nothing. On those models you should better specify nnn > 0, if you can estimate the kind of power problems that might be happening in your environment.

Another thing to consider with "old" models — you might lose the connection with the UPS, until it wakes up (with S, the serial connection is kept alive).

"new" models:

All the usual variables defined in EEPROM are respected (see S). Additionally, if nnn > 0, the nnn*6 minutes are added to EEPROM defined delay. UPS will not power up if it’s running on batteries, contrary to what "old" models used to do — the combined delay is counted from the moment of power return.

Supposedly there exist models that take 2 digits instead of 3. Just in case, NUT also supports such variation. You have to provide exactly 2 digits to trigger it (awd option, or argument to one of the supported instant commands).

K (delayed poweroff)

This is permanent poweroff — the UPS will not wake up automatically. On newer units, it will respect applicable EEPROM variables.

Z (instant poweroff)

This is also permanent poweroff — the UPS will not wake up automatically. The poweroff is executed immediately.

## SHUTDOWN CONTROL BY NUT
There are three options used to control the shutdown behaviour.

sdtype=[0-5]

This option takes a single digit (0-5) as an argument. See below for details.

advorder=no|[0-4]+

This option takes string of digits as an argument. Methods listed are tried in turn until one of them succeeds. Note that the meaning of digits is different from sdtype. See below for details.

awd=[0-9]{1,3}

This option lets you specify additional wake-up delay used by @. If you provide exactly 2 digits, the driver will try 2 digits variation (see previous section for more info). Otherwise standard 3 digits variation is used. Note: the time unit is 6 minutes !

Keep in mind that sdtype and advorder are mutually exclusive. If advorder is provided, sdtype is ignored. If advorder is set to no, sdtype is used instead.

If nothing is provided, NUT will assume sdtype=0 — which is generally fine for anything not too ancient or not too quirky.

### SDTYPE
The values permitted are from 0 to 5. Only one can be specified. Anything else will cause apcsmart to exit.

0

issue soft hibernate (S) if the UPS is running on batteries, otherwise issue hard hibernate (@)

1

issue soft hibernate (S) (if on batteries), and if it fails (or on mains) — try hard hibernate (@)

2

issue instant poweroff (Z)

3

issue delayed poweroff (K)

4

issue "force OB hack" (CS)

5

issue hard hibernate (@)

Note Hard hibernate’s additional wake-up delay can be provided by awd.

### ADVORDER
The argument is either a word no, or a string of 1..5 digits in [0..4] range. Each digit maps to the one of shutdown methods supported by APC UPSes. Methods listed in this way are tried in order, until one of them succeeds.

If advorder is undefined or set to no, sdtype is used instead.

The mapping is as follows:

0

soft hibernate (S)

1

hard hibernate (@)

2

delayed poweroff (K)

3

instant poweroff (Z)

4

"force OB hack" (CS)

Note Hard hibernate’s additional wake-up delay can be provided by awd.

## IGNORING LB STATE
APC units — even if they report LB mode — will not go into shutdown automatically. This gives us even more control with reference to "when to actually shutdown PSU". Since version 2.6.2, NUT supports ignorelb option in driver’s section of ups.conf(5). When such option is in effect, the core driver will ignore LB state as reported by specific driver and start shutdown basing the decision only on two conditions:

```
battery.charge < battery.charge.low
```

OR

```
battery.runtime < battery.runtime.low
```

Of course — if any of the variables are not available, the appropriate condition is not checked. If you want to explicitly disable one of the conditions, simply override the right hand variable causing the condition to always evaluate to false (you can even provide negative numbers).

APC UPSes don’t have battery.charge.low — you will have to define it if you want to use such condition (prefix the variable with override. or default.).

"New" units have battery.runtime.low, but depending on battery quality, firmware version, calibration and UPS load — this variable can be underestimated quite a bit — especially right after going into OB state. This in turn can cause LB to be asserted, which under normal conditions will cause NUT to initiate the shutdown. You might want to disable this condition entirely, when relying on ignorelb option (this was actually the main motivation behind introduction of such feature).

Simple example:

```
[apc]

    ignorelb

    override.battery.charge.low = 15

    override.battery.runtime.low = -1
```

This would cause apcsmart to go into shutdown only if detected battery charge < 15%. Runtime condition is always false in this example.

You could ask — why bother? Well, the reason is already hinted above. APC units can be very picky about the batteries, and their firmware can underestimate the remaining runtime (especially right after going into OB state). ignorelb option and override.* let you remain in control of the UPS, not UPS in control of you.

Furthermore, this allows to specify conditions similarly to how it’s done in apcupsd daemon, so it should be welcome by people used to that software.

## SUPPORTED INSTANT COMMANDS
The apcsmart driver exposes following instant commands:

shutdown.return

executes soft hibernate

shutdown.return cs

executes "force OB hack"

shutdown.return at:<nbr>

executes "hard hibernate" with <nbr>*6 minutes additional wake-up delay (<nbr> format is the same as of awd option)

shutdown.stayoff

executes "delayed poweroff"

load.off

executes "instant poweroff"

All the above commands must be issued 2nd time to have any effect (no less than 3 seconds, and no more than 15 seconds after the initial call). Those commands are mostly useful for manual testing, when your machine is not powered by the UPS you’re testing.

Other supported commands:

•load.on

•test.panel.start

•test.failure.start

•test.battery.start

•test.battery.stop

•bypass.start

•bypass.stop

•calibrate.start

•calibrate.stop

## PREVIOUS DRIVER VERSION
Previous driver is still available as apcsmart-old, should there be any need to use earlier version (bugs, incompatibilities with new functionality, etc.). In due time, apcsmart-old will be phased out completely, but this won’t happen until the new version gets solid exposure with no pending issues.

## BUGS
Some older APC UPS models return bogus data in the status register during a front panel test. This is usually detected and discarded, but some other unexpected values have occasionally slipped through.

APC UPS models with both USB and serial ports require a power cycle when switching from USB communication to serial, and perhaps vice versa.

## AUTHORS AND HISTORY
Nigel Metheringham <Nigel.Metheringham@Intechnology.co.uk> (drawing heavily on the original apcsmart driver by Russell Kroll) wrote a driver called newapc for a time, which was renamed in the 1.5 series.

In 2.6.2 that driver was renamed finally to apcsmart-old, being superseded by this updated version with new features which currently holds the apcsmart name, and is maintained by Michal Soltys <soltys@ziu.info>.

## SEE ALSO
nutupsdrv(8), ups.conf(5), usbhid-ups(8), solis(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


apcsmart-old

title: apcsmart-old(8)

text:
# apcsmart-old(8)

## NAME
apcsmart-old - Driver for American Power Conversion Smart Protocol UPS equipment

## SYNOPSIS
apcsmart-old -h

apcsmart-old -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the apcsmart-old driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
apcsmart-old should recognize all recent APC models that use a serial protocol at 2400 bps. This is primarily the Smart-UPS, Matrix-UPS and Back-UPS Pro lines.

The driver attempts to support every bell and whistle of the APC reporting interface, whether or not this is strictly sensible.

Some older hardware may only report a handful of variables. This is usually not a bug—they just don’t support anything else.

## CABLING
This driver expects to see a 940-0024C cable or a clone by default. You can switch to the 940-0095B dual-mode cable support with the cable= definition described below.

If your 940-0024C cable is broken or missing, use this diagram to build a clone:

https://www.networkupstools.org/cables/940-0024C.jpg

## EXTRA ARGUMENTS
This driver supports the following optional settings in the ups.conf(5):

cable=940-0095B

Configure the serial port for the APC 940-0095B dual-mode cable.

sdtype=num

Use shutdown type num, according to this table: 0

soft shutdown or powerdown, depending on battery status

1

soft shutdown followed by powerdown

2

instant power off

3

power off with grace period

4

"force OB" hack method for CS 350

Modes 0 and 1 will power up the load when power returns. Modes 2 and 3 will keep the load turned off when the power returns.

Mode 4 exploits an oddity in the CS 350 models since they only seem to support the S command, but then only when running on battery. As a result, the driver will force the UPS to go on battery if necessary before sending the shutdown command. This ensures that the load gets reset.

## BUGS
Some older APC UPS models return bogus data in the status register during a front panel test. This is usually detected and discarded, but some other unexpected values have occasionally slipped through.

APC UPS models with both USB and serial ports require a power cycle when switching from USB communication to serial, and perhaps vice versa.

## AUTHORS AND HISTORY
Nigel Metheringham <Nigel.Metheringham@Intechnology.co.uk> (drawing heavily on the original apcsmart driver by Russell Kroll).

This driver was called newapc for a time and was renamed in the 1.5 series.

In 2.6.2 the driver was renamed to apcsmart-old, being superseded by updated version with new features which currently holds the apcsmart name.

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


apcupsd-ups

title: apcupsd-ups(8)

summary: Driver for apcupsd client access

text:
# apcupsd-ups(8)

## NAME
apcupsd-ups - Driver for apcupsd client access

## SYNOPSIS
apcupsd-ups -h

apcupsd-ups -a UPS_NAME [OPTIONS]

Note This man page only documents the specific features of the apcupsd-ups driver. For information about the core driver, see nutupsdrv(8).

## DESCRIPTION
This driver is a client to apcupsd (another UPS monitoring project).

apcupsd-ups acts as an apcupsd client, simply forwarding data. This can be useful in cases where both protocols are required in a network, or in case apcupsd code base has a required UPS access mode missing from NUT.

## EXTRA ARGUMENTS
This driver supports the following optional settings in nut.conf(5):

port=<hostname>[:<port>]

This is the name of a remote host running apcupsd (plus an optional port).

For instance:

```
[apcupsd]

        driver = apcupsd-ups

        port = localhost

        desc = "apcupsd client"
```

For IPv6 addresses, use square brackets for the hostname part (so colons in it are not mistaken to be the port, especially if using the default one):

```
[apcupsd]

        driver = apcupsd-ups

        port = "[::1]:3551"

        desc = "apcupsd client"
```

## BACKGROUND
This driver was originally written in one evening to allow interoperating with apcupsd.

## SUPPORTED VARIABLES
The following variables are translated from apcupsd to NUT. All times should be converted to seconds (please file a bug if you notice a mismatch in units).

apcupsd variable

NUT variable(s)

BCHARGE

battery.charge

MBATTCHG

battery.charge.low

RETPCT

battery.charge.restart

BATTDATE

battery.date

TIMELEFT

battery.runtime

MINTIMEL

battery.runtime.low

BATTV

battery.voltage

NOMBATTV

battery.voltage.nominal

LINEFREQ

input.frequency

SENSE

input.sensitivity

HITRANS

input.transfer.high

LOTRANS

input.transfer.low

LASTXFER

input.transfer.reason

LINEV

input.voltage

MAXLINEV

input.voltage.maximum

MINLINEV

input.voltage.minimum

NOMINV

input.voltage.nominal

LINEFREQ

output.frequency

OUTPUTV

output.voltage

NOMOUTV

output.voltage.nominal

DATE

ups.date, ups.time

DSHUTD

ups.delay.shutdown

DWAKE

ups.delay.start

FIRMWARE

ups.firmware, ups.firmware.aux

UPSNAME

ups.id

LOADPCT

ups.load

MANDATE

ups.mfr.date

NOMPOWER

ups.realpower.nominal

SERIALNO

ups.serial

STATUS

ups.status

ITEMP

ups.temperature

STESTI

ups.test.interval

SELFTEST

ups.test.result

## LIMITATIONS
Access to apcupsd is strictly read only: no commands can be issued. This stems from the design of apcupsd, where the settings are changed in apctest. In order to run apctest, apcupsd must be stopped (and it is apcupsd that exposes the UPS to the network and to this NUT driver as its client).

## AUTHOR
Andreas Steinmetz

## SEE ALSO
ups.conf(5), nutupsdrv(8)

### Internet Resources:
•The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/

•The apcupsd home page: http://www.apcupsd.org/

•Development of apcupsd project itself seems to have stalled in 2016/2017, with release 3.14.14 being the latest official tag. Its community discussions do remain quite active, however.

•Just in case, a replica of its sources is stored at https://github.com/networkupstools/apcupsd


bcmxcp

title: bcmxcp(8)

text:
# bcmxcp(8)

## NAME
bcmxcp - Driver for UPSes supporting the serial BCM/XCP protocol

## SYNOPSIS
bcmxcp -h

bcmxcp -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the bcmxcp driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
This driver should recognize all serial BCM/XCP-compatible UPSes. It has been developed and tested on Powerware PW5115 and PW9120 hardware.

If your UPS has a USB connection, you may also consult the bcmxcp_usb(8) driver documentation.

## EXTRA ARGUMENTS
This driver supports the following optional settings in the ups.conf(5).

shutdown_delay=delay

The number of seconds that the UPS should wait between receiving the shutdown command (upsdrvctl shutdown) and actually shutting off.

baud_rate=rate

Communication speed for the UPS. If this is set to 9600, it tries to connect to the UPS at 9600bps. If it fails to communicate, it will go into baud-hunting. It starts at 1200 and goes up to 19200. If it succeeds, it tell you the speed it connected with. If not included in the config, it defaults to baud-hunting.

## DEFAULT VALUES FOR THE EXTRA ARGUMENTS
•shutdown_delay = 120

•baud_rate = none

## INSTANT COMMANDS
This driver supports the following Instant Commands:

shutdown.return

Turn off the load and return when power is back.

shutdown.stayoff

Turn off the load and remain off.

test.battery.start

Start a battery test.

outlet.n.shutdown.return

Turn off the load on outlet n and return when power is back. (n is the outlet number reported by the upsc command)

## TODO LIST
Report UPS statistics information

BCM/XCP supports reporting of UPS statistics data.

Change settings

Access the config register to change settings.

## BUGS
None known.

## AUTHOR
Tore Ørpetveit <tore@orpetveit.net>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### The USB BCM/XCP driver:
bcmxcp_usb(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


title: bcmxcp_usb(8)

text:
# bcmxcp_usb(8)

## NAME
bcmxcp_usb - Experimental driver for UPSes supporting the BCM/XCP protocol over USB

## SYNOPSIS
bcmxcp_usb -h

bcmxcp_usb -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the bcmxcp_usb driver. For information about the core driver, see nutupsdrv(8).

Note This driver is a variant of the serial driver bcmxcp(8) and uses the same core code.

## SUPPORTED HARDWARE
This driver should recognize all BCM/XCP-compatible UPSes that are connected via USB. It has been developed and tested on Powerware PW3501 hardware. It also has been tested on PW5110 hardware.

## EXTRA ARGUMENTS
This driver supports the following optional settings in the ups.conf(5).

shutdown_delay = delay

The number of seconds that the UPS should wait between receiving the shutdown command and actually shutting off.

Note This driver does not currently support USB-matching settings common to other drivers, such as vendor, vendorid, product, productid, serial, device or bus.

## DEFAULT VALUES FOR THE EXTRA ARGUMENTS
shutdown_delay =120

## INSTANT COMMANDS
This driver supports the following Instant Commands:

shutdown.return

Turn off the load and return when power is back.

shutdown.stayoff

Turn off the load and remain off.

test.battery.start

Start a battery test.

## TODO LIST
Report UPS alarm status

BCM/XCP supports reporting a wide range of UPS alarm conditions.

Report UPS statistics information

BCM/XCP supports reporting of UPS statistics data.

## EXPERIMENTAL DRIVER
This driver has been tagged experimental, even if it has been reported to be stable. Thus it is not suitable for production systems and it may be not built by default. This is mainly due to the fact that it is a new driver.

## INSTALLATION
This driver may be not built by default. You can require building it by using ./configure --with-usb=yes (note that it will also install other USB drivers), or ./configure --with-drivers=bcmxcp_usb. Either way, you would need libusb-dev (libraries and headers package) or equivalent for other platforms.

You also need to install manually the hotplug files (libhidups and libhid.usermap), generally in etc/hotplug/usb/, to address the permission settings problem. Lastly note that the libhidups file must have execution flag set (ie using chmod +x ...).

## IMPLEMENTATION
bcmxcp_usb only supports 1 UPS at this time. You can put the "auto" value for port in ups.conf, i.e.:

```
[pw3105]

        driver = bcmxcp_usb

        port = auto
```

## KNOWN ISSUES AND BUGS

###  Got EPERM: Operation not permitted upon driver startup""
You have forgotten to install the hotplug files, as explained in the INSTALLATION section above. Don’t forget to restart hotplug so that it applies these changes.

## AUTHORS
•Tore Ørpetveit <tore@orpetveit.net>

•Wolfgang Ocker <weo@weo1.de>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


belkin

title: belkin(8)

summary: Driver for Belkin serial UPS equipment

text:
# belkin(8)

## NAME
belkin - Driver for Belkin serial UPS equipment

## SYNOPSIS
belkin -h

belkin -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the belkin driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
The belkin driver is known to support the Regulator Pro 525 (F6C525-SER). Other similar models such as the 425 and 625 should also work.

The Trust UPS and older Belkin units are not supported.

This driver only supports serial connections. If your UPS has a USB port, please consult the Hardware Compatibility List (HCL) to see which of the USB drivers you should use.

## EXTRA ARGUMENTS
This driver does not support any extra settings in the ups.conf(5).

## BUGS
There are dragons lurking within the protocol to this UPS. I have one that essentially behaves like a glorified power strip due to some invasive probing on my part. Don’t mess with it directly.

Note The driver doesn’t go anywhere near these character sequences, so it won’t zap your UPS. I only mention this here as yet another reminder of the perils of closed hardware.

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Other Belkin drivers:
belkinunv(8), blazer_ser(8), blazer_usb(8), usbhid-ups(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


belkinunv

title: belkinunv(8)

summary: Driver for Belkin Universal UPS and compatible

text:
# belkinunv(8)

## NAME
belkinunv - Driver for Belkin "Universal UPS" and compatible

## SYNOPSIS
belkinunv -h

belkinunv -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the belkin driver. For information about the core driver, see nutupsdrv(8).

Note This driver only supports serial connections. If your UPS has a USB port, please consult the Hardware Compatibility List (HCL) to see which of the USB drivers you should use.

## SUPPORTED HARDWARE
The belkinunv driver is known to work with the Belkin Universal UPS models F6C800-UNV and F6C120-UNV, and is expected to work with other Belkin Universal UPS models. The driver only supports serial communication, not USB.

The Trust UPS and older Belkin units are not supported by this driver, and neither are the Belkin Home Office models (F6H500-SER and so forth). However, some Belkin models, such as the Regulator Pro, are supported by the belkin(8) driver, and the Home Office models are supported using the genericups(8) driver with upstype=7.

## SOFT SHUTDOWN WORKAROUND
One problem with the Belkin Universal UPS is that it cannot enter a soft shutdown (shut down the load until AC power returns) unless the batteries are completely depleted. Thus, one cannot just shut off the UPS after operating system shutdown; it will not come back on when the power comes back on. Therefore, the belkinunv driver should never be used with the -k option. Instead, the -x wait option is provided as a workaround.

When called with the -x wait option, belkinunv behaves as a standalone program (i.e., it does not fork into the background). It performs one simple task: it connects to the UPS, waits for AC power to return, and then exits with status 0.

This is meant to be used in a shutdown script as follows: during a shutdown, after all filesystems have been remounted read-only, and just before the system would normally be halted: check /etc/killpower (or similar) to see if this shutdown was caused by upsmon(8), and if yes, call belkinunv -x wait. If AC power comes back on, belkinunv exits, and things should be arranged so that the system reboots in this case. If AC power does not come back on, the UPS will eventually run out of batteries, kill the computer’s power supply, and go into soft shutdown mode, which means everything will reboot properly when the power returns. In either case, a deadlock is avoided.

In addition, if an optional integer argument is given to the -x wait option, this causes belkinunv to wait not only for AC power to be present, but also for the battery charge to reach the given level. I use this as part of my startup scripts, to ensure that the batteries are sufficiently charged before the computer continues booting. This should be put very early in the startup script, before any filesystems are mounted read/write, and before any filesystem checks are performed.

Several other -x options are provided to fine-tune this behavior. See the options below for detailed descriptions. See the examples below for examples of how to use belkinunv in shutdown and startup scripts.

## OPTIONS
See also nutupsdrv(8) for generic options. Never use the -k option with this driver; it does not work properly.

-x wait[=level]

When this option is used, belkinunv does not fork into the background, but behaves as a standalone program. It connects to the UPS and waits until AC power is present. If level is specified, it also waits until the battery charge reaches at least the given level in percent. Then, and only then, belkinunv exits. In addition, while belkinunv runs in this mode, it displays a status line with information on the UPS status and battery level. This is intended for use in the computer’s shutdown and startup scripts, as described under Soft Shutdown Workaround above.

-x nohang

This option only has an effect when used in conjunction with the -x wait option. It causes belkinunv to exit if a connection with the UPS cannot be established or is lost, instead of retrying forever, which is the default behavior. The -x nohang option should be used in a startup script, to ensure the computer remains bootable even if the UPS has been disconnected during the power failure (for instance, you attached your computer to a generator, carried it to a neighbor’s house, or whatever).

-x flash

This option only has an effect when used in conjunction with the -x wait option. It causes the UPS load to be shut off for a short time ("flashed") just after the AC power has returned and the requested battery level (if any) has been attained. This is useful if slaves are attached to this UPS; the flash will cause all of them to reboot. Note that, due to the design of the Belkin UPS hardware, the load shutdown lasts ca. 1—2 minutes; a shorter flash cannot be performed reliably. Also, the computers will reboot at the scheduled time, on battery power if necessary, even if AC power fails again in the meantime. This should not be a problem, as your startup scripts can catch this situation.

-x silent

This option only has an effect when used in conjunction with the -x wait option. It suppresses the status line which belkinunv would normally print.

-x dumbterm

This option only has an effect when used in conjunction with the -x wait option. It changes the way in which belkinunv prints its status line. Normally, terminal control sequences are used to overwrite the same line with new status information, each time the status is updated. This may not work on all terminals. If the -x dumbterm option is given, each status update is written on a new line.

## VARIABLES
battery.charge, battery.runtime

not supported by all hardware.

battery.voltage, battery.voltage.nominal, input.frequency, input.frequency.nominal

e.g. 60 for 60Hz

input.sensitivity

writable: normal/medium/low

input.transfer.high

writable: high transfer voltage point in V

input.transfer.low

writable: low transfer voltage point in V

input.voltage, input.voltage.maximum, input.voltage.minimum, input.voltage.nominal, output.frequency, output.voltage, ups.beeper.status

writable. Values: enabled/disabled/muted. This variable controls the state of the panel beeper. Enabled means sound when the alarm is present, disabled means never sound, and muted means the sound is temporarily disabled until the alarm would normally stop sounding. In the muted state, the beeper is automatically turned back on at the next event (AC failure, battery test, etc). Also, the beeper can’t be turned off during a critical event (low battery). Note that not all UPS models support the "disabled" state.

ups.firmware, ups.load, ups.model, ups.power.nominal

e.g. 800 for an 800VA system

ups.status

a list of flags; see the status flags below.

ups.temperature

not supported by all hardware.

ups.test.result, ups.delay.restart

time to restart (read only)

ups.delay.shutdown

time to shutdown (read only). This is always a multiple of 60 seconds.

ups.type

ONLINE/OFFLINE/LINEINT. This describes the basic layout of this UPS (for GUI clients which want to draw an animated picture of power flow). An offline UPS has a direct connection from AC input to AC output, and also a connection from AC input to the battery, and from the battery to AC output. An online UPS lacks the direct connection from AC input to AC output, whereas a line interactive UPS lacks the connection from AC input to the battery.

## COMMANDS
beeper.enable, beeper.disable, beeper.mute

Enable, disable or mute the panel beeper. Note that if the beeper is muted, it is automatically turned back on at the next event (AC failure, battery test, etc). Also, the beeper can’t be turned muted during a critical event (low battery).

reset.input.minmax

Reset the variables input.voltage.minimum and input.voltage.maximum.

shutdown.reboot

Shut down load immediately for about 1—2 minutes.

shutdown.reboot.graceful

After 40 second delay, shut down load for about 1—2 minutes.

shutdown.stayoff

Shut down load immediately and stay off. The only way it can be turned back on is by manually pressing the front panel button.

test.battery.start, test.battery.stop

Start/stop 10 second battery test.

test.failure.start, test.failure.stop

Start/stop "deep" battery test.

## STATUS FLAGS
OB

load is on battery, including during tests

OFF

load is off

OL

load is online

ACFAIL

AC failure. Note that this refers to the AC input, and thus it is not the same as "OB". An AC failure can occur at any time, for instance, during a battery test, or when the UPS load is off.

OVER

overload

OVERHEAT

overheat

COMMFAULT

UPS fault

LB

low battery

CHRG

charging

DEPLETED

the battery is depleted. When the UPS raises this flag, it simultaneously switches off the load.

RB

replace battery

## EXAMPLES
Here is an example for how belkinunv should be used in a computer’s shutdown script. These commands should go in the very last part of the shutdown script, after all file systems have been mounted read-only, and just before the computer halts. Note that belkinunv must be installed in a directory which is still readable at that point.

```
 # NEAR END OF SHUTDOWN SCRIPT:

 # if shutdown was caused by UPS, perform Belkin UPS workaround.

 if [ -f /etc/killpower ] || /usr/sbin/upsmon -K ; then

    echo "Waiting for AC power, or for UPS batteries to run out..."

    /usr/bin/belkinunv -x wait /dev/ttyS1

    # we get here if the power came back on. Reboot.

    echo "Power is back. Rebooting..."

    reboot

 fi
```

And here is an example of how to use belkinunv in the startup script. These commands should go near the beginning of the startup script, before any file systems are mounted read/write, and before any file system integrity checks are done.

```
 # NEAR BEGINNING OF STARTUP SCRIPT:

 # if we are recovering from a power failure, wait for the UPS to

 # charge to a comfortable level before writing anything to disk

 if [ -f /etc/killpower ] || /usr/sbin/upsmon -K ; then

    echo "Waiting for UPS battery charge to reach 60%..."

    /usr/bin/belkinunv -x wait=60 -x nohang /dev/ttyS1

 fi
```

## EXIT STATUS
When used normally, belkinunv forks into the background and its diagnostics are the same as for all NUT drivers, see nutupsdrv(8).

When used with the -x wait option, the exit status is normally 0. If the -x nohang option has also been specified, an exit status of 1 indicates that communication with the UPS was lost. If the -x flash option has been specified, an exit status of 2 indicates that the timed shutdown has failed.

## EXTRA ARGUMENTS
This driver does not support any extra settings in ups.conf(5).

## AUTHOR
Peter Selinger <selinger@users.sourceforge.net>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Other Belkin drivers:
belkinunv(8), blazer_ser(8), blazer_usb(8), usbhid-ups(8)

### Internet resources:
•The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/

•The documentation for the protocol used by this UPS: belkin-universal-ups.html (replica on NUT site)


bestfcom

title: bestfcom(8)

summary: Driver for Best Power Fortress/Ferrups

text:
# bestfcom(8)

## NAME
bestfcom - Driver for Best Power Fortress/Ferrups

## SYNOPSIS
bestfcom -h

bestfcom -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the bestfcom driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
Best Power Fortress/Ferrups implementing the Fortress UPS Protocol (f-command set). (For older Fortress units, see bestfortress(8).)

## EXTRA ARGUMENTS
This driver does not support any extra settings in the ups.conf(5).

## AUTHORS
•Kent Polk (bestfcom)

•Andreas Wrede, John Stone (bestuferrups)

•Grant Taylor (bestfort)

•Russell Kroll (bestups)

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


bestfortress

title: bestfortress(8)

text:
# bestfortress(8)

## NAME
bestfortress - Driver for old Best Fortress UPS equipment

## SYNOPSIS
bestfortress -h

bestfortress -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the bestfortress driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
This driver supports old Best Fortress UPS equipment using a serial connection.

One example is the "Fortress LI660", sold in (at least) 1995.

## EXTRA ARGUMENTS
This driver supports the following optional settings in the ups.conf(5):

baudrate=num

Set the speed of the serial connection — 1200, 2400, 4800 or 9600.

max_load=VA

Set the full-scale value of the ups.load variable.

## AUTHORS
•Holger Dietze <holger.dietze@advis.de>

•Stuart D. Gathman <stuart@bmsi.com>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### The newer Best Power drivers:
bestups(8), bestuferrups(8), bestfcom(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


bestuferrups

title: bestuferrups(8)

summary: Driver for Best Power Micro\-Ferrups

text:
# bestuferrups(8)

## NAME
bestuferrups - Driver for Best Power Micro-Ferrups

## SYNOPSIS
bestuferrups -h

bestuferrups -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the bestuferrups driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
Best Power Micro-Ferrups ME3100, probably other similar models too.

## EXTRA ARGUMENTS
This driver does not support any extra settings in the ups.conf(5).

## AUTHORS
•Andreas Wrede, John Stone (bestuferrups)

•Grant Taylor (bestfort)

•Russell Kroll (bestups)

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


bestups

title: bestups(8)

text:
# bestups(8)

## NAME
bestups - Driver for Best Power / SOLA (Phoenixtec protocol) UPS equipment

## SYNOPSIS
bestups -h

bestups -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the bestups driver. For information about the core driver, see nutupsdrv(8).

## NOTE
Please note that this driver is deprecated and will not receive new development. If it works for managing your devices — fine, but if you are running it to try setting up a new device, please consider the newer nutdrv_qx(8) instead, which should handle all Q* protocol variants for NUT.

If your device works with this driver, but does not work with nutdrv_qx(8), please report this via the mailing list or issue tracker.

## SUPPORTED HARDWARE
bestups was designed to monitor Best Power UPS hardware like the Fortress, Fortress Telecom, Axxium Rackmount and Patriot Pro. It also recognizes and supports SOLA units such as the 325, 520 and 620. In addition, the Best 610 is supported using the ‘ID’ option.

Other UPS hardware using the Phoenixtec protocol should also work, but they will generate a warning since their battery information is not known.

This driver does not support some older Best/SOLA units. (For older Fortress units, see bestfortress(8).)

## EXTRA ARGUMENTS
This driver supports the following optional settings in the ups.conf(5):

nombattvolt=num

Override the battery float voltage which is normally determined by asking the hardware. This is useful if your UPS constantly reports battery.charge values just below 100% even when it’s completely charged. If you have this problem, set this to whatever battery.voltage reports when the UPS is known to be completely charged with a good battery.

The author’s Best Fortress 750 uses nombattvolt=27.4.

battvoltmult=num

Multiply the reported battery voltage by this number. Some devices report only a fraction of the total battery voltage. For example, the SOLA 610 700VA UPS (with a 24V battery) reports the single cell voltage (about 2.27V when fully charged). In this particular case you can set battvoltmult = 12 in ups.conf(5) to fix this.

ID=string

Set the Identification response string. This should only be used with hardware that supports the Phoenixtec protocol status inquiry commands, but not the "ID" command, such as the Best/SOLA 610. Format of the ID string is: AAA,BBBB,CCC,DDD,EE.E,FF.F AAA is the three-character identification for the UPS model.

BBBB is the output power in VA (volt amperes). B is an integer number ranging from 0 to 9.

CCC is the Nominal Input Voltage. C is an integer number ranging from 0 to 9. The unit is Volts AC.

DDD is the Nominal Output Voltage. D is an integer number ranging from 0 to 9. The unit is Volts AC.

EE.E is the Battery Voltage that will cause the UPS to shut itself off. E is an integer number ranging from 0 to 9. Then unit is Volts DC and a decimal point is present.

FF.F or FFF.F is the Battery Voltage at full charge. F is an integer number ranging from 0 to 9. Then unit is Volts DC. Typically, for 700VA, 1KVA and 1.5KVA units, the format is FF.F. For 2KVA and 3KVA units, the format is FFF.F.

Example: a Best 610 1.5KVA unit would use the string "610,1500,120,120,10.0,48.0".

## BUGS
The battery charge percentage value (in battery.charge) is derived from the voltage data that the UPS returns, since the UPS doesn’t return that value directly. On some hardware, the charge will remain at 100% for a long time and then drops quickly shortly before the battery runs out. You can confirm from the battery.voltage readings that this is a problem with the UPS and not this driver.

Similarly, the float from the charger in some models forces the battery charge percentage back up to 100% immediately after the UPS goes back on-line, so you can’t tell when it is really recharged.

Finally, some models give one value for the battery’s nominal voltage and yet actually have a nominal voltage slightly below that. This leads to things such as the perpetual 98.7% charge on the author’s Fortress 750, even when it’s been charging for weeks. You can use nombattvolt= in ups.conf(5) to fix this.

## AUTHORS
•Russell Kroll

•Jason White

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


title: bicker_ser(8)

text:
# bicker_ser(8)

## NAME
bicker_ser - Driver for Bicker DC UPS via serial port connections

## SYNOPSIS
bicker_ser -h

bicker_ser -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the bicker_ser driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
bicker_ser supports all Bicker UPSes shipped with the PSZ-1053 extension module such as UPSIC-1205, UPSIC-2403, DC2412-UPS and DC2412-UPS-LD.

## CABLING
The needed cable is a standard pin-to-pin serial cable with pins 2, 3 and 5 (on DB9 connector) connected.

## EXTRA ARGUMENTS
This driver supports no extra arguments from ups.conf(5).

## VARIABLES
Depending on the type of your UPS unit, some of the following variables may be changed with upsrw(8). If the driver can’t read a variable from the UPS, it will not be made available. Whenever not explicitly stated, any variable can be disabled, in which case the action it performs will not be executed. To disable a variable, set it to an empty value.

ups.delay.shutdown (in seconds, default disabled)

If activated and the UPS is in battery mode and the set time has expired, the output will be disabled, and the UPS and energy storage will be disconnected.

ups.delay.start (in seconds, default disabled)

If activated and a restart condition switches the UPS output off and on again, the set time is the delay between switching on and off. The time should cause a defined off time so that capacities in the application can be discharged.

battery.charge.restart (in percent, default disabled)

If activated and the UPS is off or restarts, the UPS output will not be released until the energy storage device has the set charge state. The energy storage device is charged in the meantime.

battery.charge.low (in percent, default 20)

If activated and the UPS is in battery mode and the battery level drops below the set value, a shutdown command via relay event is signaled.

experimental.output.current.low (in mA, default 200)

If activated and the UPS is in battery mode and the current drops below the set value, the output of the UPS will shut down and disconnect the energy storage to prevent self-discharge.

experimental.ups.delay.shutdown.signal (in seconds, default disabled)

If activated and the UPS is in battery mode and the set time has elapsed, a shutdown command via relay event is signaled.

experimental.ups.delay.shutdown.signal.masked (in seconds, default disabled)

If activated and the UPS is in battery mode and the signal at the IN-1 input is high and the set time has expired, a shutdown command via relay event is signaled.

experimental.battery.charge.low.empty (in percent, default 20)

This parameter stores the threshold value for the "Battery Empty" signal. Currently this setting is only valid for relay signaling. Cannot be disabled.

experimental.ups.relay.mode (default 0x01)

This parameter controls the behavior of the relay in case of different events. Cannot be disabled. Available relay modes:

0x01

On power fail (normally closed)

0x02

On power fail (normally opened)

0x03

Shutdown impulse (1 second)

0x04

Battery low signal (normally closed)

0x05

Battery defect signal (normally closed)

## INSTANT COMMANDS
shutdown.return

Turn off the load and return when power is back.

## KNOWN ISSUES AND BUGS
ups.delay.shutdown is not honored

Although that delay is properly set when sending the shutdown command, it seems some UPS ignore it and use a fixed 2 seconds delay instead.

## AUTHOR
Nicola Fontana <ntd@entidi.it>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


title: blazer_ser(8)

text:
# blazer_ser(8)

## NAME
blazer_ser - Driver for Megatec/Q1 protocol serial based UPS equipment

## SYNOPSIS
blazer_ser -h

blazer_ser -a UPS_NAME [OPTIONS]

## NOTE
This man page only documents the hardware-specific features of the blazer driver. For information about the core driver, see nutupsdrv(8).

## NOTE
Please note that this driver is deprecated and will not receive new development. If it works for managing your devices — fine, but if you are running it to try setting up a new device, please consider the newer nutdrv_qx(8) instead, which should handle all Q* protocol variants for NUT.

Please do also report if your device works with this driver, but nutdrv_qx(8) would not actually support it with any subdriver!

## SUPPORTED HARDWARE
The blazer driver is known to work with various UPSes from Blazer, Energy Sistem, Fenton Technologies, General Electric, Mustek and many others. The NUT compatibility table lists all the known supported models. Keep in mind, however, that other models not listed there may also be supported, but haven’t been tested.

All devices with a serial interface (use the blazer_ser driver) and many with a USB interface (use the blazer_usb driver) are supported.

## EXTRA ARGUMENTS
You may need to override or provide defaults for some values, depending on the make and model of your UPS. The following are the ones that most likely will need changing (see ups.conf(5)):

default.battery.voltage.high = value

Maximum battery voltage that is reached after about 12 to 24 hours charging. If you want the driver to report a guesstimated battery.charge, you need to specify this (see BATTERY CHARGE GUESSTIMATION).

default.battery.voltage.low = value

Minimum battery voltage just before the UPS automatically shuts down. If you want the driver to report a guesstimated battery.charge, you need to specify this (see BATTERY CHARGE GUESSTIMATION).

default.battery.voltage.nominal = value, override.battery.voltage.nominal = value

Some devices show a wrong nominal battery voltage (or none at all), so you may need to override or set a default value.

override.battery.packs = value

Some devices report a part of the total battery voltage. For instance, if battery.voltage.nominal is 24 V, but it reports a battery.voltage of around 2 V, the number of battery.packs to correct this reading would be 12. The driver will attempt to detect this automatically, but if this fails somehow, you may want to override this value.

ondelay = value

Time to wait before switching on the UPS (minutes). Note that a value below 3 minutes, may cause earlier firmware versions to not switch on automatically, so it defaults to 3 minutes. The acceptable range is 0..9999 minutes.

offdelay = value

Time to wait before shutting down the UPS (seconds). This value is truncated to units of 6 seconds (less than 60 seconds) or 60 seconds (more than 60 seconds). Defaults to 30 seconds. The acceptable range is 12..600 seconds.

norating

Some UPSes will lock up if you attempt to read rating information from them. Setting this flag will make the driver skip this step.

novendor

Some UPSes will lock up if you attempt to read vendor information from them. Setting this flag will make the driver skip this step.

protocol = string

Skip autodetection of the protocol to use and only use the one specified. Supported values are megatec, megatec/old, mustek and zinto.

runtimecal = value,value,value,value

Parameter used in the (optional) runtime estimation. This takes two runtimes at different loads. Typically, this uses the runtime at full load and the runtime at half load. For instance, if your UPS has a rated runtime of 240 seconds at full load and 720 seconds at half load, you would enter

```
runtimecal = 240,100,720,50
```

The first load should always be higher than the second. If you have values available for loads other than 100 and 50 % respectively, you can use those too, but keep them spaced apart as far as reasonably possible. Just don’t get too close to no load (prediction of runtime depends more on idle load for the battery then).

chargetime = value

The time needed to fully recharge the battery after being fully discharged. If not specified, the driver defaults to 43200 seconds (12 hours). Only used if runtimecal is also specified.

idleload = value

Minimum battery load used by the driver to estimate the runtime. If not specified, the driver defaults to 10%. Only used if runtimecal is also specified.

### SERIAL INTERFACE ONLY
cablepower = string

By default the driver will set DTR and clear RTS (normal). If you find that your UPS isn’t detected or the communication with the UPS is unreliable, you may try if clear DTR and set RTS (reverse), set DTR and RTS (both) or clear DTR and RTS (none) improves this situation.

## UPS COMMANDS
This driver supports some instant commands (see upscmd(8)):

beeper.toggle

Toggle the UPS beeper. (Not available on some hardware.)

load.on

Turn on the load immediately.

load.off

Turn off the load immediately (see KNOWN PROBLEMS).

shutdown.return

Turn off the load and return when power is back. Uses the timers defined by ondelay and offdelay.

shutdown.stayoff

Turn off the load and remain off (see KNOWN PROBLEMS). Uses the timer defined by offdelay.

shutdown.stop

Stop a shutdown in progress.

test.battery.start.deep

Perform a long battery test (Not available on some hardware.)

test.battery.start.quick

Perform a (10 second) battery test.

test.battery.start value

Perform a battery test for the duration of value minutes.

test.battery.stop

Stop a running battery test (not available on some hardware.)

## BATTERY CHARGE GUESSTIMATION
Due to popular demand, this driver will report a guesstimated battery.charge value and optionally battery.runtime, provided you specified a couple of the EXTRA ARGUMENTS listed above.

If you specify both battery.voltage.high and battery.voltage.low in ups.conf(5), but don’t enter runtimecal, it will guesstimate the state of charge by looking at the battery voltage alone. This is not reliable under load, as this only gives reasonably accurate readings if you disconnect the load, let the battery rest for a couple of minutes and then measure the open cell voltage. This just isn’t practical if the power went out and the UPS is providing power for your systems.

```
                     battery.voltage - battery.voltage.low
battery.charge =  ------------------------------------------ x 100 %

                  battery.voltage.high - battery.voltage.low
```

There is a way to get better readings without disconnecting the load, but this requires one to keep track on how much (and how fast) current is going in- and out of the battery. If you specified the runtimecal, the driver will attempt to do this. Note however, that this heavily relies on the values you enter and that the UPS must be able to report the load as well. There are quite a couple of devices that report 0% (or any other fixed value) at all times, in which case this obviously doesn’t work.

The driver also has no way of determining the degradation of the battery capacity over time, so you’ll have to deal with this yourself (by adjusting the values in runtimecal). Also note that the driver guesses the initial state of charge based on the battery voltage, so this may be less than 100%, even when you are certain that they are full. There is just no way to reliably measure this between 0 and 100% full charge.

This is better than nothing (but not by much). If any of the above calculations are giving you incorrect readings, remember that you are the one who put in the values in ups.conf(5), so don’t complain to the author. If you need something better, consider buy an UPS that reports battery.charge and battery.runtime all by itself without the help of a NUT driver.

## NOTES FOR THE PREVIOUS USER OF MEGATEC DRIVERS
The blazer drivers having replaced the megatec ones, some configuration changes may be required by users switching to blazer.

Part of this, the following megatec options, in ups.conf, have to be changed:

battvolts

You need to use default.battery.voltage.high and default.battery.voltage.low

dtr and rts

You need to use cablepower

ignoreoff

This parameter can simply be discarded, since it was a wrong understanding of the specification.

## KNOWN PROBLEMS
Some UPS commands aren’t supported by all models. In most cases, the driver will send a message to the system log when the user tries to execute an unsupported command. Unfortunately, some models don’t even provide a way for the driver to check for this, so the unsupported commands will silently fail.

Both the load.off and shutdown.stayoff instant commands are meant to turn the load off indefinitely. However, some UPS models don’t allow this.

Some models report a bogus value for the beeper status (will always be enabled or disabled). So, the beeper.toggle command may appear to have no effect in the status reported by the driver when, in fact, it is working fine.

The temperature and load value is known to be bogus in some models.

## AUTHORS
•Arjen de Korte <adkorte-guest at alioth.debian.org>

•Alexander Gordeev <lasaine at lvk.cs.msu.su>

## SEE ALSO
blazer_usb(8), nutupsdrv(8), upsc(8), upscmd(8), upsrw(8)

### Internet Resources:
•The NUT (Network UPS Tools) home page: https://www.networkupstools.org/

•The NUT HCL: https://www.networkupstools.org/stable-hcl.html