nutdrv_siemens_sitop(8)

1NUTDRV_SIEMENS_SITOP(8)           NUT Manual           NUTDRV_SIEMENS_SITOP(8)
2
3
4

NAME

6       nutdrv_siemens_sitop - driver for the Siemens SITOP UPS500 series UPS
7

NOTE

9       This man page only documents the hardware-specific features of the
10       nutdrv_siemens_sitop driver. For information about the core driver, see
11       nutupsdrv(8).
12

SUPPORTED HARDWARE

14       nutdrv_siemens_sitop supports Siemens UPS models from the SITOP UPS500
15       series. Some models have a serial port, others have a USB port. The
16       models with USB port actually contain a serial-over-USB chip, so as far
17       as this driver is concerned, all models are serial models. This driver
18       should work with all models in the SITOP UPS500 series, as long as your
19       kernel has support for the serial port device (see section USB driver
20       below).
21
22           Note
23           This driver has only been tested with the SITOP UPS500S-2.5 with
24           USB port (Siemens product number 6EP1933-2EC41).
25

DEVICE SETTINGS

27       The UPS is configured via DIP-switches. For correct functioning in
28       combination with NUT, set the DIP-switches to the following:
29
30       switch 1-4
31           Choose whatever suits your situation. Any combination will work
32           with NUT.
33
34       switch 5 (⇒ / t)
35           Set to OFF (t). This ensures that the UPS will not cut power unless
36           NUT tells it to do so (or unless the batteries are exhausted).
37
38       switch 6-10 (delay)
39           Set to OFF (minimum delay). Setting a higher delay will actually
40           also work, but any command from NUT will be delayed as well before
41           being executed by the UPS. With the minimum setting, it will
42           already take 5 seconds before a command from NUT is executed.
43
44       switch 11 (INTERR.)
45           Set to ON (interrupt the output after the timer expires). This
46           ensures that the UPS briefly interrupts the output power in
47           response to the shutdown.return command. See the section Instant
48           Commands below.
49
50       switch 12 (ON/OFF)
51           set to ON (enable the UPS functionality). Without this, the UPS
52           will never supply power from its batteries.
53

USB DRIVER

55       The USB-versions of the UPS contain an FTDI USB-to-serial converter
56       chip. It is programmed with a non-standard product ID (for example
57       0403:e0e3), but can still be used with the normal ftdi_sio driver.
58
59           Note
60           The following hints may be specific to GNU/Linux.
61
62       Use lsusb to figure out which product ID is used in your model, and
63       replace all occurrences of e0e3 in the following examples with the
64       actual Product ID.
65
66           modprobe ftdi_sio
67           echo 0403 e0e3 > /sys/bus/usb-serial/drivers/ftdi_sio/new_id
68
69       If your system uses udev, this can be automated via a udev rule:
70
71           ACTION=="add", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="e0e3", \
72             RUN+="/sbin/modprobe ftdi_sio", \
73             RUN+="/bin/sh -c 'echo 0403 e0e3 > /sys/bus/usb-serial/drivers/ftdi_sio/new_id'"
74
75       You can use the following udev rule to obtain a predictable device
76       name, for example /dev/ttyUPS:
77
78           SUBSYSTEM=="tty" ATTRS{idVendor}=="0403", ATTRS{idProduct}=="e0e3" SYMLINK+="ttyUPS"
79

POLLING

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

EXTRA ARGUMENTS

89       This driver supports the following optional settings:
90
91       max_polls_without_data=num
92           The serial port is polled periodically for new data (see Polling).
93           If there is no valid new data after num polls, it is assumed that
94           communication with the UPS is lost. The default value is 2. Lower
95           values may cause spurious Data stale messages, especially at
96           startup.
97

INSTANT COMMANDS

99       shutdown.return
100           The behavior of this command depends on the line state:
101
102           •   on line: after 5 seconds (or longer, if DIP switches 6-10 are
103               not OFF), the UPS will shut off its output. After another 5
104               seconds, the output is activated again.
105
106           •   on battery: after 5 seconds (or longer, if DIP switches 6-10
107               are not OFF), the UPS will shut off its output. The output will
108               stay off, until the line voltage has returned.
109
110       shutdown.stayoff
111           The behavior of this command depends on the line state:
112
113           •   on line: after 5 seconds (or longer, if DIP switches 6-10 are
114               not OFF), the UPS will shut off its output. The output stays
115               off, until the line voltage has been removed for at least 1
116               second, and has been re-applied.
117
118           •   on battery: this command behaves the same as shutdown.return.
119

INSTALLATION

121       Make sure that your operating system has created a serial device for
122       the UPS. See the section USB driver for more information.
123
124       Next, make sure that NUT has access rights to this device file. For
125       example, by creating a udev rule that grants permission to the NUT
126       user, or by adding the NUT user to a user group that can access serial
127       devices (e.g. the dialout group on Debian-based systems).
128

DIAGNOSTICS

130       You can verify the correct functioning of the hardware, by monitoring
131       the serial port with a terminal program, for example picocom:
132
133           picocom -b 9600 -d 8 -p n /dev/ttyUPS
134
135       NUT must not be running when you do this. You should now see a
136       continuous stream of 5-character texts coming in, for example:
137
138           BUFRD
139           BA>85
140           DC_OK
141
142       To exit picocom, use Ctrl-A Ctrl-X.
143

KNOWN ISSUES AND BUGS

145       Untested models
146           As mentioned under Supported hardware, this driver has not been
147           tested with all models in the SITOP UPS500 series.
148
149       Data stale messages
150           The firmware in these UPSes is quite buggy. After sending data to
151           the UPS, it sometimes stops sending status updates. This driver
152           tries to prevent this (e.g. by sending commands twice, and by
153           sending additional LF characters after each command). Once the UPS
154           is in this state, communication can only be restored by rebooting
155           the UPS, or by unplugging and reconnecting the USB cable. During
156           normal operation, no commands are sent to the UPS at all (only at
157           shutdown), so this issue is expected to have little impact on
158           usability. It is not sure if the serial models are affected by this
159           issue as well.
160

AUTHOR

162       Matthijs H. ten Berge
163