Merge pull request #1313 from tchatzi/master

Added socomec_jbus implementation

docs/man/socomec_jbus.txt

@@ -0,0 +1,161 @@
+Socomec_jbus(8)
+==================
+
+NAME
+----
+
+socomec_jbus - Driver for Socomec JBUS UPS with 
+RS-232 serial Modbus connection.
+
+SYNOPSIS
+--------
+
+*socomec_jbus* -h
+
+*socomec_jbus* -a 'DEVICE_NAME' ['OPTIONS']
+
+NOTE: This man page only documents the hardware-specific features of the
+socomec_jbus driver.  For information about the core driver, see
+linkman:nutupsdrv[8].
+
+SUPPORTED HARDWARE
+------------------
+
+This driver supports Socomec JBUS series, online (double conversion)
+UPS with the following characteristics.
+
+1. Single phase and 3-phase UPS
+
+2. Connection: RS-232 
+
+These are typically provided with a Netvision WEB/SNMP management card / external 
+box that would be better served by the linkman:snmp-ups[8] driver.
+In case netvision isn't available, you can hook up the UPS directly via the
+serial port and use this driver.
+
+Currently, it has only been tested on the following model.
+
+* DIGYS 3/3 15kVA
+
+In theory, any Socomec JBUS model should work. It should be discovered
+as ``Unknown Socomec JBUS'' with a numeric id that I'll need to add it
+to the list of supported UPSs. 
+
+Sadly, Socomec document only mentions DELPHYS MX and DELPHYS MX elite and
+I have the id of my own DIGYS, so chances are, your model will not be 
+recognized but will probably mostly work. Please report successful
+or unsuccessful results to the bug tracker or the mailing list.
+Make sure to include the full model number of your UPS manually
+in your report.
+
+socomec_jbus uses the libmodbus project, for Modbus implementation.
+
+CABLING
+-------
+
+The UPS has an RS-232 port which should be connected with a NULL-modem
+cable to a PC serial port. The UPS tested has a female DB9 connector, 
+so if you construct the cable yourself, make note of the connector type to 
+avoid using gender changers.
+
+RS-232 is supported on all operating systems, either via a built-in serial
+port on your computer, or by using an external USB-to-RS-232 converter. If
+you plan to use an USB-to-RS-232 converter, make sure it's supported by your
+operating system.
+
+
+INSTALLATION
+------------
+
+This driver should be built by default if libmodbus and development headers are
+available. You can force the configure script to build it with the following 
+arguments:
+
+    configure --with-serial=yes --with-modbus=yes
+
+You also need to give proper (R/W) permissions on the local serial device file
+to allow the NUT driver run-time user to access it. This may need additional
+setup for start-up scripting, udev or upower rules, to apply the rights on every
+boot -- especially if your device nodes are tracked by a virtual filesystem.
+
+For example, a USB-to-serial converter can be identified as `/dev/ttyACM0`
+or `/dev/ttyUSB0` on Linux, or `/dev/ttyU0` on FreeBSD (note the capital "U").
+A built-in serial port can be identified as `/dev/ttyS0` on Linux or one of
+`/dev/cua*` names on FreeBSD.
+
+INSTANT COMMANDS
+----------------
+
+This driver does not (yet?) support sending commands to the UPS. 
+
+VARIABLES
+---------
+
+This driver does not support writable runtime variables (see linkman:upsrw[8]):
+for the same reasons.
+Both should be trivial to implement, but since I've already found one or two
+inconsistencies in the documentation, I'm witholding from trying them.
+
+KNOWN ISSUES AND BUGS
+---------------------
+
+Well, it is an alpha release at best, but so far appears to report the UPS status
+reliably. Mostly based on the work of Yifeng Li <tomli@tomli.me> on the huawei-ups2000 
+in that very same source tree.
+
+Read failure on some JBUS addresses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The driver polls all documented JBUS addresses and it is quite possible that your
+UPS model does not support one of them. (eg the Digys does not support address 
+0x1020 which should provide the current UPS status).
+This should be logged with LOG_ERR from modbus_read_input_registers() 
+along with the address that produced the error.
+
+Data stale
+~~~~~~~~~~~
+
+Under certain circumstances, some registers can return invalid values
+and trigger a "data stale" error. Once a data stale error has occurred,
+you should see error messages similar to the example below in the system
+log.
+
+    socomec_jbus: modbus_read_input_registers(addr:XXXX, count:Z): Illegal data address
+    upsd: Data for UPS [socomec] is stale - check driver
+    upsd: UPS [socomec] data is no longer stale
+
+So far all known problems have been fixed by the author, but an unknown one
+cannot be ruled out. If you have encountered "data stale" problems during
+normal uses, please file a bug report with full logs attached.
+
+Before troubleshooting or reporting a problem, it's important to check
+your *dmesg* log for USB connect and disconnect events to avoid wasting
+time on the NUT driver when the actual problem is USB. For example, if
+someone yanks the cable out of the USB port, or if a new USB device is
+plugged into a USB host/hub that is struggling to power its ports
+(common on single-board computers like Raspberry Pi), or if you have
+flaky cabling or EMI noise, the serial converter can get disconnected
+from USB, at least briefly. This creates a permanent data stale, the driver
+must be restarted (plugging the USB back won't fix it, since the driver
+is still using the nonexistent serial device). These USB problems usually
+have nothing to do with NUT. If it's the case, you should solve the
+underlying USB problem - check the cable, check the converter, try a
+powered USB hub, try a full-speed USB isolator, etc.
+
+AUTHOR
+------
+Thanos Chatziathanassiou <tchatzi@arx.net>
+
+SEE ALSO
+--------
+The core driver:
+~~~~~~~~~~~~~~~~
+linkman:nutupsdrv[8]
+
+Internet resources:
+~~~~~~~~~~~~~~~~~~~
+The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
+
+Socomec JBUS/Modbus Reference Guide: https://www.socomec.com/files/live/sites/systemsite/files/GB-JBUS-MODBUS-for-Delphys-MP-and-Delphys-MX-operating-manual.pdf
+
+libmodbus home page: http://libmodbus.org

drivers/Makefile.am

@@ -50,7 +50,7 @@ SERIAL_USB_DRIVERLIST = \
 	nutdrv_qx
 NEONXML_DRIVERLIST = netxml-ups
 MACOSX_DRIVERLIST = macosx-ups
-MODBUS_DRIVERLIST = phoenixcontact_modbus generic_modbus huawei-ups2000
+MODBUS_DRIVERLIST = phoenixcontact_modbus generic_modbus huawei-ups2000 socomec_jbus
 LINUX_I2C_DRIVERLIST = asem pijuice
 POWERMAN_DRIVERLIST = powerman-pdu
 IPMI_DRIVERLIST = nut-ipmipsu
@@ -281,6 +281,11 @@ generic_modbus_LDADD = $(LDADD_DRIVERS) $(LIBMODBUS_LIBS)
 huawei_ups2000_SOURCES = huawei-ups2000.c
 huawei_ups2000_LDADD = $(LDADD_DRIVERS_SERIAL) $(LIBMODBUS_LIBS)
 
+# Socomec JBUS driver
+# (this is a Modbus driver)
+socomec_jbus_SOURCES = socomec_jbus.c
+socomec_jbus_LDADD = $(LDADD_DRIVERS_SERIAL) $(LIBMODBUS_LIBS)
+
 # Linux I2C drivers
 asem_LDADD = $(LDADD_DRIVERS)
 asem_SOURCES = asem.c