TcXaeMgmt

about_TcXaeMgmt

PowerShell TwinCAT XAE Management Console (TcXaeMgmt)

SHORT DESCRIPTION

Cmdlets for managing and accessing ADS Routes, Reading/Writing Values and managing Remote targets.

LONG DESCRIPTION

The 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 over the ADS protocol.

This includes the following tasks/features:

This Module is usable under all Powershell Version \>= 5.1 including

'Windows Powershell' and 'Powershell Core' Versions.

As Prerequisite the TcXaeMgmt Module needs a local TwinCAT installation

larger equals than TwinCAT 4024.10. There are no limitations to access

other/older TwinCAT Versions remotely.

PREREQUISITES

\>= TwinCAT 3.1.4024.10 (XAR Runtime or Full) (local installation)

POWERSHELL COMPATIBILITY

\>= Windows Powershell 5.1

\>= Powershell (Core) 6.0

CMDLETS

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

PS> Get-Command -Module TcXaeMgmt -CommandType Cmdlet

The actual TcXaeMgmt cmdlets are listed below:

Add-AdsRoute

Cmdlet for adding TwinCAT Routes.

Add-MqttRoute

Adds an MQTT route to the destination system.

Close-TcSession

Closes the specified session.

Copy-AdsFile

Uploads / Downloads files from/to TwinCAT target.

Get-AdsRemoteConnections

Get-AdsRoute

List routes on a TwinCAT System / Broadcast search.

Get-AdsState

Gets the Ads State of a TwinCAT Target.

Get-AmsNetId

Get the local NetId of the TwinCAT System.

Get-AmsRouterEndpoint

Get the actual AmsConfiguration / RouterEndpoint of the process.

Get-EcBoxes

Gets the EtherCAT Boxes actually loaded on the specified target system.

Get-EcFrameStatistics

Gets the EtherCAT Frame statistics from an EtherCAT master.

Get-EcMaster

Gets actually loaded EtherCAT Master devices on the target system.

Get-IODevice

Gets actually loaded IO Devices of the target system.

Get-IoFreeRun

Gets the IO FreeRun State of the specified target.

Get-MqttRoute

Remove a MQTT Route.

Get-RTimeCpuSettings

Getting the Cpu Settings of the TwinCAT System

Get-RTimeLatency

Get the latency of TwinCAT Realtime Cores of the specified TwinCAT target system.

Get-RTimePerformance

Gets the Realtime Performance of the specified system.

Get-TcDataType

Get the DataTypes from a TwinCAT target system / Device.

Get-TcEvent

Gets TwinCAT events from event logs on local and remote computers.

Get-TcLicense

Get TwinCAT License information.

Get-TComObject

Gets the actual loaded TCOM objects in the TwinCAT environment.

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-TcSymbolStatistics

Get the Symbol statistics 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-AdsRoute

Remove an ADS Route.

Remove-MqttRoute

Remove a MQQT Route.

Reset-IoFreeRun

Resets the IO FreeRun state on the specified target.

Restart-AdsComputer

Restarts ("reboots") the operating system on local and remote TwinCAT computers.

Restart-TwinCAT

Restarts or Resets a specified TwinCAT System.

Send-TcReadWrite

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

Set-AdsRouteProperty

Sets route properties.

Set-AdsState

Writes a AdsState control request to the specified target.

Set-AmsNetId

Sets the AmsNetId of a device.

Set-AmsRouterEndpoint

Sets the AmsConfiguration (Loopback address and port, RouterEndpoint).

Set-IoFreeRun

Sets the IO FreeRun state of the target.

Set-RTimeCpuSettings

Sets the Windows (Shared) CPU cores and Isolated cores for TwinCAT.

Start-AdsProcess

Start a process via ADS on the target system.

Stop-AdsComputer

Stops (shuts down) local and remote TwinCAT computers.

Test-AdsRoute

Test the specified route connection.

Unregister-AdsHandle

Unregisters a symbol handle.

Write-TcValue

Write values to TwinCAT devices.

EXAMPLES

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

Get Target Information

PS> get-adsroute | Get-TcTargetInfo

Target          Version      Level OS   Image Device CPUArch
------          -------      ----- --   ----- ------ -------
TC3TESTA1-CP67X 3.1.4021.131 CP    Win7              IntelX86
PS> get-adsroute | Get-TcVersion

Major  Minor  Build  Revision
-----  -----  -----  --------
3      1      4021   131

PROVIDERS

The TcXaeMgmt module includes the AdsSymbolProvider and the AdsFileProvider

