Documente Academic
Documente Profesional
Documente Cultură
This document describes the application and use of the Modbus TCP Master Sample
Application. The program was written to run on a Control Logix 5000 processor with
a compatible Ethernet Module.
This sample application can be used standalone by adding any required logic for your application, or can
be added to an existing application following the directions outlined below.
The audience for this document would be Software engineers, controls engineers, and application
engineers familiar with Logix 5000 controllers, RSLogix 5000, and Modbus TCP protocol and its uses.
Knowledge of the use of the Modbus protocol is crucial to using this application.
This application will allow you to create a Modbus TCP Master capable of connecting to multiple Modbus
TCP compatible slaves(s) to read and write control data. There is also a Modbus TCP Slave Sample
application if a slave is desired, i.e. you need to be connected to by a Master.
This application is provided as is and there is no Warranty or implied merchantability.
See the Rockwell Sample Code Download Terms and Conditions.pdf that was downloaded with this
document for more information on Acceptance of Terms and Conditions. Your rights to download and use this
content are limited and can be revoked at any time. No support contract is implied or delivered with this code
or any modified version of this code.
.
| Modbus TCP Master Sample Application
Note that these limitations can be changed by the user modifying the application.
1. First assure you have a compatible Ethernet network card configured in your
application.
2. Import the Modbus TCP Master application into your project.
3. Configure the path to the Ethernet port which the application will use.
4. Enable the New program
5. Verify that your RSLogix 5000 project is working.
You will need to open two instances of RSLogix 5000, on with the Modbus Master application the
other with the application you wish to integrate it into. In the Modbus TCP Project, right click on the
PROGRAM FOLDER and select export program as shown to create an L5X file
"ModbusMasterTCP.L5X”.
| Modbus TCP Master Sample Application
Now in the application you are integrating into, right click on a task and select program import as
shown to import "ModbusMasterTCP.L5X" as shown.
NOTE: It is recommend to import into a periodic task of 50 to 100ms to insure proper operation. Slow
or faster speeds have not been tested.
| Modbus TCP Master Sample Application
* MBTU_EnetModulePort this value should be set to '$01$00' for all CompactLogix 5370
processors. This value should be set to '$01$xx‟ where xx is the 1756 backplane slot number, in hex,
of the desired Ethernet module for all 1756 ControlLogix processors, for example '$01$02' for an
Ethernet module located in 1756 backplane slot 2 or '$01$10' for an Ethernet module located in 1756
backplane slot 16.
It is recommended to leave all MSG instructions as configured. All MSG instructions are currently
configured as unconnected See Knowledgebase ID 530345 for information on connected vs.
unconnected messaging.
| Modbus TCP Master Sample Application
Once this bit is set, the Master will attempt connections (using port 502 which is setup in
MBTU_Connections[x]) to the given slave(s), and upon success will start the transactions enabled
for that connection. The read and write requests will use the local data arrays for the source or
destination data. MBTU_MB_0xx is used for coil transactions types 01, 05, and 15.
MBTU_MB_1xx is used for discrete input transaction type 2. MBTU_MB_3xx is used for input
register transaction type 4. MBTU_MB_4xx is used for holding register transactions types 3, 6, and
16.
Configuration Tags
(note: tags starting with MBT are controller scoped, all others are program scoped).
*MBTU_EnetModulePort this value should be set to '$01$00' for all CompactLogix 5370
processors. This value should be set to '$01$xx‟ where xx is the 1756 backplane slot number, in
hex, of the desired Ethernet module for all 1756 ControlLogix processors, for example '$01,$02' for
an Ethernet module located in 1756 backplane slot 2 or '$01,$10' for an Ethernet module located in
1756 backplane slot 16.
Refer to your Ethernet module documentation to configure you Ethernet module. At minimum you
should configure the address and subnet mask or select DHCP.
| Modbus TCP Master Sample Application
Configuring a connection:
Each connection is configured using it‟s element in the MBTU_Connections tag. Below is a
description of the values in the MBCOnnection UDT. The value that should be configured prior
to connection is the MBTU_DestAddress.
MBConnection
UDT
Tag Name Description
MBTU_DestAddress A string containing the IP address and port to make a
connection to of the form of „xxx.xxx.xxx.xxx?port=502‟. Notice
that port 502 is the default setting for ModbusTCP
communications. Note that “port” must be in all lower case!
MBTU_Enable A Boolean that enables and disables this single connection.
MBTI_NumberOfTransactions States the size of the Transactions array for this connection
minus one. This is basically used as the terminating value for
FOR instructions, therefore the minus 1 value.
MBTI_Connected A Bool value indicating a connection exists or no connection
exists.
MBTI_ConnLastError This value is set on various connection level errors when they
occur. A 0 represents all is well on an enabled connection.
Other values are outlined below and covered in the debugging
section. Other errors that can exist for a single transaction are
written to the Transaction‟s UDT.
Note if your changing your MBTU_DestAddress while running, you will need to disable your
connection (enable bit in the connection UDT) wait about 30 seconds, then re-enable the
connection to switch to the new address.
To configure a transaction:
You will need to set the following values.
• Enabled set to one to enable this transaction
• PollInterval set to something 1 or higher. Any other value will disable
the transaction.
• Transtype 1, 2, 3, 4, 5, 6, 15, or 16. The read or write Modbus
transaction you wish performed.
• UID (possibly) Typically used if the destination address is a gateway with
more than one device on the other side, or if a particular device
uses a UID. If this is the case enter the device‟s UID.
• BeginAddress The starting address of the operation minus 1 without the first
digit type identifier. For example, address 40001 in the PAC will be 0
here.
• Count Number of items to read or write (either registers or discrete,
whichever applies).
• LocalOffset This is the offset into the local data arrays (MBTU_MB_Xxx)
at which to begin the data for this operation.
| Modbus TCP Master Sample Application
After these have been set, clearing the ReqBuilt bit will build your new transaction string. Also for
write operations, the request string is automatically built on every transmission so the data changes
will be reflected.
To use a transaction:
In the case of reads, checking the Transcomplete and TransStat will let you know the validity of the
transaction and its data. The data can be read from MBTU_MB_0xx for coil operations,
MBTU_MB_1xx for discrete input reads, MBTU_MB_3xx for input register reads, and
MBTU_MB_4xx for holding register operations. Data will always begin at the transaction‟s specified
local offset in those arrays. The TransLastError value will indicate any errors, either local or
Modbus Exceptions received. A 0 here indicates successful transactions, any other values can be
found in the following section on error codes.
| Modbus TCP Master Sample Application
Transaction Examples
The following sections will give examples and explanations of each of the supported transaction
types. It should be noted that some devices will require a matching value in the Unit ID (UID) field of
the transactions.
The following tables show the key values in the Transaction structures for each transaction. The
description following the table describes what will happen.
Read Coils
Tag Name Value
PollInterval 10
TransType 1
BeginAddress 0
Count 10
LocalOffset 0
th
This transaction will poll every 10 time the poll timer times out, which in the case of a 100ms poll
timer, would mean this transaction is done every 1000 milliseconds or 1 second. The TransType is 1
meaning a coil read is going to be done. Begin address is 0, means we will start reading at address
00001 of the device being read. The count is 10, meaning 10 coils will be read and a LocalOffset of
0 will put the data starting at the first element (index 0) of MBTU_MB_0xx and continue on to index 9.
th
This transaction will poll every 20 time the poll timer times out, which in the case of a 100ms poll
timer, would mean this transaction is done every 2 second. The TransType is 4 meaning an input
register read is going to be done. Begin address is 4, means we will start reading at address 30005
of the device being read. The count is 10, meaning 10 16 bit input registers will be read and with a
LocalOffset of 5, the data will be placed in index 5 through 14 of MBTU_MB_3xx.
This transaction will poll every 2nd time the poll timer times out, which in the case of a 100ms poll
timer, this transaction is done 5 times a second. The TransType is 5 meaning a coil write is going to
be done. Begin address is 24, means we will write to address 00025 of the device being written to.
The count isn‟t applicable for a TransType of 5. A LocalOffset of 25 means the data will come from
index 25 of MBTU_MB_0xx.
Also keep in mind that since this is a write operation, every time you change the data to be written
you must clear the ReqBuilt flag in this transaction definition so that the request will be rebuilt with the
new data in it.
th
This transaction will poll every 5 time the poll timer times out, which in the case of a 100ms poll
timer, would mean this transaction is done twice a second. The TransType is 6 meaning it will be
writing a single register. Begin address is 9, means we will write to address 40010 of the device
being written to. The count does not apply to a TransType of 6. A LocalOffset of 10 the data will
come from index 10 of MBTU_MB_4xx.
Also keep in mind that since this is a write operation, every time you change the data to be written
you must clear the ReqBuilt flag in this transaction definition so that the request will be rebuilt with the
new data in it.
| Modbus TCP Master Sample Application
Also keep in mind that since this is a write operation, every time you change the data to be written
you must clear the ReqBuilt flag in this transaction definition so that the request will be rebuilt with the
new data in it.
Also keep in mind that since this is a write operation, every time you change the data to be written
you must clear the ReqBuilt flag in this transaction definition so that the request will be rebuilt with the
new data in it.
Retry Timers
Each connection has a retry timer which is used to re-establish communications in the event a
connection is lost or errors out. The timers are named Retry_Timers[] and their default setting is 10
seconds. You can modify these to suite your needs and network environment.
| Modbus TCP Master Sample Application
First verify that the tag NumberOfConnectios is set to 4 (default value), or whatever the total number of
connections there are in your version of the application, whether they‟re enabled or not. And
remember you will be using the Ethernet port specified in MBTU_EnetModulePort for all connections,
so ensure you have a physical path to the device your trying to connect to through that port.
Configure your transactions for that connection. Remember to set the enable tag and clear the
ReqBuilt flag so the request string will be rebuilt and the transaction will be processed. If this is the
second connection you should be modifying transactions in MBTU_Transactions_01, and for the third
MBTU_Transactions_02, etc. Also note if the poll interval is not a valid value (o or a negative value),
the Enable tag will be cleared by the application.
Set the MBTU_DestAddress in the MBTU_Connections element for the connection your configuring.
Again in the case of adding the second connection this should be
MBTU_Connections[1].MBTU_DestAddress. For a device with an IP address of 192.168.1.197. you
would be specified the DestAddr member as „192.168.1.197?port=502‟. Port 502 is the default port for
Modbus TCP communications.
The final step is to enable the actual connection and reset communications. In the
MBTU_Connections[x] array, find the element corresponding to the connection you‟re enabling and
set the MBTU_Enable value. For instance in the case of enabling the second connection you would
set MBTU_Connections[1].MBTU_Enable. Now clear the tag MBTU_ENMBTCP, wait for
approximately 10 seconds, and then set it again. This last step will clean up any loose connections
items and re-initialize all connections that are enabled.
| Modbus TCP Master Sample Application
The change is relatively simple if increasing the number of transactions, first resize the array of
transactions for that connection. Say if increasing the number from 5 to 10 for the second
connection, resize the controller scoped tag MBTU_Transactions_01 from 5 to 10 elements, then
modify the value controller tag MBTU_Connections[1].MBTI_NumberOfTransactions from 4 to 9 (it is
always set to one less than the actual number), in this case
MBTU_Connections[1].MBTI_NumberOfTransactions = 9.
To decrease the number of transactions you would do the same but in reverse. First change the
value of NumberOfTransactions, then change the actual number of elements in the tag
MBTU_Connections[x].MBTI_NumberOfTransactions. For instance on the first connection to go from
5 to 2, you would first change MBTU_Connections[0].MBTI_NumberOfTransactions to 1, then modify
MBTU_Transactions_00 to have only 2 elements.
| Modbus TCP Master Sample Application
LocalOffset The offset to begin this Note that the maximum local
operation in the appropriate addresses are 1024 for
local data array discrete operations and 256 for
(MBTU_MB_Xxx). register operations.
TransactionComplete The application will set this to 0 This value is normally cleared
when a request is made and automatically at the start of
set to 1 when a response is each request, but can be
received. cleared by the application to
ensure that the write operation
has occurred.
TransStat Integer with the status code Read only.
from the previous transaction.
0 = successful. If a response
has not been received -1,
which is normal on each poll of
the transaction for the time
from the request is made until
a response is received.
Request This is where the string for the Read Only
actual request is built. Useful
for debugging, but don‟t modify
it directly.
ReqBuilt A BOOL value indication that Clear this bit if the transaction
the transaction string has been definition is modified.
built. Clearing this bit will force
the Request string to be re-
evaluated. This should be
done if the transaction is
changed in any way, including
write operation‟s data values.
TransID The transaction ID that the last Read Only.
request was sent under. Do
not modify this value directly.
It is used to match replies to
their corresponding request.
TransLastError Records any errors that may 0 – successfully working when
occurred on transaction level. transaction is enabled on an
enabled connection. See the
following chart for error values.
| Modbus TCP Master Sample Application
Transtat values
Transstat values give you a status of the current transaction.
Other codes that are possible but not common, here is a full list:
Error Code (Dec/Hex)
22 16 EINVAL Invalid argument
32 20 EPIPE Broken pipe
40 28 EDESTADDRREQ Destination address required
41 29 EPROTOTYPE Protocol wrong type for socket
42 2A ENOPROTOOPT Protocol not available
43 2B EPROTONOSUPPORT Protocol not supported
44 2C ESOCKTNOSUPPORT Socket type not supported
If communications don‟t appear to be working at all, check the MBTI_ConnLastError values in the
MBTU_Connections arrays. Error values of -7 indicates the delete all in the MainRoutine has failed. Most
likely cause of this is the MBTU_EnetModulePort being set incorrectly. Other error values indicate an
error in creating, connecting, or dropping an existing connection. Below is a list that should give some
guidance as to where to look with each error value.
-7 Check the Delete all message in rung 2 of the MainRoutine. Most likely cause is the
MBTU_EnetModulePort being incorrectly set.
-8 An error occurred in the Create socket block for that connection. Check the corresponding MSG
block‟s error and extended error values in the MainRoutine to see what the issue is. For
example for the first connection, check the MSG block in rung 4 of the main routine. Error values
are listed above for reference.
-9 An error occurred in the Connect socket block for that connection. Check the corresponding MSG
block‟s error and extended error values in the MainRoutine to see what the issue is. For example
for the first connection, check the MSG block in rung 6 of the main routine.
Most likely causes of this error is an incorrectly specified address, or the remote device not
being accessible.
-10 A disconnect has occurred. Examine the TransLastError values in the individual transactions for
that connection for additional information.
Below is a list of values and actions you can take to further determine the root cause of the issue. The read
and write message blocks for all connections are contained in the Process_Transaction routine. The
connections are in order, so find the corresponding MSG block for the connection you are diagnosing. For
example a write error on connection one would be on rung 3 and a read error on rung 5.
-2 &-3 A write block error has occurred, check the corresponding write MSG instruction for
additional information in the Error and Extended Error values. Most likely cause is a
dropped connection or loss of network connectivity.
-4 & -5 A Read block error has occurred, check the corresponding read MSG instruction for
additional information in the Error and Extended Error values. Most likely cause is a
dropped connection or loss of network connectivity.
| Modbus TCP Master Sample Application
References
M ODBUS PROTOCOL SPECIFICATION V1.1B A
Available from http://www.Modbus.org.
ROCKWELL PUBLICATION ENET -AT 002_-EN -P. PDF ETHERNET ./IP S OCKET INTERFACE
Available from http://www.rockwellautomation.com/
literature/.
Revision History
August 31, 2012
ModbusTCP_Master_R100.ACD initial release
April 5, 2013
Document updated and renamed Modbus TCP Master Sample Application R102.
ACD modified and renamed, ModbusTCP_Master_R102.ACD, _SUB_SET_PATH added
four COP instructions to resolve an issue of not all MSG paths being properly updated.
Minor documentation/comment changes made to ACD.
Modified the Master documentation in the “Using the application” section, added
information on the amount of controller memory needed.
Modified the Master documentation in the “Sample Files in RSLogix 5000 V20 format”
section, added KB ID 470365 reference with detailed information on supported controllers.
Modified the Master documentation in the “New Modbus Master Controller Tags” section,
added KB ID 530345 reference with information on connected vs. unconnected MSGs.
Modified the Master documentation in the description section pg. 1 to enhance the As Is No
Warranty section.
| Modbus TCP Master Sample Application
Publication Modbus TCP Master Sample Application – April 2013 Copyright ©2013 Rockwell Automation, Inc. All Rights Reserved. Printed in 2013.