Citect for Windows Driver Specification Extract TWINCAT Driver

Author Jens Nasholm Sean Ju Daniel Saputra Dave Sidery Peter Geagea Trevor Hudson Peter Geagea Trevor Hudson Peter Geagea

Date 25/08/98 26/2/99 January 1999 03/03/99 30-03-99 10/5/99 12-10-99 1/11/1999 20-08-01

Comment Editing earlier written specification Add/Modify Modified Final Testing section Modified Final Testing section Minor modifications Testing after fixing Added support for REAL and STRING data types Testing after fixing Addition to section 2.5.2

Driver Design Specification

Contents

1.

TARGET DEVICE(S) AND PROTOCOL

1.1 Introduction 1.2 Device Manufacturer 1.3 Device Definition 1.4 Communications Method 1.5 Communications/Hardware Configuration
1.5.1 1.5.2 1.5.3 Wiring Diagrams I/O Device Settings Software Setup

4
4 4 4 5 5
5 5 6

1.6 Special Requirements 1.7 Maximum Request Length

6 6

2.

USER INTERFACE
2.1 Introduction 2.2 Driver Name 2.3 Boards Form
2.3.1 2.3.2 2.3.3 2.3.4 2.3.5 Board Type Address IO Port Interrupt Special Opt

7
7 7 7
7 7 7 7 7

2.4 Ports Form

2.4.1 2.4.2 2.4.3 2.4.4 2.4.5 Baud Rate Data Bits Stop Bits Parity Special Opt

7
7 7 7 7 8

2.5 IO Devices Form

2.5.1 2.5.2 Protocol Address

8
8 8

2.6 Pull-down lists Help 2.7 IO Device Variable Types

2.7.1 2.7.2 Formats and types TWINCAT.DBF Entries

8 9
9 10

2.8 PROTDIR.DBF

10

TWINCAT.DOC

20-08-01

Driver Design Specification

2.9 Parameters and INI options

2.9.1 2.9.2 Standard Parameters Driver Specific Parameters

10
10 11

2.10 2.11 2.12 2.13 2.14 2.15

Remapping Driver Specific Errors Driver Error Help Debug Messages Stats Special Counters Hints and Tips

11 11 11 11 11 12

3.

REFERENCES
3.1 References

13
13

TWINCAT.DOC

20-08-01

Driver Design Specification

1. Target Device(s) and Protocol

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

1.2 Device Manufacturer

Beckhoff Industrie Elektronik. The product developed by Beckhoff is called TwinCAT and is a SoftPLC.

1.3 Device Definition

The TwinCAT system consists of individual software objects (TwinCAT PLC, TwinCAT NC, PIDRegler, etc....). Each of these objects is defined with the aid of a standard interface, the Automation Device Specification (ADS). The exchange of messages between these objects is realised in accordance with the Automation Message Specification (AMS) and is organised by the TwinCAT Message Router. Therefore, each object within TwinCAT that conforms to ADS is identifiable and can be addressed. These are referred to as ADS devices. The local AMS Message Router method of communication to the Beckhoff TwinCAT soft-PLC, manufactured by Beckhoff Industrie Elektronik, uses the TWINCAT protocol. Using this method Citect can communicate with all devices and accessible I/O from within TwinCAT. TwinCAT, and hence Citect, can communicate to real I/O via a number of different industry standard protocols including Interbus-S, Profibus DP/FMS and Beckhoff Lightbus, and a number of different proprietary protocols. You can also configure a PLC program in the TwinCAT system where memory variables can be accessed from Citect.

TWINCAT.DOC

20-08-01

Driver Design Specification

1.4 Communications Method

TwinCAT I/O System

TwinCat PLC System

TwinCat CNC System

User Application

Citect I/O Server ADS DLL

LAN or WAN

ADS DLL

ADS DLL

ADS DLL

ADS DLL

AMS Message Router (TCP/IP).

ADS DLL
TwinCat I/O Mapper

ADS DLL
TwinCat PLC Server

ADS DLL
TwinCat CNC Server

ADS DLL
User App. Server

ADS DLL

I/O Mapping I/O Connectivity - Profibus DP/FMS - Beckhoff Lightbus - InterBus - S

