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 several 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.

Copy-AdsRemoteItem

Copies files from/to a TwinCAT target system, between ADS paths, or between local paths.

Get-TcRouterConfig

Gets the router configuration (static, trusted, and untrusted routes) from a TwinCAT target system.

Get-AdsRoute

Lists 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-MdpModules

Gets the MDP (Modular Device Profile) modules of the target system.

Get-MqttRoute

Gets MQTT routes from the target system.

Get-RTimeCpuSettings

Gets the CPU Settings of the Realtime Cores 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-AdsRemoteItem

Creates a new file or directory on a TwinCAT 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-AdsRemoteItem

Removes a file or directory from a TwinCAT target system.

Remove-MqttRoute

Remove a MQTT 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

PS> Get-Help about_AdsFileProvider
PS> Get-Help about_AdsSymbolProvider

For more details use:

AdsSymbolProvider

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

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)

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 StaticRoutes.xml on target CX_01234

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

PS> Get-Command -Module TcXaeMgmt -CommandType Function

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

PS> Get-Help Add-AdsRoute -full

For more information, most of the cmdlets have help associated with them e.g.:

PS> Get-Command Add-AdsRoute -syntax

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

PS> gcm Add-AdsRoute -syn

or more tersely:

SEE ALSO

Documentation TcXaeMgmt Module

About the TcXaeMgmt Module

Beckhoff Homepage

KEYWORDS

See also