The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

Device::Modbus::Request - Modbus requests for Device::Modbus

SYNOPSIS

use Device::Modbus::Request;

my $req = Device::Modbus::Request->new(
   code     => 0x01,
   address  => 330,
   quantity => 6
);

my $req2 = Device::Modbus::Request->new(
   function => 'Read Coils',
   address  => 330,
   quantity => 6
);

my $pdu = $req->pdu; # gets the binary representation of the request 

DESCRIPTION

This class builds Modbus request objects, which can later issue their transport-independent PDU (Protocol Data Unit). These objects can then be sent by a Device::Modbus client or received by a server. See the main documentation at Device::Modbus.

METHODS

This class offers just two methods, with the constructor being the most important one.

Constructor

Nine request functions are supported. To define the function of your request, you must define either its function name or its function code. The rest of the arguments are always mandatory, but they differ among the different request functions. Please see the summary table below; details are explained further below.

The supported request types and their arguments are:

+------+-------------------------------+------------------------------+
| Code | Function                      | Other arguments              |
+------+-------------------------------+------------------------------+
| 0x01 | Read Coils                    | address, quantity            |
| 0x02 | Read Discrete Inputs          | address, quantity            |
| 0x03 | Read Holding Registers        | address, quantity            |
| 0x04 | Read Input Registers          | address, quantity            |
| 0x05 | Write Single Coil             | address, value               |
| 0x06 | Write Single Register         | address, value               |
| 0x0F | Write Multiple Coils          | address, values              |
| 0x10 | Write Multiple Registers      | address, values              |
| 0x17 | Read/Write Multiple Registers | read_address, read_quantity, |
|      |                               | write_address, values        |
+------+-------------------------------|------------------------------+

Depending on the code or the function, the rest of the arguments become also mandatory. The table above shows a summary. Details are discussed below.

function or code

You must always specify either the function name or the function code in the constructor. See the two examples in the synopsis.

Other arguments

The rest of the arguments to the constructor depend on the request that you are building. The details are as follows:

* Read Coils, Read Discrete Inputs, Read Holding Registers, Read Input Registers

These functions have codes from 1 to 4.

address

Coded in a 16-bit word, so the address must be between 0 and 65535.

quantity

For functions 0x01 and 0x02, quantity must be less than or equal to 2000. For functions 0x03 and 0x04, the maximum is 125.

* Write Single Coil and Write Single Register

These functions have codes 5 and 6.

address

Coded in a 16-bit word, so the address must be between 0 and 65535.

value

For a single coil, the value is taken as true or false. False values include undef, the empty string, and 0. Register values are always a number between 0 and 65535.

* Write Multiple Coils

This is function code 15, 0x0F.

address

Coded in a 16-bit word, so the address must be between 0 and 65535.

values

You can enter up to 1968 values in an array reference. Each value will be treated as a true or false value.

* Write Multiple Registers

This is function code 16, 0x10.

address

Coded in a 16-bit word, so the address must be between 0 and 65535.

values

You can enter up to 123 values in an array reference. Each value will be coded in a 16-bit word, so they must be between 0 and 65535.

* Read/Write Multiple Registers

This is function number 0x17. It requires the following arguments:

read_address

The address where you want to start reading registers. As usual, it must be a number between 0 and 65535.

read_quantity

A number up to 125. This is the number of registers that will be read.

write_address

The address where you want to start writing register values. Again, it must be a number between 0 and 65535.

values

You can enter up to 121 values in an array reference. Each value will be coded in a 16-bit word, so they must be between 0 and 65535.

pdu

This method returns the binary representation of the request. Before sending it to a server (or to a slave, which amounts to the same), you must wrap the PDU within a protocol header and footer. See the ADU methods of the clients for this.

AUTHOR

Julio Fraire, <julio.fraire@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Julio Fraire This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.