Merge pull request #3228 from DarkMike-ru/must_ep2000

MUST EP2000Pro driver (modbus)

Author: jimklimov

NEWS.adoc

@@ -98,6 +98,10 @@ https://github.com/networkupstools/nut/milestone/12
  - Introduced a new NUT driver named `meanwell_ntu` which provides support for
    the Mean Well NTU series hybrid inverter and UPS units. [PR #3206]
 
+ - Introduced a new NUT driver named `must_ep2000pro` which provides support
+   for the MUST EP2000Pro compatible, line-interactive UPS models which talk
+   serial-protocol modbus protocol. [PR #3228]
+
  - `nhs_ser` driver updates:
    * Driver source code includes a table to map baud rates (defined by the OS
      as C macros) to numbers and strings more useful to the driver program.

data/driver.list.in

@@ -963,6 +963,8 @@
 
 "Minibox"	"ups"	"5"	"openUPS Intelligent UPS"	"USB port"	"usbhid-ups"
 
+"Must"	"ups"	"4"	"EP2000Pro"	""	"must_ep2000pro"
+
 "Mustek"	"ups"	"2"	"Powermust"	"400VA Plus"	"blazer_ser"
 "Mustek"	"ups"	"2"	"Powermust"	"600VA Plus"	"blazer_ser"
 "Mustek"	"ups"	"2"	"Powermust"	"800VA Pro"	"blazer_ser"

docs/man/Makefile.am

@@ -1342,6 +1342,7 @@ SRC_MODBUS_PAGES = \
 	generic_modbus.txt \
 	huawei-ups2000.txt \
 	socomec_jbus.txt   \
+	must_ep2000pro.txt   \
 	adelsystem_cbi.txt \
 	apc_modbus.txt
 
@@ -1350,6 +1351,7 @@ INST_MAN_MODBUS_PAGES = \
 	generic_modbus.$(MAN_SECTION_CMD_SYS) \
 	huawei-ups2000.$(MAN_SECTION_CMD_SYS) \
 	socomec_jbus.$(MAN_SECTION_CMD_SYS)   \
+	must_ep2000pro.$(MAN_SECTION_CMD_SYS)   \
 	adelsystem_cbi.$(MAN_SECTION_CMD_SYS) \
 	apc_modbus.$(MAN_SECTION_CMD_SYS)
 
@@ -1370,6 +1372,7 @@ INST_HTML_MODBUS_MANS = \
 	generic_modbus.html \
 	huawei-ups2000.html \
 	socomec_jbus.html   \
+	must_ep2000pro.html   \
 	adelsystem_cbi.html \
 	apc_modbus.html
 DIST_ALL_HTML_PAGES += $(INST_HTML_MODBUS_MANS)

docs/man/must_ep2000pro.txt

@@ -0,0 +1,121 @@
+MUST_EP2000Pro(8)
+=================
+
+NAME
+----
+
+must_ep2000pro - Driver for MUST EP2000Pro UPS with
+RS-232 serial Modbus connection.
+
+SYNOPSIS
+--------
+
+*must_ep2000pro* -h
+
+*must_ep2000pro* -a 'DEVICE_NAME' ['OPTIONS']
+
+NOTE: This man page only documents the hardware-specific features of the
+'must_ep2000pro' driver.  For information about the core driver, see
+linkman:nutupsdrv[8].
+
+SUPPORTED HARDWARE
+------------------
+
+This driver supports MUST EP2000Pro compatible, line-interactive
+UPS with the following characteristics:
+
+1. 12V or 24V external battery
+
+2. Connection: RS-232 or USB (via RS232-to-USB converter dongle)
+
+Some models that may be covered by this driver:
+
+* Original EP200Pro
+* Energy Smart.2
+* Luxeon UPS-500ZR
+* Bineos EP20-1000 PRO
+* any other work with original program from MUST
+
+Currently, it has only been tested on the following model:
+
+* Energy Smart.2 600W
+
+Generally, these device do not serve any identification data, so
+autodetection is not possible. Only one documented piece of info is
+"software version" with unknown meaning.
+
+The `must_ep2000pro` driver uses the libmodbus project, for Modbus
+implementation.
+
+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.
+
+EXTRA ARGUMENTS
+---------------
+
+This driver also supports the following optional settings:
+
+*lowbatt*='num'::
+Set the value of `battery.charge.low` to 'num'. Device itself has only switch-off
+on low battery voltage.
+
+INSTANT COMMANDS
+----------------
+
+This driver supports some instant commands (see linkman:upscmd[8]):
+
+*beeper.enable*::
+Enable the UPS beeper
+
+*beeper.disable*::
+Disable the UPS beeper
+
+*shutdown.return*::
+Turn off the load and wait for the power to return
+
+KNOWN PROBLEMS
+--------------
+
+If you run the *shutdown.return* command with mains present it does nothing.
+
+If you run the *shutdown.return* command without mains present it immediately
+powers off the device.
+
+There is no setting in device documentation to specify a shutdown delay.
+
+AUTHOR
+------
+
+Mikhail Mironov <[email protected]>
+
+SEE ALSO
+--------
+
+The core driver:
+~~~~~~~~~~~~~~~~
+
+linkman:nutupsdrv[8]
+
+Internet resources:
+~~~~~~~~~~~~~~~~~~~
+
+* The NUT (Network UPS Tools) home page: https://www.networkupstools.org/
+* libmodbus home page: http://libmodbus.org
+* Simple data reader for similar device: https://github.com/reverieline/ep2000pro

docs/nut.dict

@@ -132,6 +132,7 @@ Berge
 Berzonis
 Bieringer
 BigServers
+Bineos
 BlaXwan
 BlackOut
 BladeUPS
@@ -687,6 +688,7 @@ LogMin
 LowBatt
 Loyer
 Luca
+Luxeon
 Lygre
 Lynge
 MANPATH
@@ -761,6 +763,7 @@ MinGW
 MiniCOL
 MiniGuard
 Minislot
+Mironov
 Moar
 Modbus
 ModemManager

drivers/Makefile.am

@@ -90,7 +90,7 @@ SERIAL_USB_DRIVERLIST = \
 	nutdrv_qx
 NEONXML_DRIVERLIST = netxml-ups
 MACOSX_DRIVERLIST = macosx-ups
-MODBUS_DRIVERLIST = phoenixcontact_modbus generic_modbus huawei-ups2000 socomec_jbus adelsystem_cbi apc_modbus
+MODBUS_DRIVERLIST = phoenixcontact_modbus generic_modbus huawei-ups2000 socomec_jbus adelsystem_cbi apc_modbus must_ep2000pro
 LINUX_I2C_DRIVERLIST = asem pijuice hwmon_ina219
 POWERMAN_DRIVERLIST = powerman-pdu
 IPMI_DRIVERLIST = nut-ipmipsu
@@ -385,6 +385,11 @@ huawei_ups2000_LDADD = $(LDADD_DRIVERS_SERIAL) $(LIBMODBUS_LIBS)
 socomec_jbus_SOURCES = socomec_jbus.c
 socomec_jbus_LDADD = $(LDADD_DRIVERS_SERIAL) $(LIBMODBUS_LIBS)
 
+# MUST EP2000Pro driver
+# (this is a Modbus driver)
+must_ep2000pro_SOURCES = must_ep2000pro.c
+must_ep2000pro_LDADD = $(LDADD_DRIVERS_SERIAL) $(LIBMODBUS_LIBS)
+
 # Linux I2C drivers
 asem_LDADD = $(LDADD_DRIVERS) $(LIBI2C_LIBS)
 asem_SOURCES = asem.c