about_TcXaeMgmt.help.txt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
TOPIC
    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:
 
    PS> Get-Command -Module TcXaeMgmt -CommandType Cmdlet
 
    The actual TcXaeMgmt cmdlets are listed below:
 
    [ADD-ADSROUTE](ADD-ADSROUTE.MD)
    Cmdlet for adding TwinCAT Routes.
 
    [ADD-MQTTROUTE](ADD-MQTTROUTE.MD)
    Adds an MQTT route to the destination system.
 
    [CLOSE-TCSESSION](CLOSE-TCSESSION.MD)
    Closes the specified session object.
 
    [COPY-ADSFILE](COPY-ADSFILE.MD)
    Uploads / Downloads files from/to TwinCAT target.
 
    [GET-ADSROUTE](GET-ADSROUTE.MD)
    List routes on a TwinCAT System / Broadcast search.
 
    [GET-ADSSTATE](GET-ADSSTATE.MD)
    Gets the Ads State of a TwinCAT Target.
 
    [GET-AMSROUTERENDPOINT](GET-AMSROUTERENDPOINT.MD)
    Get the actual AmsConfiguration / RouterEndpoint of the process.
 
    [GET-ECBOXES](GET-ECBOXES.MD)
    Gets the EtherCAT Boxes actually loaded ton the target system.
 
    [GET-ECFRAMESTATISTICS](GET-ECFRAMESTATISTICS.MD)
    Gets the EtherCAT Frame statistics from an ETherCAT master.
 
    [GET-ECMASTER](GET-ECMASTER.MD)
    Gets the Ads State of a TwinCAT Target.
 
    [GET-IODEVICE](GET-IODEVICE.MD)
    Gets actually loaded IO Devices of the target system.
 
    [GET-IOFREERUN](GET-IOFREERUN.MD)
    Gets the IO FreeRun State of the specified target.
 
    [GET-MQTTROUTE](GET-MQTTROUTE.MD)
    Remove a MQTT Route.
 
    [GET-RTIMECPUSETTINGS](GET-RTIMECPUSETTINGS.MD)
    Getting the Cpu Settings of the TwinCAT System
 
    [GET-RTIMELATENCY](GET-RTIMELATENCY.MD)
    Get the latency of TwinCAT Realtime Cores of the specified TwinCAT target
    system.
 
    [GET-RTIMEPERFORMANCE](GET-RTIMEPERFORMANCE.MD)
    Gets the Realtime Performance of the specified system.
 
    [GET-TCDATATYPE](GET-TCDATATYPE.MD)
    Get the DataTypes from a TwinCAT target system / Device.
 
    [GET-TCEVENT](GET-TCEVENT.MD)
    Gets TwinCAT events from event logs on local and remote computers.
 
    [GET-TCLICENSE](GET-TCLICENSE.MD)
    Get TwinCAT License information.
 
    [GET-TCROUTERINFO](GET-TCROUTERINFO.MD)
    Gets the router status information of the specified target system.
 
    [GET-TCSESSION](GET-TCSESSION.MD)
    List the currently established Sessions.
 
    [GET-TCSYMBOL](GET-TCSYMBOL.MD)
    Get the symbols from a TwinCAT target system / Device.
 
    [GET-TCTARGETINFO](GET-TCTARGETINFO.MD)
    Get TwinCAT Device Target information.
 
    [GET-TCVERSION](GET-TCVERSION.MD)
    Get the TwinCAT Version of a target system.
 
    [NEW-TCSESSION](NEW-TCSESSION.MD)
    Create a new session to a TwinCAT Target.
 
    [READ-TCVALUE](READ-TCVALUE.MD)
    Reads values from TwinCAT devices.
 
    [REGISTER-ADSHANDLE](REGISTER-ADSHANDLE.MD)
    Registers and returns a symbol handle.
 
    [REGISTER-ADSNATROUTE](REGISTER-ADSNATROUTE.MD)
    Changes an standard Route to an AmsNAT route on the target system
    (obsolete).
 
    [REMOVE-ADSROUTE](REMOVE-ADSROUTE.MD)
    Remove an ADS Route.
 
    [REMOVE-MQTTROUTE](REMOVE-MQTTROUTE.MD)
    Remove a MQQT Route.
 
    [RESET-IOFREERUN](RESET-IOFREERUN.MD)
    Resets the IO FreeRun state on the specified target.
 
    [RESTART-ADSCOMPUTER](RESTART-ADSCOMPUTER.MD)
    Restarts ("reboots") the operating system on local and remote TwinCAT
    computers.
 
    [SEND-TCREADWRITE](SEND-TCREADWRITE.MD)
    Sends a Read/Write access to ADS Server / TwinCAT Devices.
 
    [SET-ADSSTATE](SET-ADSSTATE.MD)
    Set the ADS State of a TwinCAT Target.
 
    [SET-AMSROUTERENDPOINT](SET-AMSROUTERENDPOINT.MD)
    Sets the AmsConfiguration (Loopback address and port, RouterEndpoint).
 
    [SET-IOFREERUN](SET-IOFREERUN.MD)
    Sets the IO FreeRun state of the target.
 
    [STOP-ADSCOMPUTER](STOP-ADSCOMPUTER.MD)
    Stops (shuts down) local and remote TwinCAT computers.
 
    [TEST-ADSROUTE](TEST-ADSROUTE.MD)
    Test the specified route connection.
 
    [UNREGISTER-ADSHANDLE](UNREGISTER-ADSHANDLE.MD)
    Unregisters a symbol handle.
 
    [WRITE-TCVALUE](WRITE-TCVALUE.MD)
    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
    - ADS
- TwinCAT
- ManagementConsole
- Routes