TC Automation Interface

Download as pdf or txt
Download as pdf or txt
You are on page 1of 475

BECKHOFF

Automation: Foreword
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.
TwinCAT System Manager: Automation Interface
Product description
The TwinCAT Automation Interface enables the automatic creation and
manipulation of TwinCAT XAE configurations via programming/scripting
code. The automation of a TwinCAT configuration is available through so-
called automation interfaces which can be accessed from all COM-
capable programming languages (e.g. C++ or .NET) and also from
dynamic script languages - e.g. Windows PowerShell, IronPython or even
legacy VBscript.

TwinCAT Automation Interface enables an efficient engineering process


by giving customers the possibility to automate the configuration of a full
TwinCAT project configuration.
Traditionally, a machine configuration had to be manually adapted to
each new project or had even to be created from scratch, which could not
only involve a tremendous amount of engineering time and therefore
costs but is also error-prone because of human mistakes.
With TwinCAT Automation Interface, the process of adapting TwinCAT
configurations to a new environment or even create new TwinCAT
configurations from scratch can be automated according to the
customers needs.

Readers should continue with the following topics:


Basics
Topic Description
Creating/Loading Describes how to create or open a
TwinCAT XAE TwinCAT configuration
configurations
Navigating TwinCAT Describes how to navigate through a
XAE TwinCAT configuration
Custom tree item Describes how to access custom
parameters parameters of an item. This is
important to access configuration
parameters of a TwinCAT tree item.

Best practice
Topic Description
Creating and Describes how to create EtherCAT
handling EtherCAT devices and connect them to an
devices EtherCAT topology
From offline to Describes how add address information
online configuration to an offline created configuration

Additionally, this documentation also includes a full API reference of all
interfaces. The How to and Sample sections offer a free composition of
script code fragments, configuration steps and demo projects. They also
contain an unsorted and growing list of "real-world" samples.

Automation Interface
Version overview
The following table gives an overview about the available
features of the Automation Interface related to TwinCAT 2.11,
TwinCAT 3.0, TwinCAT 3.1 and a look-out to future TwinCAT versions
which may be
subject to change.

TwinCAT TwinCAT TwinCAT Future


Feature 2.11 3.0 3.1 versions
General settings
Importing configuration
templates
TwinCAT System Service
handling
(Run-/Config-mode)

Load/Save/Create/Activate
configurations

Support for remote


TwinCAT
targets

Configuring tasks with


process image
Configuring tasks without - -
process
image

Multicore support for tasks -


Handling of TwinCAT - - -
licenses
Route
management

Adding/Removing ADS
routes
Broadcast Search

I/O
Scanning for online
devices
Adding/removing devices,
boxes and terminals
Parameterization of
devices, boxes and
terminals
EtherCAT topologies
Network variables

PLC
Mapping of variables, e.g.
with I/Os
or axes

Adding/removing PLC
projects

Adding/removing PLC - -
POUs, DUTs,
GVLs

Getting/setting PLC code - -


of
POUs, DUTs, GVLs
Adding/removing PLC - -
libraries

Adding/removing PLC - -
placeholders
Adding/removing PLC - -
repositories

Adding/removing PLC - -
libaries to
repositories

Saving PLC projects as a - -


PLC
library

Compiler and error output - -


handling

PLCopen XML - -
import/export
Programing language: - - 2 2
Structured
Text (ST)

Programing language: - - 1 1
Sequential
function chart (SFC)

C++
Adding/Removing C++ - - -
project templates
Compiler and error output - - -
handling

Motion
Adding/Removing NC- - -
Tasks
Adding/Removing axes - -
Parameterization of axes - - 3 3
settings
Mapping of variables, e.g. - -
with PLC

TcCOM modules
Adding/Removing TcCOM - - -
modules

Parameterization of - - -
TcCOM modules

Measurement
Adding/Removing - - -
TwinCAT Measurement
projects

Adding/Removing charts - - -
Adding/Removing axes - - -
Adding/Removing - - -
channels
Parameterization of - - -
charts, axes and
channels

Starting/Stopping records - - -

Notes
1 possibility to implement via PLCopen
XML

2 possibility to implement
source code either in clear-text or PLCopen XML

3 with limitations. Some


settings are stored in a binary format and cannot be edited.


Automation Interface
Frequently Asked Questions
What is TwinCAT Automation Interface?

TwinCAT Automation Interface is an interface to access the


configuration of TwinCAT from an external application. This enables
customers to automate the configuration of TwinCAT.
Can I create an offline TwinCAT configuration (without
any attached devices)?

Yes. You can create the TwinCAT configuration offline by manually


