APC_MODBUS(8)
=============

NAME
----

apc_modbus - Driver for APC Smart-UPS Modbus protocol

SUPPORTED HARDWARE
------------------

Generally this driver should work for all the APC Modbus UPS devices. Some
devices might expose more than is currently supported, like multiple phases.
A general rule of thumb is that APC devices (or firmware versions) released
after 2010 are more likely to support Modbus than the USB HID standard.

Tested with the following hardware:

 - SMT1500 (Smart-UPS 1500, Firmware 9.6)
 - SMX750  (Smart-UPS X 750, Firmware 10.1)
 - SMX1500 (Smart-UPS X 1500, Firmware 15.0)

Note that you will have to enable Modbus communication. In the front panel of
the UPS, go to Advanced Menu mode, under Configuration and enable Modbus.

NOTE: This driver was tested with Serial, TCP and USB interfaces for Modbus.
Notably, the Serial ports are not available on all devices nowadays; the TCP
support may require a purchase of an additional network management card; and
the USB support *currently* requires a non-standard build of libmodbus (pull
request against the upstream library is pending, as of at the time of this
publication) as a pre-requisite to building NUT with this part of the support.
For more details (including how to build the custom library and NUT with it)
please see link:https://github.com/networkupstools/nut/pull/2063[NUT PR #2063]

NOTE: As currently published, this driver supports reading information from
the UPS. Implementation of support to write (set modifiable variables or send
commands) is expected with a later release. This can impact the host shutdown
routines in particular (no ability to actively tell the UPS to power off or
cycle in the end). As a workaround, you can try integrating `apctest` (from
the "apcupsd" project) with a "Test to kill power" into your late-shutdown
procedure, if needed.

EXTRA ARGUMENTS
---------------

This driver also supports the following optional settings:

include::nut_usb_addvars.txt[]

*porttype*='value'::
Set the type of the port used. Available values are serial for RS232/485 based
connections, tcp for TCP/IP connections and usb for USB connections.

*port*='value'::
Depending on the port type you can select a port here. For usb only auto is
supported, for serial you can pass a device path like /dev/ttyS0 and for tcp you
can pass a hostname with optional port like example.com:502.

*baudrate*='num'::
Set the speed of the serial connection. The default baudrate is 9600.

*parity*='value'::
Set the parity of the serial connection. Available values are N for none, E for
even and O for odd. The default parity is N (none).

*databits*='num'::
Set the data bits of the serial connection. The default databits is 8.

*stopbits*='num'::
Set the stop bits of the serial connection. The default stopbits is 1.

*slaveid*='num'::
Set the Modbus slave id. The default slave id is 1.

*response_timeout_ms*='num'::
Set the Modbus response timeout. The default timeout is set by libmodbus. It can
be good to set a higher timeout on TCP connections with high latency.

AUTHORS
-------

* Axel Gembe <axel@gembe.net>

SEE ALSO
--------

The core driver
~~~~~~~~~~~~~~~~

linkman:nutupsdrv[8], linkman:ups.conf[5]

Internet resources
~~~~~~~~~~~~~~~~~~

The NUT (Network UPS Tools) home page: https://www.networkupstools.org/