The Automation Device Specification (ADS) defines a device and field bus-independent interface. This reduces effort, both when integrating devices in an automation system because a standard interface is available and also when developing new devices because the interface has already been defined and realised. Diverse ADS services are defined, split into Requests, Indications, Confirmations and Responses. The Citect driver uses the ADSDLL.DLL supplied by Beckhoff. The Citect driver opens a connection to the local AMS Message Router using the ADSDLL.DLL. The ADSDLL.DLL then forwards all requests from Citect to the AMS Message Router that transports the message to the correct TwinCAT PLC Server. The AMS Message Router includes an interface for TCP/IP which means that messages can be forwarded over any LAN or WAN network.

1.5 Communications/Hardware Configuration

Not applicable. 1.5.1 Wiring Diagrams Not applicable. 1.5.2 I/O Device Settings Not applicable.

TWINCAT.DOC

20-08-01

Driver Design Specification

1.5.3 Software Setup A standard installation of TwinCAT including the ADSDLL.DLL functionality is necessary. When TwinCAT is installed it will by default use the TCP/IP address configured on the PC and add 1.1 to end of it as the AMS Net Id, with this configuration Citect have to be configured as mentioned in 5.4.5. The AMS Net Id is a 6 byte address, similar to a TCP/IP address, which each TwinCAT system will have. The AMS Net Id is unique for each networked PC. The AMS Net Id will be used by Citect to connect to the selected TwinCAT system, see 5.4.5. Citect and TwinCAT have to be on the same computer to make communication with local/remote TwinCAT systems possible. A user supplied PLC program must be configured in the TwinCAT system and if this program is not valid, the PLC program will not be compiled and Citect will not be able to communicate with TwinCAT. Once the TwinCAT Soft PLC is installed, the procedure for starting the TwinCAT system is as follows: 1. Double click the Devices icon located in the Windows NT Control Panel. 2. Four TwinCAT devices should be listed here. The Startup Type should be set to Automatic for each one. Start any devices that are not yet started. Close the window, and close Control Panel. 3. Click the small TwinCAT icon located in the Windows Task Bar Systray. 4. Select System and then Start 5. Click the TwinCAT systray icon again, and select PLC Control 6. Open the user defined TwinCAT PLC Control program. 7. From the Online menu, select Login . Click OK to Rebuild All if prompted. 8. From the Online menu, select Run

1.6 Special Requirements

Make sure that the ADSDLL.DLL is in the System32 directory.

1.7 Maximum Request Length

As the driver communicates with internal memory the request length is set as high as possible to provide the most efficient communications. The request length = 2048 bits.

TWINCAT.DOC

20-08-01

Driver Design Specification

2. User Interface

2.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.

2.2 Driver Name

TWINCAT

2.3 Boards Form

2.3.1 Board Type TWINCAT (A virtual board that is used for compilation.)

2.3.2 Address Citect requires the address of 0 for successful compilation 2.3.3 IO Port Not used. 2.3.4 Interrupt Not used. 2.3.5 Special Opt Not used.

2.4 Ports Form

2.4.1 Baud Rate Not used. 2.4.2 Data Bits Not used. 2.4.3 Stop Bits Not used. 2.4.4 Parity Not used.

TWINCAT.DOC

20-08-01

Driver Design Specification

2.4.5 Special Opt Here is where the AMS Net Id should be entered. The ID number has the following format, x.x.x.x.y.z. This number refers to the AMS Net Id specified in the TwinCAT System Properties. If the TwinCAT is on the local computer the Local Computer AMS Net Id should be used, for TwinCAT systems in a network the AMS Net Id specified in the Remote Computers should be used. For easy configuration in TwinCAT the first four digits x.x.x.x in the AMS Net Id can be the TCP/IP address of the local/remote computer, i.e. 207.10.131.202 The two last digits y.z is information used in the AMS Net Id by the TwinCAT system. These two digits have to be the same as configured in the AMS Net Id of the local/remote computer. If the AMS Net Id for the local/remote computer is set to 207.10.131.202.1.1 the Special Option field has to be set according to the example below. x y z a decimal value between 0 255 a decimal value between 0 255 a decimal value between 0 255

Example, -AMS207.10.131.202.1.1

-AMS has to be upper case.

