Nut upsuser - Mar 2018 - Interfacing with Siemens SITOP UPS500S

Hello all,

For an upcoming project I will have to interface with a 24V DC UPS from Siemens
(full name: Siemens SITOP UPS500S, manufacturer nr 6EP1933-2EC41).
As this device is not listed in the compatibility list, I will have to write my
own driver.

I already found out, that the UPS has a serial-over-USB interface (USB
full-speed, 12 MBps), using an FTDI chip.
Over this serial port, it will periodically spit out some 5-character plaintext
strings (every 75 msec):
BUFRD - battery ok, UPS functionality available
ALARM - battery critical or bad. When on line: no UPS functionality possible;
when on battery: battery level critical, will shut down very soon
DC_OK - input voltage (line) ok
DC_LO - input voltage (line) too low
***** - running on line
*BAT* - running on battery
BA>85 - battery charge > 85%
BA<85 - battery charge < 85%

The ordered device is still on its way, so at the moment I cannot test how these
strings are separated (CR/LF, space or nothing) and which combinations can
occur.

There is only one character that can be sent _to_ the UPS: the 'R'
character remotely starts the timer countdown, after which the UPS will shut off
the load.

The timer delay can be configured on the device itself, with DIP switches. It
determines the time between an 'on battery' event (or the 'R'
command) and powering off the load.

Can anyone point me in the right direction where I should start? I already found
http://networkupstools.org/docs/developer-guide.chunked/ar01s04.html, but it
doesn't give any specific tips for serial communication. For example, which
source can I use best as a starting point?
Or does anyone recognize this protocol, and is it already compatible with an
existing driver?

Thanks in advance,

Matthijs
DISCLAIMER: For our full disclaimer, please visit
www.awl.nl/en/about-us/disclaimer

On Mar 14, 2018, at 7:26 AM, Berge, Matthijs ten wrote:
> 
> Can anyone point me in the right direction where I should start? I already
found http://networkupstools.org/docs/developer-guide.chunked/ar01s04.html, but
it doesn't give any specific tips for serial communication. For example,
which source can I use best as a starting point?
> Or does anyone recognize this protocol, and is it already compatible with
an existing driver?
> 
Those strings don't show up in a quick search of the driver source code, so
it looks like you are correct in that you will need to write a new driver.

A little further down on the page you cited is the list of serial functions
provided by NUT (Section 4.11). There are also a few contrived serial examples
in drivers/skel.c, which we recommend copying as a starting point for a driver.

This is all assuming that your OS recognizes the FTDI chip as a USB-to-serial
converter, and creates the appropriate character device (for instance,
/dev/ttyUSB* on Linux). There are other USB drivers in NUT that communicate with
non-kernel-supported USB-to-serial converters, but there are complications with
wrestling the USB interface away from the kernel driver, so I'd advise
against that if you can help it.

I don't recall any other drivers which parse a continuous stream of data
without sending a query command. For a query/response example, ivtscd.c is
relatively straightforward to understand.

Given the fixed-length strings and unambiguity of the commands, you might want a
loop like the following:

ser_flush_in()
while(!done && !timed_out) {
    ser_get_char()
    // append to buffer
    check for match
    check for timeout
}

One thing that may be useful while waiting for hardware is to embed a test
harness in the code. We don't have much of a standard for this, but as long
as the code doesn't turn into spaghetti, feel free to use something like
"#ifdef TESTING" to allow the driver to be tested offline.

If you do need to do systems-level testing before the driver is complete, you
may be interested in the dummy-ups driver. It allows you to write a script of
the data you expect the SITOP driver to return, and then test system shutdown or
notifications. Obviously, this requires making a number of assumptions about the
UPS, but it is a starting point if you want to allow some parallel development.

http://new.networkupstools.org/docs/man/dummy-ups.html or if the build
infrastructure is being cranky,
http://networkupstools.org/docs/man/dummy-ups.html

Please use reply-all to include the list when responding - this list does not
mangle the headers.

Charles, thanks for your comprehensive answer. It has definitely pointed me in
the right direction. With the skeleton driver and the example ivtscd.c I can
probably figure it out now.

After testing is done, you'll see the PR (I hope) ;-)

Matthijs

-----Original Message-----
From: Charles Lepple [mailto:clepple at gmail.com]
Sent: woensdag 14 maart 2018 13:35
To: Berge, Matthijs ten <M.tenBerge at awl.nl>
Cc: nut-upsuser at lists.alioth.debian.org
Subject: Re: [Nut-upsuser] Interfacing with Siemens SITOP UPS500S

On Mar 14, 2018, at 7:26 AM, Berge, Matthijs ten wrote:
>
> Can anyone point me in the right direction where I should start? I already
found http://networkupstools.org/docs/developer-guide.chunked/ar01s04.html, but
it doesn't give any specific tips for serial communication. For example,
which source can I use best as a starting point?
> Or does anyone recognize this protocol, and is it already compatible with
an existing driver?
>
Those strings don't show up in a quick search of the driver source code, so
it looks like you are correct in that you will need to write a new driver.

A little further down on the page you cited is the list of serial functions
provided by NUT (Section 4.11). There are also a few contrived serial examples
in drivers/skel.c, which we recommend copying as a starting point for a driver.

This is all assuming that your OS recognizes the FTDI chip as a USB-to-serial
converter, and creates the appropriate character device (for instance,
/dev/ttyUSB* on Linux). There are other USB drivers in NUT that communicate with
non-kernel-supported USB-to-serial converters, but there are complications with
wrestling the USB interface away from the kernel driver, so I'd advise
against that if you can help it.

I don't recall any other drivers which parse a continuous stream of data
without sending a query command. For a query/response example, ivtscd.c is
relatively straightforward to understand.

Given the fixed-length strings and unambiguity of the commands, you might want a
loop like the following:

ser_flush_in()
while(!done && !timed_out) {
    ser_get_char()
    // append to buffer
    check for match
    check for timeout
}

One thing that may be useful while waiting for hardware is to embed a test
harness in the code. We don't have much of a standard for this, but as long
as the code doesn't turn into spaghetti, feel free to use something like
"#ifdef TESTING" to allow the driver to be tested offline.

If you do need to do systems-level testing before the driver is complete, you
may be interested in the dummy-ups driver. It allows you to write a script of
the data you expect the SITOP driver to return, and then test system shutdown or
notifications. Obviously, this requires making a number of assumptions about the
UPS, but it is a starting point if you want to allow some parallel development.

http://new.networkupstools.org/docs/man/dummy-ups.html or if the build
infrastructure is being cranky,
http://networkupstools.org/docs/man/dummy-ups.html

Please use reply-all to include the list when responding - this list does not
mangle the headers.
DISCLAIMER: For our full disclaimer, please visit
www.awl.nl/en/about-us/disclaimer