Notes on the documentation

This description is only intended for the use of trained specialists in control and automation engineering who are familiar with the applicable national standards.
It is essential that the following notes and explanations are followed when installing and commissioning these components.

The responsible staff must ensure that the application or use of the products described satisfy all the requirements for safety, including all the relevant laws, regulations, guidelines and standards.

Disclaimer

The documentation has been prepared with care. The products described are, however, constantly under development.
For that reason the documentation is not in every case checked for consistency with performance data, standards or other characteristics.
In the event that it contains technical or editorial errors, we retain the right to make alterations at any time and without warning.
No claims for the modification of products that have already been supplied may be made on the basis of the data, diagrams and descriptions in this documentation.

Trademarks

Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE® and XFC® are registered trademarks of and licensed by Beckhoff Automation GmbH.
Other designations used in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owners.

Patent Pending

The TwinCAT Technology is covered, including but not limited to the following patent applications and patents:
EP0851348, US6167425 with corresponding applications or registrations in various other countries.

Copyright

© Beckhoff Automation GmbH & Co. KG, Germany.
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without express authorization are prohibited.
Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a patent, utility model or design.


Intro

TwinCAT ADS .NET Component

Introduction

The TwinCAT.Ads DLL is a .NET class library, that provides classes to communicate with an ads device. The class library is part of the TwinCAT AdsCommLib that can be found on the Beckhoff Supplement CD. After installing TwinCAT AdsCommLib the TwinCAT.Ads DLL for the .NET framework version 1.1(Microsoft Visual Studio 2003/Borland Developer Studio 2006) can be found in the directory ..\TwinCAT\ADS Api\.NET\v1.1.4322. A version of the TwinCAT.Ads.dll for the .NET framework version 1.0(Microsoft Visual Studio 2002) can be found in the directory ..\TwinCAT\ADS Api\.NET\v1.0.3705.

The directory ..\TwinCAT\ADS Api\CompactFramework also contains a version for the .NET Compact Framework version 1.0 ( CE).


