generic_modbus(8)

1GENERIC_MODBUS(8)                 NUT Manual                 GENERIC_MODBUS(8)
2
3
4

NAME

6       generic_modbus - Driver for contact (direct) signal UPS devices
7       connected via modbus remote I/O gateways
8

SYNOPSIS

10       generic_modbus -h
11
12       generic_modbus -a DEVICE_NAME [OPTIONS]
13
14           Note
15           This man page only documents the specific features of the
16           generic_modbus driver. For information about the core driver, see
17           nutupsdrv(8).
18

SUPPORTED HARDWARE

20       This is a generic modbus driver expected to work with contact (direct)
21       signal UPS devices, connected via modbus RIO (remote I/O) either serial
22       or TCP/IP.
23
24       The driver has been tested against PULS UPS (model UB40.241) via MOXA
25       ioLogikR1212 (RS485) and ioLogikE1212 (TCP/IP).
26
27       More information about this UPS can be found here:
28           https://products.pulspower.com/ca/ubc10-241-n1.html
29
30       More information about Moxa ioLogik R1212, E1212 can be found here:
31           https://www.moxa.com/en/products/industrial-edge-connectivity/controllers-and-ios
32
33       The PULS UPS UB40.241 supports the following signals:
34
35           Ready contact      (DO) <--> HB
36           Buffering contact  (DO) <--> OL | OB
37           Battery-low        (DO) <--> LB
38           Replace Battery    (DO) <--> RB
39           Inhibit            (DI) <--> FSD
40
41       Digital port direction (DI/DO) assumes the device perspective
42
43       The driver’s concept is to map the UPS states (as defined in NUT) onto
44       UPS contacts' states. The driver has an extended configuration
45       interface implemented using variables defined in ups.conf.
46

HARDWARE INTERCONNECTION

48       The commission of modbus remote I/O server as well as UPS device is
49       carried out following the corresponding instruction manuals. The
50       following figure depicts the anticipated communication path and
51       hardware interconnection:
52
53           +------+       +----------------+       +------------+       +------------+
54           | UPSD | <---> | GENERIC_MODBUS | <---> | MODBUS RIO | <---> | UPS DEVICE |
55           +------+  (1)  +----------------+  (2)  +------------+  (3)  +------------+
56              |                   |
57              +-------------------+
58                 HOST CONTROLLER
59
60           (1) Unix IPC
61           (2) RS232 | TCP/IP
62           (3) contacts
63

EXTRA ARGUMENTS

65       This driver supports the following optional settings in the ups.conf(5)
66       file:
67
68   Generic:
69       device_mfr=value
70           A string specifying the manufacturer of the UPS device (default
71           UNKNOWN).
72
73       device_model=value
74           A string specifying the model of the UPS device (default UNKNOWN).
75
76   Serial:
77       ser_baud_rate=value
78           A integer specifying the serial port baud rate (default 9600).
79
80       ser_data_bit=value
81           A integer specifying the serial port data bit (default 8).
82
83       ser_parity=value
84           A character specifying the serial port parity (default N).
85
86       ser_stop_bit=value
87           An integer specifying the serial port stop bit (default 1).
88
89   Modbus:
90       rio_slave_id=value
91           An integer specifying the RIO modbus slave ID (default 1).
92
93   States (X = OL, OB, LB, HB, RB, CHRG, DISCHRG, FSD)
94       <X>_addr=value
95           A number specifying the modbus address for the X state.
96
97       <X>_regtype=value
98           A number specifying the modbus register type for the X state
99
100       Default values:
101
102               1 for X = OL, OB, LB ,HB, RB, CHRG, DISCHRG
103               0 for X = FSD
104
105       Valid values:
106
107               0:COIL, 1:INPUT_B, 2:INPUT_R, 3:HOLDING
108
109       <X>_noro=value
110           A number specifying the contact configuration for the X state
111           (default 1).
112
113       Valid values:
114
115               0:NC, 1:NO
116
117               Note
118               NO stands for normally open and NC for normally closed contact
119
120   Shutdown
121       FSD_pulse_duration=value
122           A number specifying the duration in ms for the inhibit pulse. If
123           it’s not defined, signal has only one transition depending on
124           FSD_noro configuration.
125
126           Examples for FSD signal configuration:
127
128           FSD_noro = 1
129           FSD_pulse_duration = 150
130
131                                +-----+
132                                |     |
133           inhibit pulse  >-----+     +------------------>
134                                 <--->
135                                 150ms
136
137
138           FSD_noro = 0
139
140           inhibit pulse  >-----+
141                                |
142                                +------------------------>
143

CONFIGURATION

145       Here is an example of generic_modbus driver configuration in ups.conf
146       file:
147
148           [generic_modbus]
149             driver = generic_modbus
150             port = /dev/ttyUSB0
151             desc = "generic ups driver"
152             # device info
153             device_mfr = "PULS"
154             device_model = "UB40.241"
155             # serial settings
156             ser_baud_rate = 9600
157             ser_parity = N
158             ser_data_bit = 8
159             ser_stop_bit = 1
160             # modbus slave id
161             rio_slave_id = 5
162             # UPS signal state attributes
163             OB_addr = 0x0
164             OB_regtype = 1
165             OB_noro = 0
166             LB_addr = 0x1
167             LB_regtype = 1
168             HB_addr = 0x2
169             HB_regtype = 1
170             RB_addr = 0x3
171             RB_regtype = 1
172             FSD_addr = 0x0
173             FSD_regtype = 0
174             FSD_pulse_duration = 150
175

INSTANT COMMANDS

177       This driver support the following instant commands:
178
179       load.off
180           executes "instant poweroff"
181

INSTALLATION

183       This driver is not built by default. You can build it by installing
184       libmodbus and running configure --with-modbus=yes.
185
186       You also need to give proper permissions on the local serial device
187       file (/dev/ttyUSB0 for example) to allow the run-time NUT driver user
188       account to access it.
189

OTHER NOTES

191       The generic_modbus driver intends to support generic UPS devices with
192       contact signals through modbus TCP/RTU gateways (also known as RIO —
193       remote I/Os). The data and signal path looks like this:
194
195           [UPSD] <--- IPC ---> [GENERIC_UPS] <--- modbus TCP/RTU ---> MODBUS-RIO <--- contacts ---> [UPS DEVICE]
196
197       On the other hand, you can setup any kind of modbus server, and
198       configure the generic_modbus driver to connect and read or write
199       specific registers. Your application / modbus server could then drive
200       NUT statuses (e.g. OL, OB, HB etc) by writing over those registers.
201

AUTHOR

203       Dimitris Economou <dimitris.s.economou@gmail.com>
204