attaching (without "Scan Devices) all devices and then providing
online values, e.g. addresses, later after all devices have been
attached. Please see our samples page for more information. There
is also an How-To sample which shows you how to provide
addressing information for pre-configured I/O devices.
Which programming and scripting languages are
supported?

Every programming or scripting language that supports the COM


object model is supported. Please see our system requirements
page for more information.
Which TwinCAT features are accessible via Automation
Interface?

Please see our version overview page for more information about
which TwinCAT features are accessible via Automation Interface.
What if I don't find an appropriate programming method
or property for a specific setting?

If you don't find an appropriate Automation Interface method or


property for a specific setting, you may use the Import/Export feature
of TwinCAT to read/write this setting. Please refer to our article about
custom tree item parameters for more information.
Can I automate the configuration of TwinCAT PLC?

Yes. This feature will be available with TwinCAT 3.1. Please refer to
our version overview page for more information.
Can I execute Automation Interface code on TwinCAT
XAR (Runtime-only) computers?

No. To execute Automation Interface code, TwinCAT XAE


(Engineering) is needed, because Automation Interface directly
accesses the Visual Studio COM object to communicate with the
TwinCAT configuration. However, you can use a TwinCAT XAE
computer to remotely connect to a TwinCAT runtime and configure it.
When should I use ADS and when Automation Interface?

This is a question which cannot be answered easily because it


heavily depends on what you would like to achieve. TwinCAT
Automation Interface has been designed primarily to help customers
to automate the configuration of TwinCAT. If you want to cyclically
read/write values to IOs or PLC variables, our ADS APIs are
probably better suited.
Do I need to modify my Automation Interface code if I
switch languages in TwinCAT XAE, e.g. from English to
German?

All TwinCAT XAE items that are language dependent (Devices,


Boxes, Axes, Channels, ...) can either be accessed via the currently
set XAE language or via their english name. For example, if the XAE
language is changed from English to German, the term "Channel"
will be displayed in XAE as "Kanal" but is still available under the
name "Channel" via Automation Interface. To be fully compatible, we
recommend to build your Automation Interface code based on
english terminology.
Please note: This feature comes with TwinCAT 3.x only! Systems
based on TwinCAT 2.x are not language independent!
I'm a machine builder and use a TwinCAT configuration
template for all machine types and only enable/disable
certain I/Os. Can I also do that with Automation Interface?

Yes. There is an How-To sample which shows you exactly how to do


that.
Can I also create ADS routes or execute a Broadcast
Search?

Yes. Please see our samples and How-To pages for more
information.

Automation Interface
System requirements
The following chapter lists all hardware and software
requirements for the TwinCAT Automation Interface and gives some
recommendations for programming and scripting languages.
Hardware and Software
TwinCAT Automation Interface will be automatically installed by TwinCAT
setup. Therefore it needs the same hardware and software system
requirements as TwinCAT System Manager / TwinCAT 3 XAE
(Engineering). When using the Automation Interface to configure a
remote TwinCAT device, it is important that the remote version of
TwinCAT equals or is higher than on the engineering computer.

Please note that you can execute Automation Interface scripts on 32-bit
and 64-bit platforms, however you need to make sure that your
program/script has been compiled for and runs in 32-bit mode.
Recommended programming languages
The following programming languages are recommended to use with
TwinCAT Automation Interface:
.NET languages, such as C#, VB.NET, F#

Please note: Although C++ implementations will also work, we highly


recommend using one of the languages above because of their easy and
straight-forward programming concepts regarding COM. Most of the
sample code in this documentation is based on C#.
Recommended scripting languages
Although every scripting language with COM support may be used to
access TwinCAT Automation Interface, the following scripting languages
are recommended:
Windows PowerShell (for more detailed information, please
visit MSDN Windows PowerShell)
IronPython (for more detailed information, please visit
IronPython)

Most of the sample code in this documentation is based on one of these


scripting languages.
Automation Interface
Installation
All files needed for the TwinCAT Automation Interface will be installed
automatically during TwinCAT setup. As mentioned in the introduction,
the Automation Interface communicates with TwinCAT via COM. All
needed COM objects are configured automatically so that COM-capable
programming and scripting languages can access these objects.

Using the Automation Interface within a .NET application
(C#, VB.NET, ...)
To access the Automation interface from a .NET application, you need to
add a reference to the corresponding COM object Beckhoff TwinCAT
XAE Base (depending on your TwinCAT version, see table below) within
the Visual Studio project.

After the reference has been added, you can access the COM object via
the namespace TCatSysManagerLib.
Please proceed with the article Accessing TwinCAT configuration which
explains all further steps in more detail.

Using the Automation Interface within scripting languages
TwinCAT Automation Interface can also be used with COM-capable
scripting languages, for example Windows PowerShell or IronPython. As
scripting languages are being interpreted at runtime and not compiled,
they always have access to all currently registered COM objects in the
operating system. Therefore a reference is not needed.
Please proceed with the article Accessing TwinCAT configuration which
explains all further steps in more detail.

Type library versions
During the TwinCAT product lifecycle, the type library mentioned above
may be delivered in different versions because of added functionalities
and/or big TwinCAT versions steps. The table below gives an overview
about all different type library versions.

Type
library
Type library name version TwinCAT version
Beckhoff 1.1 TwinCAT 2.11
TCatSysManager
1.1 Type Library
Beckhoff TwinCAT 2.0 TwinCAT 3.0
XAE Base 2.0 Type
Library
Beckhoff TwinCAT 2.1 TwinCAT 3.1
XAE Base 2.1 Type
Library

Automation Interface
Accessing TwinCAT configuration
This chapter describes how to create and access a TwinCAT
configuration project via Automation interface. The objective of this
creation process is to get access to a TwinCAT System Manager
configuration.
The following code snippets demonstrate how to get access to TwinCAT
and create a System Manager configuration.

Sample (C#):

TcSysManager systemManager = new TcSysManager();


systemManager.NewConfiguration();
//...Creating configuration...
systemManager.SaveConfiguration("C:\Sample.tsm");

Sample (Powershell):

$systemManager = new-object -comobject TCatSysManager.TcSysManager


$systemManager.NewConfiguration()
//...Creating configuration...
$systemManager.SaveConfiguration("C:\Sample.tsm")

Sample (IronPython):
sysManType = System.Type.GetTypeFromProgID("TCatSysManager.TcSysManager")
systemManager = System.Activator.CreateInstance(sysManType)
systemManager.NewConfiguration()
systemManager.SaveConfiguration("C:\Sample.tsm")

Sample (C++):
#include "stdafx.h"
#include <atlbase.h>
#import "C:\TwinCAT\Io\TCatSysManager.tlb"

int _tmain(int argc, _TCHAR* argv[])


{
HRESULT hr = CoInitialize(NULL);

if (SUCCEEDED(hr))
{
TCatSysManagerLib::ITcSysManager3Ptr pTCatSysMan;
HRESULT hr = pTCatSysMan.CreateInstance("TCatSysManager.TcSysManager.1");

CComBSTR bstrFile(L"C:\\Untitled.tsm");

hr = pTCatSysMan->OpenConfiguration(bstrFile.Detach());

if(SUCCEEDED(hr))
{
hr = pTCatSysMan->ActivateConfiguration();

if(SUCCEEDED(hr))
{
hr = pTCatSysMan->StartRestartTwinCAT();
}
}

if (FAILED(hr))
{
CComPtr<IErrorInfo> pErrorInfo;
hr = ::GetErrorInfo(0,&pErrorInfo);

if (hr == S_OK)
{
CComBSTR pbstrError(L"");
hr = pErrorInfo->GetDescription(&pbstrError);
wprintf((LPWSTR)pbstrError);
}
}
}

CoUninitialize();
return 0;
}
Automation Interface
Browsing TwinCAT configuration
In a separate article, we have already shown you how to access
TwinCAT via the Visual Studio Automation Model. This reference to
TwinCAT is being represented by an object of type ITcSysManager. From
this point on we would like to discuss now how you can navigate through
the TwinCAT configuration.
General information
It is important to understand that all information in TwinCAT is ordered in
a tree-like structure. In Automation Interface, every tree node, and
therefore every element of a TwinCAT configuration, is represented by
the interface ITcSmTreeItem.
Navigating the TwinCAT data model can be done in different ways,
depending on the sort of information that should be retrieved.
Lookup-Methods are searching for specific tree items via
specified search criterias, e.g. the path to a tree item
Iterators or browsing functions iterate over a set of retrieved
tree items

Both methods are now being discussed in the following article.



LookupMethods
The Lookup methods are always working on the whole data model
(unfiltered).
ITcSysManager::LookupTreeItem determines a tree item with
the specified absolute path name.
ITcSysManager3::LookupTreeItemById determines a tree item
with the specified item type and item Id.
ITcSmTreeItem::LookupChild determines a tree item within a
subtree specifed by a relative path name.

Each tree item in TwinCAT can be identified by its unique pathname. The
pathname of a tree item is based on the hierarchical order of its parent
item (its name) and its own name, separated by circumflex accents ('^').
To shorten the pathnames and to avoid language dependencies, the top
level tree items have special abbreviations which are listed in
ITcSysManager::LookupTreeItem.

Iterators
At the moment, three different types of iteration functions are supported:
Browsing all tree items (unfiltered)
Browsing main tree items
Browsing variables / symbols only

Browsing all tree items (unfiltered)


To browse all tree items in an unfiltered way, the property
ITcSmTreeItem::_NewEnum may be used. _NewEnum iterates over all
subnodes of the currently referenced ITcSmTreeItem. This (COM-)
property is used by many Programming and Script languages that
support the COM Enumerator model (e.g. .NET languages, VB6 or script
languages) by a 'foreach' statement. For non-supporting languages like
C++ the foreach loop must be implemented manually by using the
IEnumVariant interface.
We recommend to use this way to iterate through child nodes.
Sample (C#):

ITcSmTreeItem parent = sysMan.LookupTreeItem("TIID^Device1^EK1100");


foreach(ITcSmTreeItem child in parent)
{
Console.WriteLine(child.Name);
}
Sample (C++):
...
#import "C:\TwinCAT3\Components\Base\TCatSysManager.tlb" // Imports the System Mana
// Usage of automatically generated Auto-Pointers (see MSDN documentation of #import sta
...

void CSysManDialog::IterateCollection(TCatSysManagerLib::ITcSmTreeItemPtr parentPtr)


{
IEnumVARIANTPtr spEnum = parentPtr->_NewEnum;
ULONG nReturned = 0;
VARIANT variant[1] = {0};
HRESULT hr = E_UNEXPECTED;

do
{
hr = spEnum->Next(1, &variant[0], &nReturned);
if(FAILED(hr))
break;
for(ULONG i = 0; i < nReturned; ++i)
{
IDispatchPtr dispatchPtr;
IDispatch* pDispatch;
TCatSysManagerLib::ITcSmTreeItemPtr childPtr;
HRESULT hr;
if(variant[0].vt == VT_DISPATCH)
{
TCatSysManagerLib::ITcSmTreeItem* pChild = 0;
dispatchPtr.Attach((variant[0].pdispVal));
hr = dispatchPtr.QueryInterface(__uuidof(TCatSysManagerLib::ITcSm
childPtr.Attach(pChild);
_bstr_t strName = pChild->GetName();
}
}
}
while(hr != S_FALSE); // S_FALSE indicates end of collection
}
Sample (IronPython):

parent = systemManager.LookupTreeItem("TIRC");
for child in parent : print child.Name
Sample (PowerShell):

$systemItem = $systemManager.LookupTreeItem("TIRC")
foreach($child in $systemItem)
{
write-host$child.Name
}

Browsing Main Tree Items (Filtered)


For browsing only the main childs of the current tree item use the
ITcSmTreeItem::ChildCount and ITcSmTreeItem:Child(n) pair of
properties. These methods only work on the direct childs (non-recursive).

Browsing Variables / Symbols only


To Browse the Variables / Symbols use the ITcSmTreeItem::VarCount(x) ,
ITcSmTreeItem::Var(x,n) pair of properties. A selection of the variable
type (input variables or output variables) can be done by parameter.
Automation Interface
Custom TreeItem Parameters
The ITcSmTreeItem interface is supported by every TwinCAT tree item
and has a very generic character. To support the specification of all the
devices, boxes and terminals, together with many other different types of
tree items, all custom parameters of a tree item are accessible via the
XML representation of the tree item. This XML-String can be accessed by
the method ITcSmTreeItem::ProduceXml and its counterpart
ITcSmTreeItem::ConsumeXml. This function pair has the same
functionality as the "Export XML Description ..." and "Import XML
Description ..." commands from the main menu of the TwinCAT IDE (see
snapshot below).

With this Import/Export functionset, good parts of any script or


automation code can be tested and tailored conveniently, before it is
developed within the coding language - simply by the process of
exporting tree item data, changing its content and re-importing it.
Best practice is to export the XML content first, change its content,
importing it within the IDE and then, if everything goes successfully,
package it into the programming/script code for handling it via the
methods ProduceXml and ConsumeXml.
Using this workflow ensures that all changed properties and methods are
valid (the Xml stream is self-documenting) and in which way they can be
used (for example as Read-Only-Property, as Read-Write-Property or as
a method trigger).

Reading Properties
In this example, the Network Adapter setting of an TwinCAT configuration
should be detected (here an CX9001): Here the Adapter Settings are
available within the DeviceDef specific part of the XML Data.

The Adapter's MAC-Address can be found at the XmlPath


"TreeItem/DeviceDef/AddressInfo/Pnp/DeviceData". With this information
the script code that reads this information can be written:
Code Snippet (IronPython) for TwinCAT 3:
import System
import clr
import System.IO;

clr.AddReference('System.Xml')

from System.Xml import XmlDocument, XmlTextReader


from System.IO import File,FileInfo, Directory, DirectoryInfo
#create Visual Studio
t = System.Type.GetTypeFromProgID("VisualStudio.DTE.10.0");
dte = System.Activator.CreateInstance(t)
solution = dte.Solution

if (Directory.Exists(r"C:\SolutionFolder")):
Directory.Delete(r"C:\SolutionFolder",True)

Directory.CreateDirectory(r"C:\SolutionFolder")
Directory.CreateDirectory(r"C:\SolutionFolder\MySolution1");

solution.Create(r"C:\SolutionFolder","MySolution1")
solution.SaveAs(r"C:\SolutionFolder\MySolution1\MySolution1.sln")

template = r"C:\TwinCAT3\Components\Base\PrjTemplate\TwinCAT Project.tsp"


project = solution.AddFromTemplate(template,"C:\SolutionFolder\MySolution1"

#Get the Specific System Manager Interface


sysMan = project.Object

sysMan = project.Object
ioDevices = sysMan.LookupTreeItem("TIID")
treeItem = ioDevices.CreateChild("RTEthernet",66,"",None) #Adding the RT-Ethernet Devic
xml = treeItem.ProduceXml()

xmlDoc = XmlDocument()
xmlDoc.LoadXml(xml)
test = xmlDoc.SelectSingleNode("TreeItem/DeviceDef/AddressInfo/Pnp/DeviceData"
deviceDataString = test.InnerText;
print deviceDataString # Print the MacID of the Device (contains 000105015c2a here)

Writing Properties
In this example, the Adapter settings should also be written to the
configuration. Shortening the original XML to the following form and
changing the Adapter parameters, will activate the new parameter set
within the configuration (as long the parameters are correct). To test the
settings before writing the script code, the "Import Xml Descriptions"
Menu function is very helpful.

After the parameter change has been tested from within TwinCAT XAE, it
is easy to write the script code that creates the valid parameterset and
feeds the ITcTreeItem via the method ITcTreeItem::ConsumeXml(xml), for
example:

xml = '<TreeItem> \
<DeviceDef>\
<AddressInfo>\
<Pnp>\
<DeviceDesc>TCIXPNPE2</DeviceDesc>\
<DeviceName>TCIXPNPE2</DeviceName>\
<DeviceData>00010501958f</DeviceData>\
</Pnp>\
</AddressInfo>\
</DeviceDef>\
</TreeItem>'
device = sysMan.LookupTreeItem("TIID^RTEthernet")
device.ConsumeXml(xml)

Calling Methods
In some cases, specific methods should be triggered, for example the
ScanBoxes functionality from TwinCAT XAE, which scans the device for
all connected boxes. Looking at the XML-example from the above
chapter Reading-Properties, the XML-Content contains a flag
<ScanBoxes>0</ScanBoxes>. This sort of XmlElement is called a
"Method Trigger" and should indicate that the "ScanBoxes" functionality
is currently not triggered. Consuming the following XML-Code at the
device item will start a "ScanBoxes" and insert all found Boxes /
Terminals into the configuration.
Xml Data:

Code Snippet (IronPython):

xml = '<TreeItem> \
<DeviceDef>\
<ScanBoxes>1</ScanBoxes>\
</DeviceDef>\
</TreeItem>'
device = sysMan.LookupTreeItem("TIID^RTEthernet")
device.ConsumeXml(xml)


Automation Interface
Building an EtherCAT topology
This article explains how to build an EtherCAT topology via TwinCAT
Automation Interface. It consists of the following topics:
General information
Creating an EtherCAT device
Creating EtherCAT boxes and insert into topology
Creating EtherCAT terminals and insert into topology
Exceptions to the ItemSubType 9099
Changing the "Previous Port" of an EtherCAT terminal
Adding EtherCAT slaves to a HotConnect group

All of these topics cover the case of an offline configuration, which


means the real addresses of all devices ar not know at the time of config
creation. The last chapter of this article therefore also explains how to
Activate the configuration

General information
This documentation should give you an overview avout how to create and
handle EtherCAT devices and their corresponding topology via
Automation Interface. For an in-depth understanding about how
EtherCAT works and how it is generally integrated in TwinCAT
SystemManager/XAE, please consult the EtherCAT System
Documentation and the corresponding chapter about EtherCAT
configuration in TwinCAT. EtherCAT boxes and terminals, which are
connected to an EtherCAT Master, share a common way of creation,
which is explained in a separate article about E-Bus sub types.

Creating an EtherCAT device


The first step in creating a TwinCAT EtherCAT configuration is to create
an EtherCAT device, which may involve either to create an EtherCAT
Master, Slave or Automation Protocol (e.g. to use network variables, as
covered in a separate article). To create an EtherCAT Master/Slave,
simply make use of the ITcSmTreeItem::CreateChild() method with the
corresponding parameter for SubType (EtherCAT Master = 111,
EtherCAT Slave = 130).


EtherCAT Master - Code Snippet (C#)

ITcSmTreeItem devices = systemManager.LookupTreeItem("TIID");


ethercatMaster = devices.CreateChild("EtherCAT Master", 111, null, null);

EtherCAT Slave - Code Snippet (C#)

ITcSmTreeItem devices = systemManager.LookupTreeItem("TIID");


ethercatSlave = devices.CreateChild("EtherCAT Slave", 130, null, null);

Creating EtherCAT boxes


The second step involves creating EtherCAT boxes, for example an
EK1100 EtherCAT Coupler. As the article about E-Bus SubTypes
explains, every child item (there a few exceptions - see below) of an
EtherCAT Master uses a common SubType (9099) and will be identified
via the Product Revision, which needs to be used in the vInfo parameter
of the ITcSmTreeItem::CreateChild() method.
Code Snippet (C#)

ITcSmTreeItem ethercatMaster = systemManager.LookupTreeItem("TIID^EtherCAT Master"


ethercatMaster.CreateChild("EK1100", 9099, "", "EK1100-0000-0017");

Please note: In addition to the full product revision, you can also use a
"wildcard". If you only specify "EK1100" as vInfo, Automation Interface
will automatically detect and use the newest revision number. Example:

ITcSmTreeItem ethercatMaster = systemManager.LookupTreeItem("TIID^EtherCAT Master"


ethercatMaster.CreateChild("EK1100", 9099, "", "EK1100");

Creating EtherCAT terminals and insert into topology


The creation of EtherCAT terminals is based on the same concepts as
EtherCAT boxes. Every terminal also shares a common SubType and will
be identified via the Product Revision, which needs to be used in the
vInfo parameter of the ITcSmTreeItem::CreateChild() method. The
parameter bstrBefore lets you choose the position on which the terminal
should be inserted into the configuration.
Code Snippet (C#)
ITcSmTreeItem ek1100 = systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT)^EK
ek1100.CreateChild("Term 4 (EL2004)", 9099, "Term 3 (EL2004)", "EL2004-0000-0017");

Please note: Should you have trouble using the bstrBefore parameter,
please try to insert the terminal on a "device-level", for example:

ITcSmTreeItem device= systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT)");


device.CreateChild("Term 4 (EL2004)", 9099, "Term 3 (EL2004)", "EL2004-0000-0017");
The new terminal will then be inserted before "Term 3 (EL2004)" under
the last inserted EtherCAT box.
Please note: In addition to the full product revision, you can also use a
"wildcard". If you only specify "EL2004" as vInfo, Automation Interface
will automatically detect and use the newest revision number. Example:

ITcSmTreeItem ek1100 = systemManager.LookupTreeItem("TIID^Device 1 (EtherCAT)^EK


ek1100.CreateChild("Term 4 (EL2004)", 9099, "Term 3 (EL2004)", "EL2004");

Exceptions to the ItemSubType 9099


There are a few exceptions to the ItemSubType 9099, e.g. the RS232
terminals EP6002 (ItemSubType 9101) and EL600X (ItemSubType
9101). The following table gives an overview about all exceptions and
their corresponding ItemSubType.

I/O ItemSubType Description


EP6002 9101 RS232 / RS422 /
RS485 interface
terminal
EL6001 9101 RS232 interface
terminal
EL6002 9101 RS232 interface
terminal (2-Channel)
EL6021 9103 RS422 / RS485
interface terminal
EL6022 9103 RS422 / RS485
interface terminal (2-
Channel)

Changing the "Previous Port" of an EtherCAT terminal


The Previous Port of an EtherCAT terminal determines the position of the
terminal inside the EtherCAT topology.

In TwinCAT XAE, the DropDown box automatically includes all available


previous ports. To configure this setting via Automation Interface, you can
make use of the ITcSmTreeItem::ProduceXml() and
ITcSmTreeItem::ConsumeXml() methods to modify the XML description
of the corresponding EtherCAT terminal. This XML description therefore
includes one or more XML nodes <PreviousPort>, where its attribute
"Selected=1" determines, which previous port has been currently
selected. Each previous port device is identified by its physical address.
Example (XML description)
<TreeItem>
...
<EtherCAT>
...
<Slave>
...
<PreviousPort Selected="1">
<Port>B</Port>
<PhysAddr>1045</PhysAddr>
</PreviousPort>
<PreviousPort>
<Port>B</Port>
<PhysAddr>1023</PhysAddr>
</PreviousPort>
...
</Slave>
...
<EtherCAT>
...
</TreeItem>
If you want to change the Previous port you need to know the
<PhysAddr> of the desired device, which can also be determined via its
XML description.

Adding EtherCAT slaves to a HotConnect group


EtherCAT HotConnect allows pre-configured sections to be removed
from or added to the data traffic before the start or during operation of the
system. For more information about EtherCAT HotConnect please read
our EtherCAT System documentation.
In TwinCAT XAE, an EtherCAT slave can be added to a HotConnect
group by clicking the corresponding option in the context menu of the
device.
In TwinCAT Automation Interface, the same can be achieved by
consuming the following XML structure on the EtherCAT slave:
Example (XML description):

<TreeItem>
<EtherCAT>
<Slave>
<HotConnect>
<GroupName>Term 1 (EK1101)</GroupName>
<GroupMemberCnt>4</GroupMemberCnt>
<IdentifyCmd>
<Comment>read hot connect identity</Comment>
<Requires>cycle</Requires>
<Cmd>1</Cmd>
<Adp>0</Adp>
<Ado>4096</Ado>
<DataLength>2</DataLength>
<Cnt>1</Cnt>
<Retries>3</Retries>
<Validate>
<Data>0000</Data>
<Timeout>5000</Timeout>
</Validate>
</IdentifyCmd>
</HotConnect>
</Slave>
</EtherCAT>
</TreeItem>
Please note:
The <GroupMemberCnt> tag needs to specify the exact
amount of terminals plus the device itself

Activate the EtherCAT configuration


To activate a created TwinCAT configuration via Automation Interface, the
ITcSysManager::ActivateConfiguration() method may be used. However,
the previous chapters only explained how to create an offline
configuration, which means that every device created does not have real
addresses, e.g. the EtherCAT Master has not been linked to a physical
network interface card yet. Before activating the configuration you
therefore need to configure each device with online addresses. To
determine the real addresses, you can run a ScanDevices on the online
system, determine the real addresses via the XML description
(ITcSmTreeItem::ProduceXml()) and then import the address information
via ITcSmTreeItem::ConsumeXml() into the created (offline)
configuration. There are two HowTo samples which help you exactly with
this kind of configuration:
Scan Devices via Automation Interface




Automation Interface
From offline to online configurations
This article explains how to convert a TwinCAT configuration, which has
been created 'offline', via TwinCAT Automation Interface to an online
configuration. The term "offline" means that no physical I/Os are present
at the time of configuration creation and therefore the real address
information is not available, e.g. for an EtherCAT Master . The following
topics are part of this article:
General information
Creating an offline configuration
Switching to an online configuration

General information
When creating a TwinCAT configuration, there are two common
scenarios:
Scenario 1: this scenario is based on the real physical device,
on which the TwinCAT configuration should run later.
Therefore, all I/Os are online and already available and
attached to the device.
Scenario 2: this scenario could involve to create the
configuration offline (that means without any I/Os attached to
the engineering device) and later switch to an online
configuration when the I/Os are available. This is the scenario
which will be the primary focus of this article.

Both scenarios are possible via TwinCAT Automation Interface. However,


as scenario 2 lacks some important information about some of the I/Os,
e.g. their physical addresses, this scenario could be slightly more
complex because you need to hand in the required (address) information
later.
The familiar TwinCAT XAE functionality "Scan Devices" plays a
significant role in this use-case because it scans for all available I/O
devices and automatically attaches them to the configuration - together
with all needed additional information, e.g. physical addresses.

On a physical controller, this functionality can also be called via


Automation Interface and then returns an XML representation of all found
I/O devices including their corresponding address information.
When a TwinCAT configuration should be activated on the controller, the
required address information needs to be set for all I/O devices that are
part of the configuration. This can be done by calling the "Scan Devices"
functionality via Automation Interface and setting the address information
for the I/O devices in the configuration. This will be explained in more
detail now.

Creating an offline configuration


There are several articles which explain how to create an offline TwinCAT
configuration. Please refer to our Product Description page to get an
overview.

Switching to an online configuration


If you finally have created a TwinCAT configuration that should now be
activated on the physical controller, the following steps need to be taken
to ensure that all required address information is available before
downloading the configuration:
Step 1 [optional]: Connecting to the target device
Step 2: Scanning the device for available I/Os
Step 3: Iterating through XML and configuring address
information of I/Os
Step 4: Activating the configuration

Of course, you can also always create an online configuration directly by


using the ScanDevices functionality. There is an own sample which
shows you exactly how to do that.

Step 1 [optional]: Connecting to the target device
If the physical controller is not located on the same machine as the
Automation Interface code runs on, you can use the
ITcSysManager::SetTargetNetId() method to connect to the remote
device and then continue with the next steps.

Step 2: Scanning the device for available I/Os
The "Scan Devices" functionality mentioned above can be triggered via
Automation Interface by calling the ITcSmTreeItem::ProduceXml()
method on the I/O devices node.
Code Snippet (C#):
ITcSmTreeItem ioDevices = systemManager.LookupTreeItem("TIID");
string foundDevices = ioDevices.ProduceXml();

Step 3: Iterating through XML and configuring address information
of I/Os
In this example we want to update the address information of an
EtherCAT device which is already part of our offline configuration. The
ProduceXml() in step 2 has already returned the available I/O devices on
the system, which is now available in the variable 'foundDevices'. We will
identify the EtherCAT device in this XML via its item sub type (111) and
then update the address information of the EtherCAT Master in our
configuration.
Code Snippet (C#):
XmlDocument doc = new XmlDocument();
doc.LoadXml(foundDevices);
XmlNodeList devices = doc.SelectNodes("TreeItem/DeviceGrpDef/FoundDevices/Device");
foreach (XmlNode device in devices)
{
xmlNode typeNode = device.SelectSingleNode("ItemSubType");
int subType = int.Parse(typeNode.InnerText);
if (subType == 111)
{
XmlNode addressInfo = device.SelectSingleNode("AddressInfo");
ITcSmTreeItem deviceToUpdate = systemManager.LookupTreeItem("TIID^EtherCAT
string xmlAddress = string.Format("<TreeItem><DeviceDef>{0}</DeviceDef></TreeI
deviceToUpdate.ConsumeXml(xmlAddress);
}
}

Step 4: Activating the configuration
The last step only involves activating the configuration on the target
device. Simply use the ITcSysManager::ActivateConfiguration() method
to do that.
Code Snippet (C#):
sysManager.ActivateConfiguration();




Automation Interface
Reference
This chapter contains a documentation of all classes and methods of the
TwinCAT Automation Interface. The provided interfaces can be divided
into different "levels" in which the higher level interfaces represent the
primary interfaces and therefore the basic interaction with the Automation
Interface.
Please note that this differentiation comes only from a logical point-of-
view, to get a better understanding about which interfaces are most
important and which interfaces are of secondary importance.

Level 1 interfaces
As mentioned in our introduction, there are only two main interfaces
which are being used for navigating and referencing tree items in
TwinCAT configuration.

Available
Main class Description since
ITcSysManager Base class TwinCAT
2.11
to create and parameterize a
TwinCAT configuration

ITcSmTreeItem Represents a tree item within a TwinCAT


TwinCAT configuration 2.11


Level 2 interfaces
These interfaces are considered as "helper classes" which are always
used together with level 1 classes, for example to cast an ITcSmTreeItem
object into a more specific type of tree item, for example a POU
(ITcPlcPou) or a linked task (ITcTaskReference).

Available
Helper class Description since
ITcPlcLibraryManager Defines methods and TwinCAT
properties for PLC library 3.1
management
ITcPlcPou Defines methods and TwinCAT
properties to handle PLC 3.1
POUs
ITcPlcDeclaration Defines methods to TwinCAT
read/write the declaration 3.1
area of a PLC POU
ITcPlcImplementation Defines methods to TwinCAT
read/write the 3.1
implementation area of a
PLC POU
ITcPlcProject Defines methods and TwinCAT
properties regarding a PLC 3.1
project, e.g. setting the
project as a boot project

ITcPlcIECProject Defines methods needed to TwinCAT


import/export PLC projects 3.1
in PLCopen XML and
also install them as a PLC
library

ITcPlcTaskReference Defines methods and TwinCAT


properties to link the PLC 3.1
project to a task
ITcPlcLibrary Helper TwinCAT
3.1
class which represents a
single PLC library

ITcPlcLibraries Helper class which TwinCAT


represents a collection of 3.1
PLC libraries
ITCPlcReferences Helper class which TwinCAT
represents a collection of 3.1
ITcPlcLibRef objects (and
therefore references in a
PLC project)

ITcPlcLibRef Helper class which TwinCAT


represents a base class for 3.1
ITcPlcLibrary and
ITcPlcPlaceholderRef
objects

ITcPlcPlaceholderRef Helper class which TwinCAT


represents a single PLC 3.1
placeholder
ITcPlcLibRepository Helper class which TwinCAT
represents a single PLC 3.1
library repository
ITcPlcLibRepositories Helper class which TwinCAT
represents a collection of 3.1
PLC library repositories
Automation Interface
ITcSysManager
ITcSysManager is the main interface of the TwinCAT
Automation Interface. This interface allows basic operations to configure
TwinCAT 3
XAE and consists of several methods for doing so. Over the years, the
ITcSysManager interface has been extended with more functionalities to
give customers a better way to access all Automation Interface features.
However, due to restrictions in the COM object model, these features
needed to be added as separate interfaces to the Automation Interface.
Therefore, each time a new set of features was added, these features
were assembled in a new interface which was named ITcSysManagerX,
where X is a number which is incremented each time a new interface was
added. The following tables explain which methods are part of the
ITcSysManager interface and which have been added to each new
"feature-set"
interface.
Methods
ITcSysManager
methods
Description Available since
NewConfiguration Generates a TwinCAT 2.11
new
configuration
OpenConfiguration Loads a prior TwinCAT 2.11
created
configuration
file (WSM
file)

SaveConfiguration Saves the TwinCAT 2.11


configuration
in a file with
the given
name or with
the current
name

ActivateConfiguration Activates the TwinCAT 2.11


configuration
(same as
"Save To
Registry")

LookupTreeItem Looks up to a TwinCAT 2.11


configuration
item (item in
the tree)
by name and
returns a
ITcSmTreeItem
interface

StartRestartTwinCAT Starts or TwinCAT 2.11


Restarts the
TwinCAT
System
IsTwinCATStarted Evaluates if TwinCAT 2.11
the TwinCAT
System is
running
LinkVariables Links two TwinCAT 2.11
variables given
by names
UnlinkVariables Clears the link TwinCAT 2.11
between two
variables given
by names
or all links from
one variable.

ITcSysManager2
methods
Description Available since
SetTargetNetId Set the target TwinCAT 2.11
NetId of the
currently
opened
TwinCAT
configuration.

GetTargetNetId Gets the TwinCAT 2.11


target NetId
of the
currently
opened
TwinCAT
configuration.

GetLastErrorMessages Get the last TwinCAT 2.11


error
messages
which
occurred in
the TwinCAT
subsystem.

ITcSysManager3
methods
Description Available since
LookupTreeItemById Looks for a TwinCAT 2.11
configuration
tree item
with the
specifed
Item id.

ProduceMappingInfo Produces a TwinCAT 3.1


Xml-
Description
of the actual
configuration
mappings.

ClearMappingInfo Clears the TwinCAT 2.11


mapping
info.
Comments
The ITcSysManager interface contains two methods used for
navigating within TwinCAT XAE: ITcSysManager::LookupTreeItem and
ITcSysManager3::LookupTreeItemById.
A detailed explanation of browsing TwinCAT XAE can be found in the
chapter TreeItem Browsing Models.
Warning: The three methods ITcSysManager::NewConfiguration,
ITcSysManager::OpenConfiguration and
ITcsSysManager::SaveConfiguration are only available in Compatiblity
Mode.
Calling them in standard mode will throw an E_NOTSUPPORTED
Exception.
The ITcSysmanager and the ITcSmTreeItem interface allows full access
to a TwinCAT configuration. In the How to... section of this
documentation there is a long (but incomplete) list of samples how to
manipulate a TwinCAT configuration automatically.

Version information
Required TwinCAT version
This interface is supported in TwinCAT 2.11 and above
Automation Interface
ITcSysManager::NewConfiguration
The NewConfiguration() method generates a new TwinCAT configuration
file.
HRESULT NewConfiguration();
Return Values
S_OK
the function returns successfully.
E_ACCESSDENIED
the current document in the system manager instance is locked.
This occurs if at least one reference to the system managers object
or one of the tree elements are open.
E_FAIL
the function fails.
Comments
Warning: The three methods ITcSysManager::NewConfiguration,
ITcSysManager::OpenConfiguration and
ITcsSysManager::SaveConfiguration are only available in Compatiblity
Mode.
Calling them in standard mode will throw an E_NOTSUPPORTED
Exception.
Automation Interface
ITcSysManager::OpenConfiguration
The OpenConfiguration() methid loads a previously created TwinCAT
configuration
file.

HRESULT OpenConfiguration(
BSTR bstrFile
);
Parameters
bstrFile
[in, defaultvalue(L"")] contains the file path of the
configuration file that should be loaded or an empty string if a
new configuration should generated. The currently running
configuration of a
target device may also be read by using "CURRENTCONFIG".
Return Values
S_OK
function returns successfully.
E_ACCESSDENIED
the current document in the system manager instance is locked.
This occurs if at least one reference to the system managers object
or one of the tree elements are open.
E_INVALIDARG
the given file path does not refers to a valid configuration
file.
Comments
Warning: The three methods ITcSysManager::NewConfiguration,
ITcSysManager::OpenConfiguration and
ITcsSysManager::SaveConfiguration are only available in Compatiblity
Mode.
Calling them in standard mode will throw an E_NOTSUPPORTED
Exception.
Automation Interface
ITcSysManager::SaveConfiguration
The SaveConfiguration() method saves a TwinCAT configuration in a file
with the
specified name.

HRESULT SaveConfiguration(
BSTR bstrFile
);
Parameters
bstrFile
[in, defaultvalue(L"")] contains the file path in
that the configuration file that should be saved. If
bstrFile is an empty string, the current file name will be
used.
Return Values
S_OK
function returns successfully.
E_INVALIDARG
the given file path is invalid.
Comments
Warning: The three methods ITcSysManager::NewConfiguration,
ITcSysManager::OpenConfiguration and
ITcsSysManager::SaveConfiguration are only available in Compatiblity
Mode.
Calling them in standard mode will throw an E_NOTSUPPORTED
Exception.
Automation Interface
ITcSysManager::ActivateConfiguration
The ActivateConfiguration() method activates the TwinCAT configuration
(same as "Save To Registry"). A following start or restart of the TwinCAT
system must be performed to activate the configuration physically.
HRESULT ActivateConfiguration();
Return Values
S_OK
function returns successfully.
E_FAIL
the function fails.
Automation Interface
ITcSysManager::IsTwinCATStarted
The IsTwinCATStarted() method evaluates if the TwinCAT System is
running.
HRESULT IsTwinCATStarted(
VARIANT_BOOL*
pStarted
);
Parameters
pStarted
[out, retval] Points to the location of a boolean value that receives the
result.
Return Values
S_OK
function returns successfully.
Automation Interface
ITcSysManager::StartRestartTwinCAT
The StartRestartTwinCAT() method starts or restarts the TwinCAT
System. If TwinCAT is already started, the function performs a restart, if
TwinCAT is stopped it performs a start.
HRESULT StartRestartTwinCAT();
Return Values
S_OK
function returns successfully.
E_FAIL
TwinCAT could not be started.
Automation Interface
ITcSysManager::LinkVariables
The LinkVariables() method links two variables, which are specified by
their names. The two variables
represented by their tree path name will be linked. The path names
must have the same syntax as described in
ITcSysManager::LookupTreeItem.
The same shortcuts can be
used.

HRESULT LinkVariables(
BSTR bstrV1,
BSTR bstrV2,
long offs1,
long offs2,
long size
);
Parameters
bstrV1
[in] path name of the first variable. The full path name is
required and each branch must be separated by a circumflex accent
'^' or a tab.
bstrV2
[in] path name of the second variable. The full path name is
required and each branch must be separated by a circumflex accent
'^' or a tab.
offs1
[in, defaultvalue(0)] bit offset of the first variable (used if
the two variables have different sizes or not the whole variable
should be linked).
offs2
[in, defaultvalue(0)] bit offset of the second variable.
size
[in, defaultvalue(0)] bit count how many bits should linked. If
size is 0 the minimum of the variable size of variable one
and two is used.
Return Values
S_OK
function returns successfully.
TSM_E_ITEMNOTFOUND (0x98510001)
one or both of the path name(s) does not qualify an existing
tree item.
TSM_E_INVALIDITEMTYPE (0x98510002)
one or both of the tree item(s) is not a variable.
TSM_E_MISMATCHINGITEMS (0x98510004)
the two variables cannot linked together. May be you have tried
to link an output of one task with an output of another task or an
output of a task with an input of a device or to variables of the
same owner.
E_INVALIDARG
the values of offs1, offs2 and/or size does not fit to the variables.
Automation Interface
ITcSysManager::UnlinkVariables
The UnlinkVariables() method unlinks two variables, which are specified
by their names, or clears all links from the first variable if the name bstrV2
of the second variable is empty. The two variables represented by their
tree path name will be unlinked. The path names must have the same
syntax as described in ITcSysManager::LookupTreeItem.
The same shortcuts can be used.

HRESULT UnlinkVariables(
BSTR bstrV1,
BSTR bstrV2
);
Parameters
bstrV1
[in] path name of the first variable. The full path name is required and
each branch must be separated by a circumflex accent '^' or a tab.
bstrV2
[in, defaultvalue(L"")] path name of the second variable. If set the full
path name is required and each branch must be separated by a
circumflex accent '^' or a tab.
Return Values
S_OK
function returns successfully.
S_FALSE
the two variables have no link between them.
TSM_E_ITEMNOTFOUND (0x98510001)
one or both of the path name(s) does not qualify an existing tree
item.
TSM_E_INVALIDITEMTYPE (0x98510002)
one or both of the tree item(s) is not a variable.
TSM_E_CORRUPTEDLINK (0x98510005)
the two variables cannot unlinked.
Comments
If bstrV2 is an empty string the function clears all links of variable given
by bstrV1. If bstrV2 is not empty only an existing link between both
variables will be deleted.
Automation Interface
ITcSysManager2::GetTargetNetId
The GetTargetNetId() method returns the NetId of the current TwinCAT
system.
HRESULT GetTargetNetId();
Parameters
None
Return Values
STRING
returns target's NetId.
Automation Interface
ITcSysManager2::SetTargetNetId
The SetTargetNetId() method sets the NetId of the current TwinCAT
system.
HRESULT SetTargetNetId(
STRING netId
);
Parameters
netId
represents the target's NetId.
Return Values
S_OK
function returns successfully.
Automation Interface
ITcSysManager2::GetLastErrorMessages
The GetLastErrorMessages() metod returns the last error messages.
HRESULT GetLastErrorMessages();
Parameters
None
Return Values
STRING
Returns last error messages.
Automation Interface
ITcSysManager::LookupTreeItem
The LookupTreeItem() method returns a ITcTreeItem pointer of a tree
item given by it's full path name.
HRESULT LookupTreeItem(
BSTR bstrItem,
ITcSmTreeItem** pipItem
);
Parameters
bstrItem
[in] path name of the tree item looking for. The full path name is
required and each branch must be separated by a circumflex accent
'^' or a tab. A list of shortcuts for the main tree items is listed below.
pipItem
[out, retval] points to the location of a ITcSmTreeItem interface
pointer on return.
The interface pointer gives access to specific methods belonging to
the tree item.
Return Values
S_OK
function returns successfully.
TSM_E_ITEMNOTFOUND (0x98510001)
the path name does not qualify an existing tree item.
Shortcuts
The main tree items that exists in every configuration file can be
accessed via shortcuts. These shortcuts are language neutral and
require less memory:
"TIIC": shortcut for "I/O Configuration"
"TIID": shortcut for "I/O Configuration^I/O Devices" or "I/O
Configuration" TAB "I/O
Devices"

"TIRC": shortcut for "Real-Time Configuration"


"TIRR": shortcut for "Real-Time Configuration^Route Settings"
"TIRT": shortcut for "Real-Time Configuration^Additional Tasks" or "Real-Time
Configuration" TAB "Additional Tasks"
"TIRS": shortcut for "Real-Time Configuration^Real-Time Settings" or "Real-
Time Configuration" TAB "Real-Time
Settings"

"TIPC": shortcut for "PLC Configuration"


"TINC": shortcut for "NC Configuration"
"TICC": shortcut for "CNC Configuration"
"TIAC": shortcut for "CAM Configuration"
Sample (C++):
ITcSmTreeItem* ipItem;
BSTR bstrItem = L"TIID^Device 1 (C1220)";
if ( SUCCEEDED(spTsm->LookupTreeItem( bstrItem, &ipItem )) )
{
// do anything with ipItem

ipItem->Release();
}
Sample (VB):
Dim ipItem As ITcSmTreeItem
set ipItem = spTsm.LookupTreeItem("TIID^Device 1
(C1220)")
' do anything with ipItem
Both samples retrieves a ITcSmTreeItem pointer of the I/O
device with the name "Device 1 (C1220).
Comments
Automation Interface
ITcSysManager3::LookupTreeItemById
The LookupTreeItemById() method returns a ITcTreeItem pointer of a tree
item given by it's full path name.
HRESULT LookupTreeItemById(
long itemType,
long itemId,
ITcSmTreeItem** pipItem
);
Parameters
itemType
[in] Item type of the TreeItem to find.
itemId
[in] ID of the TreeItem
pipItem
[out, retval] points to the location of a ITcSmTreeItem interface
pointer on return.
The interface pointer gives access to specific methods belonging to
the tree item.
Return Values
S_OK
function returns successfully.
TSM_E_ITEMNOTFOUND (0x98510001)
the itemType itemId combination doesn't qualify a valid tree item.
Automation Interface
ITcSysManager3::ProduceMappingInfo
Generates an XML output that includes all currently configured
mappings,
e.g. between PLC and I/O.

HRESULT ProduceMappingInfo();
Parameters
none
Return Values
STRING: Returns XML structure that includes all configured mappings.
The
following snippet shows an example for this structure:
<VarLinks>

<OwnerA Name="TIID^Device 1 (EtherCAT)">

<OwnerB Name="TIXC^Untitled2^Untitled2_Obj1 (CModule1)">

<Link VarA="Term 1 (EK1100)^Term 3 (EL1008)^Channel 5^Input" VarB="Input

<Link VarA="Term 1 (EK1100)^Term 2 (EL2008)^Channel 4^Output" VarB="Outp

</OwnerB>

</OwnerA>

<OwnerA Name="TIPC^Untitled1^Untitled1 Instance">

<OwnerB Name="TIID^Device 1 (EtherCAT)^Term 1 (EK1100)^Term 2 (EL2008)">

<Link VarA="PlcTask Outputs^MAIN.bOutput1" VarB="Channel 1^Output" />

<Link VarA="PlcTask Outputs^MAIN.bOutput3" VarB="Channel 3^Output" />

<Link VarA="PlcTask Outputs^MAIN.bOutput2" VarB="Channel 2^Output" />

</OwnerB>

<OwnerB Name="TIID^Device 1 (EtherCAT)^Term 1 (EK1100)^Term 3 (EL1008)">

<Link VarA="PlcTask Inputs^MAIN.bInput1" VarB="Channel 1^Input" />

<Link VarA="PlcTask Inputs^MAIN.bInput3" VarB="Channel 3^Input" />


<Link VarA="PlcTask Inputs^MAIN.bInput2" VarB="Channel 2^Input" />

<Link VarA="PlcTask Inputs^MAIN.bInput4" VarB="Channel 4^Input" />

</OwnerB>

</OwnerA>

</VarLinks>

This example shows mappings between PLC <--> I/O and TcCOM (C++)
<-->
I/O.
Automation Interface
ITcSysManager3::ConsumeMappingInfo
Consumes an XML structure that includes the mapping information for a
project.
HRESULT ConsumeMappingInfo(BSTR bstrXml);
Parameters
bstrXml
[in]: String with XML structure. The XML mapping information can be
acquired by using ITcSysManager3::ProduceMappingInfo().
Automation Interface
ITcSmTreeItem
Each tree item in a TwinCAT XAE configuration
is represented by an instance of the ITcSmTreeItem interface, which
enables various
interactions with the tree item.
A tree item of this interface will be, for example, returned by
calling the ITCatSysManager::LookupTreeItem method, which is used to
navigate through the tree.
Properties
ITcSmTreeItem
Property Type Access Description
Name BSTR RW Name of tree item
Comment BSTR RW Comment.
Disabled BOOL RW Get/Set state of tree item which can
one of the following enum
values:
SMDS_NOT_DISABLED
(item is enabled)
SMDS_DISABLED (item
disabled)
SMDS_PARENT_DISABL
(read only, set if one of it
parent is disabled)

PathName BSTR R Path of


tree item in TwinCAT XAE. The
branches are separated by '^'. The
PathName
may be used in other method calls, e
ITCatSysManager::LookupTreeItem
Please note that this property unique
identifies a tree item in
TwinCAT XAE.

ItemType ENUM R Categorization of a tree item, e.g.


Devices, Boxes, PLC, ... . As
defined by item types.
ItemSubType LONG RW Sub type of a tree
item.

Parent ITcSmTreeItem* R Pointer to the parent tree item.


ChildCount LONG R Number of childs. Childs counted by
property enclose only
main childs of the tree item (e.g. box
are main childs of a
device but not the device process
image). To access all childs use
the _NewEnum property.

Child(LONG n) ITcSmTreeItem* R ITcSmTreeItem pointer of the n-th ch


VarCount((LONG LONG R Number of variables belonging to the
x) tree item. x = 0 counted
the input variables, x = 1 the outputs

Var(LONG x, ITcSmTreeItem* R ITcSmTreeItem pointer of the n-th


LONG n) variable. x = 0 uses the
input variables, x = 1 the outputs

_NewEnum IUnknown* R Returns a enum interface that


(IEnumVariant*) enumerates all child tree
items of the current tree item. This
property may be used, for example, b
For-Each statement.
Methods
ITcSmTreeItem Available
Methods Description since
CreateChild Creates a child tree item. TwinCAT
2.11
DeleteChild Deletes a child tree item. TwinCAT
2.11
ImportChild Imports a child item from TwinCAT
the clipboard or a 2.11
previously exported file.

ExportChild Exports a child item to the TwinCAT


clipboard or a 2.11
file.

ProduceXml Returns a String containing TwinCAT


the XML representation of 2.11
the item, with all its item-
specific data and
parameters.

ConsumeXml Consumes a String TwinCAT


containing the XML 2.11
representation
of the tree item, with all its
item-specific data and
parameters.

GetLastXmlError Gets the error message of TwinCAT


the last 2.11
erroneous ConsumeXml()
call.
LookupChild Searches for a child with TwinCAT
the specified relative 2.11
path.

ITcSmTreeItem2 Available
Methods Description since
ResoucesCount For interal use only TwinCAT
2.11
ChangeChildSubType Changes the SubType of TwinCAT
the ITcSmTreeItem. 2.11
ClaimResources For internal use only TwinCAT
2.11

ITcSmTreeItem3 Available
Methods Description since
CompareItem Compares the actual TwinCAT
ITcSmTreeItem to the 2.11
specified
other.


Version information
Required TwinCAT version
This interface is supported
in TwinCAT 2.11 and above
Automation Interface
ITcSmTreeItem Item Types
Every tree item in TwinCAT System Manager / TwinCAT XAE is being
categorized into various groups, e.g. devices, boxes, task, ... . You can
check the item type of a tree item by manually adding it to TwinCAT
System Manager or XAE
and then exporting its XML description via the corresponding menu entry.
TwinCAT System Manager: Actions --> Export XML
description
TwinCAT XAE: TwinCAT --> Selected item --> Export XML
description

In the resulting XML file, the item type is represented by the node
<ItemType>.

General item types


Item
type Tag Description
0 TREEITEMTYPE_UNKNOWN ---
1 TREEITEMTYPE_TASK ---
9 TREEITEMTYPE_IECPRJ ---
10 TREEITEMTYPE_CNCPRJ ---
11 TREEITEMTYPE_GSDMOD Module of a
Profibus
GSD device
12 TREEITEMTYPE_CDL ---
13 TREEITEMTYPE_IECLZS ---
14 TREEITEMTYPE_LZSGRP ---
15 TREEITEMTYPE_IODEF ---
16 TREEITEMTYPE_ADDTASKS ---
17 TREEITEMTYPE_DEVICEGRP ---
18 TREEITEMTYPE_MAPGRP ---
30 TREEITEMTYPE_CANPDO ---
31 TREEITEMTYPE_RTIMESET ---
32 TREEITEMTYPE_BCPLC_VARS ---
33 TREEITEMTYPE_FILENAME ---
34 TREEITEMTYPE_DNETCONNECT ---
37 TREEITEMTYPE_FLBCMD ---
43 TREEITEMTYPE_EIPCONNECTION ---
44 TREEITEMTYPE_PNIOAPI ---
45 TREEITEMTYPE_PNIOMOD ---
46 TREEITEMTYPE_PNIOSUBMOD ---
47 TREEITEMTYPE_ETHERNETPROTOCOL ---
200 TREEITEMTYPE_CAMDEF ---
201 TREEITEMTYPE_CAMGROUP ---
202 TREEITEMTYPE_CAM ---
203 TREEITEMTYPE_CAMENCODER ---
204 TREEITEMTYPE_CAMTOOLGRP ---
205 TREEITEMTYPE_CAMTOOL ---
300 TREEITEMTYPE_LINEDEF ---
400 TREEITEMTYPE_ISGDEF ---
401 TREEITEMTYPE_ISGCHANNEL ---
402 TREEITEMTYPE_ISGAGROUP ---
403 TREEITEMTYPE_ISGAXIS ---
500 TREEITEMTYPE_RTSCONFIG ---
501 TREEITEMTYPE_RTSAPP ---
502 TREEITEMTYPE_RTSAPPTASK ---
503 TREEITEMTYPE_RTSADI ---
504 TREEITEMTYPE_CPPCONFIG ---
505 TREEITEMTYPE_SPLCCONFIG ---

I/O item types


Item
type Tag Description
2 TREEITEMTYPE_DEVICE I/O Device
3 TREEITEMTYPE_IMAGE Process
Image
4 TREEITEMTYPE_MAPPING ---
5 TREEITEMTYPE_BOX I/O Box (e.g.
"BK2000",
child of I/O
Devices)

6 TREEITEMTYPE_TERM I/O Terminal


(child of
terminal
couplers
(box))
7 TREEITEMTYPE_VAR Variable
8 TREEITEMTYPE_VARGRP Variable
Group (e.g.
"Inputs")

35 TREEITEMTYPE_NVPUBLISHERVAR ---
36 TREEITEMTYPE_NVSUBSCRIBERVAR ---

PLC item types


Item
type Tag Description
600 TREEITEMTYPE_PLCAPP PLC
application
(root PLC
object) 1
601 TREEITEMTYPE_PLCFOLDER PLC folder 1
602 TREEITEMTYPE_PLCPOUPROG POU
Program 1
603 TREEITEMTYPE_PLCPOUFUNC POU
Function 1
604 TREEITEMTYPE_PLCPOUFB POU
Function
Block 1
605 TREEITEMTYPE_PLCDUTENUM DUT enum
data type 1
606 TREEITEMTYPE_PLCDUTSTRUCT DUT struct
data type 1
607 TREEITEMTYPE_PLCDUTUNION DUT union
data type 1
608 TREEITEMTYPE_PLCACTION PLC action
1

609 TREEITEMTYPE_PLCMETHOD PLC


method 1
610 TREEITEMTYPE_PLCITFMETH PLC
interface
method 1
611 TREEITEMTYPE_PLCPROP PLC
property 1
612 TREEITEMTYPE_PLCITFPROP PLC
interface
property 1
613 TREEITEMTYPE_PLCPROPGET PLC
property
getter 1
614 TREEITEMTYPE_PLCPROPSET PLC
property
setter 1
615 TREEITEMTYPE_PLCGVL GVL (Global
variable list)
1

616 TREEITEMTYPE_PLCTRANS PLC


Transition 1
617 TREEITEMTYPE_PLCLIBMAN PLC library
manager 1
618 TREEITEMTYPE_PLCITF PLC
interface 1
619 TREEITEMTYPE_PLCVISOBJ PLC visual
object 1
620 TREEITEMTYPE_PLCVISMAN PLC visual
manager 1
621 TREEITEMTYPE_PLCTASK PLC task
object 1
622 TREEITEMTYPE_PLCPROGREF PLC
program
reference 1
623 TREEITEMTYPE_PLCDUTALIAS DUT Alias
624 TREEITEMTYPE_PLCEXTDATATYPECONT PLC
external
data type
container 1
625 TREEITEMTYPE_PLCTMCDESCRIPTION PLC TMC
description
file 1
654 TREEITEMTYPE_PLCITFPROPGET PLC
interface
property
getter
655 TREEITEMTYPE_PLCITFPROPSET PLC
interface
property
setter

NC item types
Item
type Tag Description
19 TREEITEMTYPE_NCDEF ---
20 TREEITEMTYPE_NCAXISES ---
21 TREEITEMTYPE_NCCHANNEL NC Channel
22 TREEITEMTYPE_NCAXIS NC Axis
23 TREEITEMTYPE_NCENCODER ---
24 TREEITEMTYPE_NCDRIVE ---
25 TREEITEMTYPE_NCCONTROLLER ---
26 TREEITEMTYPE_NCGROUP ---
27 TREEITEMTYPE_NCINTERPRETER ---
40 TREEITEMTYPE_NCTABLEGRP ---
41 TREEITEMTYPE_NCTABLE ---
42 TREEITEMTYPE_NCTABLESLAVE ---

Notes
1 requires TwinCAT
3.1
Automation Interface
ITcSmTreeItem Item Sub Types
Item sub types specify what kind of device, box or terminal is being
used, for example a sub type of 2408 identifies a KL2408 digital output
terminal. You can check the sub type of an item by manually adding it in
TwinCAT System Manager or XAE and then export its XML
description via the corresponding menu entry.
TwinCAT System Manager: Actions --> Export XML
description
TwinCAT XAE: TwinCAT --> Selected item
--> Export XML description

In the resulting XML file, the sub type is represented by the node
<ItemSubType>. In the above example, we exported the XML
description of an EL2008 terminal. The XML file shows that this terminal
has a sub type of 9099.

The following tables will give you a good overview about some of the
available sub types. If your devices is not listed, please perform the
above steps to determine the sub type of your specific device.
Shortcuts:
Devices
Boxes
Terminals: E-Bus (ELxxxx)
Terminals: K-Bus digital input (KL1xxx)
Terminals: K-Bus digital output (KL2xxx)
Terminals: K-Bus analog input (KL3xxx)
Terminals: K-Bus analog output (KL4xxx)
Terminals: K-Bus position measurement (KL5xxx)
Terminals: K-Bus communication (KL6xxx)
Terminals: K-Bus power (KL8xxx)
Terminals: K-Bus safety (KLx90x)
Terminals: K-Bus system (KL9xxx)


Automation Interface
ITcSmTreeItem Item Sub Types: E-Bus
Due to their architecture, E-Bus boxes, terminals and modules will be
handled differently than their K-Bus counterparts, e.g. during creation
using the CreateChild() method. As each K-Bus terminal will be specified
according to its specific sub type, E-Bus terminals are recognized via one
common sub type and then specified via their "Product
Revision" which will be used as the vInfo parameter in the CreateChild()
method.

Sub
type Description
9099 Generic sub type for all EtherCAT terminals. In case
of CreateChild(), a specific terminal will be defined
via vInfo parameter.

There are a few exceptions to this rule, e.g. for RS232 terminals. The
following table gives an overview about these exceptions:

I/O ItemSubType Description


EP6002 9101 RS232 / RS422 /
RS485 interface
terminal
EL6001 9101 RS232 interface
terminal
EL6002 9101 RS232 interface
terminal (2-Channel)
EL6021 9103 RS422 / RS485
interface terminal
EL6022 9103 RS422 / RS485
interface terminal (2-
Channel)


Code Snippet (C#)
ITcSmTreeItem ek1100 = systemManager.LookupTreeItem("TIID^EtherCAT Master^EK110
ek1100.CreateChild("EL2002 - 1", 9099, "", "EL2002-0000-0016");

Product revision
Each E-Bus box/terminal/module has its own product revision, which you
can view either by exporting its
XML description or in the "Add Device" dialog in TwinCAT XAE.

For example,
the EL2002 digital output terminal has the product revision EL2002-0000-
0016, as you can also see in its XML description:
To get the XML description of a tree item, simply do the following:
TwinCAT 2: Add the item to System Manager, select it and,
from the menu, choose "Actions" --> "Export XML description"
TwinCAT 3: Add the item to XAE, select it and, from the
menu, choose "TwinCAT" --> "Selected item" --> "Export XML
description"


Automation Interface

11
ITcSmTreeItem Item Sub Types: Devices
Devices: Miscellaneous
Sub
type Tag Description
0 IODEVICETYPE_UNKNOWN ---
6 IODEVICETYPE_BKHFPC Beckhoff Industrial-
PC C2001
9 IODEVICETYPE_LPTPORT LPT Port
10 IODEVICETYPE_DPRAM Generic DPRAM
11 IODEVICETYPE_COMPORT COM Port
18 IODEVICETYPE_FCXXXX Beckhoff-
FeldbusCard
32 IODEVICETYPE_SMB Motherboard System
Management Bus
43 IODEVICETYPE_BKHFNCBP Beckhoff NC
Rückwand
44 IODEVICETYPE_SERCANSPCI Sercos Master
(SICAN/IAM PCI)
46 IODEVICETYPE_SERCONPCI Sercon 410B or 816
Chip Master or Slave
(PCI)
53 IODEVICETYPE_BKHFAH2000 Beckhoff AH2000
(Hydraulik Backplane)
55 IODEVICETYPE_AH2000MC Beckhoff-AH2000 mit
Profibus-MC

Devices: Beckhoff CX Terminal Devices


Sub
type Tag Description
120 IODEVICETYPE_CX5000 CX5000 Terminal
Device
135 IODEVICETYPE_CX8000 CX8000 Terminal
Device
105 IODEVICETYPE_CX9000_BK CX9000 Terminal
Device
65 IODEVICETYPE_CX1100_BK CX1100 Terminal
Device
124 IODEVICETYPE_CCAT Beckhoff CCAT Adapter

Devices: Beckhoff CP Devices


Sub
type Tag Description
14 IODEVICETYPE_BKHFCP2030 Beckhoff CP2030
(Pannel-Link)
31 IODEVICETYPE_BKHFCP9030 Beckhoff CP9030
(Pannel-Link with
UPS, ISA)
52 IODEVICETYPE_BKHFCP9040 Beckhoff CP9040 (CP-
PC)
54 IODEVICETYPE_BKHFCP9035 Beckhoff CP9035
(Pannel-Link with
UPS, PCI)
116 IODEVICETYPE_BKHFCP6608 Beckhoff CP6608(IXP
PC)

Devices: Beckhoff BC/BX Devices


Sub
type Tag Description
77 IODEVICETYPE_BX_BK BX Klemmenbus Interface
78 IODEVICETYPE_BX_M510 BX SSB-Master
103 IODEVICETYPE_BC8150 BCXX50 Serial Slave
104 IODEVICETYPE_BX9000 BX9000 Ethernet Slave
107 IODEVICETYPE_BC9050 BC9050 Etherent Slave
108 IODEVICETYPE_BC9120 BC9120 Etherent Slave
110 IODEVICETYPE_BC9020 BC9020 Etherent Slave

Devices: Beckhoff EtherCAT


Sub
type Tag Description
94 IODEVICETYPE_ETHERCAT Obsolete:
EtherCAT
Master. Use
"111" instead.
111 IODEVICETYPE_ETHERCATPROT EtherCAT
Master
130 IODEVICETYPE_ETHERCATSLV EtherCAT
Slave
106 IODEVICETYPE_EL6601 EtherCAT
Automation
Protocol via
EL6601
112 IODEVICETYPE_ETHERNETNVPROT EtherCAT
Automation
Protocol
(Network
variables)

Devices: Beckhoff Lightbus Master/Slave


Sub
type Tag Description
67 IODEVICETYPE_CX1500_M200 PC104 Lightbus-
Master
68 IODEVICETYPE_CX1500_B200 PC104 Lightbus-
Slave
36 IODEVICETYPE_FC200X Beckhoff-Lightbus-
I/II-PCI-Card
114 IODEVICETYPE_EL6720 Beckhoff-Lightbus-
EtherCAT-Klemme
1 IODEVICETYPE_C1220 Beckhoff Lightbus
ISA interface card
C1220
2 IODEVICETYPE_C1200 Beckhoff Lightbus
ISA interface card
C1200

Devices: Beckhoff Profibus Master/Slave


Sub
type Tag Description
69 IODEVICETYPE_CX1500_M310 PC104 ProfiBus-
Master
70 IODEVICETYPE_CX1500_B310 PC104 ProfiBus-
Slave
33 IODEVICETYPE_PBMON Beckhoff-PROFIBUS-
Monitor
38 IODEVICETYPE_FC3100 Beckhoff-Profibus-
PCI-Card
56 IODEVICETYPE_FC3100MON Beckhoff-Profibus-
Monitor-PCI-Karte
60 IODEVICETYPE_FC3100SLV Beckhoff-Profibus-
PCI-Karte als Slave
79 IODEVICETYPE_BX_B310 BX ProfiBus-Slave
83 IODEVICETYPE_BC3150 BCxx50 ProfiBus-
Slave
86 IODEVICETYPE_EL6731 Beckhoff-Profibus-
EtherCAT-Klemme
97 IODEVICETYPE_EL6731SLV Beckhoff-Profibus-
Slave-EtherCAT-
Klemme

Devices: Beckhoff CANopen Master/Slave


Sub
type Tag Description
71 IODEVICETYPE_CX1500_M510 PC104 CANopen-
Master
72 IODEVICETYPE_CX1500_B510 PC104 CANopen-
Slave
39 IODEVICETYPE_FC5100 Beckhoff-CanOpen-
PCI-Card
58 IODEVICETYPE_FC5100MON Beckhoff-CANopen-
Monitor-PCI-Karte
61 IODEVICETYPE_FC5100SLV Beckhoff-CanOpen-
PCI-Karte als Slave
81 IODEVICETYPE_BX_B510 BX CANopen-Slave
84 IODEVICETYPE_BC5150 BCxx50 CANopen-
Slave
87 IODEVICETYPE_EL6751 Beckhoff-CanOpen-
EtherCAT-Klemme
98 IODEVICETYPE_EL6751SLV Beckhoff-CanOpen-
Slave-EtherCAT-
Klemme

Devices: Beckhoff DeviceNet Master/Slave


Sub
type Tag Description
73 IODEVICETYPE_CX1500_M520 PC104 DeviceNet-
Master
74 IODEVICETYPE_CX1500_B520 PC104 DeviceNet-
Slave
41 IODEVICETYPE_FC5200 Beckhoff-DeviceNet-
PCI-Card
59 IODEVICETYPE_FC5200MON Beckhoff-DeviceNet-
Monitor-PCI-Karte
62 IODEVICETYPE_FC5200SLV Beckhoff-DeviceNet-
PCI-Karte als Slave
82 IODEVICETYPE_BX_B520 BX DeviceNet-Slave
85 IODEVICETYPE_BC5250 BCxx50 DeviceNet-
Slave
88 IODEVICETYPE_EL6752 Beckhoff-DeviceNet-
EtherCAT-Klemme
99 IODEVICETYPE_EL6752SLV Beckhoff-DeviceNet-
Slave-EtherCAT-
Klemme

Devices: Beckhoff Sercos Master/Slave


Sub
type Tag Description
75 IODEVICETYPE_CX1500_M750 PC104 Sercos-
Master
76 IODEVICETYPE_CX1500_B750 PC104 Sercos-Slave
48 IODEVICETYPE_FC7500 Beckhoff-SERCOS-
PCI-Card

Devices: Ethernet
Sub
type Tag Description
66 IODEVICETYPE_ENETRTMP Ethernet Real Time
Miniport
109 IODEVICETYPE_ENETADAPTER Real-Time Ethernet
Adapter (Multiple
Protocol Handler)
138 --- Real-Time Ethernet
Protocol (BK90xx,
AX2000-B900)
45 IODEVICETYPE_ETHERNET Virtual Ethernet
Interface

Devices: USB
Sub
type Tag Description
57 IODEVICETYPE_USB Virtual USB Interface
125 --- Virtual USB Interface
(Remote)

Devices: Hilscher
Sub
type Tag Description
4 IODEVICETYPE_CIF30DPM ISA ProfiBus-Master 2
kByte (Hilscher Card)
5 IODEVICETYPE_CIF40IBSM ISA Interbus-S-Master 2
kByte (Hilscher-Card)
12 IODEVICETYPE_CIF30CAN ISA CANopen-Master
(Hilscher-Card)
13 IODEVICETYPE_CIF30PB ISA ProfiBus-Master 8
kByte (Hilscher-Card)
16 IODEVICETYPE_CIF30IBM ISA Interbus-S-Master
(Hilscher-Card)
17 IODEVICETYPE_CIF30DNM ISA DeviceNet-Master
(Hilscher-Card)
19 IODEVICETYPE_CIF50PB PCI ProfiBus-Master 8
kByte (Hilscher-Card)
20 IODEVICETYPE_CIF50IBM PCI Interbus-S-Master
(Hilscher-Card)
21 IODEVICETYPE_CIF50DNM PCI DeviceNet-Master
(Hilscher-Card)
22 IODEVICETYPE_CIF50CAN PCI CANopen-Master
(Hilscher-Card)
23 IODEVICETYPE_CIF60PB PCMCIA ProfiBus-
Master (Hilscher-Card)
24 IODEVICETYPE_CIF60DNM PCMCIA DeviceNet-
Master (Hilscher-Card)
25 IODEVICETYPE_CIF60CAN PCMCIA CANopen-
Master (Hilscher-Card)
26 IODEVICETYPE_CIF104DP PC104 ProfiBus-Master
2 kByte (Hilscher-Card)
27 IODEVICETYPE_C104PB PC104 ProfiBus-Master
8 kByte (Hilscher-Card)
28 IODEVICETYPE_C104IBM PC104 Interbus-S-
Master 2 kByte
(Hilscher-Card)
29 IODEVICETYPE_C104CAN PC104 CANopen-
Master (Hilscher-Card)
30 IODEVICETYPE_C104DNM PC104 DeviceNet-
Master (Hilscher-Card)
35 IODEVICETYPE_CIF60IBM PCMCIA Interbus-S-
Master (Hilscher-Card)
49 IODEVICETYPE_CIF30IBS ISA Interbus-S-Slave
(Hilscher-Card)
50 IODEVICETYPE_CIF50IBS PCI Interbus-S-Slave
(Hilscher-Card)
51 IODEVICETYPE_C104IBS PC104 Interbus-S-Slave
(Hilscher-Card)
89 IODEVICETYPE_COMPB COM ProfiBus-Master 8
kByte (Hilscher-Karte)
90 IODEVICETYPE_COMIBM COM Interbus-S-Master
(Hilscher-Karte)
91 IODEVICETYPE_COMDNM COM DeviceNet-Master
(Hilscher-Karte)
92 IODEVICETYPE_COMCAN COM CANopen-Master
(Hilscher-Karte)
93 IODEVICETYPE_COMIBS COM CANopen-Slave
(Hilscher-Karte)
100 IODEVICETYPE_C104PPB PC104+ ProfiBus-
Master 8 kByte
(Hilscher-Karte)
101 IODEVICETYPE_C104PCAN PC104+ CANopen-
Master (Hilscher-Karte)
102 IODEVICETYPE_C104PDNM PC104+ DeviceNet-
Master (Hilscher-Karte)

Devices: Profinet / Profibus


Sub
type Tag Description
3 IODEVICETYPE_SPC3 ProfiBus
Slave
(Siemens
Card)
7 IODEVICETYPE_CP5412A2 ProfiBus-
Master
(Siemens-
Card)
34 IODEVICETYPE_CP5613 PCI
ProfiBus-
Master
(Siemens-
Card)
113 IODEVICETYPE_PROFINETIOCONTROLLER PROFINET
Master
115 IODEVICETYPE_PROFINETIODEVICE PROFINET
Slave

Devices: Indramat
Sub
type Tag Description
8 IODEVICETYPE_SERCANSISA Sercos Master
(Indramat)

Devices: Phoenix
Sub
type Tag Description
15 IODEVICETYPE_IBSSCIT Interbus-S-Master
(Phoenix-Card)
47 IODEVICETYPE_IBSSCRIRTLK Interbus-S-Master
with Slave-Part LWL
Basis
(Phoenix-Card)

63 IODEVICETYPE_IBSSCITPCI PCI Interbus-S-


Master (Phoenix-
Karte)
64 IODEVICETYPE_IBSSCRILKPCI PCIInterbus-S-
Master mit Slave-Teil
auf LWL Basis
(Phoenix-Karte)
80 IODEVICETYPE_IBSSCRIRTPCI PCIInterbus-S-
Master mit Slave-Teil
auf Kupfer Basis
(Phoenix-Karte)
Automation Interface
ITcSmTreeItem Item Sub Types: Boxes
Sub
type Tag Description
0 BOXTYPE_UNKNOWN ---
1 BOXTYPE_BK2000 BK2000 Lightbus
coupler
2 BOXTYPE_M1400 M1400 Lightbus
digital input/output
module
3 BOXTYPE_M2400 M2400 Lightbus
input/output
module
4 BOXTYPE_M3120_1 M3120 Lightbus
incremental
encoder interface
5 BOXTYPE_M3120_2 M3120 Lightbus
incremental
encoder interface
6 BOXTYPE_M3120_3 M3120 Lightbus
incremental
encoder interface
7 BOXTYPE_M3120_4 M3120 Lightbus
incremental
encoder interface
8 BOXTYPE_M3000 M3000 absolute /
incremental
encoder
9 BOXTYPE_C1120 ---
10 BOXTYPE_BK2010 BK2010 Lightbus
coupler
11 BOXTYPE_AX2000 ---
12 BOXTYPE_M2510 ---
20 BOXTYPE_BK2020 BK2020 Lightbus
coupler
21 BOXTYPE_BC2000 ---
31 BOXTYPE_FOX20 ---
32 BOXTYPE_FOX50 ---
33 BOXTYPE_FOXRK001 ---
34 BOXTYPE_FOXRK002 ---
35 BOXTYPE_CP1001 ---
40 BOXTYPE_IPXB2 ---
41 BOXTYPE_ILXB2 ---
42 BOXTYPE_ILXC2 ---
50 BOXTYPE_TSMBOX_200 ---
51 BOXTYPE_BX2000 ---
52 BOXTYPE_CX1500_B200 ---
1001 BOXTYPE_BK3000 ---
1002 BOXTYPE_BK3100 ---
1003 BOXTYPE_PBDP_GSD ---
1004 BOXTYPE_BK3010 ---
1005 BOXTYPE_BK3110 ---
1006 BOXTYPE_BK3500 ---
1007 BOXTYPE_LC3100 ---
1008 BOXTYPE_PBDP_DRIVE ---
1009 BOXTYPE_BK3020 ---
1010 BOXTYPE_BK3120 ---
1011 BOXTYPE_BC3100 ---
1012 BOXTYPE_PBDP_DRIVE2 ---
1013 BOXTYPE_PBDP_DRIVE3 ---
1014 BOXTYPE_PBDP_DRIVE4 ---
1015 BOXTYPE_PBDP_DRIVE5 ---
1016 BOXTYPE_PBDP_DRIVE6 ---
1017 BOXTYPE_PBDP_DRIVE7 ---
1018 BOXTYPE_PBDP_DRIVE8 ---
1019 BOXTYPE_BK3150 ---
1020 BOXTYPE_BC3150 ---
1021 BOXTYPE_BK3XXX ---
1022 BOXTYPE_BC3XXX ---
1030 BOXTYPE_IPXB3 ---
1031 BOXTYPE_ILXB3 ---
1032 BOXTYPE_ILXC3 ---
1040 BOXTYPE_TSMBOX_310 ---
1041 BOXTYPE_BX3100 ---
1042 BOXTYPE_CX1500_B310 ---
1043 BOXTYPE_FC310X_SLAVE ---
1044 BOXTYPE_EL6731_SLAVE ---
1051 BOXTYPE_AX2000_B310 ---
1100 BOXTYPE_TCPBDPSLAVE ---
1101 BOXTYPE_TCFDLAGAG ---
1102 BOXTYPE_TCMPI ---
1103 BOXTYPE_TCPBMCSLAVE ---
1104 BOXTYPE_TCPBMCSLAVE2 ---
1105 BOXTYPE_TCPBMCSLAVE3 ---
1106 BOXTYPE_TCPBMCSLAVE4 ---
1107 BOXTYPE_TCPBMCSLAVE5 ---
1108 BOXTYPE_TCPBMCSLAVE6 ---

1109 BOXTYPE_TCPBMCSLAVE7 ---


1110 BOXTYPE_TCPBMCSLAVE8 ---
1111 BOXTYPE_TCPBMONSLAVE ---
2001 BOXTYPE_BK4000 ---
2002 BOXTYPE_IBS_GENERIC ---
2003 BOXTYPE_IBS_BK ---
2004 BOXTYPE_BK4010 ---
2005 BOXTYPE_BK4500 ---
2006 BOXTYPE_BK4510 ---
2007 BOXTYPE_IBS_SLAVEBOX ---
2008 BOXTYPE_BC4000 ---
2009 BOXTYPE_BK4020 ---
2020 BOXTYPE_CP2020 ---
2030 BOXTYPE_IPXB4 ---
2031 BOXTYPE_ILXB4 ---
2032 BOXTYPE_ILXC4 ---
3001 BOXTYPE_SERCOSAXIS ---
3011 BOXTYPE_BK7500 ---
3012 BOXTYPE_BK7510 ---
3013 BOXTYPE_BK7520 ---
3021 BOXTYPE_SERCOSMASTERBOX ---
3031 BOXTYPE_SERCOSSLAVEBOX ---
4001 BOXTYPE_BK8100 BK8100 bus
coupler
4002 BOXTYPE_BK8110 BK8110 bus
coupler
4003 BOXTYPE_BK8000 BK8000 bus
coupler
4004 BOXTYPE_BK8010 BK8010 bus
coupler
4005 BOXTYPE_CP9040 CP9040 PCB
4011 BOXTYPE_BC8000 BC8000 bus
terminal controller
4012 BOXTYPE_BC8100 BC8100 bus
terminal controller
4030 BOXTYPE_IPXB80 ---
4031 BOXTYPE_ILXB80 ---
4032 BOXTYPE_ILXC80 ---
4040 BOXTYPE_IPXB81 ---
4041 BOXTYPE_ILXB81 ---
4042 BOXTYPE_ILXC81 ---
4050 BOXTYPE_BC8150 BC8150 bus
terminal controller
5001 BOXTYPE_BK5100 BK5100 bus
coupler
5002 BOXTYPE_BK5110 BK5110 bus
coupler
5003 BOXTYPE_CANNODE ---
5004 BOXTYPE_BK5120 BK5120 bus
coupler
5005 BOXTYPE_LC5100 ---
5006 BOXTYPE_CANDRIVE ---
5007 BOXTYPE_AX2000_B510 ---
5008 BOXTYPE_BK5150 BK5150 bus
coupler
5009 BOXTYPE_BK5151 BK5151 bus
coupler
5011 BOXTYPE_BC5150 BC5150 bus
terminal controller
5030 BOXTYPE_IPXB51 ---
5031 BOXTYPE_ILXB51 ---
5032 BOXTYPE_ILXC51 ---
5040 BOXTYPE_TSMBOX_510 ---
5041 BOXTYPE_BX5100 BX5100 CANopen
bus terminal
controller
5042 BOXTYPE_CX1500_B510 ---
5043 BOXTYPE_FC510XSLV ---
5050 BOXTYPE_TCCANSLAVE ---
5051 BOXTYPE_CANQUEUE CAN Interface
5201 BOXTYPE_BK5200 ---
5202 BOXTYPE_BK5210 ---
5203 BOXTYPE_DEVICENET ---
5204 BOXTYPE_BK5220 ---
5205 BOXTYPE_LC5200 ---
5211 BOXTYPE_BK52XX ---
5212 BOXTYPE_BC52XX ---
5230 BOXTYPE_IPXB52 ---
5231 BOXTYPE_ILXB52 ---
5232 BOXTYPE_ILXC52 ---
5250 BOXTYPE_TCDNSLAVE ---
9001 BOXTYPE_BK9000 BK9000 Ethernet
TCP/IP bus
coupler
9002 BOXTYPE_BK9100 BK9100 Ethernet
TCP/IP bus
coupler
9005 BOXTYPE_BK9050 BK9050 Ethernet
TCP/IP bus
coupler
9011 BOXTYPE_BC9000 BC9000 Ethernet
TCP/IP bus
terminal controller
9012 BOXTYPE_BC9100 BC9100 Ethernet
TCP/IP bus
terminal controller
9013 BOXTYPE_BX9000 BX9000 Ethernet
TCP/IP bus
terminal controller
9014 BOXTYPE_BX9000SLV ---
9015 BOXTYPE_BC9050 BC9050 Ethernet
TCP/IP bus
terminal controller
9016 BOXTYPE_BC9050SLV BC9050 Ethernet
TCP/IP bus
terminal controller
slave
9017 BOXTYPE_BC9120 BC9120 Ethernet
TCP/IP bus
terminal controller
9018 BOXTYPE_BC9120SLV BC9120 Ethernet
TCP/IP bus
terminal controller
slave

9019 BOXTYPE_BC9020 BC9020 Ethernet


TCP/IP bus
terminal controller
9020 BOXTYPE_BC9020SLV BC9020 Ethernet
TCP/IP bus
terminal controller
slave
9030 BOXTYPE_IPXB9 ---
9031 BOXTYPE_ILXB9 ---
9032 BOXTYPE_ILXC9 ---
9041 BOXTYPE_REMOTETASK ---
9051 BOXTYPE_NV_PUB Network Publisher.
9052 BOXTYPE_NV_SUB Network
Subscriber.
9053 BOXTYPE_NV_PUBVAR Publisher variable.
9054 BOXTYPE_NV_SUBVAR Subscriber
variable.
9055 BOXTYPE_NV_PUBDATA Publisher data
object.
9056 BOXTYPE_NV_SUBDATA Subscriber data
object.
9061 BOXTYPE_AX2000_B900 ---
9071 BOXTYPE_FLB_FRAME ---
9081 BOXTYPE_BK1120 ---
9085 BOXTYPE_IPXB11 ---
9086 BOXTYPE_ILXB11 ---
9087 BOXTYPE_ILXC11 ---
9105 BOXTYPE_FSOESLAVE ---
9121 BOXTYPE_PNIODEVICE ---
9122 BOXTYPE_PNIOTCDEVICE ---
9123 BOXTYPE_PNIODEVICEINTF Profinet TwinCAT
Device Interface
9124 BOXTYPE_PNIO_DRIVE ---
9125 BOXTYPE_PNIOBK9103 ---
9126 BOXTYPE_PNIOILB903 ---
9132 BOXTYPE_BK9053 BK9053 K-Bus
coupler,
PROFINET IO RT
9133 BOXTYPE_EIPSLAVEINTF ---
9143 BOXTYPE_PTPSLAVEINTF ---
9151 BOXTYPE_RAWUDPINTF ---
9500 BOXTYPE_BK9500 BK9500
9510 BOXTYPE_BK9510 BK9510
9520 BOXTYPE_BK9520 BK9520
9591 BOXTYPE_CPX8XX ---
9700 BOXTYPE_CX1102 ---
9701 BOXTYPE_CX1103 ---
9702 BOXTYPE_CX1190 ---

Automation Interface
ITcSmTreeItem Item Sub Types: Terminals: K-Bus
digital input (KL1)

Sub type Description


1002 KL1002 2-Channel digital input terminal
1012 KL1012 2-Channel digital input terminal
1032 KL1032 2-Channel digital input terminal
1052 KL1052 2-Channel digital input terminal
1104 KL1104 4-Channel digital input terminal
1114 KL1114 4-Channel digital input terminal
1124 KL1124 4-Channel digital input terminal
1154 KL1154 4-Channel digital input terminal
1164 KL1164 4-Channel digital input terminal
1184 KL1184 4-Channel digital input terminal
1194 KL1194 4-Channel digital input terminal
1212 KL1212 2-Channel digital input terminal
1232 KL1232 2-Channel digital input terminal
1302 KL1302 2-Channel digital input terminal
1304 KL1304 4-Channel digital input terminal
1312 KL1312 2-Channel digital input terminal
1314 KL1314 4-Channel digital input terminal
1352 KL1352 2-Channel digital input terminal
1362 KL1362 2-Channel digital input terminal
1382 KL1382 2-Channel digital input terminal
1402 KL1402 2-Channel digital input terminal
1404 KL1404 4-Channel digital input terminal
1408 KL1408 8-Channel digital input terminal
1412 KL1412 2-Channel digital input terminal
1414 KL1414 4-Channel digital input terminal
1418 KL1418 8-Channel digital input terminal
1434 KL1434 4-Channel digital input terminal
1488 KL1488 8-Channel digital input terminal
1498 KL1498 8-Channel digital input terminal
1501 KL1501 1-Channel digital input terminal
1512 KL1512 2-Channel digital input terminal
1702 KL1702 2-Channel digital input terminal
1712 KL1712 2-Channel digital input terminal
16778928 KL1712-0060 2-Channel digital input terminal
1722 KL1722 2-Channel digital input terminal
1804 KL1804 4-Channel digital input terminal
1808 KL1808 8-Channel digital input terminal
1809 KL1809 16-Channel digital input terminal
1814 KL1814 4-Channel digital input terminal
1819 KL1819 16-Channel digital input terminal
1859 KL1859 8-Channel digital input terminal
1862 KL1862 16-Channel digital input terminal
16779078 KL1862-0010 16-Channel digital input terminal
1872 KL1872 16-Channel digital input terminal
1889 KL1889 16-Channel digital input terminal
1202 KL1202 2-Channel digital input terminal
Automation Interface
ITcSmTreeItem Item Sub Types: Terminals: K-Bus
digital output (KL2)

Sub type Description


2408 KL2408 8-Channel digital output terminal
2012 KL2012 2-Channel digital output terminal
2022 KL2022 2-Channel digital output terminal
2032 KL2032 2-Channel digital output terminal
2114 KL2114 4-Channel digital output terminal
2124 KL2124 4-Channel digital output terminal
2134 KL2134 4-Channel digital output terminal
2184 KL2184 4-Channel digital output terminal
2212 KL2212 2-Channel digital output terminal
2404 KL2404 4-Channel digital output terminal
2212 KL2212 2-Channel digital output terminal
2404 KL2404 4-Channel digital output terminal
2408 KL2408 8-Channel digital output terminal
2284 KL2284 4-Channel digital output terminal
2424 KL2424 4-Channel digital output terminal
2442 KL2442 2-Channel digital output terminal
2488 KL2488 8-Channel digital output terminal
2502 KL2502 2-Channel PWM output terminal
2512 KL2512 2-Channel PWM output terminal
2521 KL2521 1-Channel Pulse Train output terminal
2531 KL2531 1-Channel Stepper Motor terminal
16779747 KL2531-1000 1-Channel Stepper Motor terminal
2532 KL2532 2-Channel DC Motor amplifier output
terminal
2535 KL2535 2-Channel PWM amplifier output
terminal
2541 KL2541 1-Channel Stepper Motor terminal
16779757 KL2541-1000 1-Channel Stepper Motor terminal
2542 KL2542 2-Channel DC Motor amplifier terminal
2545 KL2545 2-Channel PWM amplifier output
terminal
2552 KL2552 2-Channel DC Motor amplifier terminal
2602 KL2602 2-Channel output relay terminal
2612 KL2612 2-Channel output relay terminal
2622 KL2622 2-Channel output relay terminal
2631 KL2631 1-Channel power output relay terminal
2641 KL2641 1-Channel power output relay terminal
2652 KL2652 2-Channel power output relay terminal
2701 KL2701 1-Channel solid state load relay terminal
2702 KL2702 2-Channel output solid sate relay
terminal
16779918 KL2702-0002 2-Channel output solid state relay
terminal
33557134 KL2702-0020 2-Channel output solid state relay
terminal
2712 KL2712 2-Channel triac output terminal
2722 KL2722 2-Channel triac output terminal
2732 KL2732 2-Channel triac output terminal
2744 KL2744 4-Channel output solid state relay
2751 KL2751 1-Channel universal dimmer terminal
33557183 KL2751-1200 1-Channel universal dimmer
terminal
2761 KL2761 1-Channel universal dimmer terminal
2784 KL2784 4-Channel output terminal
2791 KL2791 1-Channel speed controller terminal
33557223 KL2791-1200 1-Channel speed controller
terminal
2794 KL2794 4-Channel output terminal
2808 KL2808 8-Channel output terminal
2809 KL2809 16-Channel output terminal
2872 KL2872 16-Channel output terminal
2889 KL2889 16-Channel output terminal
Automation Interface
ITcSmTreeItem Item Sub Types: Terminals: K-Bus
analog input (KL3)

Sub type Description


3001 KL3001 1-Channel analog input terminal
3002 KL3002 3-Channel analog input terminal
3011 KL3011 1-Channel analog input terminal
3012 KL3012 2-Channel analog input terminal
3021 KL3021 1-Channel analog input terminal
3022 KL3022 2-Channel analog input terminal
3041 KL3041 1-Channel analog input terminal
3042 KL3042 2-Channel analog input terminal
3044 KL3044 4-Channel analog input terminal
3051 KL3051 1-Channel analog input terminal
3052 KL3052 2-Channel analog input terminal
3054 KL3054 4-Channel analog input terminal
3061 KL3061 1-Channel analog input terminal
3062 KL3062 2-Channel analog input terminal
3064 KL3064 4-Channel analog input terminal
3102 KL3102 2-Channel analog input terminal
3112 KL3112 2-Channel analog input terminal
3122 KL3122 2-Channel analog input terminal
3132 KL3132 2-Channel analog input terminal
3142 KL3142 2-Channel analog input terminal
3152 KL3152 2-Channel analog input terminal
3158 KL3158 8-Channel analog input terminal
3162 KL3162 2-Channel analog input terminal
3172 KL3172 2-Channel analog input terminal
33557604 KL3172-0500 2-Channel analog input terminal
67112036 KL3172-1000 2-Channel analog input terminal
3182 KL3182 2-Channel analog input terminal
3201 KL3201 1-Channel analog input terminal
3202 KL3202 2-Channel analog input terminal
3204 KL3204 4-Channel analog input terminal
33557640 KL3208-0010 8-Channel analog input terminal
3222 KL3222 2-Channel analog input terminal
3228 KL3228 8-Channel analog input terminal
3302 KL3302 2-Channel analog input terminal
3311 KL3311 1-Channel analog input terminal
3312 KL3312 2-Channel analog input terminal
3314 KL3314 4-Channel analog input terminal
3351 KL3351 1-Channel resistor bridge terminal
50334999 KL3351-0001 1-Channel resistor bridge terminal
3356 KL3356 1-Channel precise resistor bridge
terminal
3361 KL3361 1-Channel oscilloscope terminal
3362 KL3362 2-Channel oscilloscope terminal
3403 KL3403 3-Phase power measuring terminal
3404 KL3404 4-Channel analog input terminal
3408 KL3408 8-Channel analog input terminal
3444 KL3444 4-Channel analog input terminal
3448 KL3448 8-Channel analog input terminal
3454 KL3454 4-Channel analog input terminal
3458 KL3458 8-Channel analog input terminal
3464 KL3464 4-Channel analog input terminal
3468 KL3468 8-Channel analog input terminal
Automation Interface
ITcSmTreeItem Item Sub Types: Terminals: K-Bus
analog output (KL4)

Sub
type Description
4001 KL4001 1-Channel analog output terminal
4002 KL4002 2-Channel analog output terminal
4004 KL4004 4-Channel analog output terminal
4011 KL4011 1-Channel analog output terminal
4012 KL4012 2-Channel analog output terminal
4021 KL4021 1-Channel analog output terminal
4022 KL4022 2-Channel analog output terminal
4031 KL4031 1-Channel analog output terminal
4032 KL4032 2-Channel analog output terminal
4034 KL4034 4-Channel analog output terminal
4112 KL4112 2-Channel analog output terminal
4122 KL4122 2-Channel analog output terminal
4132 KL4132 2-Channel analog output terminal
4404 KL4404 4-Channel analog output terminal
4408 KL4408 8-Channel analog output terminal
4414 KL4414 4-Channel analog output terminal
4418 KL4418 8-Channel analog output terminal
4424 KL4424 4-Channel analog output terminal
4428 KL4428 8-Channel analog output terminal
4434 KL4434 4-Channel analog output terminal
4438 KL4438 8-Channel analog output terminal
4494 KL4494 2-Channel analog output terminal
Automation Interface
ITcSmTreeItem Item Sub Types: Terminals: K-Bus
measuring (KL5)

Sub type Description


5001 KL5001 1-Channel SSI encoder terminal
5051 KL5051 1-Channel Bi-SSI encoder terminal
16782267 KL5051-0010 1-Channel Bi-SSI encoder
terminal
5101 KL5101 incremental encoder 5V terminal
5111 KL5111 incremental encoder 24V terminal
5121 KL5121 4-Channel line-motion-controller
terminal
5151 KL5151 1-Channel incremental encoder terminal
33559583 KL5151-0021 1-Channel incremental encoder
terminal
16782367 KL5151-0050 2-Channel incremental encoder
terminal
5152 KL5152 2-Channel incremental encoder terminal
Automation Interface
ITcSmTreeItem Item Sub Types: Terminals: K-Bus
communication (KL6)

Sub type Description


16783217 KL6001 interface RS232C terminal
50337649 KL6001 interface RS232 terminal
16783227 KL6011 interface TTY terminal
50337659 KL6011 interface TTY terminal
16783237 KL6021 interface RS422/485 terminal
50337669 KL6021 interface RS485 terminal
100669317 KL6021 interface RS485 terminal
100669327 KL6031 interface RS232 terminal
50337679 KL6031 interface RS232 terminal
100669337 KL6041 interface RS485 terminal
50337689 KL6041 interface RS485 terminal
16783257 KL6041-0100 interface RS485 terminal
6051 KL6051 data exchange terminal
335550521 KL6201 ASI-Master terminal
369104953 KL6201 ASI-Master terminal
402659385 KL6201 ASI-Master terminal
335550531 KL6211 ASI-Master terminal
369104963 KL6211 ASI-Master terminal
402659395 KL6211 ASI-Master terminal
6224 KL6224 I/O-Link Master terminal
16783440 KL6224 I/O-Link Master terminal
33560656 KL6224 I/O-Link Master terminal
50337872 KL6224 I/O-Link Master terminal
33560733 KL6301 EIB terminal
33560833 KL6401 LON terminal
33561013 KL6581 EnOcean terminal
33561203 KL6771 MP-Bus Master terminal
6781 KL6781 M-Bus interface terminal
6811 KL6811 DALI-Master terminal
6821 KL6821 eDALI-Master terminal
Automation Interface
ITcSmTreeItem Item Sub Types: Terminals: K-Bus
power (KL8)

Sub type Description


33562433 KL8001 1-Channel power terminal
8001 KL8001 3-Channel power terminal
8519 KL8519 16 digital input terminal
8524 KL8524 2x4 digital output terminal
8528 KL8528 8 digital output terminal
8548 KL8548 8-Channel analog output terminal
8610 KL8610 1-Channel adapter terminal KL8601
16785826 KL8610 2-Channel adapter terminal KL8601
33563042 KL8610 3-Channel adapter terminal KL8601
50340258 KL8610 4-Channel adapter terminal KL8601
67117474 KL8610 5-Channel adapter terminal KL8601
83894690 KL8610 6-Channel adapter terminal KL8601
100671906 KL8610 7-Channel adapter terminal KL8601
117449122 KL8610 8-Channel adapter terminal KL8601
Automation Interface
ITcSmTreeItem Item Sub Types: Terminals: K-Bus
system (KL9)

Sub type Description


9010 KL9010 end terminal
9020 KL9020 bus extension end terminal
9050 KL9050 bus extension coupler terminal
9060 KL9060 adapter terminal
9070 KL9070 shield terminal
9080 KL9080 separation terminal
9100 KL9100 power supplier terminal
9110 KL9110 power supplier terminal
9150 KL9150 power supplier terminal
9160 KL9160 power supplier terminal
9180 KL9180 potential connection terminal
9181 KL9181 potential connection terminal
9182 KL9182 potential connection terminal
9183 KL9183 potential connection terminal
9184 KL9184 potential connection terminal
9185 KL9185 potential connection terminal
9186 KL9186 potential connection terminal
9187 KL9187 potential connection terminal
9188 KL9188 potential connection terminal
9189 KL9189 potential connection terminal
9190 KL9190 power feed terminal
9195 KL9195 shield terminal
9200 KL9200 power supplier terminal
9210 KL9210 power supplier terminal
9250 KL9250 power supplier terminal
9260 KL9260 power supplier terminal
9290 KL9290 power supplier terminal
9300 KL9300 4-Channel diode array terminal
9301 KL9301 7-Channel diode array terminal
9302 KL9302 7-Channel diode array terminal
9309 KL9309 interface terminal for KL85xx
9400 KL9400 K-Bus power supplier terminal
9505 KL9505 power supplier terminal
167781665 KL9505-0010 power suppler terminal
9508 KL9508 power supplier terminal
167781668 KL9508-0010 power supplier terminal
9510 KL9510 power supplier terminal
167781670 KL9510-0010 power supplier terminal
9512 KL9512 power supplier terminal
167781672 KL9512-0010 power supplier terminal
9515 KL9515 power supplier terminal
167781675 KL9515-0010 power supplier terminal
9528 KL9528 power supplier terminal
9540 KL9540 surge filter field supply terminal
9550 KL9550 surge filter system and field supply
terminal
9560 KL9560 power supplier terminal
9570 KL9570 buffer capacitor terminal
Automation Interface
ITcSmTreeItem Item Sub Types: Terminals: K-Bus
safety (KLx90x)
Sub type Description
1904 KL1904 4-Channel safety input terminal
1908 KL1908 8-Channel safety input terminal
2904 KL2904 4-Channel safety output terminal
6904 KL6904 safety logic (7 TwinSAFE connections)
terminal
16784120 KL6904 safety logic (15 TwinSAFE connections)
terminal
Automation Interface
ITcSmTreeItem Item Sub Types: Modules: K-Bus
digital input (KM1)

Sub type Description


838861802 KM1002 16-Channel digital input module
838861804 KM1004 32-Channel digital input module
838861808 KM1008 64-Channel digital input module
838861812 KM1012 16-Channel digital input module
838861814 KM1014 32-Channel digital input module
838861818 KM1018 64-Channel digital input module
838862444 KM1644 4-Channel digital input module
Automation Interface
ITcSmTreeItem Item Sub Types: Modules: K-Bus
digital output (KM2)

Sub type Description


838862802 KM2002 16-Channel digital output module
838862804 KM2004 32-Channel digital output module
838862808 KM2008 64-Channel digital output module
838862822 KM2022 16-Channel digital output module
838862842 KM2042 16-Channel digital output module
838863404 KM2604 4-Channel digital output relay module
838863414 KM2614 4-Channel digital output relay module
838863442 KM2642 2-Channel digital power output relay
module
838863452 KM2652 2-Channel digital power output relay
module
16779990 KM2774 4-Channel blinds control terminal
2774 KM2774-1001 4-Channel blinds control terminal
Automation Interface
ITcSmTreeItem Item Sub Types: Modules: K-Bus
analog input (KM3)
Sub type Description
838864501 KM3701 1-Channel differential pressure
measuring
872418933 KM3701-0340 1-Channel differential pressure
measuring
838864502 KM3702 2-Channel absolute pressure
measuring
838864512 KM3712 2-Channel absolute pressure
measuring
Automation Interface
ITcSmTreeItem Item Sub Types: Modules: K-Bus
analog output (KM4)
Sub type Description
838865402 KM4602 2-Channel analog output terminal
Automation Interface
ITcSmTreeItem Item Sub Types: Modules: K-Bus
communication (KM6)
Sub type Description
6551 KM6551 IEEE802.15.4 terminal
838867463 KM6663 Ethernet changeover switch terminal
Automation Interface
ITcSmTreeItem::ProduceXml
The ProduceXml() method returns a XML string with item specific
information and
parameter.

HRESULT ProduceXml(
VARIANT_BOOL bRecursive,

BSTR* pXML);
Parameters
bRecursive
[in, defaultvalue(0)] Optional parameter for future use.
pXML
[out, retval] Contains the XML representation of the item
specific data and parameter.
Return Values
S_OK
function returns successfully.
E_POINTER
pXML pointer is invalid.
Comments
The following XML string is an incomplete example of the
resulting information if the tree item is a I/O device of the type
SERCOS Master/Slave FC750x. This string can be used as input
for the IXMLDOMDocument::loadXML method to create a XML DOM
document.
<?xml version="1.0"?>
<TreeItem>
<ItemName>Device 1 (FC750x)</ItemName>
<PathName>TIID^Device 1 (FC750x)</PathName>
<ItemType>2</ItemType>
<ItemId>1</ItemId>
<ItemSubType>48</ItemSubType>
<ItemSubTypeName>SERCOS Master/Slave FC750x, PCI
[Beckhoff FC7502 PCI]</ItemSubTypeName>
<ChildCount>0</ChildCount>
<Disabled>0</Disabled>
<DeviceDef>
<AmsPort>0</AmsPort>
<AddressInfo>
<Pci>
<BusNo>0</BusNo>
<SlotNo>16</SlotNo>
<IrqNo>9</IrqNo>
<FcChannel>0</FcChannel>
</Pci>
</AddressInfo>
<SercosMaster>
<Baudrate>0</Baudrate>
<OperationMode>0</OperationMode>
<SendPower>1</SendPower>
<AccessTime>200</AccessTime>
<ShiftTime>50</ShiftTime>
<StartupToPhase4>1</StartupToPhase4>
<CheckTiming>1</CheckTiming>
</SercosMaster>
</DeviceDef>
</TreeItem>
See also
ITcSmTreeItem::ConsumeXML


Automation Interface
ITcSmTreeItem::ConsumeXml
The ConsumeXml() method consumes a BSTR containing the XML
representation with item specific data and updates found parameters.
This method is used to change item parameters not directly accessible by
the ITcSmTreeItem interface.
HRESULT ConsumeXml(
BSTR bstrXML
);
Parameters
bstrXML
[in] string with the XML representation of the item specific parameter.
The corresponding parameter will be updated in the System
Manager database.
Return Values
S_OK
function returns successfully.
E_FAIL
the bstrXML string does not contain a valid xml document.
Comments
The document can only contain the specific parameter that should be
changed. The document structure has to fit to the item specific XML tree,
but parameter that should not be changed can be omitted. The following
document is a minimal example that can be used to change the specific
parameter CheckNumberBoxes of the item (in this case a C1220 fieldbus
card). If the parameters in the document are not known by the item, they
will be ignored.
<TreeItem><DeviceDef><DevC1220Def>
<CheckNumberBoxes>0</CheckNumberBoxes></DevC1220Def>
</DeviceDef></TreeItem>

The set of parameter of a specific tree item is defined in the xml schema
document that comes with the TwinCAT System Manager. The parameter
of a specific item can also evaluated by calling the
ITcSmTreeItem::ProduceXML method. The resulting xml string contains
all parameters of that item, but not all of them are changeable. The xml
string can contain any number and hierarchical order of xml elements
that are valid in terms of the xml schema. It is allowed to change only one
parameter at a time (like in the example above), change a set of
parameters at once or delivers the full parameter set that
ITcSmTreeItem::ProduceXML returns (normally with same parameters
changed).
There are some special xml elements that are not corresponding to
parameters, they will "execute" a function. An example is the <Rescan>
element of a PLC project tree item. The string:

<TreeItem><PlcDef><ReScan>1</ReScan></PlcDef></TreeItem>

as a parameter of ConsumeXml will cause the System Manager to
rescan the PLC project (like a manually rescan by pressing the "Rescan"
button on a PLC project). The parameters and the functions that are
available are documented in the xml schema file.

See also
ITcSmTreeItem::ProduceXML
Automation Interface
ITcSmTreeItem::CreateChild
Creates a child item on a parent
node . The child is being specified by
it's sub type .

HRESULT CreateChild(
BSTR


bstrName


,
long
nSubType
,
BSTR
bstrBefore
,
VARIANT


vInfo


,


ITcSmTreeItem**


pipItem


);


The following example
demonstrates this behavior in better detail.

In this example, an EK1100 coupler is being added to an EtherCAT


Master device (Device 1) in TwinCAT XAE. In Automation Interface, this
could be done with the CreateChild() method. The parent node (Device 1
EtherCAT) has the item type '2'
(TREEITEMTYPE_DEVICE). The sub type specifies the child item and
therefore the EK1100, which is sub type '9099' (BOXTYPE_EXXXXX).
Parameters
bstrName
[in] Item name of the new
child item.
nSubType
[in] S ub type of the
new child item. The usable sub type depends on the item type (the
category) of the parent tree item . For example, a PLC Functionblock
may only be added to the item type PLCFOLDER and not to a
DEVICE.
bstrBefore
[in,
defaultvalue("")] If set, the parameter contains the name
of another child item before that the new item should be
inserted.
vInfo
[in, optional] An optional
parameter with additional creation
information ,
which depends on the
sub
type . The different
dependencies are listed in the table below.
pipItem
[out, retval] Points to the location of a ITcSmTreeItem interface
pointer that receives the result.
Return Values
S_OK
function returns
successfully.
E_POINTER
the location of the
returning pointer is invalid
TSM_E_INVALIDITEMSUBTYPE
(0x98510003)
the given sub type is
invalid.
TSM_E_ITEMNOTFOUND
(0x98510001)
The item bstrBefore was not found.
Optional vInfo parameter
Depending on the item sub type of the new child item , some additional
information may be required to create the child item. This information c
an be provided via the
vInfo parameter.

Child: Item
sub type vInfo parameter(s)
E-Bus box / Contains the Identity Object (CoE 1018h,
terminal / VendorId, ProductCode and optional
RevisionNo and SerialNo) of the EtherCAT
module (item
sub type 9099) box. The type of the variant must be an array
of LONG
(VT_I4|VT_ARRAY, 2-4 elements).
Alternatively contains a BSTR of the following
formats (with %X = value in hex notation, e.g.
"V00000002_P044c2c52_R00000000"):
V%X_P%X_R%X_S%X
V%X_P%X_R%X
V%X_P%X

Especially for Beckhoff E-Bus terminals /


modules, please read the corresponding E-
Bus article.

Interbus box. Contains the


(item sub type
IdentCode and LengthCode of the Interbus
2002)
box. The type of the variant must be an
unsigned short (VT_I2), the low byte contains
the IdentCode the high byte the LengthCode.

AX2000 (item Optionally


sub type 5007) contains a bool value (VT_BOOL) and if set
CANDrive (item an additional variable for the `Following
sub type 5006) Error`will be created.

DeviceNET Optionally
(item sub type
contains the file path to an EDS file
5203)
(VT_BSTR).
TcDNSSlave
(item sub type
5250)
CX1500 (item
sub type 1042)
FC520X Slave
(item sub type
1043)
BK3000 and all Optionally contains the file path to an GSD
other file (VT_BSTR).
PROFIBUS box
types

Variable Optionally
contains the bit address of the new variable.
The type of the variant can be a SHORT or a
LONG (VT_I2 or VT_I4).

PLC POU Contains IEC language type as Integer, as


Functionblock defined by IECLANGUAGETYPES.
(item sub type
604)
PLC POU Contains a string[2] array, which hols the
Function (item following values:
sub type 603)
array[0] = IEC language type as
Integer, as defined by
IECLANGUAGETYPES.
array[1] = return data type of
function. May be any PLC data
type, for example DINT, BOOL, ...
Automation Interface
ITcSmTreeItem::DeleteChild
Deletes a child item.
HRESULT DeleteChild(
BSTR
bstrName
);
Parameters
bstrName
[in] Item name of the child item that should be deleted.
Return Values
S_OK
function returns successfully.
E_ACCESSDENIED
it is not allowed to delete the child item.
TSM_E_ITEMNOTFOUND (0x98510001)
The item bstrBefore was not found.
Automation Interface
ITcSmTreeItem::ImportChild
Imports a child item from the clipboard or a previously exported file.
HRESULT ImportChild(
BSTR bstrFile,
BSTR bstrBefore,
VARIANT_BOOL bReconnect,
BSTR bstrName,
ITcSmTreeItem** pipItem
);
Parameters
bstrFile
[in, defaultvalue(L"")] File name of the file from which the new child
will be imported. If no file name specified (empty string) the child will
be imported from the clipboard.
bstrBefore
[in, defaultvalue(L"")] If set, the parameter contains the name of
another child item in front of which the new item should be inserted.
If not set, the child will be appended at the end.
bReconnect
[in, defaultvalue(VARIANT_TRUE)] An optional flag that instructs the
System Manager to try to reconnect the variables from the imported
item to other variables in the configuration (by name).
bstrName
[in, defaultvalue(L"")] If set, overrides the child item name with its
name in the import file.
pipItem
[out, retval] Points to the location of a ITcSmTreeItem interface
pointer that receives the result.
Return Values
S_OK
function returns successfully.
NTE_NOT_FOUND (0x80090011)
the file can not be found/opened.
NTE_BAD_SIGNATURE (0x80090006)
the file does not contain a valid tree item.
TSM_E_MISMATCHINGITEMS (0x98510004)
the item in the file is not a valid child item.
Automation Interface
ITcSmTreeItem::ExportChild
Exports a child item to the clipboard or a file.
HRESULT ExportChild(
BSTR bstrName,
BSTR bstrFile
);
Parameters
bstrName
[in] Name of the child being exported.
bstrFile
[in, defaultvalue("")] File name of the file to which
the child will be exported. If no file name specified (empty
string) the child will be exported to the clipboard.
Return Values
S_OK
function returns successfully.
TSM_E_ITEMNOTFOUND (0x98510001)
The item bstrName was not found.
TwinCAT System Manager: Automation Reference
ITcSmTreeItem::LookupChild
Returns a ITcTreeItem pointer of a descendant child tree item given by
it's relative path name.
HRESULT LookupChild(BSTRbstrName, ITcSmTreeItem**pipItem);
Parameters
bstrName
[in] relative path of the tree item you are looking for. The relative path
name is required and each branch must be separated by a
circumflex accent '^' or a tab.
pipItem
[out, retval] points to the location of a ITcSmTreeItem interface
pointer on return. The interface pointer gives access to specific
methods belonging to the tree item.
Return Values
S_OK
function returns successfully.
TSM_E_ITEMNOTFOUND (0x98510001)
the path name does not qualify an existing tree item.
Comments
Automation Interface
ITcSmTreeItem2::ResourcesCount
For internal use only.
HRESULT ResourcesCount(
long* pnCount
);
Parameters
pnCount
[out,retval] Count of resources.
Return Values
S_OK
function returns successfully.
Comments
Automation Interface
ITcSmTreeItem::ChangeChildSubType
For internal use only.
HRESULT ChangeChildSubType(
BSTR bstrChild,
long nNewSubType,
VARIANT_BOOL bAggressive,
VARIANT vInfo,
ITcSmTreeItem2** pipItem
);
Parameters
bstrChild
[in]
nNewSubType
[in]
bAggressive
[in, defaultvalue(-1)]
vInfo
[in, optional]
pipItem
[out, retval]
Return Values
S_OK
function returns successfully.
TSM_E_ITEMNOTFOUND (0x98510001)
the path name does not qualify an existing tree item.
Comments
Automation Interface
ITcSmTreeItem2::ClaimResources
For internal use only.
HRESULT ClaimResources(
long resourceIdx
);
Parameters
resourceIdx
[in,defaultValue(1)]
Return Values
S_OK
function returns successfully.
Comments
Automation Interface
ITcSmTreeItem3::CompareItem
Compares the current ITcSmTreeItem with a specified second one for its
XML content (ProduceXml comparison). This comparison can be done
only for the specified nodes or for the whole subtree (recursive).
HRESULT CompareItem(

ITcSmTreeItem* pItem, VARIANT_BOOL bRecursive, long* pnRet

);
Parameters
pItem
[in] Reference to the ITcSmTreeItem to be compared with the current
ITcSmTreeItem.
bRecursive
[in, defaultvalue(0)] Indicates that the comparison should be
processed recursively for the whole subtree (Subtree comparison)
pnRet
[out, retval]: Return value: 0 for Equality, ret > 0 or ret < 0 for
InEquality.
Return Values
S_OK
Compare Item succeeded.
TwinCAT System Manager: Automation Reference


ITcSmTreeItem::GetLastXmlError
Gets the Item path / Error message of the last erroneous ConsumeXml
call.
HRESULT GetLastXmlError(BSTR *pXML);
Parameters
pXML
[out, retval] Error message.
Return Values
S_OK
function returns successfully.
Automation Interface
ITcPlcProject
The class ITcPlcProject enables developers to set properties for a PLC
project. It usually targets the root node of a PLC project, as shown in the
picture below:

The following C# code snippet shows an example about how this class
may be used in Automation Interface code: ITcSmTreeItem
plcProjectRootItem =
systemManager.LookupTreeItem("TIPC^PlcGenerated"); ITcPlcProject
iecProjectRoot = (ITcPlcProject)plcProjectRootItem;
iecProjectRoot.BootProjectAutostart = true;
iecProjectRoot.GenerateBootProject (true);
Please note: If you would like to compile a PLC project, please use the
compiler functionalities of the Visual Studio COM object EnvDTE, as
shown in many of our Samples.

Methods
ITcPlcProject Available
methods Description since
GenerateBootProject() Equals the entry TwinCAT 3.1
"Activate Boot project"
from the TwinCAT XAE
context menu

Properties
ITcPlcProject Available
properties Get/Set Description since
BootProjectAutoStart Yes / Equals the TwinCAT
Yes checkbox 3.1
"Autostart Boot
Project" in the
dialog shown
above
BootProjectEncryption Yes / Equals the TwinCAT
Yes dropdown box 3.1
"Encryption"
in the dialog
shown above

TmcFileCopy Yes / Equals the TwinCAT


Yes checkbox "Copy 3.1
TMC File to
Target" in the
dialog shown
above

Version information
Required TwinCAT version
This interface is supported in TwinCAT 3.1 and above

Automation Interface
ITcPlcProject::GenerateBootProject
Activates or deactivates the PLC project as a boot project, depending on
the bool parameter you specify.
HRESULT GenerateBootProject(
VARIANT_BOOL bActivate
);
Parameters
bActivate
[in, optional, defaultvalue(-1)] Specifies if the boot project should be
activated
Return Values
S_OK
Boot project successfully generated
Automation Interface
ITcPlcPou
To handle POUs and their content within a TwinCAT 3 project, the
interfaces ITcPlcPou, ITcPlcDeclaration and ITcPlcImplementation may
be used.
For example, if you would like to create a new function block for a
PLC project and fill it with code, you can use these interfaces to
do so. For more information, please refer to our best practise article
about "How to access and create PLC-Objects".
Properties
Get /
ITcPlcPou Available
Set
properties Description since
DocumentXml Yes / Gets/Sets PLC TwinCAT 3.1
Yes code of a POU in
XML format (not
PLCopen XML)

ReturnType Yes / No Return type of the TwinCAT 3.1


POU, for example
the return type of a
function. May be
any data
type known to the
PLC, for example
BOOL, DINT, ... .
The return
type is being set
when creating the
POU via the
CreateChild()
method.


Version information
Required TwinCAT version
This interface is supported
in TwinCAT 3.1 and above
Automation Interface
IECLanguageTypes
The enumeration IECLanguageTypes defines different
programming languages according to IEC standard and may be used
when creating a
new POU via the method ITcSmTreeItem::CreateChild().

Entry Value Description


IECLANGUAGE_NONE 0 ---
IECLANGUAGE_ST 1 Structured Text
IECLANGUAGE_IL 2 Instruction List
IECLANGUAGE_SFC 3 Sequential Function Chart
IECLANGUAGE_FBD 4 Function Block Diagram
IECLANGUAGE_CFC 5 Continous Function Chart
IECLANGUAGE_LD 6 Ladder Diagram


Automation Interface
ITcPlcDeclaration
The interface ITcPlcDeclaration provides access to the declaration area
of PLC POUs and their sub-nodes (like Actions, Methods, ...). Please
also see the best practice article "Handling PLC-Objects"
for more information about how to use this interface.
Properties (in VTable Order)
ITcPlcDeclaration Get / Available
properties Set Description since
DeclarationText Yes / Represents the TwinCAT 3.1
Yes declaration area of
the item and
gets/sets its
content in
cleartext

Version information
Required TwinCAT version
This interface is supported in TwinCAT 3.1 and above

Automation Interface
ITcPlcImplementation
The interface ITcPlcImplementation provides access to the
implementation area of PLC POUs and their sub-nodes (like Actions,
Methods, ...). Please also see the best practise article about "Handling
PLC-Objects"
for more information about how to use this interface.
Properties (in VTable Order)
Get
ITcPlcImplementation / Available
properties Set Description since
ImplementationText Yes Represents the TwinCAT
/ declaration area 3.1
Yes of the item and
gets/sets its
content in
cleartext
ImplementationXml Yes Gets/Sets the TwinCAT
/ content in XML 3.1
Yes format (not
PLCopen XML)
Language Yes Gets the IEC TwinCAT
/ No language used in 3.1
the
implementation
area

Version information
Required TwinCAT version
This interface is supported in TwinCAT 3.1 and above

Automation Interface
ITcPlcIECProject
The interface ITcPlcIECProject provides methods for importing
and exporting PLC projects according to the PlcOpen XML standard or
saving PLC projects as a PLC library. Compared to the TwinCAT XAE
GUI, this interface represents the following four options:
Methods (in VTable Order)
ITcPlcIECProject
methods
Description Available since
PlcOpenExport() Exports the TwinCAT 3.1
specified
tree nodes and
their content to a
PlcOpen conform
XML file

PlcOpenImport() Imports a PlcOpen TwinCAT 3.1


conform XML file
and its content

SaveAsLibrary() Saves the selected TwinCAT 3.1


PLC project as a
PLC library and
optionally also
installs it.


Version information
Required TwinCAT version
This interface is supported
in TwinCAT 3.1 and above


Automation Interface
PlcImportOptions
This enum contains the following options and is being used when
importing a
PlcOpen conform XML file via method
ITcPlcIECProject::PlcOpenImport().

Supported
Element Description By
PLCIMPORTOPTIONS_NONE --- TwinCAT
3.1
PLCIMPORTOPTIONS_RENAME In case the TwinCAT
imported 3.1
item
already
exists in the
PLC project,
it is
automatically
renamed

PLCIMPORTOPTIONS_REPLACE In case the TwinCAT


imported 3.1
item
already
exists in the
PLC project,
the existing
project is
being
replaced

PLCIMPORTOPTIONS_SKIP In case the TwinCAT


imported
3.1
item
already
exists in the
PLC project,
skip it



Automation Interface
ITcPlcIECProject::PlcOpenExport
Exports the specified tree nodes and their content to a PlcOpen conform
XML file. A path to the XML file and the tree nodes will be specified in a
parameter of this method.
HRESULT PlcOpenExport(
BSTR bstrFile
BSTR bstrSelection
);
Parameters
bStrFile
[in] : Path to the XML file bstrSelection
[in] : Selection of tree items which should be exported. The items are
separated by a semicolon, e.g. "POUs.FBItem1;POUs.FBItem2"
Return Values
S_OK
Items successfully exported into PlcOpen XML file.
Comments
Automation Interface
ITcPlcIECProject::PlcOpenImport
Imports a PlcOpen conform XML file and its content. A path to the XML
file will be passed to the method via a parameter.
HRESULT PlcOpenImport(
BSTR bstrFile,
int options,
BSTR bstrSelection,
VARIANT_BOOL bFolderStructure
);
Parameters
bstrFile
[in] : Path to the XML file.
options
[in, optional, defaultvalue(0)] : Options for import, according to enum
PLCIMPORTOPTIONS.
bstrSelection
[in, optional, defaultvalue("")] : Selects which items from the XML
structure should be imported bFolderStructure
[in, optional, defaultvalue(-1)] : If set to true (-1), the folder structure
of the imported objects remains the same, if this information is
available in the XML file
Return Values
S_OK
PlcOpen XML file successfully imported.
Automation Interface
ITcPlcIECProject::SaveAsLibrary
Saves the PLC project as a PLC library and optionally installs it.
HRESULT SaveAsLibrary(

BSTR bstrLibraryPath VARIANT_BOOL binstall );


Parameters
bStrLibraryPath
[in] : Path to the location where the PLC library should be saved to
binstall
[in] : set to "true" if PLC library should also be installed
Return Values
S_OK
PLC project successfully saved as a PLC library.
Automation Interface
ITcPlcLibraryManager
The ITcPlcLibraryManager interface extends the Automation
Interface by enabling access to PLC libraries of a TwinCAT 3
PLC project or PLC repositories of a TwinCAT system.
Methods (in VTable Order)
ITcPlcLibraryManager
methods Description Available since
AddLibrary() Adds a library TwinCAT 3.1
to a PLC
project.
AddPlaceholder() Adds a TwinCAT 3.1
placeholder to
a PLC project
InsertRepository() Creates a TwinCAT 3.1
repository,
which
represents a
logical
container for
several
libraries.

InstallLibrary() Installs a TwinCAT 3.1


library into a
repository.
MoveRepository() Changes the TwinCAT 3.1
position of the
repository in
the
repository
location list.

RemoveReference() Removes TwinCAT 3.1


library from the
PLC project.
RemoveRepository() Removes a TwinCAT 3.1
repository.
ScanLibraries() Returns a list TwinCAT 3.1
of all libraries
found in the
system. The
returned object
is of type
ITcPlcLibraries,
which is a
collection of
ITcPlcLibrary
objects.

SetEffectiveResolution() Sets the TwinCAT 3.1


Effective
Resolution of a
placeholder
UninstallLibrary() Uninstalls a TwinCAT 3.1
library from a
repository.
Properties (in VTable Order)
Get
ITcPlcLibraryManager / Available
properties Set Description since
References Yes Gets an object of type TwinCAT
/ 3.1
ITcPlcReferences,
No
which is a collection
of
ITcPlcLibrary or
ITcPlcPlaceholderRef
objects.
Represents a list of all
references added to
the PLC project.

Repositories Yes Gets an object of type TwinCAT


/ ITcPlcLibRepositories, 3.1
No which is a
collection of
ITcPlcLibRepository
objects.
Represents a list of all
currently configured
repositories.


Version information
Required TwinCAT version
This interface is supported
in TwinCAT 3.1 and above


Automation Interface
ITcPlcLibraryManager::AddLibrary
Adds a library to the PLC project. A library can either be added by its
attributes (Name, Version, Company) or by its display text.

HRESULT AddLibrary(

BSTR bstrLibName,

BSTR bstrVersion,

BSTR bstrCompany

);
Parameters
bstrLibName
[in] Library
name.
bstrVersion
[in, optional, defaultvalue("")]
Library version.
bstrCompany
[in, optional, defaultvalue("")]
Company which created the library.
Return Values
S_OK
Library successfully added..
Comments
Two common ways to add a PLC library are:
libraryManager.AddLibrary("Tc2_MDP",
"3.2.0.0", "Beckhoff Automation GmbH"); // Adding library via
its
attributes
libraryManager.AddLibrary("Tc2_MDP,
3.2.0.0 (Beckhoff Automation GmbH)"); // Adding library via its
display name

Where librayManager is an object of type ITcPlcLibraryManager.


Automation Interface
ITcPlcLibraryManager::InsertRepository
Adds a new library repository at the specified position. The position
represents the index at which the repositories is located in the repository
list in TwinCAT 3. In addition to the index, a repository is identified via its
name and path to a directory in the file system.
HRESULT InsertRepository(

BSTR bstrName, BSTR rootFolder, int iIndex

);
Parameters
bstrName
[in] Repository name.
rootFolder
[in] Path to repository (file system).
iIndex
[in] Indicates on which position the repository is located in the list of
repositories.
Return Values
S_OK
Repository successfully inserted
Comments
Automation Interface
ITcPlcLibraryManager::InstallLibrary
Installs a library into an existing library repository.
HRESULT InstallLibrary(

BSTR bstrRepositoryName, BSTR bstrLibPath, VARIANT_BOOL bOverwrite );


Parameters
bstrRepositoryName
[in] :
Name of repository, where the library should be inserted
bstrLibPath
[in] : Path to the library
bOverwrite
[in]
: If another library already exists, set this parameter to overwrite it
Return Values
S_OK
Library installation successful.
Comments
Automation Interface
ITcPlcLibraryManager::MoveRepository
Moves the repository to a new position in the list of repositories. The
position is marked by its index, which starts at 0.
HRESULT MoveRepository(

BSTR bstrRepositoryName, int iNewIndex );


Parameters
bstrRepositoryName
[in] :
Name of the repository
iNewIndex
[in] : Index of the repository
Return Values
S_OK
Comments
Automation Interface
ITcPlcLibraryManager::RemoveLibrary
Removes a library reference from the actual project. Please note that this
only
removes the reference, not the actual library file from the repository. For
this, the method UninstallLibrary() needs to be used. Similar to the
method AddLibrary(), a
library can be removed either by specifying its attributes (Name, Version,
Company) or display text.

HRESULT RemoveLibrary(

BSTR bstrLibName,

BSTR bstrVersion,

BSTR bstrCompany

);
Parameters
bstrLibName
[in] : Name of
library
bstrVersion
[in, optional, defaultvalue("")] :
bstrCompany
[in, optional, defaultvalue("")]
Return Values
S_OK
Comments
Two common ways to remove a PLC library are:
libraryManager.RemoveLibrary("Tc2_MDP",
"3.2.0.0", "Beckhoff Automation GmbH"); // Removing library
via
its attributes
libraryManager.RemoveLibrary("Tc2_MDP,
3.2.0.0 (Beckhoff Automation GmbH)"); // Removing library via
its
display name

Where librayManager is an object of type ITcPlcLibraryManager.


Automation Interface
ITcPlcLibraryManager::RemoveRepository
Removes a library repository. A repository is specified by its unique
name.
HRESULT RemoveRepository(
BSTR bstrName
);
Parameters
bstrName
[in] Name of repository.
Return Values
S_OK
Automation Interface
ITcPlcLibraryManager::ScanLibraries
Returns a collection of all registered libraries in all
repositories.

HRESULT ScanLibraries(

ITcPlcLibraries** ppEnumLibraries,

);
Parameters
ppEnumLibraries
[out, retval] Returns object of type ITcPlcLibraries, which is a
collection of
ITcPlcLibrary objects.
Return Values
S_OK
Comments
This method provides the same functionality as importing the
following XML structure via ConsumeXml() on the tree node
"Library Manager":

<TreeItem>
<PlcLibDef>
<ScanLibraries>
<Active>true</Active>
</ScanLibraries>
</PlcLibDef>
</TreeItem>
Automation Interface
ITcPlcLibraryManager::UninstallLibrary
Uninstalls a library from a repository.
HRESULT UninstallLibrary(

BSTR bstrRepositoryName, BSTR bstrLibraryName, BSTR bstrVersion, BSTR bstrDistribu


Parameters
bstrRepositoryName
[in] :
Name of repository
bstrLibraryName
[in] : Name of library
bstrVersion
[in,
optional] : Version of library
bstrDistributor
[in, optional] : Distributor of library
Return Values
S_OK
Comments
Automation Interface
ITcPlcLibrary
Represents a single PLC library when used with collection
ITcPlcLibraries and method
ITcPlcLibraryManager::ScanLibraries() or
property ITcPlcLibraryManager::References.

Properties (in VTable Order)
ITcPlcLibrary Get /
properties Set Description Available since
DisplayName Yes / Display name to TwinCAT 3.1
No identify library
in library list

Distributor Yes / Library creator TwinCAT 3.1


No
Name Yes / Library name TwinCAT 3.1
No
Version Yes / Library version TwinCAT 3.1
No

Version information
Required TwinCAT version
This interface is supported
in TwinCAT 3.1 and above


Automation Interface
ITcPlcLibraries
ITcPlcLibraries represents a collection of
ITcPlcLibrary objects, for example when using
method ITcPlcLibraryManager::ScanLibraries()
or property ITcPlcLibraryManager::Libraries.
Methods (in VTable Order)
ITcPlcLibraries
methods
Description Available since
get_Item() Returns item TwinCAT 3.1
of type
ITcPlcLibrary
which
is located on
a specified
position.
Properties (in VTable Order)
ITcPlcLibraries Get /
properties Set Description Available since
Count Yes / Returns the TwinCAT 3.1
No amount of
ITcPlcLibrary
objects in the
collection


Version information
Required TwinCAT version
This interface is supported
in TwinCAT 3.1 and above


Automation Interface
ITcPlcLibraries::get_Item
Returns ITcPlcLibrary object on specified position.
HRESULT AddLibrary(
long n,
ITcPlcLibrary** pipType
);
Parameters
n
[in] Position of item in list.
pipType
[out, retval] Returns object of type ITcPlcLibrary
Return Values

Comments
Automation Interface
ITcPlcLibRepository
The ITcPlcLibRepository interface represents a single repository, for
example when used with collection ITcPlcLibRepositories and property
ITcPlcLibraryManager::Repositories.
Properties
ITcPlcLibRepository Get / Available
properties Set Description since
Folder Yes / Path to TwinCAT 3.1
No repository (file
system)
Name Yes / Repository TwinCAT 3.1
No name.

Version information
Required TwinCAT version
This interface is supported in TwinCAT 3.1 and above

Automation Interface
ITcPlcLibRepositories
ITcPlcLibraries represents a collection of
ITcPlcLibRepository objects, for example when using property
ITcPlcLibraryManager::Repositories.
Methods (in VTable Order)
ITcPlcLibRepositories
methods
Description Available since
get_Item() Returns item of TwinCAT 3.1
type
ITcPlcLibRepository
which is located on
a specified position.
Properties (in VTable Order)
Get
ITcPlcLibRepositories / Available
properties Set Description since
Count Yes Returns the amount TwinCAT
/ of 3.1
No ITcPlcLibRepository
objects in the
collection

Version information
Required TwinCAT version
This interface is supported in TwinCAT 3.1 and above

TwinCAT 3: Automation Interface


ITcPlcLibRepositories::get_Item
Returns ITcPlcLibRepository object on specified position.
HRESULT AddLibrary(
long n,
ITcPlcLibRepository** ppRepo
);
Parameters
n
[in] Position of item in list.
pipType
[out, retval] Returns object of type ITcPlcLibRepository
Return Values

Comments

Automation Interface
ITcPlcTaskReference
The ITcPlcTaskReference interface enables programmers to get or set
the currently linked task of a PLC project. This matches the following
TwinCAT XAE entry:
Properties (in VTable Order)
Get /
ITcPlcTaskReference Available
Set
properties Description since
LinkedTask Yes / Gets or sets the TwinCAT
Yes linked task of a 3.1
PLC project.
When setting a
new linked task,
the task will be
specified as a
string which
represents the
path to the task
in the TwinCAT
XAE tree.

TwinCAT System Manager: Automation - Samples
Samples

Programming
Description language Download
Sample 1: Adding C++ SysManSamples.exe (Self extracting)
of Additional Tasks
and Variables;
TwinCAT Start /
Stop
Sample 2: C# SysManSamples.zip
OpenConfiguration
and
CloseConfiguration,
Scan Devices,
Scan Boxes, Scan
Terminals, Adding
EtherCAT Devices,
Import/Export
Sample 3: Linking a C# LinkPLCProjectTC2.zip
PLC project
PowerShell LinkPLCProjectTC2_PS.zip

Sample 4: C# ActivatePreviousConfigurationTC2.zip
Activating a
PowerShell ActivatePreviousConfigurationTC2_PS.zip
configuration
IronPython ActivatePreviousConfigurationTC2_PY.zip
Sample 5: Linking C# LinkVariablesTC2.zip
PLC variables to IO
PowerShell LinkVariablesTC2_PS.zip
IronPython LinkVariablesTC2_PY.zip

Sample 6: Activate C# ActivateConfigurationRemoteTC2.zip


configuration on a
PowerShell ActivateConfigurationRemoteTC2_PS.zip
remote target
IronPython ActivateConfigurationRemoteTC2_PY.zip

Sample 7: Creating C# EtherCATLinkingTC2.zip


System Manager
PowerShell EtherCATLinkingTC2_PS.zip
project with multiple
EtherCAT boxes, IronPython EtherCATLinkingTC2_PY.zip
including PLC and
IO linking (very
detailed sample)
Sample 8: C# ScanBoxesTC2.zip
Scanning for new
devices and boxes

Sample 9: Adding C# AddingRoutesTC2.zip


an ADS route to a
remote target







TwinCAT System Manager: Automation - How to...
How to
Instead of downloadable sample code which comes included in a Visual
Studio project, this section provides code snippets for several tasks.
Please note that many code snippets are also included in some way or
another in one of our sample code downloads, which should allow you to
understand its usage in an overall picture.

How To
How to - Activate a previously created configuration

How to - Link variables

How to - Unlink variables

How to - Disable/enable a tree item (e.g. an I/O device)

How to - Change the path to a plc project and/or rescan the


project

How to - Change the fieldbus address (station no.) of a profibus


box

How to - Export/import the information of a child of a tree item

How to - Enumerate through the child's of a tree item

How to - Add child items (devices, boxes, terminals, variables


etc.)

How to - Update the address information of I/O devices

How to - Create/change a linkage of a nc axis, encoder or drive


to an I/O device, box or terminal

How to - Exchange a fieldbus device and move all childs to the


new one
How to - Add a route to a remote ADS target
How to - Execute a broadcast search

TwinCAT System Manager: Automation - How To...

[This is preliminary documentation and subject to change.]


How to activate a previously created
configuration
To activate a previously created configuration, an instance of the
TwinCAT System Manager has to be created, the configuration has to be
loaded and activated.
Procedure
The ProgId "TCatSysManager.TcSysManager" can be used to create
an instance of the System Manager that implements the ITcSysManager
interface. This interface allows same basic operations with TwinCAT
configurations.

Sample (vbscript):
dim tsm
set tsm = CreateObject("TCatSysManager.TcSysManager")
call tsm.OpenConfiguration("c:\twincat\myConfig.wsm")
call tsm.ActivateConfiguration

Sample (javascript):
var tsm
tsm = ActiveXObject("TCatSysManager.TcSysManager");
tsm.OpenConfiguration("c:\twincat\myConfig.wsm");
tsm.ActivateConfiguration();
See Also
How to... section, ITcSysManager

Built on Tuesday, Mai 01, 2001
TwinCAT System Manager: Automation - How To...

[This is preliminary documentation and subject to change.]


How to link variables
To link variables in a configuration, an instance of the TwinCAT System
Manager has to be created and the two variables has to be referenced by
there pathnames.
Procedure
The ProgId "TCatSysManager.TcSysManager" can be used to create
an instance of the System Manager that implements the ITcSysManager
interface. This interface has a LinkVariables method. To link the two
variables "TIPC^Project 1^Standard^Outputs^MyOutput" and
"TIID^Device 1 (C220)^Box 1^Term 1^Channel 1^Output" the following
vbscript code can be used:

Sample (vbscript):
dim tsm
set tsm = CreateObject("TCatSysManager.TcSysManager")
call tsm.OpenConfiguration("c:\twincat\myConfig.wsm")
call tsm.LinkVariables("TIPC^Project 1^Standard^Outputs^MyOutput",
"TIID^Device 1 (C220)^Box 1^Term 1^Channel 1^Output")
call tsm.SaveConfiguration
If the two variables have different sizes, the LinkVariables method has
three further optional parameters to specify which bits and bytes are to
be linked together.
See Also
How to... section, ITcSysManager, ITcSysManager::LinkVariables

Built on Tuesday, Mai 01, 2001
TwinCAT System Manager: Automation - How To...

[This is preliminary documentation and subject to change.]


How to unlink variables
To unlink variables in a configuration, an instance of the TwinCAT System
Manager has to be created and the two variables to be unlinked from
each other have to be referenced by their pathnames. An alternative is to
reference only to one variable and all linkages of that variable will be
removed.
Procedure
The ProgId "TCatSysManager.TcSysManager" can be used to create
an instance of the System Manager that implements the ITcSysManager
interface. This interface has an UnlinkVariables method. To unlink the
variable "TIPC^Project 1^Standard^Outputs^MyOutput" from
"TIID^Device 1 (C220)^Box 1^Term 1^Channel 1^Output" the following
vbscript code can be used:

Sample (vbscript):
dim tsm
set tsm = CreateObject("TCatSysManager.TcSysManager")
call tsm.OpenConfiguration("c:\twincat\myConfig.wsm")
call tsm.UnlinkVariables("TIPC^Project 1^Standard^Outputs^MyOutput",
"TIID^Device 1 (C220)^Box 1^Term 1^Channel 1^Output")
call tsm.SaveConfiguration
If all linkages from "TIPC^Project 1^Standard^Outputs^MyOutput" should
be removed, the following code can be used:

dim tsm
set tsm = CreateObject("TCatSysManager.TcSysManager")
call tsm.OpenConfiguration("c:\twincat\myConfig.wsm")
call tsm.UnlinkVariables("TIPC^Project 1^Standard^Outputs^MyOutput")
call tsm.SaveConfiguration
See Also
How to... section, ITcSysManager, ITcSysManager::UnlinkVariables

Built on Tuesday, Mai 01, 2001
TwinCAT System Manager: Automation -
How To...

[This is preliminary documentation


and subject to change.]
How to disable/enable a tree item (e.g. an I/O
device)
To disable/enable a tree item in a configuration, an instance of the
TwinCAT
System Manager has to be created and the configuration has to be
opened. The LookupTreeItem method of the ITcSysManager interface
returns
a ITcSmTreeItem interface pointer implemented
by the tree item referenced by its pathname.
This interface contains a Disabled property of the tree item.
Procedure
The ProgId "TCatSysManager.TcSysManager" can be used to
create an instance of the System Manager that implements the
ITcSysManager interface. This interface has a LookupTreeItem method
that returns a ITcSmTreeItem pointer to a
specific tree item given by its pathname. To disable/enable the
tree item "TIID^Device 1 (C1220)" the following
vbscript code can be used:

Sample (vbscript):
dim tsm
dim item
set tsm = CreateObject("TCatSysManager.TcSysManager")
call tsm.OpenConfiguration("c:\twincat\myConfig.wsm")
set item = tsm.LookupTreeItem("TIID^Device 1 (C220)")
item.Disabled = SMDS_DISABLED '(or item.Disabled =
SMDS_NOT_DISABLED to enable
the tree item)
call tsm.SaveConfiguration
See Also
How to... section, ITcSysManager,
LookupTreeItem, ITcSmTreeItem,
Disabled

Built on Tuesday, Mai 01, 2001
TwinCAT System Manager: Automation - How To...

[This is preliminary documentation and subject to change.]


How to change the path to a plc project and/or
rescan the project
To change the path to a plc project and/or rescan the project in a
configuration, an instance of the TwinCAT System Manager has to be
created and the configuration has to be opened. The LookupTreeItem
method of the ITcSysManager interface returns a ITcSmTreeItem
interface pointer implemented by the tree item referenced by its
pathname. This interface contains a ConsumeXml method of the tree
item.
Procedure
The ProgId "TCatSysManager.TcSysManager" can be used to create
an instance of the System Manager that implements the ITcSysManager
interface. This interface has a LookupTreeItem method that returns a
ITcSmTreeItem pointer to a specific tree item given by its pathname. To
change the path to a plc project and rescan the project "TIPC^MyProject"
the following vbscript code can be used:

Sample (vbscript):
dim tsm
dim item
set tsm = CreateObject("TCatSysManager.TcSysManager")
call tsm.OpenConfiguration("c:\twincat\myConfig.wsm")
set item = tsm.LookupTreeItem("TIPC^MyProject")
call item.ConsumeXml("<TreeItem><PlcDef>
<ProjectPath>c:\twincat\plc\NewProject.pro</ProjectPath>
<ReScan>1</ReScan></PlcDef></TreeItem>")
call tsm.SaveConfiguration
The next sample just rescans the current project:

dim tsm
dim item
set tsm = CreateObject("TCatSysManager.TcSysManager")
call tsm.OpenConfiguration("c:\twincat\myConfig.wsm")
set item = tsm.LookupTreeItem("TIPC^MyProject")
call item.ConsumeXml("<TreeItem><PlcDef><ReScan>1</ReScan></PlcDef>
</TreeItem>")
call tsm.SaveConfiguration

See Also
How to... section, ITcSysManager, LookupTreeItem, ITcSmTreeItem,
ConsumeXml

Built on Tuesday, Mai 01, 2001
TwinCAT System Manager: Automation -
How To...

[This is preliminary documentation


and subject to change.]
How to change the fieldbus address (station no.)
of a profibus box
To change the the fieldbus address (station no.) of a profibus box in a
configuration, an instance of the TwinCAT
System Manager has to be created and the configuration has to be
opened. The LookupTreeItem method of the ITcSysManager interface
returns
a ITcSmTreeItem interface pointer implemented
by the tree item referenced by its pathname.
This interface contains a ConsumeXml method of the tree item.
Procedure
The ProgId "TCatSysManager.TcSysManager" can be used to
create an instance of the System Manager that implements the
ITcSysManager interface. This interface has a LookupTreeItem method
that returns a ITcSmTreeItem pointer to a
specific tree item given by its pathname. To change the
the fieldbus address (station no.) of a profibus box "TIID^Device 1
(FC310x)^Box 1 (BK3100)" to 44 the following
vbscript code can be used:

Sample (vbscript):
dim tsm
dim item
set tsm = CreateObject("TCatSysManager.TcSysManager")
call tsm.OpenConfiguration("c:\twincat\myConfig.wsm")
set item = tsm.LookupTreeItem("TIID^Device 1 (FC310x)^Box 1 (BK3100)")
call item.ConsumeXml("<TreeItem><BoxDef>
<FieldbusAddress>44</FieldbusAddress></BoxDef></TreeItem>")
call tsm.SaveConfiguration
See Also
How to... section, ITcSysManager,
LookupTreeItem, ITcSmTreeItem,
ConsumeXml

Built on Tuesday, Mai 01, 2001
TwinCAT System Manager: Automation - How To...

[This is preliminary documentation and subject to change.]


How to export/import the information of a child of
a tree item
To export/import the information of a child of a tree item in a
configuration, an instance of the TwinCAT System Manager has to be
created and a configuration has to be opened. The LookupTreeItem
method of the ITcSysManager interface returns a ITcSmTreeItem
interface pointer implemented by the parent tree item referenced by the
parents pathname. This interface contains a ExportChild and a
ImportChild method of the tree item.
Procedure
The ProgId "TCatSysManager.TcSysManager" can be used to create
an instance of the System Manager that implements the ITcSysManager
interface. This interface has a LookupTreeItem method that returns a
ITcSmTreeItem pointer to a specific tree item given by its pathname. To
export the information of a tree item "TIID^Device 1 (FC310x)^Box 1
(BK3100)" the following vbscript code can be used:

Sample (vbscript):
dim tsm
dim item
set tsm = CreateObject("TCatSysManager.TcSysManager")
call tsm.OpenConfiguration("c:\twincat\myConfig.wsm")
set item = tsm.LookupTreeItem("TIID^Device 1 (FC310x)")
call item.ExportChild("Box 1 (BK3100)", "c:\twincat\box1.tce")
To import the information of a tree item as a child of "TIID^Device 1
(FC310x)" the following vbscript code can be used:

dim tsm
dim item
set tsm = CreateObject("TCatSysManager.TcSysManager")
call tsm.OpenConfiguration("c:\twincat\myConfig.wsm")
set item = tsm.LookupTreeItem("TIID^Device 1 (FC310x)")
call item.ImportChild("c:\twincat\box1.tce")
The ImportChild method has same optional parameters that are
described in the documentation of that method.
See Also
How to... section, ITcSysManager, LookupTreeItem, ITcSmTreeItem,
ExportChild, ImportChild

Built on Tuesday, Mai 01, 2001
TwinCAT System Manager: Automation -
How To...

[This is preliminary documentation


and subject to change.]
How to enumerate through the child's of a tree
item
To enumerate through the childs of a tree item in a configuration, an
instance of the TwinCAT
System Manager has to be created and a configuration has to be
opened. The LookupTreeItem method of the ITcSysManager interface
returns
a ITcSmTreeItem interface pointer implemented
by the tree item referenced by its pathname.
This interface contains two ways of child enumeration. The first one is the
_NewEnum property that is automatically used by the VB ForEach
statement and enumerates
over all childs of a tree item. This includes for example the process image
child and the input and output childs of an I/O device. The second way is
to
use the ChildCount and Child(i) property that allows to enumerate over
the "main" child (e.g. only
over the I/O boxes of an I/O device).
Procedure
The ProgId "TCatSysManager.TcSysManager" can be used to
create an instance of the System Manager that implements the
ITcSysManager interface. This interface has a LookupTreeItem method
that returns a ITcSmTreeItem pointer to a
specific tree item given by its pathname. To enumerate through the
all childs of a tree item "TIID^Device 1
(FC310x)^Box 1 (BK3100)" the following
vbscript code can be used:

Sample (vbscript):
dim tsm
dim item
dim str
dim itemChild
set tsm = CreateObject("TCatSysManager.TcSysManager")
call tsm.OpenConfiguration("c:\twincat\myConfig.wsm")
set item = tsm.LookupTreeItem("TIID^Device 1 (FC310x)")
For Each Child In item
Set itemChild = Child
str = itemChild.Name
Next Child
To enumerate only through the main childs of a tree item "TIID^Device 1
(FC310x)^Box 1 (BK3100)" the following
vbscript code can be used:
dim tsm
dim item
dim str
set tsm = CreateObject("TCatSysManager.TcSysManager")
call tsm.OpenConfiguration("c:\twincat\myConfig.wsm")
set item = tsm.LookupTreeItem("TIID^Device 1 (FC310x)")
For i = 1 To item.ChildCount
str = item.Child(i).Name
Next
See Also
How to... section, ITcSysManager,
LookupTreeItem, ITcSmTreeItem,
_NewEnum, ChildCount,
Child(i)

Built on Tuesday, Mai 01, 2001
TwinCAT System Manager: Automation - How To...

[This is preliminary documentation and subject to change.]


How to add child items (devices, boxes,
terminals, variables etc.)
To add child items (devices, boxes, terminals, variables etc.) in a
configuration, an instance of the TwinCAT System Manager has to be
created and a configuration has to be opened. The LookupTreeItem
method of the ITcSysManager interface returns a ITcSmTreeItem
interface pointer implemented by the parent tree item referenced by the
parents pathname. This interface contains a CreateChild method.
Procedure
The ProgId "TCatSysManager.TcSysManager" can be used to create
an instance of the System Manager that implements the ITcSysManager
interface. This interface has a LookupTreeItem method that returns a
ITcSmTreeItem pointer to a specific tree item given by its pathname. To
add a child item to a tree item "TIID^Device 1 (FC310x)" the following
vbscript code can be used:

Sample (vbscript):
dim tsm
dim item
dim str
dim itemChild
set tsm = CreateObject("TCatSysManager.TcSysManager")
call tsm.OpenConfiguration("c:\twincat\myConfig.wsm")
set item = tsm.LookupTreeItem("TIID^Device 1 (FC310x)")
call item.CreateChild("Box 1 (BK3100)", BOXTYPE_BK3100)
The tree item type of the child is implicit given by the parent type (e.g.
child of I/O devices are always I/O boxes, child of bus couplers are
always terminals...). The item sub type has to be specified as a
parameter of CreateChild. The CreateChild method has same optional
parameters that are described in the documentation of that method.

Optional CreateChild() parameter 'vInfo':


See CreateChild.
See Also
How to... section, ITcSysManager, LookupTreeItem, ITcSmTreeItem,
CreateChild

Built on Tuesday, Mai 01, 2001
TwinCAT System Manager: Automation - How To...

[This is preliminary documentation and subject to change.]


How to update the address information of I/O
devices
To update the address information of I/O devices in a configuration, an
instance of the TwinCAT System Manager has to be created and a
configuration has to be opened. A call to the ProduceXml method of the
"I/O devices" tree item retrieves the current address information of all
installed I/O devices (internally by calling the scan devices function).
These address information can be used to update a specific I/O device in
the configuration.
Procedure
The ProgId "TCatSysManager.TcSysManager" can be used to create
an instance of the System Manager that implements the ITcSysManager
interface. This interface has a LookupTreeItem method that returns a
ITcSmTreeItem pointer to the "I/O Devices" tree item (use the
abbreviation "TIID").

Sample (vbscript):
Set tsm = CreateObject("TCatSysManager.TcSysManager")
Call tsm.OpenConfiguration("c:\test.wsm")
Set Item = tsm.LookupTreeItem("TIID")
Set xml = CreateObject("Msxml.DOMDocument")
The following call to Item.ProduceXml scans the installed I/O devices
(among other things) and returns a XML string that contains these
information that will be stored in the XML document by the method
xml.loadXml.

Call xml.loadXml(Item.ProduceXml)
The following line sets a DOM node list object that contains all found
devices as DOM nodes

Set devs = xml.selectNodes("TreeItem/DeviceGrpDef/FoundDevices/Device")


For i = 0 To devs.length - 1
If the ItemSubType of the device corresponds to the type of device to
update...

If devs(i).selectSingleNode("ItemSubType").nodeTypedValue = 48 Then ' 48


= IODEVICETYPE_FC7500
The AddressInfo node of that device will be extracted
Set ainfo = devs(i).selectSingleNode("AddressInfo") A ITcSmTreeItem
pointer of that device in the configuration will be evaluated

Set dev = tsm.LookupTreeItem("TIID^MyDev") And finally the address info


will be stored to the device

Call dev.ConsumeXml(ainfo.xml)
Call tsm.SaveConfiguration
Exit For
End If
Next
See Also
How to... section, ITcSysManager, LookupTreeItem, ITcSmTreeItem,
ConsumeXml, ProduceXml

Built on Tuesday, Mai 01, 2001
TwinCAT System Manager: Automation - How To...

[This is preliminary documentation and subject to change.]


How to create/change a linkage of a nc axis,
encoder or drive to an I/O device, box or terminal
To create/change a linkage of a nc axis, encoder or drive to an I/O
device, box or terminal in a configuration, an instance of the TwinCAT
System Manager has to be created and a configuration has to be
opened.
Procedure
The ProgId "TCatSysManager.TcSysManager" can be used to create
an instance of the System Manager that implements the ITcSysManager
interface.

Sample (vbscript):
Set tsm = CreateObject("TCatSysManager.TcSysManager")
Call tsm.OpenConfiguration("c:\test.wsm")
Set Item = tsm.LookupTreeItem("TINC^NC-Task 1 SAF^Axes^Axis 1")
Call Item.ConcumeXml("<TreeItem><NcAxisDef><IoItem>
<PathName>TIID^Device 1 (FC750x)^Box 1 (Sercos Axis)</PathName>
</IoItem></NcAxisDef></TreeItem>")

See Also
How to... section, ITcSysManager, LookupTreeItem, ITcSmTreeItem,
ConsumeXml

Built on Tuesday, Mai 01, 2001
TwinCAT System Manager: Automation -
How To...

[This is preliminary documentation


and subject to change.]
How to exchange a fieldbus device and move all
childs to the new one
To exchange a fieldbus device and move all childs to the new one, an
instance of the TwinCAT
System Manager has to be created and a configuration has to be
opened. The LookupTreeItem method of the ITcSysManager interface
returns
a ITcSmTreeItem interface pointer implemented
by the old fieldbus device.
This interface contains a ExportChild and a ImportChild method of the
tree item.
Procedure
The ProgId "TCatSysManager.TcSysManager" can be used to
create an instance of the System Manager that implements the
ITcSysManager
interface.

Sample (vbscript):
set tsm = CreateObject("TCatSysManager.TcSysManager")
call tsm.OpenConfiguration("c:\exchange.wsm")
set item = tsm.LookupTreeItem("TIID")
set itemNew = item.CreateChild("Device 2 (FC310x)", 38)
set itemOld = tsm.LookupTreeItem("TIID^Device 1 (CP5412)")
for i = 1 to itemOld.ChildCount
call itemOld.ExportChild(itemOld.Child(i).Name)
call itemNew.ImportChild()
next
set itemOld = nothing
call item.DeleteChild("Device 1 (CP5412)")
call tsm.SaveConfiguration("c:\exchange2.wsm")
See Also
How to... section, ITcSysManager,
LookupTreeItem, ITcSmTreeItem,
ExportChild, ImportChild

Built on Tuesday, Mai 01, 2001
Automation Interface
How to scan devices and boxes
When creating a new configuration it is often necessary to align the
TwinCAT XAE configuration to the actually available hardware. One
option to fullfill this is to start a new TwinCAT XAE
configuration from scratch and process the following steps:
Creation of a new TwinCAT XAE configuration
Setting the address of the target system
Scan of the available devices
Addition and parametrization of the devices to be used
Scanning and insertion of boxes for each device
Procedure
The procedure to create the ITcSysManager interface (the
'systemManager' instance here) is described in the chapter Accessing
TwinCAT Configurations. This interface has a LookupTreeItem method
that returns a ITcSmTreeItem pointer to a specific tree item given by its
pathname, in this case the shortcut "TIID" which references the I/O
devices node.
Code snippet (C#):
ITcSysManager3 systemManager = null; // How to create the System Manager instance and h

public void ScanDevicesAndBoxes()

systemManager.SetTargetNetId("1.2.3.4.5.6"); // Setting of the target NetId.

ITcSmTreeItem ioDevicesItem = systemManager.LookupTreeItem("TIID"); // Get The

// Scan Devices (Be sure that the target system is in Config mode!) string scannedXml =

XmlDocument xmlDoc = newXmlDocument(); xmlDoc.LoadXml(scannedXml); // Loa

int deviceCount = 0;

// Add all found devices to configuration foreach (XmlNode node in xmlDeviceList) {


// Add a selection or subrange of devices int itemSubType = int.Parse(node.Select

ITcSmTreeItem device = ioDevicesItem.CreateChild(string.Format("Device_{0}"

string xml = string.Format("<TreeItem><DeviceDef>{0}</DeviceDef></TreeItem

// Scan all added devices for attached boxes foreach (ITcSmTreeItem device in devices)

string xml = "<TreeItem><DeviceDef><ScanBoxes>1</ScanBoxes></DeviceDef

try

device.ConsumeXml(xml); // Consume starts the ScanBoxes and inserts eve

catch (Exception ex)

Console.WriteLine("Warning: {0}",ex.Message); }

foreach (ITcSmTreeItem box in device) {


Console.WriteLine(box.Name); }


Code snippet (IronPython):

import xml.etree.ElementTree as ET

# Create the System Manage instance “sysMan” first


ioDevicesItem = sysMan.LookupTreeItem("TIID") # Get the IO Devices Node
scannedXml = ioDevicesItem.ProduceXml(False) # Produce Xml implicitly starts the ScanD

xmlDoc = ET.fromstring(scannedXml) # Loads the Xml data into an XML Document


xmlDeviceList = xmlDoc.findall("./DeviceGrpDef/FoundDevices/Device")
devices = [] # Container to store Scanned devices
deviceCount = 0

# Add the Scanned devices


for device in xmlDeviceList:
typeName = device.findtext("ItemSubTypeName")
itemSubType = device.findtext("ItemSubType")
xmlAddress = device.find("AddressInfo")
deviceCount = deviceCount + 1;
device = ioDevicesItem.CreateChild("Device_" + str(deviceCount) + typeName, itemS
xml = "<TreeItem><DeviceDef>" + ET.tostring(xmlAddress) + "</DeviceDef></TreeItem
device.ConsumeXml(xml); # Consumes Xml Parameters (here the Address of the Device)
devices.append(device);
for device in devices:
xml = "<TreeItem><DeviceDef><ScanBoxes>true</ScanBoxes></DeviceDef></TreeIte
try:
print device.ConsumeXml(xml) # Consumes starts the ScanBoxes and inserts every fou
except:
print "Scan Failed!"

for box in device:


print box.Name
TwinCAT System Manager: Automation - How To...
How to add routes to a remote ADS device
Adding ADS routes via the Automation Interface can be achieved by
using the ConsumeXml() method. However, it is important to understand
the underlying XML structure before adding routes to a remote target.
XML structure
The following snippet is a sample XML structure for adding routes to a
remote target. Please note that you can either specify the IP address or
the hostname of the remote target.
<TreeItem>
<ItemName>Route Settings</ItemName>
<PathName>TIRR</PathName>
<RoutePrj>
<TargetList>
<BroadcastSearch>true</BroadcastSearch> <!-- Triggers
Broadcast search -->
</TargetList>
<AddRoute>
<RemoteName>RouteName</RemoteName> <!-- Description of
the route on the remote device, can be any name -->
<RemoteNetId>1.2.3.4.5.6</RemoteNetId> <!-- AdsNetID of the
remote device -->
<RemoteIpAddr>1.2.3.4</RemoteIpAddr> <!-- IP Address of the
remote target -->
<!-- or -->
<RemoteHostName>hostName</RemoteHostName> <!--
Hostname of the remote target -->
<UserName>userName</UserName> <!-- Username used to
connect to remote device -->
<Password>password</Password> <!-- Password used to
connect to remote device -->
<NoEncryption></NoEncryption> <!-- Encrypt password -->
<LocalName>LocalName</LocalName> <!-- Description of the
route on the local device, can be any name-->
</AddRoute>
<AddProjectRoute> <!-- Use for adding a project route -->
<Name>RouteName</Name> <!-- Description of the route on the
local device, can be any name-->
<NetId>1.2.3.4.5.6</NetId> <!-- AdsNetID of the remote device --
>
<HostName>hostName</HostName> <!-- Hostname of the
remote target -->
<!-- or -->
<IpAddr>1.2.3.4</IpAddr> <!-- IP Address of the remote target -->
</AddProjectRoute>
</RoutePrj>
</TreeItem>

Sample (C#):
The following code snippet can also be downloaded in our sample
section (Sample 13). It consumes the following XML structure on the
node "Route Settings":
<TreeItem>
<ItemName>Route Settings</ItemName>
<PathName>TIRR</PathName>
<RoutePrj>
<TargetList>
<BroadcastSearch>true</BroadcastSearch>
</TargetList>
<AddRoute>
<RemoteName>RouteName</RemoteName>
<RemoteNetId>10.1.128.217.1.1</RemoteNetId>
<RemoteIpAddr>10.1.128.217</RemoteIpAddr>
<UserName>Administrator</UserName>
<Password>1</Password>
<NoEncryption></NoEncryption>
<LocalName>LocalName</LocalName>
</AddRoute>
</RoutePrj>
</TreeItem>
Please adapt the NetIds and IP addresses to your needs.
class Program
{
private static string _tsmPath = "C:\\Temp\\Sample.tsm";
private static TcSysManager _sysManager;

static void Main(string[] args)
{
_sysManager = new TcSysManager();
_sysManager.NewConfiguration();

string xmlString = "<TreeItem><ItemName>Route Settings</ItemName>
<PathName>TIRR</PathName><RoutePrj><TargetList>
<BroadcastSearch>true</BroadcastSearch></TargetList><AddRoute>
<RemoteName>RouteName</RemoteName>
<RemoteNetId>10.1.128.217.1.1</RemoteNetId>
<RemoteIpAddr>10.1.128.217</RemoteIpAddr>
<UserName>Administrator</UserName><Password>1</Password>
<NoEncryption></NoEncryption></AddRoute></RoutePrj></TreeItem>";
ITcSmTreeItem routesNode = _sysManager.LookupTreeItem("TIRR");
routesNode.ConsumeXml(xmlString);

_sysManager.SaveConfiguration(_tsmPath);
}
}
See Also
How to... section, ITcSysManager, LookupTreeItem, ITcSmTreeItem,
ConsumeXml
TwinCAT
System Manager: Automation - How to...
How to execute a broadcast search
To find unknown remote ADS devices, a broadcast search needs to be
executed. This can be done by making use of the ConsumeXml() and
ProduceXml() methods of the TwinCAT Automation Interface.

Sample (C#):
class Program
{

private static string _tsmPath =


Path.GetDirectoryName(Assembly.GetEntryAssembly().Location) +
"\\Templates\\Sample.tsm";

private static TcSysManager _sysManager;

static void Main(string[] args)

_sysManager = new TcSysManager();

_sysManager.NewConfiguration();

/* ==============================================
* XML String as shown above

* ============================================== */
string xmlString = "<TreeItem><RoutePrj><TargetList>
<BroadcastSearch>true</BroadcastSearch></TargetList></RoutePrj>
</TreeItem>";

/* ==============================================
* Lookup System Manager node "SYSTEM^Route Settings" using
Shortcut "TIRR" and consume XML string

* ============================================== */
ITcSmTreeItem routesNode = _sysManager.LookupTreeItem("TIRR");

routesNode.ConsumeXml(xmlString);

/* ==============================================

* Calling ProduceXml() on the same node executes the broadcast search


and returns its results

* ============================================== */
string result = routesNode.ProduceXml();

Console.WriteLine(result);

/* ==============================================

* Save configuration

* ============================================== */
_sysManager.SaveConfiguration(_tsmPath);

}
}
Automation Interface
ITcSysManager3::ClearMappingInfo

Parameters

Return Values

Comments
No comments.

You might also like