TwinCAT.Ads in Visual Studio .NET (C#)

TwinCAT ADS .NET Component

Linking into Microsoft Visual Studio .NET (C#)

Creating new project

Start Microsoft Visual Studio and create new project (Windows Forms Application).

Adding reference

In order to select the TwinCAT.Ads class library you must choose the command Add Reference... under the Project menu. This opens the Add Reference dialog:

In this dialog you have to press the Browse button and select the file TwinCAT.Ads.dll. In the Solution Explorer you can check, if the component has been added to the list of references.

All accessible types (classes,structures ...) belong to the namespace TwinCAT.Ads. Therefore one has to insert the following line at the beginning of the source :

using System.IO, TwinCAT.Ads;

This enables access to the types defined in TwinCAT.Ads without including the name of the namespace. The class TcAdsClient is the core of the TwinCAT.Ads class library and enables the user to communicate with an ads device. To begin with an instance of the class must be created. Then a connection to the ADS device is established by means of the Connect method.

Establish a connection to an ADS device:

TcAdsClient tcAds = new TcAdsClient();
tcAds.Connect("172.16.3.217.1.1",801);

The data is transmitted with the help of the AdsStream class, that inherits form System.IO.MemoryStream. To write data to the stream one can utilize the System.IO.BinaryWriter class and the System.IO.BinaryReader class is necessary to read data from the stream.

Reading a PLC variable:

// creates a stream with a length of 4 byte
AdsStream ds = new AdsStream(4);
BinaryReader br = new BinaryReader(ds);

// reads a DINT from PLC
tcAds.Read(0x4020,0,ds);

ds.Position = 0;
textBox1.Text = br.ReadInt32().ToString();

Writing to a PLC variable:

// creates a stream with a length of 4 byte
AdsStream ds = new AdsStream(4);
BinaryWriter bw = new BinaryWriter(ds);

ds.Position = 0;
bw.Write((int) 100);

// writes a DINT to PLC
tcAds.Write(0x4020,0,ds);

Disconnect a connection to an ADS device:

tcAds.Dispose();

PLC Program:

PROGRAM MAIN
VAR
    test AT%MD0 : DINT;
END_VAR
test := test + 1;


TwinCAT.Ads in Visual Studio .NET (VB)

TwinCAT ADS .NET component

Integration in Microsoft Visual Studio .NET (VB)

Create new project

The TwinCAT.Ads component can only be integrated in an existing project. Start Visual Studio and select the following command from the menu: File->New->Project...

In the New Project dialog please select as project type: Visual Basic->Windows Forms Application.

Adding a reference

To select the class library TwinCAT.Ads select the command Add Reference... from the Project menu. The Add Reference dialog opens.
Alternatively you double-click on My Project (1) to open the Project Properties window and click the Add... button (3) under Reference (2).

In this dialog you should select the Browse tab and navigate to file TwinCAT.Ads.dll. Confirm the selected dll with OK. By default the TwinCAT.Ads component is located in the ..TwinCAT\Ads Api\.NET\ folder.

Add namespace

All class library types belong to the TwinCAT.Ads namespace. Therefore the following lines should be added at the beginning of the source text:

Imports TwinCAT.Ads
Imports System.IO

This enables access to the data types defined in TwinCAT.Ads without having to specify the namespace repeatedly. The TcAdsClient class is the core of the TwinCAT.Ads class library and enables communication with an Ads device. The first step is to create an instance of the TcAdsClient class. Then make use of the Connect method to establish a connection with the ADS device.

Establishing a connection to an Ads device:

Private tcAds As TcAdsClient
...

tcAds = New TcAdsClient
tcAds.Connect("1.2.3.4.1.1", 801)

...

The data are transmitted with the aid of the AdsStream class, which is derived from System.IO.MemoryStream. The class System.IO.BinaryWriter can be used to write data to the stream, the class System.IO.BinaryReader can be used to read data from the stream.

Reading a PLC variable:

' creates a stream with a length of 4 byte
Dim ds = New AdsStream(4)
Dim br = New BinaryReader(ds)

' reads a DINT from PLC
tcAds.Read(&H4020, 0, ds)
ds.Position = 0
TextBox1.Text = br.ReadInt32().ToString()

Writing a PLC variable:

' creates a stream with a length of 4 byte
Dim ds = New AdsStream(4)
Dim bw = New BinaryWriter(ds)

ds.Position = 0
bw.Write(New Integer = 100)

' writes a DINT to PLC
tcAds.Write(&H4020, 0, ds)

Separating a connection to an Ads device:

tcAds.Dispose();

PLC program:

PROGRAM MAIN
VAR
    test AT%MD0 : DINT;
END_VAR
test := test + 1


Delphi examples: TwinCAT.Ads in BDS2006

TwinCAT ADS .NET component

Integration in Borland Developer Studio 2006

Creating a new project

Create a new project in Borland Developer Studio (Windows Forms Application).

Add reference

To select the class library TwinCAT.ADS select the command Add Reference... from the Project menu. The Add Reference dialog opens.

In this dialog press the Browse... button and select the file TwinCAT.Ads.dll.

Add namespace

The project manager offers an option for checking whether the component was added to the reference list.

All class library types belong to the TwinCAT.ADS namespace. This namespace must be added in the uses section:

uses
    System.Drawing, System.Collections, System.ComponentModel,
    System.Windows.Forms, System.Data, System.IO, TwinCAT.Ads;

This enables access to the data types defined in TwinCAT.ADS without having to specify the namespace repeatedly. The TcAdsClient class is the core of the TwinCAT.ADS class library and enables the user to communicate with an Ads device. The first step is to create an instance of the TcAdsClient class. Then make use of the Connect method to establish a connection with the ADS device.

Establishing a connection to an ADS device:

var	tcAds : TcAdsClient;
procedure TWinForm.Connect();
begin
    tcAds := TcAdsClient.Create();
    tcAds.Connect('172.16.3.217.1.1', 801);
end;

Reading a PLC variable:

The data (4 bytes integer in the flag area) are transferred with the aid of the AdsStream class, which is derived from System.IO.MemoryStream. The class System.IO.BinaryWriter can be used to write data to the stream, the class System.IO.BinaryReader can be used to read data from the stream.

procedure TWinForm.ReadVar();
var 	ds : AdsStream;
    br : BinaryReader;
begin
    // creates a stream with a length of 4 byte
    ds := AdsStream.Create(4);
    br := BinaryReader.Create(ds);

    // reads a DINT from PLC
    tcAds.Read($4020,0,ds);

    ds.Position := 0;
    textBox1.Text := br.ReadInt32().ToString();
end;

Writing a PLC variable:

procedure TWinForm.WriteVar();
var 	ds : AdsStream;
    bw : BinaryWriter;
begin
    // creates a stream with a length of 4 byte
    ds := AdsStream.Create(4);
    bw := BinaryWriter.Create(ds);

    ds.Position := 0;
    bw.Write( Int32(100));

    // writes a DINT to PLC
    tcAds.Write($4020,0,ds);
end;

Separating a connection to an ADS device:

procedure TWinForm.Disconnect();
begin
    tcAds.Dispose();
end;

PLC program:

PROGRAM MAIN
VAR
    test AT%MD0 : DINT;
END_VAR
test := test + 1;


Delphi Prism examples: TwinCAT.Ads in VS2010

TwinCAT ADS .NET component

Integration in Delphi Prism (Embarcadero Prism XE2, Oxygene for .NET)

Embarcadero Prism XE2 = Oxygene for .NET

Delphi Prism uses Microsoft Visual Studio 2010 as IDE and integrates itself in an existing VS installation from there. The Visual Studio IDE is supplied with the Delphi Prism installation if it is not yet available.

Create new project

The TwinCAT.ADS component can only be integrated in an existing project. Start VS and select the following command from the menu: File->New->Project...

In the New Project dialog please select as project type: Delphi Prism->Windows Forms Application.

Adding a reference

To select the class library TwinCAT.ADS select the command Add Reference... from the Project menu. The Add Reference dialog opens.

In this dialog should select the Browse tab and navigate to file TwinCAT.ADS.dll. Confirm the selected dll with Add and OK. By default the TwinCAT.ADS component is located in folder ..TwinCAT\Ads Api\.NET\ .

Add namespace

The project manager offers an option for checking whether the component was added to the reference list.

All class library types belong to the TwinCAT.ADS namespace. This namespace must be added in the uses section:

namespace AdsNETSample;'
interface

uses
  System.Drawing,
  System.Collections,
  System.Collections.Generic,
  System.Windows.Forms,
  System.ComponentModel,
  System.IO,
  TwinCAT.Ads;

This enables access to the data types defined in TwinCAT.ADS without having to specify the namespace repeatedly. The TcAdsClient class is the core of the TwinCAT.ADS class library and enables the user to communicate with an ADS device. The first step is to create an instance of the TcAdsClient class. Then make use of the Connect method to establish a connection with the ADS device.

Establishing a connection to an ADS device:

type

//...

  MainForm = partial class(System.Windows.Forms.Form)
  private
    tcAds : TcAdsClient;
    method MainForm_Load(sender: System.Object; e: System.EventArgs);
    method MainForm_FormClosing(sender: System.Object; e: System.Windows.Forms.FormClosingEventArgs);
    method ReadVar_Click(sender: System.Object; e: System.EventArgs);
    method WriteVar_Click(sender: System.Object; e: System.EventArgs);
  protected
    method Dispose(disposing: Boolean); override;
  public
    constructor;
  end;

implementation
//...
ethod MainForm.MainForm_Load(sender: System.Object; e: System.EventArgs);
begin
    tcAds := new TcAdsClient();
    tcAds.Connect('1.2.3.4.1.1', 801);
end;

Reading a PLC variable:

The data (4 bytes integer in the flag area) are transferred with the aid of the AdsStream class, which is derived from System.IO.MemoryStream. The class System.IO.BinaryWriter can be used to write data to the stream, the class System.IO.BinaryReader can be used to read data from the stream.

method MainForm.ReadVar_Click(sender: System.Object; e: System.EventArgs);
begin
    // creates a stream with a length of 4 byte
    var ds := new AdsStream(4);
    var br := new BinaryReader(ds);
    // reads a DINT from PLC
    tcAds.Read($4020,0,ds);
    ds.Position := 0;
    textBox1.Text := br.ReadInt32().ToString();
end;

Writing a PLC variable:

method MainForm.WriteVar_Click(sender: System.Object; e: System.EventArgs);
begin
    // creates a stream with a length of 4 byte
    var ds := new AdsStream(4);
    var bw := new BinaryWriter(ds);
    ds.Position := 0;
    bw.Write( Int32(100));
    // writes a DINT to PLC
    tcAds.Write($4020,0,ds);
end;

Separating a connection to an ADS device:

method MainForm.MainForm_FormClosing(sender: System.Object; e: System.Windows.Forms.FormClosingEventArgs);
begin
    tcAds.Dispose();
end;

PLC program:

PROGRAM MAIN
VAR
    test AT%MD0 : DINT;
END_VAR
test := test + 1;