citect for windows driver specification modnet driver · citect for windows driver specification...

Citect for Windows Driver Specification

Modnet Driver

Author Date Comment

Matthew Dalton 5/2/97 Original

David Rossini 19/12/97 Modifications for Multiple Outstanding Request

Trevor Hudson 6/04/98 Testing

David Rossini 29/04/98 Bit manipulation of Input Registers permitted. Ini mods.

David Rossini 11/05/98 List float modes available.

Sean Ju 28/05/1998 Multiple outstanding requests

David Rossini 08/06/99 Added comments for 5.12 Debug Messages

Alex Sivokho 16/08/1999 Modifications for the Gateway

Trevor Hudson 30/08/99 Re Testing after modifications

Trevor Hudson 1/12/99 Re Testing after extended addressing modifications

Stephen Burman 2/2/2000 New parameter added

Huang Weiguang 18/09/2001 Modifications for the Adam 5000/TCP

Stephen Straton 30 Oct. 01 Testing modifications for the Adam 5000/TCP

Lin Gu 13 Dec 2001 Modifications for some parameter default value. Ncr17503

Junmei Cao 09Jan2002 New INI options are added. NCR15168

JO Reyes 05 Apr 2002 Upgraded Modnet driver for Smart blocking, and added new String data types, please see NCRs18208 and NCR18209

Trevor Hudson 11 may 2002 Testing after modifications

Carol Jia 21 May 2002 Additional data types, to avoid issues when blocking occurs and mixed even & odd boundary reals, longs are being used

JO Reyes 24 May 2002

Updated default values for AccumulateTime and CacheTimeout parameters, modified the description of the UseIncludeProjects parameter.

Driver Design Specification

MODNETv3.DOC 12/08/2006 2



Contents

1. INTRODUCTION 6

1.1 Scope. 6

1.2 Outline. 6

2. QA 7

2.1 Developers Guidelines 7

3. TARGET DEVICE(S) AND PROTOCOL 9

3.1 Introduction 9

3.2 Device Manufacturer 9

3.3 Device Definition 9

3.3.1 Point-to-point to a PLC 9

3.3.2 Indirect connection for the Gateway 11

4. PROTOCOL REQUIREMENTS 13

4.1 Introduction 13

4.2 Initialising the Board 13

4.3 Initialising the Port 13

4.4 Initialising the IO Device 13

4.5 IO Device Online Test 13

4.6 State Flow Description 13

4.7 Message Structure 13

4.8 Data Format 14

4.8.1 Request Frames (to PLC) 14

4.8.2 Reply Frames (from PLC) 14

4.9 Error Handling 15

4.10 CRC calculation 15

4.11 Performance issues 15

4.11.1 Multiple outstanding requests. 15

4.11.2 Concurrent connections. 15

4.12 Comparison against Modbus RTU 15

5. USER INTERFACE 17

5.1 Introduction 17

5.2 Driver Name 17

5.3 Boards Form 17



5.3.1 Board Type 17

5.3.2 Address 17

5.3.3 IO Port 17

5.3.4 Special Opt 17

5.4 Ports Form 17

5.4.1 Port Number 17

5.4.2 Baud Rate 17

5.4.3 Data Bits 17

5.4.4 Stop Bits 17

5.4.5 Parity 18

5.4.6 Special Opt 18

5.5 IO Devices Form 18

5.5.1 Protocol 18

5.5.2 Address 18

5.6 Pulldown lists Help 18

5.7 IO Device Variable Types 18

5.8 PROTDIR.DBF 20

5.9 Parameters and INI options 20

5.9.1 Standard Parameters 20

5.9.2 Driver Specific Parameters 20

5.10 Driver Specific Errors 23

5.11 Driver Error Help 23

5.12 Debug Messages 23

5.13 Stats Special Counters 23

5.14 Hints and Tips 24

5.14.1 Modnet 24

5.14.2 Address Field 24

5.14.3 Bit Addressing 24

5.14.4 Smart blocking is supported from version 3.00.00.000 B onwards: 24

5.14.5 New String data types from version 3.00.00.000 B onwards: 25

6. BASIC TESTING 26

6.1 Introduction 26

6.2 Procedure 26

6.3 Start of Testing 26

6.4 Problems Found 27

7. RE TESTING AFTER MODIFICATIONS 28

7.1 Start of Testing for Extended addressing modifications 28

7.2 Faults Found 28



8. TESTING MODIFICATIONS FOR THE ADAM5000/TCP 30

8.1 Intro 30

8.2 Hardware Setup 30

8.3 Express Communications Wizard Tests 30

8.4 Basic Communications Tests 30

8.4.1 Citect Compile, Start Up and Shut Down Tests 30

8.4.2 Basic Read/Write Testing 31

8.4.3 Break in Communications Tests 31

8.4.4 Duration/Longevity Testing 31

8.5 Faults 31

9. TESTING MODIFICATIONS DATED 5APRIL 2002 32

10. PERFORMANCE TESTING 33

10.1 Introduction 33

10.2 Calculating the Blocking Constant 33

11. REFERENCES AND CONTACTS 34

11.1 References 34

11.2 Contacts 34

12. APPENDIX A – OPEN MODBUS TCPIP SPECIFICATION 35



1. Introduction

1.1 Scope.

This document follows the development of the new driver. It serves as a functional specification, design specification and test specification.

1.2 Outline.

The specification is broken down into the following sections: Section 1 - Introduction. This section defines the scope of a board driver specification and outlines the items

addressed by the specification. Section 2 - Quality Assurance. The QA section defines the requirements and procedures for Quality Assurance

Accreditation. It is important you read this if you want your driver integrated into Citect. Section 3 - Physical Communication Method. The Physical Communication Method section defines the physical communication method

supported, hardware/software suppliers, how the method is setup, any wiring diagrams involved etc.

Section 4 - Protocol Requirements. The Protocol Requirements section details the technical considerations required or

