POWERCOM(8)
===========

NAME
----

powercom - UPS driver for serial Powercom/Trust/Advice UPS equipment

SYNOPSIS
--------

*powercom* -h

*powercom* -a 'UPS_NAME' ['OPTIONS']

NOTE: This man page only documents the hardware-specific features of the
powercom driver.  For information about the core driver, see
linkman:nutupsdrv[8].

SUPPORTED HARDWARE
------------------

This driver supports many similar kinds of serial UPS hardware (as well as a
few USB UPS models with USB-to-serial adapters).  The most common ones are the
Trust 425/625, Powercom, and Advice Partner/King PR750.  Others using the same
protocol may also work. For USB connections, you might need linkman:usbhid-ups[8].

For more specific guidance on which driver is applicable for a USB connection,
see the NUT Hardware Compatibility List (HCL).

EXTRA ARGUMENTS
---------------

This driver supports the following optional settings in the
linkman:ups.conf[5] file:

*linevoltage*='value'::
An integer specifying the line voltage. It can't be auto detected. Acceptable
values are in the range of 110-120 or 220-240. The default is '230'.

*manufacturer*='name'::
Specify the manufacturer name, which also can't be auto detected. This is a
user defined string, so any name is acceptable. The default is 'PowerCom'.

*modelname*='name'::
Specify the model name, which also can't be auto detected. This is a user
defined string, so any name is acceptable. The default is 'Unknown'.

*serialnumber*='value'::
Like modelname above, but for the serial number. The default is 'Unknown'.

