Berge, Matthijs ten
2018-Mar-14 11:26 UTC
[Nut-upsuser] 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.
Berge, Matthijs ten
2018-Mar-15 13:04 UTC
[Nut-upsuser] Interfacing with Siemens SITOP UPS500S
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