socomec_jbus(8)

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

NAME

6       socomec_jbus - Driver for Socomec JBUS UPS with RS-232 serial Modbus
7       connection.
8

SYNOPSIS

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

SUPPORTED HARDWARE

20       This driver supports Socomec JBUS series, online (double conversion)
21       UPS with the following characteristics.
22
23        1. Single phase and 3-phase UPS
24
25        2. Connection: RS-232
26
27       These are typically provided with a Netvision WEB/SNMP management card
28       / external box that would be better served by the snmp-ups(8) driver.
29       In case netvision isn’t available, you can hook up the UPS directly via
30       the serial port and use this driver.
31
32       Currently, it has only been tested on the following model.
33
34       •   DIGYS 3/3 15kVA
35
36       In theory, any Socomec JBUS model should work. It should be discovered
37       as “Unknown Socomec JBUS” with a numeric id that I’ll need to add it to
38       the list of supported UPSs.
39
40       Sadly, Socomec document only mentions DELPHYS MX and DELPHYS MX elite
41       and I have the id of my own DIGYS, so chances are, your model will not
42       be recognized but will probably mostly work. Please report successful
43       or unsuccessful results to the bug tracker or the mailing list. Make
44       sure to include the full model number of your UPS manually in your
45       report.
46
47       socomec_jbus uses the libmodbus project, for Modbus implementation.
48

CABLING

50       The UPS has an RS-232 port which should be connected with a NULL-modem
51       cable to a PC serial port. The UPS tested has a female DB9 connector,
52       so if you construct the cable yourself, make note of the connector type
53       to avoid using gender changers.
54
55       RS-232 is supported on all operating systems, either via a built-in
56       serial port on your computer, or by using an external USB-to-RS-232
57       converter. If you plan to use an USB-to-RS-232 converter, make sure
58       it’s supported by your operating system.
59

INSTALLATION

61       This driver should be built by default if libmodbus and development
62       headers are available. You can force the configure script to build it
63       with the following arguments:
64
65           configure --with-serial=yes --with-modbus=yes
66
67       You also need to give proper (R/W) permissions on the local serial
68       device file to allow the NUT driver run-time user to access it. This
69       may need additional setup for start-up scripting, udev or upower rules,
70       to apply the rights on every boot — especially if your device nodes are
71       tracked by a virtual filesystem.
72
73       For example, a USB-to-serial converter can be identified as
74       /dev/ttyACM0 or /dev/ttyUSB0 on Linux, or /dev/ttyU0 on FreeBSD (note
75       the capital "U"). A built-in serial port can be identified as
76       /dev/ttyS0 on Linux or one of /dev/cua* names on FreeBSD.
77

INSTANT COMMANDS

79       This driver does not (yet?) support sending commands to the UPS.
80

VARIABLES

82       This driver does not support writable runtime variables (see upsrw(8)):
83       for the same reasons. Both should be trivial to implement, but since
84       I’ve already found one or two inconsistencies in the documentation, I’m
85       withholding from trying them.
86

KNOWN ISSUES AND BUGS

88       Well, it is an alpha release at best, but so far appears to report the
89       UPS status reliably. Mostly based on the work of Yifeng Li
90       <tomli@tomli.me> on the huawei-ups2000 in that very same source tree.
91
92   Read failure on some JBUS addresses
93       The driver polls all documented JBUS addresses and it is quite possible
94       that your UPS model does not support one of them (e.g. the Digys does
95       not support address 0x1020 which should provide the current UPS
96       status). This should be logged with LOG_ERR from
97       modbus_read_input_registers() along with the address that produced the
98       error.
99
100   Data stale
101       Under certain circumstances, some registers can return invalid values
102       and trigger a "data stale" error. Once a data stale error has occurred,
103       you should see error messages similar to the example below in the
104       system log.
105
106           socomec_jbus: modbus_read_input_registers(addr:XXXX, count:Z):
107               Illegal data address
108           upsd: Data for UPS [socomec] is stale - check driver
109           upsd: UPS [socomec] data is no longer stale
110
111       So far all known problems have been fixed by the author, but an unknown
112       one cannot be ruled out. If you have encountered "data stale" problems
113       during normal uses, please file a bug report with full logs attached.
114
115       Before troubleshooting or reporting a problem, it’s important to check
116       your dmesg log for USB connect and disconnect events to avoid wasting
117       time on the NUT driver when the actual problem is USB. For example, if
118       someone yanks the cable out of the USB port, or if a new USB device is
119       plugged into a USB host/hub that is struggling to power its ports
120       (common on single-board computers like Raspberry Pi), or if you have
121       flaky cabling or EMI noise, the serial converter can get disconnected
122       from USB, at least briefly. This creates a permanent data stale, the
123       driver must be restarted (plugging the USB back won’t fix it, since the
124       driver is still using the nonexistent serial device). These USB
125       problems usually have nothing to do with NUT. If it’s the case, you
126       should solve the underlying USB problem - check the cable, check the
127       converter, try a powered USB hub, try a full-speed USB isolator, etc.
128

AUTHOR

130       Thanos Chatziathanassiou <tchatzi@arx.net>
131