2.5 IO Devices Form

2.5.1 Protocol TWINCAT 2.5.2 Address In the each TwinCAT system you can have up to 4 PLC s, each PLC will get a consecutive Port Number as follows. PLC1 801, PLC2 811, PLC3 821 and PLC4 831, these unique Port Numbers will automatically be assigned to each PLC in the TwinCAT system. The address specified in the address field has to be one of these numbers as the driver uses the address when communicating to the TwinCAT system. This means that every local/remote TwinCAT system will have 1 to 4 PLC s which Citect can read. Which PLC is read on the local/remote TwinCAT system by Citect is decided by the IO Device Address. Which computer the PLC is located on is decided by the AMS Net Id (Special Opt in the Ports form). The Address field has to be either 301-311, 801, 811, 821 or 831. Example, 801

2.6 Pull-down lists Help

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

TYPE PROTOCOL BOARDTYPE ADDRESS

DATA TWINCAT TWINCAT 0

FILTER

TWINCAT

TWINCAT.DOC

20-08-01

Driver Design Specification

2.7 IO Device Variable Types

2.7.1 Formats and types

IO Device Type Inputs Inputs Inputs Inputs Inputs Inputs Outputs Outputs Outputs Outputs Outputs Outputs Memory Memory Memory Memory Memory Memory Where: I Q M [.b]

Citect data format IXx.b IBx[.b] IWx[.b] IDx[.b] IRx ISx QXx.b QBx[.b] QWx[.b] QDx[.b] QRx QSx MXx.b MBx[.b] MWx[.b] MDx[.b] MRx MSx

Citect data types DIGITAL BYTE INT,UINT LONG REAL STRING DIGITAL BYTE INT,UINT LONG REAL STRING DIGITAL BYTE INT,UINT LONG REAL STRING

Description/Special Usage/Limitations/ Valid Ranges x = byte no.(0-64511) , b = bit no (0-7) x = byte no.(0-64511) , b = bit no (0-7) x = word no.(0-64510 even no. only) , b = bit no (0-15) x = double word no.(0-64508, every 4th address only), b = bit no (0-31) x = real no. (0-64508, every 4th address only) x = starting byte no. (0-64511) maximum string length = 255 characters x = byte no.(0-64511) , b = bit no (0-7) x = byte no.(0- 64511) , b = bit no (0-7) x = word no.(0- 64510 even no. only) , b = bit no (0-15) x = double word no.(0- 64508, every 4th address only), b = bit no (0-31) x = real no. (0-64508, every 4th address only) x = starting byte no. (0-64511) maximum string length = 255 characters x = byte no.(0- 64511) , b = bit no (0-7) x = byte no.(0- 64511) , b = bit no (0-7) x = word no.(0- 64510 even no. only) , b = bit no (0-15) x = double word no.(0- 64508, every 4th address only) , b = bit no (0-31) x = real no. (0-64508, every 4 address only) x = starting byte no. (0-64511) maximum string length = 255 characters
th

Refers to inputs on the TwinCAT system Refers to outputs on the TwinCAT system Refers to Memory variables in memory on the TwinCAT system Refers to optional bit requests

Note. Only even address numbers are accessible when using INT or UINT data types, and only every fourth address is available if LONG or REAL data types are used. Also optional bit requests can only be refered to from Citect.

TWINCAT.DOC

20-08-01

Driver Design Specification

2.7.2 TWINCAT.DBF Entries

TEMPLATE UNIT_TYPE RAW_TYPE BIT_WIDTH LOW HIGH COMMENT

IX%U(0,0,64511).%u(0,0,7) IB%U(0,0,64511).%u(0,0,7) IW%U(0,0,64510).%u(0,0,15) ID%U(0,0,64508).%u(0,0,31) IB%U(0,0,64511) IS%U(0,0,64511) IW%U(0,0,64510)%/2 ID%U(0,0,64508)%/4 IR%U(0,0,64508)%/4 QX%U(0,0,64511).%u(0,0,7) QB%U(0,0,64511).%u(0,0,7) QW%U(0,0,64510).%u(0,0,15) QD%U(0,0,64508).%u(0,0,31) QB%U(0,0,64511) QS%U(0,0,64511) QW%U(0,0,64510)%/2 QD%U(0,0,64508)%/4 QR%U(0,0,64508)%/4 MX%U(0,0,64511).%u(0,0,7) MB%U(0,0,64511).%u(0,0,7) MW%U(0,0,64510).%u(0,0,15) MD%U(0,0,64508).%u(0,0,31) MB%U(0,0,64511) MS%U(0,0,64511) MW%U(0,0,64510)%/2 MD%U(0,0,64508)%/4 MR%U(0,0,64508)%/4