incorporated by the driver. Section 5 - User Interface. The User Interface section defines how the user will see and setup the driver in Citect. Section 6 - Basic Testing. The Basic Testing section defines the items which should be addressed in Basic testing by the developer. Section 7 - Performance Testing. The Performance Testing section is used in full testing of the driver by the Citect Testing Department of CiT. Once complete, this will provide details on the reliability and stability of the driver, and point out where the driver needs to be improved. Section 8 - References and Contacts. The References and Contacts section should be used as a record of reference materials and contacts used in developing this driver.



2. QA

2.1 Developers Guidelines

These guidelines are meant as a rough indication of what options there are for developing Citect drivers and the advantages of these options. It is not a technical discussion of options, rather a marketing guideline. Drivers fall into two categories, Accredited and Independent. Accredited Drivers. Accredited drivers are those drivers that have been put through the CiT Driver QA Scheme and have passed all stages of this accreditation process. It is a precondition to becoming accredited that these drivers will be included with Citect in a normal release. Accreditation has the following advantages: The driver will be included in the product and a certificate stating this driver has achieved Accreditation will be sent to the developer. Accredited drivers will be honoured as part of the product in terms of Citect Support and receive full cooperation between Citect Support personnel and the developer. On the other hand, independent driver problems will immediately be referred on to the original developer. Help documentation and Express Wizards is provided, free of charge, for all Accredited drivers. Help documentation for Independent drivers is the responsibility of the developer. Accreditation is included in the cost of the DDK. A high level of quality is expected and if this is not met the driver will not be Accredited. Citect Customers see value in Accredited drivers as there is some assurance that the driver will operate as documented. Some customers may only accept Accredited drivers. Independent Drivers. Independent drivers are those that have not completed or are not intended to complete the Accreditation process. These drivers will not be included in Citect, nor will they be given any support by Citect Support personnel. We would request all drivers be sent to CiT regardless, even if they are not to be included in the product. If this is done, we can try to ensure compatibility with future versions of Citect. Independent Drivers have the following advantages: Drivers may be written by or for an end user giving them an edge over their opposition by using Citect. Drivers may be developed as part of a package offered by System Integrators or including pre-configured packages etc., thereby maintaining the intellectual and financial investment. This would be similar to value added or OEM style marketing.



Accreditation process The following check list defines the QA steps for generating a new driver. This procedure must be followed for drivers to be integrated into Citect. It is advisable to ensure that items before each checkpoint are complete before proceeding to avoid rework if changes are required. Description Person Date

1 This specification document is written. Matthew Dalton 21/3/97

2 Specification reviewed and accepted by CiT Driver Development. Bruce Kinchin 18/6/97

At this checkpoint coding is ready to be commenced.

3 Driver coded. Matthew Dalton 4/97

4 Code and specification reviewed and accepted by CiT Driver Development.

5 Testing with connection project, and performance test.

6 Driver integrated into Citect source and built.

7 Documentation is written.

8 Documentation reviewed.

At this checkpoint coding is done and the driver is available as a beta.

9a Full testing is carried out. Trevor Hudson 15/5/98

Full testing after modification for Gateway Trevor Hudson 13/9/99

9b Performance testing is carried out.

9c Specification and documentation updated from testing/performance tests

At this checkpoint the testing is complete.

10a Review for completeness by developer, tester, documenter and CiT Driver Development

10b Add driver to install disks

10c Add driver to drivers database

10d Support notified of new driver for training purposes

11 Sales notified of new driver

The driver is now finished.

The hand over of a driver requires that all the above steps are completed and checked off.



3. Target Device(s) and Protocol

3.1 Introduction

This section defines the types of I/O Devices that are targeted by this driver.

3.2 Device Manufacturer

Schneider Automation Pty Ltd. Advantech Co.,Ltd.

3.3 Device Definition

3.3.1 Point-to-point to a PLC

The test unit uses a Modicon Quantum TCPIP Ethernet module to communicate using the MODNET protocol. The Quantum Ethernet modules works with all Quantum processors with the following version minimums:

• Quantum executive (flash down-loadable): V2

• Modsoft programming software: V2.31

• Concept programming software: V2.0

• Modlink DDE software: V2.0 The CPUs in the Quantum range are:

• 140 CPU 113 02

• 140 CPU 113 03

• 140 CPU 213 04

• 140 CPU 424 02 This driver can also communicate with the Adam 5000/TCP modules provided by Advantech. A standard PC Ethernet card with 10BaseT connector is also required. Communications Method Communications is by TCP/IP over Ethernet using 10BaseT (twisted pair or UTP). Communications/Hardware Configuration


MODNETv3.DOC 12/08/2006 10

Ethernet Hub

NetworkAdaptor

Modicon PLCwith Ethernet

TCP/IP module

RJ45

�

Wiring All cables to the Ethernet modules should be routed through Ethernet hubs. They should not be connected directly to the Computer’s network adaptor. Each Ethernet module requires a standard ethernet twisted pair cable with RJ45 connectors at both ends. I/O Device Settings Each PLC connected to the system must have a unique IP address on the network. Software Setup The Default IP address is labelled above the RJ45 socket on the front of the module. The rightmost eight digits represent the IP address in dot decimal format. e.g.

540B72A8 → 54.0B.72.A8 → 84.11.114.168 To allocate a custom IP address, use one of the following software packages: Quantum Executive 2.0 (or later) Modsoft 2.31 (or later) Concept 2.0 (or later) ModLink 2.0 (or later) Using Concept 2.0 (Win 95) to allocate the IP address: Make sure the Hardware is working properly: The ‘Active’ light on the NOE (Ethernet) module should be lit. The ‘Ready’ and ‘Link’ lights on the NOE (Ethernet) module should be lit. The ‘Run’ light on the NOE (Ethernet) module should be blinking. The ‘Ready’ light on the CPU module should be lit. Connect the PLC to the computer using the MODBUS port on the CPU and a serial cable. For a wiring diagram of the serial cable, see the help for the MODBUS protocol. Start Concept. Start a new project. Choose ‘Online | connect’ from the menu. Choose ‘Modbus’ from the Protocol type list Enter the station number (found on the back of the CPU module - req’d for Modbus) in the PLC Node box. Make sure the Controller is stopped by selecting ‘Online | Online Control Panel’ from the menu. Select ‘Change Configuration’ access level Press OK. After a few seconds the PLC will connect to Concept. An Error message may appear stating that the PLC type in the database does not match that of the controller. Press OK. Choose ‘Project | Configurator’ from the menu. Choose ‘Configure | PLC type’ from the menu. Select the PLC type and memory. Choose ‘Configure | Config Extensions’ from the menu. Change the value ‘Ethernet’ to 1. (if you are only using 1 NOE module). Choose ‘Configure | IO Map’ from the menu.


