DESCRIPTION

This module provides a basic Modbus client for reading from and writing to various ModBus serial slaves using RTU or ASCII modes.

METHODS

The Modbus::Client module defines the following methods:

Modbus::Client->new()

Create a new serial client to talk to a ModBus. Accepts two kinds of parameters - the first kind is the serial device the modbus is connected to. If this type of parameter is specified, Modbus::Client optionally accept a second paramater to define the baud rate. By default, Modbus::Client will initiate communications at 9600 baud, no parity.

    $bus = new Modbus::Client "/dev/cua00", POSIX::B19200;

The second type of parameter is a file handle. If this parameter is passed, it is assumed that you have initiated the connection, and Modbus::Client will simply use the connection you have already established. This allows you to easily use different baud rates or to connect to a TCP port associated with a serial-to-ether adapter, such as the Digi One SP. For devices like this, make sure you DISABLE software flow control!

    use FileHandle;
    use Socket;
    $fd = new FileHandle;
    $host = "something.yournet.com";
    $port = 2101;
    $remote = inet_aton($host)  || die "No such host $host";
    socket($fd, PF_INET, SOCK_STREAM, getprotobyname('tcp'))
                                || die "Can't create socket - $!";
    $paddr = sockaddr_in($port, $remote);
    connect($fd, $paddr)        || die "Can't connect to $host:$port - $!";
    $fd->autoflush(1);
    $bus = Modbus::Client->new($fd);

NOTE FOR WINDOWS USERS: For finer control of the serial connection, it is possibly better if you open the connection and pass the FileHandle to the new method. This is because Windows does not implement POSIX::Termios.

$bus->device()

Create a new device on a Modbus. The single parameter is the device number. Note that according to the Modbus spec, a device number of 0 is the broadcast address.

    $unit = $bus->device(1);

$unit->read_one()

The read_one method is a convenience routine that is called with a single modbus address to read, and it returns a single scalar value from that register. The read method is more powerful, but also more complicated.

The API for the read_one method does not distinguish between ModBus Coils, Status Registers, Holding Registers, or Input Registers. It makes the necessary ModBus calls to get all of them to work.

$unit->read()

The read method may be called with two kinds of parameters: a list of addresses to read, or a reference to hash table (where the keys are the addresses to read, and the values will be filled in by the method).

It may also be called in an array context (in which case it returns the values of the registers that were read. The order in which they are returned is equal to the order specified (when called with an array of values) or in sorted key order (when called with a reference to a hash table).

    @array = $unit->read(30001..30010);
    $hash  = $unit->read(10001..10037);

    %hash = map {$_, 1} (20007, 20012..20015, 30029, 40006)
    @array = $unit->read(\%hash);
    $hash  = $unit->read(\%hash);

If the method is called in a scalar context, then a reference to a hash table is returned (where the keys are the register addresses and the values are the values read). The referenced hash will be the same as the input hash, or if an array of addresses is passed as a parameter, the referenced hash will be an anonymous one.

The API for the read method does not distinguish between ModBus Coils, Status Registers, Holding Registers, or Input Registers. It makes the necessary ModBus calls to get all of them to work, even if they are mixed in a single invocation of the read method.

General Reference registers are not presently supported, neither are FIFO queues - ask and ye shall receive, though...

$unit->write()

The write method is called with a hash table or a reference to hash table as a paremeter (where the keys of the hash are the addresses to write, and the values of the hash are written to the corresponding addresses).

    $unit->write(6 => 1, 8 => 0, 2007 => 10, 2008 => 2);
    %hash = (6 => 1, 8 => 0, 2007 => 10, 2008 => 2);
    $unit->write(%hash);
    $unit->write(\%hash);

The API for the write method does not distinguish between ModBus Coils or Holding Registers. It makes the necessary ModBus calls to get all of them to work, even if they are mixed in a single invocation of the write method.

General Reference registers are not presently supported, neeither are Mask Write nor combined Read/Write functions - ask and ye shall receive, though...

$clump_size = $self->clump([$new_clump_size]))

The clump method is used to set the number of elements that may be read or written in a single operation. Note that read() and write() will always operate on as many elements as are specified, but to reduce the possibility of errors, it will break them up into clumps. This routine specifies the maximum size of such a clump. The initial value is 125 (as implied by the Modbus spec), and may in any event not exceed 127 (since the byte count in returned data is stored in an 8 bit field, and 127 16-bit registers is 254 bytes).

Setting the clump size on a device changes the behavior of that device only. Setting the clump size on a modbus changes the behavior of all devices that are created after the change (that is, there is only partial inheritance).

$mode = $self->mode([M_RTU | M_ASCII]))

The mode method is used to set the communication mode to the device. The two choices are M_ASCII and M_RTU (both are constants exported by the Modbus::Client package, the default mode is M_RTU). ASCII mode is more readable (for debugging), RTU mode is faster (using fewer bytes). The method returns the current mode.

Setting the mode on a device or an a modbus changes the mode for all devices on the bus (since according to the spec, all devices must comunicate using the same mode).

$mode = $self->debug(1 | 0))

The debug method is used to enable or disable communication debugging.

Setting debug mode on a device or an a modbus changes the mode for all devices on the bus.

AUTHOR

Daniel V. Klein <dan@klein.com>

SEE ALSO

http://www.modbus.org/specs.php for the complete Modbus specifications