TcXaeMgmt Module

Topic

PowerShell TwinCAT XAE Management Console (TcXaeMgmt)

Short Description

Describes the Powershell TwinCAT Management Console (TcXaeMgmt) module and how to use the contained cmdlets and functions.

Long Description

Powershell TwinCAT Management Console is a PowerShell module that provides a number of useful cmdlets for TwinCAT System Management and for communicating

with ADS devices with the ADS protocol.

This includes TwinCAT Route Management as finding routes (find targets, broadcast search), establishing and removing route connections (Add-AdsRoute, Remove-AdsRoute) and the

test of registered routes (Test-AdsRoute) or communication (Get-AdsState).

Furthermore Ads Sessions can be established for further use (New-TcSession), Symbol information

can be browsed (Get-TcSymbol, Get-TcDataType) and data read/write from/to to ADS Devices

(Read-TcValue, Write-TcValue). Uploading and Downloading files to or from the TwinCAT Target systems is an additional feature

(Copy-AdsFile).

Powershell Compatibility

Actually, the TwinCAT Management Console is written for Powershell 3.0 and higher.

Preference Variables

Cmdlets

To see what cmdlets are provided by the TcXaeMgmt Module, execute the command:

Get-Command -Module TcXaeMgmt -CommandType Cmdlet

The actual TcXaeMgmt cmdlets are listed below:

Add-AdsNatRoute

Adds an AmsNAT Route to the destination system (obsolete).

Add-AdsRoute

Cmdlet for adding TwinCAT Routes.

Add-MqttRoute

Adds an MQTT route to the destination system.

Close-TcSession

Closes the specified session object.

Copy-AdsFile

Uploads / Downloads files from/to TwinCAT target.

Get-AdsRoute

List routes on a TwinCAT System / Broadcast search.

Get-AdsState

Gets the Ads State of a TwinCAT Target.

Get-TcDataType

Get the DataTypes from a TwinCAT target system / Device.

Get-TcLicense

Get TwinCAT License information.

Get-TcRouterInfo

Gets the router status information of the specified target system.

Get-TcSession

List the currently established Sessions.

Get-TcSymbol

Get the symbols from a TwinCAT target system / Device.

Get-TcTargetInfo

Get TwinCAT Device Target information.

Get-TcVersion

Get the TwinCAT Version of a target system.

New-TcSession

Create a new session to a TwinCAT Target.

Read-TcValue

Reads values from TwinCAT devices.

Register-AdsHandle

Registers and returns a symbol handle.

Register-AdsNatRoute

Changes an standard Route to an AmsNAT route on the target system (obsolete).

Remove-AdsNatRoute

Removes an AmsNAT Route from the destination system (obsolete).

Remove-AdsRoute

Remove an ADS Route.

Remove-MqttRoute

Remove a MQTT Route.

Send-TcReadWrite

Sends a Read/Write request to ADS Server / TwinCAT Devices.

Set-AdsState

Set the ADS State of a TwinCAT Target.

Test-AdsRoute

Test the specified route connection.

Unregister-AdsHandle

Unregisters a symbol handle.

Write-TcValue

Write values to TwinCAT devices.

First Steps

Getting Route

PS> $route = get-adsroute TC3TEST*
PS> $route
Name            NetId             Address       Sub Version RTSystem
----            -----             -------       --- ------- --------
TC3TESTA1-CP67X 172.17.62.105.1.1 172.17.62.105     0.0     Unknown

Create Session

PS> $session = New-TcSession -Route $route -Port 851
PS> $session
ID Address               IsConnected EstablishedAt
-- -------               ----------- -------------
1  172.17.62.105.1.1:851 True        12/12/2016 12:22:02 PM

Read Ads Value (Struct)

PS> $v1 = Read-TcValue -SessionId 1 -Path "GVL.vgStruct"
PS> $v1
vBool   : True
vByte   : 123
vWord   : 12345
vDWord  : 12345678
vSInt   : -121
vUSInt  : 212
vInt    : -12121
vUInt   : 21212
vDInt   : -1212121
vUDInt  : 2121212
vReal   : 123,456
vLReal  : 1234567890,12346
vString : QWERTZUIOPÜASDFGHJKLÖÄYXCVBNM;:_
vTime   : 01:02:03.0040000
vTod    : 23:45:06.7890000
vDate   : 17.11.2005 00:00:00
vDT     : 17.11.2005 12:34:56
vAlias  : 8
vEnum   : 8
vRange  : 7
PSValue : ...

Read Ads Value (Boolean)

PS> $v2 = Read-TcValue -SessionId 1 -Path "Main.bChange"
PS> $v2
False

Read Ads Value (Array of Strings)

PS> $v3 = Read-TcValue -SessionId 1 -path "GVL.vgaString"
Dimensions                     Elements                                                             PSValue
----------                     --------                                                             -------
{TwinCAT.TypeSystem.Dimension} {QWERTZUIOPÜASDFGHJKLÖÄYXCVBNM;:_, _:;MNBVCXYÄÖLKJHGFDSAÜPOIUZTREWQ} ...

Read Array Of Structs