MODNETv3.DOC 12/08/2006 11

Select the row describing the PLC (most likely drop 1, ‘Quantum I/O’). Press the Edit button. If the ‘Poll’ checkbox is checked, the CPU module will detect the presence of the modules on the PLC rack. Confirm them by pressing the buttons in the Module column and choosing the correct module from the list. Click on the row that contains the NOE module. Press the ‘Params’ button. Enter the IP address and choose the framing type (usually IEEE 802.3). Press OK on all 3 forms. Choose ‘Online | Download’ from the menu. Press the ‘All’ button and then the ‘Download’ button. Downloading the information takes a few minutes. The new configuration should then be loaded in the CPU module. To update the configuration in the NOE module, it must be lifted from the backplane and then reinserted. The modules can be hot swapped, so there is no need to power down. The IP address should now be properly configured. Check this by using ‘ping’ or the ‘Network Options Ethernet Tester’ program. Special Requirements Software required: Any of the software packages mentioned above. Maximum Request Length 2000 bits

3.3.2 Indirect connection for the Gateway

Gateway devices are now available in the market place.They are designed to bridge the gap between the Modnet protocol and Modbus or ModbusPlus protocol devices.

Network

adapter

TCP/IP

Modnet

PLC PLC PLC PLC

Gateway

Alternate protocol (serial)


MODNETv3.DOC 12/08/2006 12

174 CEV 300 Gateway cable pinout

(RS232/485)

2

3

4

6

5

7

8

4

3

2

5

9 pin RJ45


MODNETv3.DOC 12/08/2006 13

4. Protocol Requirements

4.1 Introduction

This section documents all the requirements of the protocol itself.

4.2 Initialising the Board

No special initialisation procedure.

4.3 Initialising the Port


4.4 Initialising the IO Device


4.5 IO Device Online Test

The driver reads a address specified in the citect.ini file (InitVar=n). If no such option appears in the citect.ini file, the address 40001 is read.

4.6 State Flow Description

The driver supports multiple outstanding requests. The “INV_ID” field, listed in section 4.7, is utilised to match individual replies with requests.

4.7 Message Structure

The message structure for the MODNET protocol is given below. INV_ID 16 bits

PROTOCOL 16 bits

LENGTH 16 bits

DEST_ID 8 bits

FUNCTION 8 bits

DATA N x 8 bits

INV_ID Invoke Identifier

Associates a request with the response. The client application picks the invoke identifier, and the server returns the same invoke identifier in the response. This value cycles modulo 65536.

PROTOCOL Protocol Type Identifies the protocol type. Currently only MODBUS is supported.

LENGTH Message Length This is the size of the rest of the message in bytes (ie excluding this field).

DEST_ID Destination ID For the Point–to–point connection this field must be set to zero.

For Gateway this field contains the module address and it determines the message’s destination.


MODNETv3.DOC 12/08/2006 14

FUNCTION Function Modbus function / command Possible values:

Symbol Definition Value

RD_DIG_OUT Read digital output 1

RD_DIG_IN Read digital input 2

RD_WORD_OUT Read register output 3

RD_WORD_IN Read register input 4

WR_BIT_OUT Write digital output 5

WR_WORD_OUT Set single register 6

WR_BITS_OUT Set multiple coils 15

WR_WORDS_OUT Set multiple registers 16

DATA Data

Modbus data

4.8 Data Format

4.8.1 Request Frames (to PLC)

Single Writes: Data field consists of two fields. The first contains the address. The second contains the value to be written to that address. The amount of bytes per variable depends on the raw data type.

Address 16 bits

Value 16 bits

Block Writes: Data field consists of four fields. The first contains the starting address. The second contains the number of values to be written. The third contains the number of bytes in the remainder of the data field. The fourth contains the values to be written.

Address 16 bits

Unit Count 16 bits

n 8 bits

value 1

value 2 … value n

Reads: Data field consists of two fields. The first contains the starting read address. The second contains the length of read required.

Address 16 bits

Length 16 bits

4.8.2 Reply Frames (from PLC)

Reply from Reads: Data field consists of two fields. The first contains the number of bytes in the remainder of the data field. The second contains all of the values.

N 8 bits

value 1 value 2 … value n


MODNETv3.DOC 12/08/2006 15

4.9 Error Handling

Two timeouts in succession will cause the unit to go offline.

4.10 CRC calculation

This driver relies on the TCP/IP CRC error checking. It does not use the protocol’s error checking.

4.11 Performance issues

4.11.1 Multiple outstanding requests.

This driver supports multiple outstanding requests. The maximum number of requests outstanding, (ie the maximum number of requests allowed to be sent to the PLC at a given time), is defined by the MaxOutstanding INI parameter (refer to Section 5.9.2). Note that the standard INI parameter ‘MaxPending’ defines the maximum number of requests pending for the driver to execute, whereas the ‘MaxOutstanding’ parameter defines the maximum number of requests that can be outstanding to the PLC. MaxPending should always be greater than MaxOutstanding. MaxOutstanding should be adjusted to coincide with the number of requests the PLC can process in one scan cycle. The appropriate value is best obtained by analysing a ‘debug * all’ dump to determine the number of PLC replies received in one PLC scan. If the PLC is running at very short scan rates, the scan time may have to be temporarily stretched to 30msec, in order to easily identify the different PLC scans. Note that empirical testing indicates that longer PLC scan times allows the PLC to process more requests per scan. Setting the MaxOutstanding parameter unnecessarily high will actually degrade throughput. The number of requests the PLC can process per scan essentially determines the driver’s performance. This value is dependent on both the tuning of the PLC scan times, and on the PLC’s overheads such as modbus communications. The default value for MaxOutstanding is set to four.

