TC Automation Interface
TC Automation Interface
TC Automation Interface
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.
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.
Load/Save/Create/Activate
configurations
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
Adding/removing PLC - -
placeholders
Adding/removing PLC - -
repositories
Adding/removing PLC - -
libaries to
repositories
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
Automation Interface
Frequently Asked Questions
What is TwinCAT 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?
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?
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#
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#):
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
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
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
}
clr.AddReference('System.Xml')
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")
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:
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
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.
EtherCAT Master - Code Snippet (C#)
<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
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.
Available
Main class Description since
ITcSysManager Base class TwinCAT
2.11
to create and parameterize a
TwinCAT configuration
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
ITcSysManager2
methods
Description Available since
SetTargetNetId Set the target TwinCAT 2.11
NetId of the
currently
opened
TwinCAT
configuration.
ITcSysManager3
methods
Description Available since
LookupTreeItemById Looks for a TwinCAT 2.11
configuration
tree item
with the
specifed
Item id.
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"
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>
</OwnerB>
</OwnerA>
</OwnerB>
</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)
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>.
35 TREEITEMTYPE_NVPUBLISHERVAR ---
36 TREEITEMTYPE_NVSUBSCRIBERVAR ---
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:
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: 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: 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)
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)
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.
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
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).
);
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
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().
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
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
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(
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
);
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(
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
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(
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
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
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...
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...
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...
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...
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...
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...
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...
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...
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.
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
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...
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...
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
// Scan Devices (Be sure that the target system is in Config mode!) string scannedXml =
int deviceCount = 0;
// Scan all added devices for attached boxes foreach (ITcSmTreeItem device in devices)
try
Console.WriteLine("Warning: {0}",ex.Message); }
Code snippet (IronPython):
import xml.etree.ElementTree as ET
_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);
/* ==============================================
* ============================================== */
string result = routesNode.ProduceXml();
Console.WriteLine(result);
/* ==============================================
* Save configuration
* ============================================== */
_sysManager.SaveConfiguration(_tsmPath);
}
}
Automation Interface
ITcSysManager3::ClearMappingInfo
Parameters
Return Values
Comments
No comments.