*type*='name'::
The exact type of the communication protocol within the powercom family, that
will be used to communicate with the UPS. The type is named after the first
modelname that was coded with that protocol. The acceptable names are
'Trust', 'Egys', 'KP625AP', 'IMP', 'KIN', 'BNT', 'BNT-other' and 'OPTI'.
The default is 'Trust'.
+
'BNT-other' is a special type for other BNT models (such as the 1500A at 120V
and can be used to override ALL models using ALL of the following values.

*shutdownArguments*={{'minutes','seconds'},'whether_minutes_should_be_used'}::
The minutes and seconds that the UPS should wait between receiving the
shutdown command and actually shutting off. The other argument should be set
to the character 'n' only when the minutes value should be skipped and not
sent to the UPS. The default is type-dependent and is given below. The braces
and commas are mandatory. Note that there should be no whitespace characters.

*numOfBytesFromUPS*='value'::
The number of bytes in a UPS frame: 16 is common, 11 for 'Trust'. The default
is type-dependent and is given below.

*methodOfFlowControl*='name'::
The method of serial communication flow control that is engaged by the UPS.
The default is type-dependent and is given below. Acceptable names are
'dtr0rts1', 'dtr1' or 'no_flow_control'.

*validationSequence*={{'index1','value1'},{'index2','value2'},{'index3','value3'}}::
(Only for types KP625AP, Trust, Egys.)
3 pairs to be used for validating the UPS by comparing bytes of the raw data
with constant values. The index selects the byte from the UPS (see
numOfBytesFromUPS) and the value is for matching to the byte. The default is
type-dependent and is given below. The braces and commas are mandatory, as
the lack of white space characters.

*frequency*={'A','B'}::
(Only for types KP625AP, Trust, Egys.)
A pair to convert the raw frequency data to a human-readable frequency
reading using the function 1/(A*x+B). If the raw value x IS the frequency,
then set A=1/(x^2) and B=0. The default is type-dependent and is given below.
Do note that the braces and commas are mandatory as well, as the lack of
whitespace characters.

*loadPercentage*={'BatteryA','BatteryB','LineA','LineB'}::
(Only for types KP625AP, Trust, Egys.)
A quad to convert the raw load data to human readable load percentage reading
using the function A*x+B. If the raw value x IS the Load Percent, then set
A=1 and B=0. The default is type-dependent and is given below. Do note that
the braces and commas are mandatory, as the lack of white space
characters.

*batteryPercentage*={'Battery1','Battery2','Battery3','Line4','Line5'}::
(Only for KP625AP, Trust, Egys.)
A 5 tuple to convert the raw battery and line data to a human-readable
battery and line percentage reading using the functions (Battery)
A*x+B*y+C and (Line) D*x+E. If the raw value x IS the Battery Percent, then
set A=1, B=0, C=0, D=1, E=0. The default is type-dependent and is given below.
Do note that the braces and commas are mandatory, as the lack of white space
characters.

*voltage*={'240A','240B','120A','120B'}::
(Only for types KP625AP, Trust, Egys.)
A quad that is used convert the raw voltage data to a human-readable voltage
reading using the function A*x+B. If the raw value x IS HALF the Voltage,
then set A=2, B=0. The default is type-dependent and is given below. Do note
that the braces and commas are mandatory, as well as the lack of whitespace
characters.

*nobt*::
If this flag is present, the battery check on startup is skipped. This is
useful for systems that tend to overload the UPS when testing the battery on
system startup -- just when the power consumption tends to be high.

DEFAULT VALUES FOR THE EXTRA ARGUMENTS
--------------------------------------

 linevoltage = 230
 manufacturer = PowerCom
 modelname = Unknown
 serialnumber = Unknown
 type = Trust

The rest of the default values for the extra arguments are type-dependent.
However, 'BNT-other' is a special type that can be used to override ALL
values for ALL models.

Trust
~~~~~

 numOfBytesFromUPS = 11
 methodOfFlowControl = dtr0rts1
 validationSequence = {{5,0},{7,0},{8,0}}
 shutdownArguments = {{0,10},n}
 frequency = {0.00020997,0.00020928}
 loadPercentage = {6.1343,-0.3808,4.3110,0.1811}
 batteryPercentage = {5.0000,0.3268,-825.00,4.5639,-835.82}
 voltage = {1.9216,-0.0977,0.9545,0.0000}

KP625AP
~~~~~~~

 numOfBytesFromUPS = 16
 methodOfFlowControl = dtr0rts1
 validationSequence = {{5,0x80},{7,0},{8,0}}
 shutdownArguments = {{0,10},n}
 frequency = {0.00020997,0.00020928}
 loadPercentage = {6.1343,-0.3808,4.3110,0.1811}
 batteryPercentage = {5.0000,0.3268,-825.00,4.5639,-835.82}
 voltage = {1.9216,-0.0977,0.9545,0.0000}

Egys
~~~~

 numOfBytesFromUPS = 16
 methodOfFlowControl = no_flow_control
 validationSequence = {{5,0x80},{7,0},{8,0}}
 shutdownArguments = {{0,10},n}
 frequency = {0.00020997,0.00020928}
 loadPercentage = {6.1343,-0.3808,1.3333,0.6667}
 batteryPercentage = {5.0000,0.3268,-825.00,2.2105,-355.37}
 voltage = {1.9216,-0.0977,0.9545,0.0000}

IMP
~~~

 numOfBytesFromUPS = 16
 methodOfFlowControl = no_flow_control
 validationSequence = {{5,0xFF},{7,0},{8,0}}
 shutdownArguments = {{1,30},y}

KIN
~~~

 numOfBytesFromUPS = 16
 methodOfFlowControl = no_flow_control
 validationSequence = {{11,0x4b},{8,0},{8,0}}
 shutdownArguments = {{1,30},y}

BNT
~~~

 numOfBytesFromUPS = 16
 methodOfFlowControl = no_flow_control
 validationSequence = {{11,0x42},{8,0},{8,0}}
 shutdownArguments = {{1,30},y}

BNT-other
~~~~~~~~~

 numOfBytesFromUPS = 16
 methodOfFlowControl = no_flow_control
 validationSequence = {{8,0},{8,0},{8,0}}
 shutdownArguments = {{1,30},y}
 frequency = {0.00027778,0.0000}
 loadPercentage = {1.0000,0.0,1.0000,0.0}
 batteryPercentage = {1.0000,0.0000,0.0000,1.0000,0.0000}
 voltage = {2.0000,0.0000,2.0000,0.0000}

OPTI
~~~~

 numOfBytesFromUPS = 16
 methodOfFlowControl = no_flow_control
 validationSequence = {{5,0xFF},{7,0},{8,0}}
 shutdownArguments = {{1,30},y}

AUTHORS
-------

* Peter Bieringer <pb@bieringer.de>
* Alexey Sidorov <alexsid@altlinux.org>
* Keven L. Ates <atescomp@gmail.com>
* Rouben Tchakhmakhtchian <rouben@rouben.net>

SEE ALSO
--------

The core driver:
~~~~~~~~~~~~~~~~

linkman:nutupsdrv[8]

Internet resources:
~~~~~~~~~~~~~~~~~~~

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