4.11.2 Concurrent connections.

The Quantum TCP/IP module supports up to 20 concurrent connections. This includes connections to other PLCs, Citect stations etc. This driver utilises multiple outstanding requests. If the user wishes to enhance the performance by taking advantage of concurrent connections the user can do that by defining extra Citect Ports and Units . Concurrent connections and multiple outstanding requests can be used at the same time.

4.12 Comparison against Modbus RTU

Modicon have published a document on the Internet that defines the standard for Modbus using TCP/IP communications. This document is commonly called "Open Modbus / TCP Specification". The MODNET driver is based on this document. Citect supports a specific implementation of this standard. This implementation, using the Citect MODNET driver, supports the Modicon Quantum Ethernet TCP/IP module. This KB article outlines the differences between the Modicon specification (last revision date 3rd of Sept., 1997) and the MODNET driver operation. This article does not cover the issues of the 'conformance classes' that are documented in the specification, as the conformance classes are directly related to the data types supported by the MODNET driver.


MODNETv3.DOC 12/08/2006 16

Half-duplex Vs Full-Duplex The specification states that "Requests are sent in half-duplex fashion (response MUST be received before the next request may be sent on a socket)". The MODNET driver operates in a Full-Duplex fashion, effectively having multiple outstanding requests. This feature is supported by the Modicon Quantum Ethernet TCP/IP module, although this feature can be partially disabled in the MODNET driver by setting [MODNET]MaxOutstanding=1. Invoke Identifier (also known as simply "Identifier") The specification also indicates that the identifier field is "usually 0". The MODNET driver uses a cycling module 65536 value. CRC The specification does not explicitly highlight whether the Modbus RTU CRC field is used in the protocol. From experience, we have found that the CRC field is not used by the Modicon Quantum Ethernet TCP/IP module, but rather relies on the TCP/IP Checksum. As a result, the MODNET driver does not use a CRC field but also relies on the TCP/IP Checksum. Destination ID (also known as 'Unit Identifier' or 'Slave address') The specification indicates that the Destination ID may be used to take advantage of devices such as gateways and bridges, so that on IP address can support multiple end units. As the MODNET driver was designed specifically for the Modicon Quantum Ethernet TCP/IP module, this Destination ID is permanently hard-coded to 0. Future revisions of the MODNET driver may allow for the Destination ID to be user configurable in Citect.


MODNETv3.DOC 12/08/2006 17

5. User Interface

5.1 Introduction

This section defines how the user will see the driver. This relates directly to how the Citect forms need to be filled out and any special INI options. For the kernel, the debug trace messages and the Stats.Special counters are documented.

5.2 Driver Name

MODNET

5.3 Boards Form

5.3.1 Board Type

TCPIP

5.3.2 Address

Set this field to 0.

5.3.3 IO Port

Leave blank.

5.3.4 Special Opt

Leave Blank.

5.4 Ports Form

5.4.1 Port Number

Leave Blank

5.4.2 Baud Rate

Leave Blank.

5.4.3 Data Bits

Leave Blank.

5.4.4 Stop Bits

Leave Blank.


MODNETv3.DOC 12/08/2006 18

5.4.5 Parity

Leave Blank.

5.4.6 Special Opt

Enter “-I<number>” where <number> is the IP address for the PLC. For example, “-I84.11.114.168”. Note that either upper or lower case "i" may be used to specify the IP address option. Enter "-P<port>" where <port> is the TCP/IP port, if the port number is omitted, This driver will use port 502 as default.

5.5 IO Devices Form

5.5.1 Protocol

MODNET

5.5.2 Address

Leave Blank for point-to-point connection. If it is Gateway this field must have the module address. For example: 24 For Adam 5000/TCP, always fill this with 1.

5.6 Pulldown lists Help

The following entries should be included in the Citect HELP.DBF spec file.

TYPE DATA FILTER

PROTOCOL MODNET

5.7 IO Device Variable Types

IO Device Type Citect data format

Citect data types

Description/Special Usage/Limitations/ Valid Ranges

Output Coils N DIGITAL Range1: 00001 to 099999

Input Status N DIGITAL Range1: 10001 to 199999

Input Registers n* INT / REAL / LONG / BCD / LONGBCD / STRING

Range1: 30001 to 399999

Output Registers N* INT / REAL / LONG / BCD / LONGBCD / STRING

Range1: 40001 to 499999

Extended Registers f:r INT / REAL / LONG / BCD /

Range:


MODNETv3.DOC 12/08/2006 19

LONGBCD / STRING

f : from 1 to 999

r: from 0 to 9999

Modbus 4 string N STRING Range: S400001 to S499999

Modbus 3 string N STRING Range: S300001 to S399999

Input Registers odd address

N☺ LONG/LONGBCD/REAL

Range: 300001 to 399999

Input Registers Even address


Range: 300001 to 399999

Output Registers odd address


Range: 400001 to 499999

output Registers even address


Range: 400001 to 499999

Where:

N Decimal number within the range specified above

1 Range refers to the range for the numbers after the first digit. The first digit remains constant for the device type.

* The individual bits in a register (1..16) can be written to by using the format “n.BitPosition” (eg 40001.1) Note that writing to sequential bits requires individual write commands. The convention of the bit order direction used in numbering the bits is user selectable, via the INI parameter RegisterBitReverse (refer to Section 5.9.2)

☺ O3##### and O4##### have to be an odd address, return DRIVER_BAD_UNIT_TYPE error if an even address is used.

E3##### and E4##### have to be an even address, return DEIVER_BAD_UNIT_TYPE error if an odd address is used.

