nut-debian/docs/man/nutdrv_siemens_sitop.txt

NUTDRV_SIEMENS_SITOP(8)
=======================

NAME
----

nutdrv_siemens_sitop - driver for the Siemens SITOP UPS500 series UPS

NOTE
----

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

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

*nutdrv_siemens_sitop* supports Siemens UPS models from the SITOP UPS500 series.
Some models have a serial port, others have a USB port.
The models with USB port actually contain a serial-over-USB chip,
so as far as this driver is concerned, all models are serial models.
This driver should work with all models in the SITOP UPS500 series,
as long as your kernel has support for the serial port device
(see section *USB driver* below).

NOTE: This driver has only been tested with the SITOP UPS500S-2.5
with USB port (Siemens product number 6EP1933-2EC41).

DEVICE SETTINGS
---------------

The UPS is configured via DIP-switches.
For correct functioning in combination with NUT, set the DIP-switches
to the following:

*switch 1-4*::
Choose whatever suits your situation. Any combination will work with NUT.

*switch 5* (=> / t)::
Set to OFF (t). This ensures that the UPS will not cut power unless NUT
tells it to do so (or unless the batteries are exhausted).

*switch 6-10* (delay)::
Set to OFF (minimum delay). Setting a higher delay will actually also work,
but any command from NUT will be delayed as well before being executed
by the UPS. With the minimum setting, it will already take 5 seconds
before a command from NUT is executed.

*switch 11* (INTERR.)::
Set to ON (interrupt the output after the timer expires). This ensures that
the UPS briefly interrupts the output power in response to the shutdown.return
command. See the section *Instant Commands* below.

*switch 12* (ON/OFF)::
set to ON (enable the UPS functionality). Without this, the UPS will never
supply power from its batteries.

USB driver
----------

The USB-versions of the UPS contain an FTDI USB-to-serial converter chip.
It is programmed with a non-standard product ID (for example _0403:e0e3_),
but can still be used with the normal ftdi_sio driver.

NOTE: The following hints may be specific to GNU/Linux.

Use *lsusb* to figure out which product ID is used in your model, and
replace all occurrences of _e0e3_ in the following examples with the actual
Product ID.

....
modprobe ftdi_sio
echo 0403 e0e3 > /sys/bus/usb-serial/drivers/ftdi_sio/new_id
....

If your system uses *udev*, this can be automated via a udev rule:

----
ACTION=="add", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="e0e3", \
  RUN+="/sbin/modprobe ftdi_sio", \
  RUN+="/bin/sh -c 'echo 0403 e0e3 > /sys/bus/usb-serial/drivers/ftdi_sio/new_id'"
----

You can use the following udev rule to obtain a predictable device name,
for example _/dev/ttyUPS_:
----
SUBSYSTEM=="tty" ATTRS{idVendor}=="0403", ATTRS{idProduct}=="e0e3" SYMLINK+="ttyUPS"
----

POLLING
-------

The UPS does not have a special 'get status' command. Instead, it continuously
sends out status update messages (tens of messages per second).
Every *pollinterval*, these messages are read from the serial port buffer.
In order to react quickly on status changes from the UPS, and to prevent the serial buffer
from overflowing, *pollinterval* should be set to a relatively low value. The recommended
value is 1 (second).

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

This driver supports the following optional settings:

*max_polls_without_data*='num'::
The serial port is polled periodically for new data (see *Polling*).
If there is no valid new data after 'num' polls, it is assumed that communication
with the UPS is lost.
The default value is 2. Lower values may cause spurious 'Data stale' messages,
especially at startup.

INSTANT COMMANDS
----------------

*shutdown.return*::
The behavior of this command depends on the line state:

* *on line*: after 5 seconds (or longer, if DIP switches 6-10 are not OFF),
the UPS will shut off its output. After another 5 seconds, the output is
activated again.
* *on battery*: after 5 seconds (or longer, if DIP switches 6-10 are not OFF),
the UPS will shut off its output. The output will stay off, until the
line voltage has returned.

*shutdown.stayoff*::
The behavior of this command depends on the line state:

* *on line*: after 5 seconds (or longer, if DIP switches 6-10 are not OFF),
the UPS will shut off its output. The output stays off, until the line voltage
has been removed for at least 1 second, and has been re-applied.
* *on battery*: this command behaves the same as *shutdown.return*.

INSTALLATION
------------

Make sure that your operating system has created a serial device for the UPS.
See the section *USB driver* for more information.

Next, make sure that NUT has access rights to this device file.
For example, by creating a udev rule that grants permission to the NUT user,
or by adding the NUT user to a user group that can access serial devices
(e.g. the *dialout* group on Debian-based systems).

DIAGNOSTICS
-----------

You can verify the correct functioning of the hardware, by monitoring the
serial port with a terminal program, for example picocom:

....
picocom -b 9600 -d 8 -p n /dev/ttyUPS
....

NUT must not be running when you do this.
You should now see a continuous stream of 5-character texts coming in,
for example:

....
BUFRD
BA>85
DC_OK
....
To exit picocom, use Ctrl-A Ctrl-X.

KNOWN ISSUES AND BUGS
---------------------

*Untested models*::
As mentioned under *Supported hardware*, this driver has not been tested
with all models in the SITOP UPS500 series.

*Data stale messages*::
The firmware in these UPSes is quite buggy. After sending data to the UPS,
it sometimes stops sending status updates. This driver tries to prevent this
(e.g. by sending commands twice, and by sending additional LF characters after
each command).
Once the UPS is in this state, communication can only be restored by rebooting
the UPS, or by unplugging and reconnecting the USB cable.
During normal operation, no commands are sent to the UPS at all
(only at shutdown), so this issue is expected to have little impact on
usability.
It is not sure if the serial models are affected by this issue as well.

AUTHOR
------

Matthijs H. ten Berge

SEE ALSO
--------

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

linkman:nutupsdrv[8]

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

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