PS> $v4 = Read-TcValue -SessionId 1 -path "GVL.vgastruct"
Dimensions                     Elements
----------                     --------
{TwinCAT.TypeSystem.Dimension} {@{vBool=True; vByte=123; vWord=12345; vDWord=12345678; vSInt=-121; vUSInt=212; vInt=-12121; vUInt=21212; vDInt=-1212121; vUD...

Dump Array Elements

PS> $v4.Dimensions.ElementCount
2
PS> $v4.Elements
vBool   : True
vByte   : 123
vWord   : 12345
vDWord  : 12345678
vSInt   : -121
vUSInt  : 212
vInt    : -12121
vUInt   : 21212
vDInt   : -1212121
vUDInt  : 2121212
vReal   : 123,456
vLReal  : 1234567890,12346
vString : QWERTZUIOPÜASDFGHJKLÖÄYXCVBNM;:_
vTime   : 01:02:03.0040000
vTod    : 23:45:06.7890000
vDate   : 17.11.2005 00:00:00
vDT     : 17.11.2005 12:34:56
vAlias  : 8
vEnum   : 8
vRange  : 7
PSValue : ...

vBool   : False
vByte   : 234
vWord   : 23456
vDWord  : 23456789
vSInt   : 121
vUSInt  : 131
vInt    : 12121
vUInt   : 13131
vDInt   : 1212121
vUDInt  : 1313131
vReal   : 456,321
vLReal  : 987654321,123457
vString : _:;MNBVCXYÄÖLKJHGFDSAÜPOIUZTREWQ
vTime   : 11:22:33.0440000
vTod    : 11:22:33.4440000
vDate   : 22.01.1999 00:00:00
vDT     : 22.01.1999 11:22:33
vAlias  : 9
vEnum   : 9
vRange  : -5
PSValue : ...

Browse Data Types (Query by Category)

PS> $session | Get-TcDataType | where Category -eq "Array" }
Name                      Size     Category   Comment          ElementType      Dimensions       Members
----                      ----     --------   -------          -----------      ----------       -------
ARRAY [-1..1] OF INT      6        Array                       INT              {TwinCAT.Type...
ARRAY [-10..-8] OF BOOL   3        Array                       BOOL             {TwinCAT.Type...
ARRAY [0..1] OF A_Alias   4        Array                       A_Alias          {TwinCAT.Type...
....

Browse DataTypes by name

PS> $session | Get-TcDataType -name "Array*"

Browse all Symbols recursively

PS> $session | Get-TcSymbol -recurse

... returns all symbols

Browse Symbols recursivly by Symbol Path

Here specific array index 'TaskInfo[1]'

PS> $session | Get-TcSymbol -recurse -path "*TaskInfo``[1``]*","*.ProjectName"
InstanceName            DataType              Size InstancePath                                                   Comment
------------            --------              ---- ------------                                                   -------
ProjectName             STRING(63)            64   TwinCAT_SystemInfoVarList._AppInfo.ProjectName
_TaskInfo[1]            PLC.PlcTaskSystemInfo 128  TwinCAT_SystemInfoVarList._TaskInfo[1]
ObjId                   OTCID                 4    TwinCAT_SystemInfoVarList._TaskInfo[1].ObjId
CycleTime               UDINT                 4    TwinCAT_SystemInfoVarList._TaskInfo[1].CycleTime
Priority                UINT                  2    TwinCAT_SystemInfoVarList._TaskInfo[1].Priority
AdsPort                 UINT                  2    TwinCAT_SystemInfoVarList._TaskInfo[1].AdsPort
CycleCount              UDINT                 4    TwinCAT_SystemInfoVarList._TaskInfo[1].CycleCount
DcTaskTime              LINT                  8    TwinCAT_SystemInfoVarList._TaskInfo[1].DcTaskTime
LastExecTime            UDINT                 4    TwinCAT_SystemInfoVarList._TaskInfo[1].LastExecTime
FirstCycle              BOOL                  1    TwinCAT_SystemInfoVarList._TaskInfo[1].FirstCycle
CycleTimeExceeded       BOOL                  1    TwinCAT_SystemInfoVarList._TaskInfo[1].CycleTimeExceeded
InCallAfterOutputUpdate BOOL                  1    TwinCAT_SystemInfoVarList._TaskInfo[1].InCallAfterOutputUpdate
RTViolation             BOOL                  1    TwinCAT_SystemInfoVarList._TaskInfo[1].RTViolation
TaskName                STRING(63)            64   TwinCAT_SystemInfoVarList._TaskInfo[1].TaskName

Browse only Symbols ending with path *.ProjectName

PS> $project = Get-TcSymbol -Session $session -recurse -path "*.ProjectName"
InstanceName DataType   Size InstancePath                                   Comment
------------ --------   ---- ------------                                   -------
ProjectName  STRING(63) 64   TwinCAT_SystemInfoVarList._AppInfo.ProjectName

Ads Read ProjectName

PS> $project | Read-TcValue -Session $session
ADS_DynSymbols

Ads Write ProjectName

PS> $project | Write-TcValue -Session $session -Value "NewProjectName"
PS> $project | Read-TcValue -Session $session
NewProjectName

ReadWrite by Symbol Path

PS> Read-TcValue -SessionId 1 -Path "Main.bChange"
false
PS> Write-TcValue -SessionId 1 -Symbol "Main.bChange" -Value True
PS> Read-TcValue -SessionId 1 -Path "GVL.vgBool"
PS> Write-TcValue -SessionId 1 -Path "GVL.vgBool" -value $true

ReadWrite by Piping

PS> $projectNameSymbol = $session | Get-TcSymbol -Recurse -path "*ProjectName"
PS> $projectNameSymbol | Read-TcValue -SessionId 1
PS> $projectNameSymbol | Write-TcValue -SessionId 1 -Value "NewProjectName"
PS> $projectNameSymbol | Read-TcValue -SessionId 1