Note: For Adam 5000/TCP, Basing on Modbus standard, the addresses of the I/O modules you place into the ADAM-5000/TCP system are defined by a simple rule. Please refer the following figure to map the I/O address. For example, if there is a ADAM-5024 (4-channel AO Module) in slot 2, the address of this module should be 40017~40020. Some Adam5000 data types that are accessible through serial are not available with this driver. The data types that are available and their addresses can be found using the ADAM-5000/TCP Utility.


MODNETv3.DOC 12/08/2006 20

5.8 PROTDIR.DBF

TAG FILE BIT_BLOCK MAX_LENGTH OPTIONS

MODNET MODNET 1920 1920 0x37f

5.9 Parameters and INI options

5.9.1 Standard Parameters

Block 250 Delay 0 MaxPending 2 Polltime 0 Timeout 1000 Retry 1 WatchTime 30

5.9.2 Driver Specific Parameters

CITECT.INI parameters:


MODNETv3.DOC 12/08/2006 21

StringReverse reverses order of bytes in string variable types - “ABCD” → “BADC” Allowed values: 0 - no reverse (default) 1 - reverse FloatMode specifies order of bytes in REAL variable types Allowed values: 0 = 1 0 3 2 byte order (default) 1 = 3 2 1 0 byte order 2 = 0 1 2 3 byte order 3 = 2 3 0 1 byte order InitVar address of variable read on startup to confirm connection

Allowed values: any address in the ranges defined in section 5.7 IO Device Variable Types, on page 18 of this document. The default address is 40001.

MaxBits maximum read size in one request Allowed values: 1 ~ 1920, default = 1920 MaxOutstanding If this parameter is placed under the section [MODNET] all ports in the

project will have this parameter set to this number.

If this parameter is placed under the section[MODNET.<Port_name>] the particular port will have this parameter set to this number and previous number will be overwritten. [MODNET.<Port_name>] parameter has the highest precedence.

If MaxOutstanding parameter is missing the number of the outstanding requests will be set to 1 (default = 1) for all ports in the project.

Allowed values: 1 ~ 32,

(Refer to Section 4.11.1 for details)

• Example:

[MODNET.TCPPORT1] MaxOutstanding =3

[MODNET.TCPPORT2] MaxOutstanding =4

In this case TCPPORT1 is set to 3 and port TCPPORT2 set to 4

• Example:

[MODNET] MaxOutstanding =3 [MODNET. TCPPORT1]

MaxOutstanding =5

In this case TCPPORT1 is set to 5 and all other ports in the project (if any) are set to 3 For Adam 5000/TCP, do not use multioutstanding, set this parameter to 1.

RegisterBitReverse Defines the order in which bits in a register are individually addressed Allowed values: 1 – Setting Bit 1 (only) will result in a register value of 1


MODNETv3.DOC 12/08/2006 22

0 – Setting Bit 16 (only) will result in a register value of 1 (default is 0) SendBCDSwap Defines the order of the bytes in a BCD word Allowed values: 1 - Big Endian format (Motorola or Network format) 0 - Small Endian format (Intel format) (default is 1) LongDataType When using the MODBUS protocol, Citect will combine two registers to store

a long data type in a PLC. The way in which it does this is defined by this parameter in the "citect.ini" file.

Allowed values : 0 - implies 10,000 * low register + high register

1 - implies 65,536 * low register + high register 2 - implies 10,000 * high register + low register 3 - implies 65,536 * high register + low register (default is 3)

Debug Allows extra debug information to be displayed in the Citect kernel window

and logged into syslog.dat file. Allowed values: 1 - turn on the extra debug information option 0 - turn off the extra debug information option (default is 0) ConnTimeout Timeout period for channel initialisation in milleseconds. Allowed values: 1 – 65535 (default is 15000) ForceMultiCoilsOnly Optionally use only function codes 15. To use function code 15 rather than

15 and 5 for coil writes set ForceMultiCoilsOnly = 1. Default=0 PresetMultiRegisterOnly Optionally use only function codes 16. To use function code 16

rather than 16 and 6 for register writes set PresetMultiRegisterOnly = 1. Default=1 (complies with Class0 Modbus/TCP device)

New INI parameters from version 3.00.00.000 B onwards: CacheTimeout time in milliseconds in order to judge if a device cache item is stale, if it is

stale, a new request is sent to the device, otherwise, the request will be satisfied from the device cache itself. Default value is 200 ms. Allowed values: 0 - 1000

AccumulateTime time in milliseconds to queue incoming Citect requests, after which all

requests up to the Accumulate time will be blocked intelligently if possible. Default value is 20 ms. Allowed values: 0 - 500

UseIncludeProjects This parameter signals the driver to enable or disable the use of Citect

include projects. If this parameter is set to 1, the driver will look for main project’s include.dbf file, get a list of all the include projects for that main project, and for each include project in the list, locate the corresponding variable.dbf files. All these files will then be used to build the driver cache. If this parameter is set to 0, the driver simply uses the variable.dbf file of the main project, and uses this to build its cache.

Default value is 1, or enabled.


MODNETv3.DOC 12/08/2006 23

5.10 Driver Specific Errors

Driver Error Code

(Hexadecimal)

Mapped to (Generic Error label) Meaning of Error Code

0x100 MISMATCH_GTW_PTP Gateway/Point-to-Point mismatch

0x20xx PLC exception Errors

0x2002 GENERIC_ADDRESS_RANGE_ERROR Variable address is out of range

0x2003 GENERIC_ADDRESS_RANGE_ERROR Address/length is out of range

0x21xx Driver specific Errors

0x2100 FUNCTION_CODE_MISMATCH Request/response doesn't match

0x2101 INVALID_BCD_ERROR Bad BCD format

5.11 Driver Error Help

The following entries should be included in the Citect PROTERR.DBF spec file.

PROTOCOL MASK ERROR MESSAGE REFERENCE ACTION COMMENT

1 MODNET Alias

MODNET 0 28 Bad Response from PLC

5.12 Debug Messages