0 0 0 0 1 1 2 3 3 4 4 4 4 5 5 6 7 7 8 8 8 8 9 9 10 11 11

0 0 0 0 8 7 1 4 2 0 0 0 0 8 7 1 4 2 0 0 0 0 8 7 1 4 2

8 8 8 8 8 2040 16 32 32 8 8 8 8 8 2040 16 32 32 8 8 8 8 8 2040 16 32 32

0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

Input Bit Input Bit Input Bit Input Bit Input Byte Input String Input Word Input Double Word Input Real Output Bit Output Bit Output Bit Output Bit Output Byte Output String Output Word Output Double Word Output Real Memory Bit Memory Bit Memory Bit Memory Bit Memory Byte Memory String Memory Word Memory Double Word Memory Real

2.8 PROTDIR.DBF
TAG TWINCAT FILE TWINCAT BIT_BLOCK 2048 MAX_LENGTH 2048 OPTIONS 0xcf

2.9 Parameters and INI options

2.9.1 Standard Parameters Block Delay 256 0

TWINCAT.DOC

20-08-01

10

Driver Design Specification

MaxPending Polltime Timeout Retry WatchTime

2 10 (millisecond) 0 0 30 (seconds)

2.9.2 Driver Specific Parameters None

2.10 Remapping
Not supported.

2.11 Driver Specific Errors

None.

2.12 Driver Error Help

None.

2.13 Debug Messages

There are three different message formats that will be displayed if the debug functions are used. The formats are shown below:
Fri Feb 26 14:19:58 1999 25:51:28.286 Reading: UNIT:TWINUNIT Tag:IX600 LENGTH:102 Length 102 AC 53 53 AC 00 00 00 00 00 00 00 00 00 00 00 00 .SS............. 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 00 00 00 00 55 AC ....U. Fri Feb 26 14:19:58 1999 25:51:28.306 Reading: UNIT:TWINUNIT Tag:IX2000 LENGTH:2 Length 2 55 AC U. Fri Feb 26 14:20:05 1999 25:51:35.763 Writing: UNIT:TWINUNIT IX516095 LENGTH:1 Length 1 01 .

2.14 Stats Special Counters

Number 0 1 2 3 4 5 6 5 6 7 Label Total Writes Total Reads Unit Status Checks Bad Commands Dll Response Errors Bit Reads Bit Writes Byte Reads Byte Writes Int Reads Purpose/Meaning of this counter Total number of write requests Total number of read requests Total number of times the units have been checked Total number of unknown commands received Total number of error responses from dll Total number of times a Bit read instruction is issued Total number of times a Bit write instruction is issued Total number of times a Byte read instruction is issued Total number of times a Byte write instruction is issued Total number of times a Int read instruction is issued

TWINCAT.DOC

20-08-01

11

Driver Design Specification

8 9 10

Int Writes Real Reads Real Writes

Total number of times a Int write instruction is issued Total number of times a Real read instruction is issued Total number of times a Real write instruction is issued

2.15 Hints and Tips

1. This driver is using LONG data type to represent SoftPLC s Double word such that when the data value is greater then 2147483647 in the SoftPLC, Citect will display this data value as negative one. 2. This driver is using INT data type to represent SoftPLC s word such that when the data value is greater then 32767 in the SoftPLC, Citect will display this data value as negative one. 3. Citect and TwinCAT have to be on the same computer to make communication with local/remote TwinCAT systems possible

TWINCAT.DOC

20-08-01

12

Driver Design Specification

3. References

3.1 References
TwinCAT ADS-PLC.DOC Index and groups.DOC Description of the API to the ADSDLL.DLL (German) Description of how to use indexes and groups in the ADSDLL.DLL

TWINCAT.DOC

20-08-01

13