about_TcXaeMgmt.help.txt
|
# 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: - Establishing/Removing Route Connections (**Add-AdsRoute**, **Remove-AdsRoute**) - Browsing Routes locally and within the network (**Broadcast Search**, **Get-AdsRoute**) - Getting remote device states and information (**Get-AdsState**, **Get-TcTargetInfo**, **Get-TcVersionInfo**) - Establishing and Closing Remote communication sessions (**New-TcSession**,**Get-TcSession**,**Close-TcSession**) - Browsing Symbol Information (**Get-TcSymbol**, **Get-TcDataType**) - Reading/Writing raw and symbolic values (**Read-TcValue**, **Write-TcValue**, **Send-TcReadWrite**) - Uploading/Downloading files to/from remote devices (**Copy-AdsFile**) - Browsing License information (**Get-TcLicense**) 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: ```powershell 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 ```powershell 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 ```powershell 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) ```powershell 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) ```powershell PS> $v2 = Read-TcValue -SessionId 1 -Path "Main.bChange" PS> $v2 False ``` ### Read Ads Value (Array of Strings) ```powershell 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 ```powershell 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 ```powershell 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) ```powershell 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 ```powershell PS> $session | Get-TcDataType -name "Array*" ``` ### Browse all Symbols recursively ```powershell PS> $session | Get-TcSymbol -recurse ... returns all symbols ``` ### Browse Symbols recursivly by Symbol Path (Here specific array index 'TaskInfo[1]'( ```powershell 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 ```powershell 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 ```powershell PS>$project | Read-TcValue -Session $session ADS_DynSymbols ``` ### Ads Write ProjectName ```powershell PS>$project | Write-TcValue -Session $session -Value "NewProjectName" PS>$project | Read-TcValue -Session $session NewProjectName ``` ### ReadWrite by Symbol Path ```powershell 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 ```powershell 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 ```powershell PS> get-adsroute | Get-TcTargetInfo Target Version Level OS Image Device CPUArch ------ ------- ----- -- ----- ------ ------- TC3TESTA1-CP67X 3.1.4021.131 CP Win7 IntelX86 ``` ```powershell PS> get-adsroute | Get-TcVersion Major Minor Build Revision ----- ----- ----- -------- 3 1 4021 131 ``` ## PROVIDERS The TcXaeMgmt module includes the AdsSymbolProvider and the AdsFileProvider For more details use: ```powershell PS> Get-Help about_AdsFileProvider PS> Get-Help about_AdsSymbolProvider ``` ### 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) ```powershell 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 ```powershell 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 ```powershell PS> get-help about_providers ``` ### Example: Create a new AdsFileProvider Drive to the TwinCAT Device CX_01234 ```powershell > 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 ```powershell > 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 ```powershell 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 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](https://infosys.beckhoff.com/content/1033/tc3_ads_ps_tcxaemgmt/index.html) [About the TcXaeMgmt Module](https://infosys.beckhoff.com/help/redirect.asp?F1=BeckhoffSearchNamespace.about_tcxaeMgmt&locale=en-US&codeLang=) [Beckhoff Homepage](https://www.beckhoff.com/) # KEYWORDS - ADS - TwinCAT - ManagementConsole - Routes |