The trace statements produced are self-explanatory, and can be divided into two groups. The first group is enabled immediately when debugging is initiated (via a command such as ‘debug * all’). This group covers the basics of requesting data and receiving responses from the device, as well as identifying any TCPIP errors encountered. The second group is enabled by setting the INI parameter Debug to one (in addition to initiating the debugging system as per the first group) . This group produces more detailed traces of the drivers operation. The majority of trace statements also include a dump of the buffer relevant to the request or response operation being traced. Refer to 4.7 Message Structure and 4.8 Data Format as a guide for interpreting these buffers.

5.13 Stats Special Counters

Number Label Purpose/Meaning of this counter

0 Max Outstanding Value of the MaxOutstanding INI parameter

1 Frames Transmitted Total number of frame transmitted

2 Frames Received Total number of frame received

3 Receive Interrupts Total number of receive interrupt received

4 Write Requests Total number of write request made


MODNETv3.DOC 12/08/2006 24

5 MaxRead Maximum frame length encountered

6 Read Request Total number of number of frames read

7 Read Char Total number of number of characters read

8 Char/Read Req Average number of characters per frame read

9 Max Receive Time Maximum time to receive response

10 Frames Concatenated Number of occurrences of concatenated frames

11 Max Concatenation The greatest frame concatenation (in frames)

12 Req Outstanding The number of requests currently outstanding

13 Partial Frame Reads Total number of incomplete/invalid response received

14 Partial Frame Left Total number of incomplete response left unprocessed

15 Peak Outstanding msg The peak outstanding message number

16 Unmatched msgs Total number of unmatched msgs received

17 ResponseBuffer overflow Total number of overflow occurred

5.14 Hints and Tips

Once the PLC’s IP address is set the setup is fairly straightforward.

5.14.1 Modnet

The name MODNET was originally used by AEG Modicon in reference to an INTERBUS derivative. Citect’s MODNET driver does not support, or in any way relate to, the AEG Schneider INTERBUS derivative.

5.14.2 Address Field

Note that the address field in the units form should always be blank for point-to-point connections. For projects constructed with version 2.12 of this driver (or earlier), that does not have the address field blank, should be corrected before placing the project into operation. The driver will now issue the address, shown in the address field, in a request to the device, previously the driver would always have issued an address of zero.

5.14.3 Bit Addressing

This driver now has the capability of writing to an Integer register with bit addressing, eg. 40001.b where b is the bit address. You should be aware that if the register were set to BCD type, then by using the bit addressing capability you would be able to force an illegal value into that register. The result would send that register into #COM.

5.14.4 Smart blocking is supported from version 3.00.00.000 B onwards:

Normally, mixed data types are not blocked by the Citect compiler even though these addresses are just adjacent with each other or within blocking range. For example a graphics page containing address 400001 as an integer, 400003 as a real, 400004 as a BCD, will result to 3 read requests to the device, although physically one request was enough to read that block of data. The Modnet driver was modified to work around this Citect behaviour. To get around this limitation, a cache is implemented per unit in the new driver from 3.00.00.000 B onwards. In addition to this, requests coming in to the driver will be queued for a short period of time and this time will be configurable thru the AccumulateTime INI parameter, of which the default value is set to 100 milliseconds. All DCBs received for the driver within this time, will be intelligently blocked (thus Smart Blocking) if possible, so that physical requests to the device will be maximised. Only DCBs for same unit and unit types can be Smart blocked. There is also a configurable INI parameter CacheTimeout, the purpose of which is to satisfy some Citect requests that ask for the same data within this time immediately from the unit’s cache. The user


MODNETv3.DOC 12/08/2006 25

can increase the CacheTimeout so that requests may be serviced from the cache. It is not advisable to set this parameter to a value grater than 1000ms as this is not practical anymore since data may be stale for that period of time.

5.14.5 New String data types from version 3.00.00.000 B onwards:

Citect requires strings to be NULL terminated, but according to the MODBUS specification, it is not required for the device to terminate the string with a NULL character in the device. To comply with this requirement, there are 2 new data type formats added from version 3.00.00.000 B onwards. These are: S4%U(1,1,99999) to read and write 4xxxxx register as a string; eg: S400001, S400999... S3%U(1,1,99999) to read 3xxxxx register as a string; eg: S300038, S399999... These new data types are forced NOT to be blocked by the compiler, so this will increase the number of separate requests (especially if there are many strings).


MODNETv3.DOC 12/08/2006 26

6. Basic Testing

6.1 Introduction

The programmer will perform a minimum level of testing which is outlined here. A sample Project is available which can be used as a starting point for the programmers test Project. When the programmer has completed basic testing and debugging this Project should by backed up and supplied to the Citect Testing department.

6.2 Procedure

The following are points should be covered by basic testing.

• On startup the IO Device comes online without errors.

• The driver supports IO Devices of addresses as documented in the specification.

• The driver reports the IO Device offline when the IO Device is a) powered down, b) disconnected.

• The driver will re-establish communication with the IO Device after a) power cycle, b) disconnection/ reconnection.

• Confirm that retries (if supported) and error reporting operate correctly.

• The driver reads all the device data types documented as readable in this specification.

• The driver writes to all the device data types documented as write-able in this specification.

• The driver reads and writes all data formats supported by the protocol, ie DIGITAL, INT, LONG, REAL, BCD, LONG_BCD.

• Test the limit of the IO Devices request size, this should be done for at least DIGITAL and an INT data formats.

• Let the driver run over night and check that no retries or other errors have occurred.

• If a multidrop or network protocol and if the hardware is available then the protocol should be tested with more than one IO Device connected.

6.3 Start of Testing

The hardware used for testing was as follows: DESCRIPTION MAKE MODEL NO TSX Quantum Modicon Software used for testing: Operating System Citect Version Driver NT4 V5r1 2.01.03 The Protdir.dbf settings were


MODNET MODBUS 2000 2000 0x37f

Introduction The PLC used was already configured with an IP address and in use on the network. The IP set up procedure and documentation has not yet been tested. Help documentation is not yet available and has not been tested. Test 1: Basic Communication Test This test was use to check that everything works fine before creating any other tests.

Test Checked OK

Test 2: Read/Write of each data type


MODNETv3.DOC 12/08/2006 27