AdsSymbolProvider

Binds the target device symbolic information to a PSDrive. To register a symbol server as

PSDrive type (here the Target Route 'CX_01234' with AmsPort: 851)

PS> New-PSDrive -Name CX_01234_Symbols -PSProvider AdsSymbolProvider -Address CX_01234 -Port 851 -Root 
PS> cd CX_01234_Symbols:
PS> CX_01234_Symbols:> dir

AdsFileProvider

PS> New-PSDrive -name CX_01234 -PSProvider AdsFileProvider -Address CX_01234 -Root ''
PS> dir CX_01234:

Mode             LastWriteTime                    Length     Name
----             -------------                    ------     ----
d----            30.11.2021 16:11:31                         BootDir
d----            03.12.2021 01:17:20                         BootProject
d----            17.03.2021 14:33:53                         ConfigDir
d----            03.12.2021 01:17:20                         Generic
d----            18.06.2021 08:00:22                         InstallDir
d----            03.12.2021 01:17:20                         RepositoryDir
d----            03.12.2021 15:32:03                         TargetDir

> cd CX_01234:/BootDir

PS CX_01234:\BootDir> dir

Mode             LastWriteTime                    Length     Name
----             -------------                    ------     ----
d----            05.10.2021 10:36:34                         CurrentConfig
-a---            05.10.2021 10:36:34              4563       CurrentConfig.tszip
-a---            05.10.2021 10:36:34              17113      CurrentConfig.xml
-a---            30.11.2021 16:11:31              126976     LoggedEvents.db
d----            27.10.2021 11:32:43                         Plc

More Information about Providers

PS> get-help about_providers

Example: Create a new AdsFileProvider Drive to the TwinCAT Device CX_01234

> New-PSDrive -name CX_01234 -PSProvider AdsFileProvider -Address CX_01234 -Root ''

Name           Used (GB)     Free (GB) Provider        Root                 CurrentLocation
----           ---------     --------- --------        ----------           ---------------
CX_01234                               AdsFileProvider \TargetDir

Example: Browse the files on the TwinCAT Device CX_01234

> dir

Mode             LastWriteTime                    Length     Name
----             -------------                    ------     ----
d----            26.11.2021 17:44:27                         CACerts
-a---            14.03.2012 14:50:50              619        DefaultConfig.xml
d----            11.05.2021 14:42:45                         License
d----            18.06.2021 08:01:03                         Resource
d----            17.03.2021 15:15:51                         Routes
d----            18.06.2021 08:00:33                         StartMenuAdmin
d----            17.03.2021 14:33:35                         StartUp
-a---            30.11.2021 18:46:08              2253       StaticRoutes.xml
-a---            01.02.2012 16:42:58              494        TargetFeatures.xml
-a---            17.03.2021 14:42:50              3113       TcSelfSigned.xml

Example: Read the content of the StaticRouts.xml on target CX_01234

r> get-content .\StaticRoutes.xml
<?xml version="1.0"?>
<TcConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <RemoteConnections>
                <Route>
                        <Name>TargetIPC</Name>
                        <Address>172.17.60.147</Address>
                        <NetId>172.17.60.147.1.1</NetId>
                        <Type>TCP_IP</Type>
                        <Tls IgnoreCn="true">
                                <Ca>...</Ca>
                        </Tls>
                </Route>
                <Server>
                        <Tls IgnoreCn="true">
                                <Ca>c:\twincat\3.1\target\CACerts\RootCA.pem</Ca>
                                <Cert>c:\twincat\3.1\target\CACerts\TargetIPC.crt</Cert>
                                <Key>c:\twincat\3.1\target\CACerts\TargetIPC.key</Key>
                        </Tls>
                </Server>
        </RemoteConnections>
</TcConfig>

FEEDBACK

Please submit any feedback, including defects and enhancement requests,

to

support@beckhoff.com

We are also interested in suggestions you may have for cmdlets. Over

time, we hope to be able to add some more features.

NOTE

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

PS> Get-Command -Module TcXaeMgmt -CommandType Function

For more information, most of the cmdlets have help associated with

them e.g.:

PS> Get-Help Add-AdsRoute -full

The definitive information on a cmdlet's parameters can be obtained

by executing:

PS> Get-Command Add-AdsRoute -syntax

or more tersely:

PS> gcm Add-AdsRoute -syn

SEE ALSO

Documentation TcXaeMgmt Module

About the TcXaeMgmt Module

Beckhoff Homepage

PS> get-help about_providers

KEYWORDS