generic_modbus - Man Page
Driver for contact (direct) signal UPS devices connected via modbus remote I/O gateways
Synopsis
generic_modbus -h
generic_modbus -a DEVICE_NAME [OPTIONS]
Note
This man page only documents the specific features of the generic_modbus driver. For information about the core driver, see nutupsdrv(8).
Supported Hardware
This is a generic modbus driver expected to work with contact (direct) signal UPS devices, connected via modbus RIO (remote I/O) either serial or TCP/IP.
The driver has been tested against PULS UPS (model UB40.241) via MOXA ioLogikR1212 (RS485) and ioLogikE1212 (TCP/IP).
More information about this UPS can be found here:
https://products.pulspower.com/ca/ubc10-241-n1.html
More information about Moxa ioLogik R1212, E1212 can be found here:
https://www.moxa.com/en/products/industrial-edge-connectivity/controllers-and-ios
The PULS UPS UB40.241 supports the following signals:
Ready contact (DO) <--> HB Buffering contact (DO) <--> OL | OB Battery-low (DO) <--> LB Replace Battery (DO) <--> RB Inhibit (DI) <--> FSD
Digital port direction (DI/DO) assumes the device perspective
The driver’s concept is to map the UPS states (as defined in NUT) onto UPS contacts' states. The driver has an extended configuration interface implemented using variables defined in ups.conf.
Hardware Interconnection
The commission of modbus remote I/O server as well as UPS device is carried out following the corresponding instruction manuals. The following figure depicts the anticipated communication path and hardware interconnection:
+------+ +----------------+ +------------+ +------------+
| UPSD | <---> | GENERIC_MODBUS | <---> | MODBUS RIO | <---> | UPS DEVICE |
+------+ (1) +----------------+ (2) +------------+ (3) +------------+
| |
+-------------------+
HOST CONTROLLER
(1) Unix IPC
(2) RS232 | TCP/IP
(3) contactsExtra Arguments
This driver supports the following optional settings in the ups.conf(5) file:
Generic
- device_mfr=value
A string specifying the manufacturer of the UPS device (default UNKNOWN).
- device_model=value
A string specifying the model of the UPS device (default UNKNOWN).
Serial
- ser_baud_rate=value
A integer specifying the serial port baud rate (default 9600).
- ser_data_bit=value
A integer specifying the serial port data bit (default 8).
- ser_parity=value
A character specifying the serial port parity (default N).
- ser_stop_bit=value
An integer specifying the serial port stop bit (default 1).
Modbus
- rio_slave_id=value
An integer specifying the RIO modbus slave ID (default 1).
States (X = OL, OB, LB, HB, RB, CHRG, DISCHRG, FSD)
- <X>_addr=value
A number specifying the modbus address for the X state.
- <X>_regtype=value
A number specifying the modbus register type for the X state
Default values:
1 for X = OL, OB, LB ,HB, RB, CHRG, DISCHRG 0 for X = FSD
Valid values:
0:COIL, 1:INPUT_B, 2:INPUT_R, 3:HOLDING
- <X>_noro=value
A number specifying the contact configuration for the X state (default 1).
Valid values:
0:NC, 1:NO
Note
NO stands for normally open and NC for normally closed contact
Shutdown
- FSD_pulse_duration=value
A number specifying the duration in milliseconds for the inhibit pulse. If it’s not defined, signal has only one transition depending on FSD_noro configuration.
Examples for FSD signal configuration:
FSD_noro = 1
FSD_pulse_duration = 150
+-----+
| |
inhibit pulse >-----+ +------------------>
<--->
150ms
FSD_noro = 0
inhibit pulse >-----+
|
+------------------------>Configuration
Here is an example of generic_modbus driver configuration in ups.conf file:
[generic_modbus] driver = generic_modbus port = /dev/ttyUSB0 desc = "generic ups driver" # device info device_mfr = "PULS" device_model = "UB40.241" # serial settings ser_baud_rate = 9600 ser_parity = N ser_data_bit = 8 ser_stop_bit = 1 # modbus slave id rio_slave_id = 5 # UPS signal state attributes OB_addr = 0x0 OB_regtype = 1 OB_noro = 0 LB_addr = 0x1 LB_regtype = 1 HB_addr = 0x2 HB_regtype = 1 RB_addr = 0x3 RB_regtype = 1 FSD_addr = 0x0 FSD_regtype = 0 FSD_pulse_duration = 150
Instant Commands
This driver support the following instant commands:
- load.off
executes "instant poweroff"
Installation
This driver may be not built by default. You can build it by installing libmodbus and running configure --with-modbus=yes.
You also need to give proper permissions on the local serial device file (/dev/ttyUSB0 for example) to allow the run-time NUT driver user account to access it.
Other Notes
The generic_modbus driver intends to support generic UPS devices with contact signals through modbus TCP/RTU gateways (also known as RIO — remote I/Os). The data and signal path looks like this:
[UPSD] <--- IPC ---> [GENERIC_UPS] <--- modbus TCP/RTU ---> MODBUS-RIO <--- contacts ---> [UPS DEVICE]
On the other hand, you can setup any kind of modbus server, and configure the generic_modbus driver to connect and read or write specific registers. Your application / modbus server could then drive NUT statuses (e.g. OL, OB, HB etc) by writing over those registers.
Known Issues
Using host names for UPS NMC
An UPS network management card may be assigned a fixed/static IP address or a dynamic one (e.g. by DHCP) in your network. Due to this, you may want or have to use a dynamic naming service to access the UPS. Note that this may become a problem specifically during large outages and shutdowns, when your DHCP/DNS server might already go down while the driver needs to resolve the name involved (especially during late-shutdown hooks, when a new instance of the driver program might start just to tell the UPS to power off or to power-cycle).
It may be wise to ensure your OS name service client can cache the UPS name sufficiently long, or to use fixed IP addressing (and an entry in /etc/hosts for good measure, so you only have one spot to eventually re-configure this).
Author
Dimitris Economou <dimitris.s.economou@gmail.com>
See Also
The core driver
Internet resources
- The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/
- libmodbus home page: http://libmodbus.org