All data types were written to and read from with Citect. A backup of the main project that was used to test the protocol may be found in H:\CITECT\DRIVERS\PROJECTS\

Test Checked OK

Test 3: Break in communication and recovery The communication cable was pulled out from the PLC and Citect was observed to go offline and a hardware alarm was recorded. The cable was re inserted and Citect went back on line.

Test Checked OK

Test 4: Bulk Test All supported variable tags were created to cover all the available IO addresses. Pages were created to read and write to each variable tag. When many blocks of addresses were available, the first group of words, the middle group of words, and the last group of words were tested. A backup of the main project that was used to test the protocol may be found in H:\CITECT\DRIVERS\PROJECTS\MODNET

Check all types read/write to the correct address OK

Test 6: Unusual or Illegal procedures Test Attempted to set illegal data types, write to read only tags and overload the PLC with continuous write commands.

Test checked OK

Test 7: Debug String captures

6.4 Problems Found

1 Help documentation is not yet available and has not been tested. (Being addressed)

2 The Protdir.dbf does not match the specs.

3 This driver is currently hard coded to 502. (NCR11630)

4 Compile error when using a tag with bit addressing ie. 40001.1 (Bad I/O device variable). This was fixed with a new Modnet.dbf file from David Rossini (Make sure the build files are updated)

5 Bit addressing of output registers is not quite right. 40001.1 through to 40001.15 are OK but 40001.16 is mapped to 40002.16 This is now fixed with another updated Modnet.dbf file (Make sure the build files are updated)

6 RegisterBitOrder INI parameter is not working. This has been fixed by changing the spec to RegisterBitReverse (Check the help for this modification)

7 With a register set to BCD I can write invalid values to the individual bits and the driver does not return an error. ie with the lower four bits set to on the integer value returned is 15 this is an error as the maximum BCD value for the lower four bits is nine (1001) (NCR11630)

8 I can write and read back a LONG from 49999.


MODNETv3.DOC 12/08/2006 28

7. Re Testing After Modifications

Re-testing with the Hardware configured as above and using Citect V521 and Modnet driver V2.01.02 Also tested with multiple point to point devices, but with only a single gateway device. Driver Version number updated to 2.01.03 after fixes were tested OK . Problems Found

1 Debug * write not working correctly Fixed And tested OK.

2 Driver never recovers from a faulty response “Un-matched response” message. Fixed And tested OK.

3 Citect.INI parameter FloatMode is not working. Fixed And tested OK.

4 Modnet Help for Citect.INI parameter ‘RegisterBitReverse’ does not agree with the spec. The parameter works as per the spec. NCR raised to Ross

5 Modnet Help for Citect.INI parameter ‘LongDataType’ missing. NCR raised to Ross

6 I suspect that the Citect.INI parameter ‘SendBDCSetup’ should be SendBCDSwap. Also no help on this parameter in the help file. NCR raised to Ross

7 SendBCDSetup parameter not working. (SendBDCSetup and SendBCDSwap not working either) Fixed And tested OK.

8 Stats Special Counter number 13 ‘Partial frame Reads’ is showing a very large value, almost 100% of the frame received. Fixed And tested OK.

9 Data type valid ranges are not correct… I can compile without error with an address range up to x99999 (where x = 0,1,3, or 4) and I can get a valid response from the Modicon Output register up to address 415000. NCR raised to Ross

10 Suggestion that perhaps the Hot Standby Citect.INI parameter [MODBUS] Status=x,x,x,x,x, should be incorporated in this driver to be on par with the MODBUS driver!

11 This driver has not been tested with multiple Gateways.

12 SendBCDSwap only swaps on the write eg write 1234 reads back as 3412

13 SendBCDSwap does not swap at all for LongBCD Fixed And tested OK..

7.1 Start of Testing for Extended addressing modifications

The hardware used for testing was as follows: DESCRIPTION MAKE MODEL NO TSX Quantum Modicon CPU 424 02 Software used for testing: Operating System Citect Version Driver Version NT4 V521 MODNET Driver v2.02.02 The Protdir.dbf settings were


MODBUS MODBUS 400 2000 0x37f

7.2 Faults Found

1 Cannot write to Extended registers, Kernel reports “Address is out of range”. Reads to the same register are OK. Fixed And tested OK.


MODNETv3.DOC 12/08/2006 29

2 Digital mapping not correct. It looks like the upper eight and the lower eight bits are swapped. Fixed and tested OK

3 Looks like a blocking problem. When extended tags and normal tags are on the same page. Cicode writes to all tags in quick succession will miss the Extended-registers. Fixed and tested OK

4 Write using Cicode to Extended register bits to a common INT register will miss some writes, Read modify write not working correctly. Fixed and tested OK

5 With more than 120 consecutive extended tags on a page then #COM on the first 120. A work around fix is to set Bit Block in the protdir file to 400. Fixed and tested OK

6 InitVar not correct for when using output coil address 00001 to 09999. It appears that the bottom byte of the address in the init string is always 0x00. Not a problem

7 MaxBits in the help file should be changed from 2000 to 1920 , Citect Editor notified.


MODNETv3.DOC 12/08/2006 30

8. Testing Modifications for the Adam5000/TCP

8.1 Intro

This section describes the testing of the Modnet driver with the ADAM5000/TCP data acquisition modules.

8.2 Hardware Setup

The hardware used for testing was as follows: DESCRIPTION MAKE MODEL NO ADAM-5000/TCP CPU Advantech ADAM-5000/TCP 8 Channel High speed input module. Attached to Slot 1

Advantech ADAM-5017H

16 Channel Digital input module. Attached to Slot 0

Advantech ADAM-5051

6 Channel relay output module. Attached to Slot 3

Advantech ADAM-5060

4 Channel Counter/frequency module. Attached to Slot 2

Advantech ADAM-5080

Software used for testing: Operating System Citect Version Driver NT4 Service Pack 6 V5.40 2.05.00.000

8.3 Express Communications Wizard Tests

These tests check whether the Citect Communications Wizard fills out the communications forms (Boards, Ports, I/O Devices) correctly.

