270 lines
8.6 KiB
Groff
270 lines
8.6 KiB
Groff
'\" t
|
|
.\" Title: nutdrv_siemens_sitop
|
|
.\" Author: [see the "AUTHOR" section]
|
|
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
|
|
.\" Date: 04/26/2022
|
|
.\" Manual: NUT Manual
|
|
.\" Source: Network UPS Tools 2.8.0
|
|
.\" Language: English
|
|
.\"
|
|
.TH "NUTDRV_SIEMENS_SITOP" "8" "04/26/2022" "Network UPS Tools 2\&.8\&.0" "NUT Manual"
|
|
.\" -----------------------------------------------------------------
|
|
.\" * Define some portability stuff
|
|
.\" -----------------------------------------------------------------
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.\" http://bugs.debian.org/507673
|
|
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\" -----------------------------------------------------------------
|
|
.\" * set default formatting
|
|
.\" -----------------------------------------------------------------
|
|
.\" disable hyphenation
|
|
.nh
|
|
.\" disable justification (adjust text to left margin only)
|
|
.ad l
|
|
.\" -----------------------------------------------------------------
|
|
.\" * MAIN CONTENT STARTS HERE *
|
|
.\" -----------------------------------------------------------------
|
|
.SH "NAME"
|
|
nutdrv_siemens_sitop \- driver for the Siemens SITOP UPS500 series UPS
|
|
.SH "NOTE"
|
|
.sp
|
|
This man page only documents the hardware\-specific features of the \fBnutdrv_siemens_sitop\fR driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
|
|
.SH "SUPPORTED HARDWARE"
|
|
.sp
|
|
\fBnutdrv_siemens_sitop\fR 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 \fBUSB driver\fR below)\&.
|
|
.if n \{\
|
|
.sp
|
|
.\}
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
\fBNote\fR
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
This driver has only been tested with the SITOP UPS500S\-2\&.5 with USB port (Siemens product number 6EP1933\-2EC41)\&.
|
|
.sp .5v
|
|
.RE
|
|
.SH "DEVICE SETTINGS"
|
|
.sp
|
|
The UPS is configured via DIP\-switches\&. For correct functioning in combination with NUT, set the DIP\-switches to the following:
|
|
.PP
|
|
\fBswitch 1\-4\fR
|
|
.RS 4
|
|
Choose whatever suits your situation\&. Any combination will work with NUT\&.
|
|
.RE
|
|
.PP
|
|
\fBswitch 5\fR (⇒ / t)
|
|
.RS 4
|
|
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)\&.
|
|
.RE
|
|
.PP
|
|
\fBswitch 6\-10\fR (delay)
|
|
.RS 4
|
|
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\&.
|
|
.RE
|
|
.PP
|
|
\fBswitch 11\fR (INTERR\&.)
|
|
.RS 4
|
|
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
|
|
\fBInstant Commands\fR
|
|
below\&.
|
|
.RE
|
|
.PP
|
|
\fBswitch 12\fR (ON/OFF)
|
|
.RS 4
|
|
set to ON (enable the UPS functionality)\&. Without this, the UPS will never supply power from its batteries\&.
|
|
.RE
|
|
.SH "USB DRIVER"
|
|
.sp
|
|
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 \fI0403:e0e3\fR), but can still be used with the normal ftdi_sio driver\&.
|
|
.if n \{\
|
|
.sp
|
|
.\}
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
\fBNote\fR
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
The following hints may be specific to GNU/Linux\&.
|
|
.sp .5v
|
|
.RE
|
|
.sp
|
|
Use \fBlsusb\fR to figure out which product ID is used in your model, and replace all occurrences of \fIe0e3\fR in the following examples with the actual Product ID\&.
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
modprobe ftdi_sio
|
|
echo 0403 e0e3 > /sys/bus/usb\-serial/drivers/ftdi_sio/new_id
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
If your system uses \fBudev\fR, this can be automated via a udev rule:
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
ACTION=="add", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="e0e3", \e
|
|
RUN+="/sbin/modprobe ftdi_sio", \e
|
|
RUN+="/bin/sh \-c \*(Aqecho 0403 e0e3 > /sys/bus/usb\-serial/drivers/ftdi_sio/new_id\*(Aq"
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
You can use the following udev rule to obtain a predictable device name, for example \fI/dev/ttyUPS\fR:
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
SUBSYSTEM=="tty" ATTRS{idVendor}=="0403", ATTRS{idProduct}=="e0e3" SYMLINK+="ttyUPS"
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.SH "POLLING"
|
|
.sp
|
|
The UPS does not have a special \fIget status\fR command\&. Instead, it continuously sends out status update messages (tens of messages per second)\&. Every \fBpollinterval\fR, 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, \fBpollinterval\fR should be set to a relatively low value\&. The recommended value is 1 (second)\&.
|
|
.SH "EXTRA ARGUMENTS"
|
|
.sp
|
|
This driver supports the following optional settings:
|
|
.PP
|
|
\fBmax_polls_without_data\fR=\fInum\fR
|
|
.RS 4
|
|
The serial port is polled periodically for new data (see
|
|
\fBPolling\fR)\&. If there is no valid new data after
|
|
\fInum\fR
|
|
polls, it is assumed that communication with the UPS is lost\&. The default value is 2\&. Lower values may cause spurious
|
|
\fIData stale\fR
|
|
messages, especially at startup\&.
|
|
.RE
|
|
.SH "INSTANT COMMANDS"
|
|
.PP
|
|
\fBshutdown\&.return\fR
|
|
.RS 4
|
|
The behavior of this command depends on the line state:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fBon line\fR: 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\&.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fBon battery\fR: 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\&.
|
|
.RE
|
|
.RE
|
|
.PP
|
|
\fBshutdown\&.stayoff\fR
|
|
.RS 4
|
|
The behavior of this command depends on the line state:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fBon line\fR: 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\&.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fBon battery\fR: this command behaves the same as
|
|
\fBshutdown\&.return\fR\&.
|
|
.RE
|
|
.RE
|
|
.SH "INSTALLATION"
|
|
.sp
|
|
Make sure that your operating system has created a serial device for the UPS\&. See the section \fBUSB driver\fR for more information\&.
|
|
.sp
|
|
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 \fBdialout\fR group on Debian\-based systems)\&.
|
|
.SH "DIAGNOSTICS"
|
|
.sp
|
|
You can verify the correct functioning of the hardware, by monitoring the serial port with a terminal program, for example picocom:
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
picocom \-b 9600 \-d 8 \-p n /dev/ttyUPS
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
NUT must not be running when you do this\&. You should now see a continuous stream of 5\-character texts coming in, for example:
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
BUFRD
|
|
BA>85
|
|
DC_OK
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
To exit picocom, use Ctrl\-A Ctrl\-X\&.
|
|
.SH "KNOWN ISSUES AND BUGS"
|
|
.PP
|
|
\fBUntested models\fR
|
|
.RS 4
|
|
As mentioned under
|
|
\fBSupported hardware\fR, this driver has not been tested with all models in the SITOP UPS500 series\&.
|
|
.RE
|
|
.PP
|
|
\fBData stale messages\fR
|
|
.RS 4
|
|
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\&.
|
|
.RE
|
|
.SH "AUTHOR"
|
|
.sp
|
|
Matthijs H\&. ten Berge
|
|
.SH "SEE ALSO"
|
|
.SS "The core driver:"
|
|
.sp
|
|
\fBnutupsdrv\fR(8)
|
|
.SS "Internet resources:"
|
|
.sp
|
|
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/
|