networkupstools · zykh · Jul 31, 2019 · Mar 23, 2018 · Mar 23, 2018 · Mar 26, 2018
diff --git a/data/driver.list.in b/data/driver.list.in
@@ -943,6 +943,9 @@
 
 "Rucelf"	"ups"	"2"	"Rucelf UPOII-3000-96-EL"	""	"blazer_ser" # http://www.rucelf.ua/en/catalog/upoii-3000-96-el/
 
+"Siemens"	"ups"	"4"	"SITOP UPS500"	"serial"	"nutdrv_siemens_sitop (experimental, untested)"
+"Siemens"	"ups"	"4"	"SITOP UPS500"	"USB"	"nutdrv_siemens_sitop (experimental)"
+
 "SmartLabs"	"pdu"	"1"	"2412S Power Line Modem"	"for X10/Insteon"	"powerman-pdu (experimental)"
 
 "SMS (Brazil)"	"ups"	"2"	"Manager III"	""	"blazer_ser"

diff --git a/docs/man/nutdrv_siemens_sitop.txt b/docs/man/nutdrv_siemens_sitop.txt
@@ -0,0 +1,188 @@
+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.
+
+AUTHORS
+-------
+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/
diff --git a/docs/nut.dict b/docs/nut.dict
@@ -28,6 +28,7 @@ ARS
 ATEK
 ATR
 ATT
+ATTRS
 ATX
 ATs
 AVL
@@ -93,6 +94,7 @@ BTIntervl
 BTS
 BTTime
 BTV
+BUFRD
 BUZ
 BYP
 BZ
@@ -113,6 +115,7 @@ BayTech
 BeepTone
 Belkin's
 Benedikt
+Berge
 BestPort
 BiWeekly
 Bieringer
@@ -404,6 +407,7 @@ INIGO
 INNO
 INSTCMDDESC
 INTERNETOFFICE
+INTERR
 INTL
 INV
 INVOLT
@@ -551,6 +555,7 @@ Martinezgarza
 Martín
 Marzouk
 Massimo
+Matthijs
 MaxACVI
 MaxACVO
 MaxDCV
@@ -1424,6 +1429,7 @@ devd
 devel
 devscan
 dfl
+dialout
 dipsw
 dir
 disp
@@ -1537,6 +1543,7 @@ frob
 frontends
 fs
 fsd
+ftdi
 fuji
 fullload
 gamatronic
@@ -1814,11 +1821,13 @@ mmddyyyy
 mn
 modbus
 modelname
+modprobe
 monmaster
 monpasswd
 monslave
 monuser
 morbo
+msec
 multi
 multilink
 multimeter
@@ -1958,6 +1967,7 @@ pfy
 ph
 phasewindow
 phoenixcontact
+picocom
 pid
 pidpath
 pinout
@@ -2134,11 +2144,14 @@ shutdownpolarity
 shutdowntime
 shutup
 si
+siemens
 sigaction
 sigmask
 simplejson
 simu
+sio
 sitesearch
+sitop
 sizeof
 skel
 slavesync
@@ -2266,6 +2279,7 @@ tsd
 tty
 ttyS
 ttySx
+ttyUPS
 ttyUSB
 ttya
 ttyb

diff --git a/drivers/Makefile.am b/drivers/Makefile.am
@@ -33,7 +33,7 @@ SERIAL_DRIVERLIST = al175 bcmxcp belkin belkinunv bestfcom	\
  bestfortress bestuferrups bestups dummy-ups etapro everups 	\
  gamatronic genericups isbmex liebert liebert-esp2 masterguard metasys	\
  mge-utalk microdowell mge-shut oneac optiups powercom rhino 	\
- safenet skel solis tripplite tripplitesu upscode2 victronups powerpanel \
+ safenet nutdrv_siemens-sitop skel solis tripplite tripplitesu upscode2 victronups powerpanel \
  blazer_ser clone clone-outlet ivtscd apcsmart apcsmart-old apcupsd-ups riello_ser
 SNMP_DRIVERLIST = snmp-ups
 USB_LIBUSB_DRIVERLIST = usbhid-ups bcmxcp_usb tripplite_usb \
@@ -135,6 +135,7 @@ powerpanel_LDADD = $(LDADD) -lm
 rhino_SOURCES = rhino.c
 rhino_LDADD = $(LDADD) -lm
 safenet_SOURCES = safenet.c
+nutdrv_siemens_sitop_SOURCES = nutdrv_siemens_sitop.c
 solis_SOURCES = solis.c
 solis_LDADD = $(LDADD) -lm
 tripplite_SOURCES = tripplite.c
@@ -227,7 +228,7 @@ powerman_pdu_LDADD = $(LDADD) $(LIBPOWERMAN_LIBS)
 # IPMI PSU
 nut_ipmipsu_SOURCES = nut-ipmipsu.c
 if WITH_FREEIPMI
-  nut_ipmipsu_SOURCES += nut-libfreeipmi.c 
+  nut_ipmipsu_SOURCES += nut-libfreeipmi.c
 endif
 nut_ipmipsu_LDADD = $(LDADD) $(LIBIPMI_LIBS)