TEST STATUS

Correct Manufacturer, Model and Communications Protocols appear in Drivers Tree

Fail*

‘Driver Address Help’ button functions correctly Status

Boards form filled out according to specification Status

Ports form filled out according to specification Status

I/O Devices form filled out according to specification Status

Protocol appears in drop-down list in ‘Board Type’ field of Boards form and ‘Protocol’ field of I/O Devices form.

* See fault 1.

8.4 Basic Communications Tests

These tests are used to check that the driver performs its basic functions correctly. Theoretically, all these tests should be successful, as the developer will have performed similar testing prior to passing the driver over for QA.

8.4.1 Citect Compile, Start Up and Shut Down Tests

TEST STATUS

Project with a configured I/O device for the driver compiles without error. Pass


MODNETv3.DOC 12/08/2006 31

Citect Runtime launches and the driver initialises without error. Pass

Citect Runtime shuts down without error. Pass

8.4.2 Basic Read/Write Testing

Each supported data type on the I/O device should be read and, where applicable written to. Correspondence with all relevant Citect data types should be checked.

8.4.2.1 Read Tests

I/O DEVICE DATA TYPE CORRESPONDING CITECT DATA TYPE

STATUS

Relay Digital Pass

High Speed Input Integer Pass

8.4.2.2 Write Tests

I/O DEVICE DATA TYPE CORRESPONDING CITECT DATA TYPE

STATUS

Relay on ADAM-5060 Digital Pass

8.4.3 Break in Communications Tests

The driver should detect when an I/O device is offline and generate a hardware alarm. Citect should re-establish communications when the device returns online.

TEST STATUS

Citect detects when an I/O device goes offline. Hardware alarm is generated. Pass

Citect attempts to re-establish communications. The period between attempts corresponds to the specified WatchTime parameter.

Pass

Citect detects when the device comes online again and re-establishes communications.

Pass

8.4.4 Duration/Longevity Testing

The driver should be tested over an extended period of time. Stability and memory usage should be monitored. Start Time 4:30 pm Tuesday End Time Duration of Test Mem. usage when project has started 11320 KB Mem. usage after 24 hours Mem. usage at end of test Test Status

8.5 Faults

1. The Express Communication Wizard has no option to use Modnet driver for ADAM-5000(CPU).


MODNETv3.DOC 12/08/2006 32

9. Testing Modifications Dated 5April 2002

Testing specifications are now separate documents. Link to Testing document MODNET Smart blocking Testing.DOC


MODNETv3.DOC 12/08/2006 33

10. Performance Testing

10.1 Introduction

Tests which give some indication of the drivers performance. The programmer needs to perform these tests since the results feed back into the Constants structure and the PROTDIR.DBF.

10.2 Calculating the Blocking Constant

The Performance test procedure is documented in the driver development kit in Appendix A, ‘Calculating the Block Constant’. The results of the performance test are recorded here.

Protocol Timing Test for Modnet protocol

Data:

Maximum Request Size [words] 125

Request size [words] 1 33 65 97 125

Response Time [ms] 10 11 12 13 14

Linear Response Time [ms] 9.97569 11.00066 12.02562 13.05059 13.947438

0

2

4

6

8

10

12

14

1 33 65 97 125

Real Data

Linear Data

Calculation:

Overhead [mS] 9.94366

Slope [ms/word] 0.03203

Blocking Const [words] 310

[bytes] 621

[bits] 4967

Constants.Block [bytes] 256

BIT_BLOCK [bits] 2048

The timing test sets Constants.Block to the Citect maximum of 256 words. The PLC is limited to 125 words, so Constants.Block will be set to this value.


MODNETv3.DOC 12/08/2006 34

11. References and Contacts

11.1 References

Modicon Quantum Ethernet TCP/IP Module User Guide Version 1.0, AEG Schneider Automation, 1996 Network Options Ethernet Tester example application code, AEG Schneider Automation, 1996

11.2 Contacts

Allan Thorne Schneider 02 9436 1313


MODNETv3.DOC 12/08/2006 35

12. Appendix A – Open MODBUS TCPIP Specification

Summary: Modicon have published a document on the Internet that defines the standard for Modbus using TCP/IP communications. This document is commonly called "Open Modbus / TCP Specification". Does Citect support this specification? Solution: Citect supports a specific implementation of this standard. This implementation, using the Citect MODNET driver, supports the Modicon Quantum Ethernet TCP/IP module. This KB article outlines the differences between the Modicon specification (last revision date 3rd of Sept., 1997) and the MODNET driver operation. This article does not cover the issues of the 'conformance classes' that are documented in the specification, as the conformance classes are directly related to the datatypes supported by the MODNET driver. Half-duplex Vs Full-Duplex The specification states that "Requests are sent in half-duplex fashion (response MUST be received before the next request may be sent on a socket)". The MODNET driver operates in a Full-Duplex fashion, effectively having multiple outstanding requests. This feature is supported by the Modicon Quantum Ethernet TCP/IP module although this feature can be partially disabled in the MODNET driver by setting [MODNET]MaxOutstanding=1. Invoke Identifier (also known as simply "Identifier") The specification also indicates that the identifier field is "usually 0". The MODNET driver uses a cycling module 65536 value. CRC The specification does not explicitly highlight whether the Modbus RTU CRC field is used in the protocol. From experience we have found that the CRC field is not used by the Modicon Quantum Ethernet TCP/IP module, but rather relies on the TCP/IP Checksum. As a result, the MODNET driver does not use a CRC field but also relies on the TCP/IP Checksum. Destination ID (also known as 'Unit Identifier' or 'Slave address') The specification indicates that the Destination ID may be used to take advantage of devices such as gateways and bridges, so that on IP address can support multiple end units. As the MODNET driver was designed specifically for the Modicon Quantum Ethernet TCP/IP module, this Destination ID is permanently hard-coded to 0. Future revisions of the MODNET driver may allow for the Destination ID to be user configurable in Citect. Author: Bruce Kinchin

citect for windows driver specification modnet driver · citect for windows driver specification...

Documents