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
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 and works with Powershell
    4.0.
    
PREFERENCE VARIABLES

CMDLETS
    To see what cmdlets are provided by the TcXaeMgmt Module, execute the command:
    Get-Command -Module TcXaeMgmt -CommandType Cmdlet
    The current TcXaeMgmt cmdlets are listed below:

    Add-AdsRoute
        Cmdlet for adding TwinCAT Routes.

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

    Remove-AdsRoute
        Remove an ADS Route.

    Set-AdsState
        Set the ADS State of a TwinCAT Target.

    Test-AdsRoute
        Test the specified route connection.

    Write-TcValue
        Write values to TwinCAT devices.


FIRSTSTEPS
    # 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)
    > $v1 = Read-TcValue -SessionId 1 -Path "GVL.vgStruct"
    > $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)
    > $v2 = Read-TcValue -SessionId 1 -Path "Main.bChange"
    > $v2
    False

    # Read Ads Value (Array of Strings)
    > $v3 = Read-TcValue -SessionId 1 -path "GVL.vgaString"

    Dimensions                     Elements                                                             PSValue
    ----------                     --------                                                             -------
    {TwinCAT.TypeSystem.Dimension} {QWERTZUIOPÜASDFGHJKLÖÄYXCVBNM;:_, _:;MNBVCXYÄÖLKJHGFDSAÜPOIUZTREWQ} ...

    # Read Array Of Structs
    > $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
    > $v4.Dimensions.ElementCount
    2

    > $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)
    > $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
    > $session | Get-TcDataType -name "Array*"

    # Browse all Symbols recursively
    > $session | Get-TcSymbol -recurse
    ... returns all symbols

    # Browse Symbols recursivly by Symbol Path (Here specific array index 'TaskInfo[1]'(
    > $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
    >$project = Get-TcSymbol -Session $session -recurse -path "*.ProjectName"

    InstanceName DataType   Size InstancePath                                   Comment
    ------------ --------   ---- ------------                                   -------
    ProjectName  STRING(63) 64   TwinCAT_SystemInfoVarList._AppInfo.ProjectName

    # Ads Read ProjectName
    >$project | Read-TcValue -Session $session
    ADS_DynSymbols

    # Ads Write ProjectName
    >$project | Write-TcValue -Session $session -Value "NewProjectName"
    >$project | Read-TcValue -Session $session
    NewProjectName

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

    # ReadWrite by Piping
    > $projectNameSymbol = $session | Get-TcSymbol -Recurse -path "*ProjectName"
    > $projectNameSymbol | Read-TcValue -SessionId 1
    > $projectNameSymbol | Write-TcValue -SessionId 1 -Value "NewProjectName"
    > $projectNameSymbol | Read-TcValue -SessionId 1
 
    # Get Target Information
    > get-adsroute | Get-TcTargetInfo

    Target          Version      Level OS   Image Device CPUArch
    ------          -------      ----- --   ----- ------ -------
    TC3TESTA1-CP67X 3.1.4021.131 CP    Win7              IntelX86

    > get-adsroute | Get-TcVersion

    Major  Minor  Build  Revision
    -----  -----  -----  --------
    3      1      4021   131
        
PROVIDERS
    The TcXaeMgmt module includes the AdsSymbolProvider, which binds the target
    device symbolic information to a PSDrive. To register a symbol server as
    PSDrive type (here the Target Route 'TC3TESTA1-CP67X' with AmsPort: 851)

    > New-PSDrive -Name AdsSymbols -PSProvider AdsSymbolProvider -Address TC3TESTA1-CP67X -Port 851 -Root ''
    > cd AdsSymbols:
    > dir
        
    get-help about_providers
        
FUNCTIONS
    To see what functions are provided by TcXaeMgmt, execute the command:
    Get-Command -Module TcXaeMgmt -CommandType Function
    The current TcXaeMgmt functions are listed below:

    (Add-Route
        Adding a route to the specified TwinCAT System)
    
        
TCXAEMGMT ALIASES
    To see what aliases get created by TcXaeMgmt, execute the command:
    Get-Command -Module TcXaeMgmt -CommandType Alias
    The current TcXaeMgmt defined aliases are listed below:

    (fhex          : alias for Format-Hex cmdlet)

MISCELLANOUS FEATURES

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.

SEE ALSO
    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
     
    about_providers