Send-TcReadWrite
SYNOPSIS
Sends a Read/Write access to ADS Server / TwinCAT Devices.
SYNTAX
NetIdPortIndexed (Default)
Send-TcReadWrite -IndexGroup <UInt32> [-IndexOffset <UInt32>] [-WriteValue <Object>] [-WriteLength <Int32>]
[-ReadLength <Int32>] [-ReadType <Type>] [-NetId <AmsNetId[]>] -Port <Int32> [-Encoding <Encoding>] [-Async]
[-Timeout <Int32>] [-Force] [-Quiet] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm]
[<CommonParameters>]
AddressIndexed
Send-TcReadWrite -IndexGroup <UInt32> [-IndexOffset <UInt32>] [-WriteValue <Object>] [-WriteLength <Int32>]
[-ReadLength <Int32>] [-ReadType <Type>] -Address <String[]> -Port <Int32> [-Encoding <Encoding>] [-Async]
[-Timeout <Int32>] [-Force] [-Quiet] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm]
[<CommonParameters>]
RouteIndexed
Send-TcReadWrite -IndexGroup <UInt32> [-IndexOffset <UInt32>] [-WriteValue <Object>] [-WriteLength <Int32>]
[-ReadLength <Int32>] [-ReadType <Type>] -Route <IRoute[]> -Port <Int32> [-Encoding <Encoding>] [-Async]
[-Timeout <Int32>] [-Force] [-Quiet] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm]
[<CommonParameters>]
SessionIndexed
Send-TcReadWrite -IndexGroup <UInt32> [-IndexOffset <UInt32>] [-WriteValue <Object>] [-WriteLength <Int32>]
[-ReadLength <Int32>] [-ReadType <Type>] -Session <ISession[]> [-Encoding <Encoding>] [-Async]
[-Timeout <Int32>] [-Force] [-Quiet] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm]
[<CommonParameters>]
SessionIdIndexed
Send-TcReadWrite -IndexGroup <UInt32> [-IndexOffset <UInt32>] [-WriteValue <Object>] [-WriteLength <Int32>]
[-ReadLength <Int32>] [-ReadType <Type>] -SessionId <Int32[]> [-Encoding <Encoding>] [-Async]
[-Timeout <Int32>] [-Force] [-Quiet] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm]
[<CommonParameters>]
DESCRIPTION
This Cmdlet Read/Writes values from/to TwinCAT Devices and works with different ValueProviders.
Because this is a low level data access, only IndexGroup/IndexOffset addressing is available.
IMPORTANT: Sending Read/Write commands should be done with highest care because it could destabilize the TwinCAT System when the write operation is not addressed properly.
To enhance secure operation, the user is enforced to use Length parameters in conjunction with the in/out values which will be checked by the Cmdlet.
The highest attention should also be taken with the IndexGroup/IndexOffset because that represents the Address in the Process Image and cannot be checked by principle.
To prevent that process image overwrites important data by accident please use the -WhatIf and -Confirm parameters whenever it is appropriate and inform about the $ConfirmPreference settings ( PS\> get-help about_Preference_Variables) before usage of the Send-TcReadWrite Cmdlet.
EXAMPLES
EXAMPLE 1
PS> Send-TcReadWrite -NetId 1.2.3.4.5.6 -Port 851 -IndexGroup SymbolValueByName -IndexOffset 0 -WriteValue "TwinCAT_SystemInfoVarList._AppInfo.ProjectName" -ReadType string -ReadLength 1024
ReadWrite access of process image on target '1.2.3.4.5.6:851':
Start ReadWrite operation WriteData: 'TwinCAT_SystemInfoVarList._AppInfo.ProjectName'(IG:0xf004,IO:0x0000,Len:47),
Read: Type 'System.String' (Len:'1024) on target '1.2.3.4.5.6:851'?
[Y] Yes[A] Yes to All[N] No[L] No to All[S] Suspend[?] Help(default is "Y"): y
ADS_DynSymbols
Sends a Read/Write request with index group 0xf004 (SymbolValueByName) and offset 0.
The write data will be initialized with the project symbol path and an returned (read) string (Default encoded) returned.
EXAMPLE 2
PS> Send-TcReadWrite -NetId 1.2.3.4.5.6 -Port 851 -IndexGroup SymbolValueByName -WriteValue "TwinCAT_SystemInfoVarList._AppInfo.ProjectName" -ReadLength 64 | format-hex
ReadWrite access of process image on target '1.2.3.4.5.6:851':
Start ReadWrite operation WriteData: 'TwinCAT_SystemInfoVarList._AppInfo.ProjectName'(IG:0xf004,IO:0x0000,Len:47),
Read: Type 'System.Byte[]' (Len:'64) on target '1.2.3.4.5.6:851'?
[Y] Yes[A] Yes to All[N] No[L] No to All[S] Suspend[?] Help(default is "Y"): y
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
00000000 41 44 53 5F 44 79 6E 53 79 6D 62 6F 6C 73 00 00 ADS_DynSymbols..
00000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00000020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
Sends a Read/Write request with index group 0xf004 (SymbolValueByName) and offset 0.
The write data will be initialized with the project symbol path and the returned (read) data is by default a byte array of 64 bytes.
The result value will be formatted as hex code.
EXAMPLE 3
PS> $route = Get-AdsRoute -Name 'CX-123456'
PS> $session = $route | New-TcSession -Port 851
PS> $handle = $session | Send-TcReadWrite -IndexGroup SymbolHandleByName -WriteValue "GVL.vgInt" -ReadType Int32 -force
PS> $session | Read-TcValue -IndexGroup SymbolValueByHandle -IndexOffset $handle -ValueType Int16
42
Create a session to the PLC (Port 851) of a target system, determine the SymbolHandle by InstancePath and use this handle to read its 'Int16' Value (INT on PLC System).
PARAMETERS
-IndexGroup
IndexGroup of the Value to ReadWrite, only for IndexGroup/IndexOffset access.
IMPORTANT: Please be aware, that writing data via IndexGroup/IndexOffset can overwrite data in the ProcessImage and posibly destabilizes the system.
No validity check is done for the symbol alignment and therefore this should be done with highest care!
Type: UInt32
Parameter Sets: (All)
Aliases: IG
Required: True
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-IndexOffset
IndexOffset of the Value to write, only for IndexGroup/IndexOffset access.
IMPORTANT: Please be aware, that writing data via IndexGroup/IndexOffset simply overwrites data in the ProcessImage and can destabilize the system.
No validity check is done for the symbol alignment and therefore this should be done with highest care!
If applicable writing data via symbolic information should be preferred!
Type: UInt32
Parameter Sets: (All)
Aliases: IO
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-WriteValue
The value to write.
If no additional Length parameter is set, the Write-TcValue Cmdlet marshals this value to its appropriate size.
To not overwrite data of other symbols within the process image, special attention must be taken (see the Confirm and Whatif parameters).
Type: Object
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-WriteLength
The Length of the data that will be overwritten within the process image.
By default the marshal size of the object used in the -WriteValue parameter is taken.
This parameter is used to override the marshal size and can be helpful to secure the write operation - to not overwrite more data then expected.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: -1
Accept pipeline input: False
Accept wildcard characters: False
-ReadLength
The Length of the data that will be read from the process image.
By default, when not specifiying this parameter the marshalling size of the -ReadType parameter will be taken.
This -ReadLength parameter is only helpful when the marshalling size cannot be determined from the read type (e.g.
byte\[\])
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: -1
Accept pipeline input: False
Accept wildcard characters: False
-ReadType
Use the ReadType parameter to specify the Read/Return type of the data.
If not used, this cmdlet returns the raw byte\[\] as result.
Type: Type
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: System.Byte[]
Accept pipeline input: False
Accept wildcard characters: False
-NetId
The ADS target NetID(s) of the system(s) where to read/write the Value.
More than one target will be supported.
When not specified, this argument defaults to AmsNetId.Local.
Type: AmsNetId[]
Parameter Sets: NetIdPortIndexed
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Route
The target system (as Route) where to read/write the value.
Type: IRoute[]
Parameter Sets: RouteIndexed
Aliases: Destination
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Address
The target address where to read/write the Value.
The Address can consist of RouteName, NetId, HostName or IPAddress.
Wildcards are permitted.
Type: String[]
Parameter Sets: AddressIndexed
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True
-Session
The session object represents the target session where to read/write the value.
Type: ISession[]
Parameter Sets: SessionIndexed
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False
-SessionId
The session ID represents the target session where to read/write the value.
Type: Int32[]
Parameter Sets: SessionIdIndexed
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Port
The Port, where to read/write the value.
This Parameter is used in combination with the NetId, Route or Address input parameter.
Type: Int32
Parameter Sets: NetIdPortIndexed, AddressIndexed, RouteIndexed
Aliases:
Required: True
Position: Named
Default value: 10000
Accept pipeline input: False
Accept wildcard characters: False
-Encoding
Specifies the Encoding for strings.
The Default is ANSI with actual code page.
Type: Encoding
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: System.Text.UTF8Encoding+UTF8EncodingSealed
Accept pipeline input: False
Accept wildcard characters: False
-Async
Starts the write on different threads.
Only for internal use and test purposes.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: True
Accept pipeline input: False
Accept wildcard characters: False
-Timeout
The communication ADS timeout in milliseconds.
A value of 0 disables the timeout.
A value \<= 0 sets the Default (5000 ms).
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: -1
Accept pipeline input: False
Accept wildcard characters: False
-Force
Forces the Read/Write operation, even if the FailFastHandler is active.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-Quiet
The Quiet parameter suppresses the 'ShouldProcess' messsage and the Cmdlet will be processed without further user confirmation.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: Silent
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-Confirm
Prompts you for confirmation before running the cmdlet.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ProgressAction
{{ Fill ProgressAction Description }}
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-WhatIf
Shows what would happen if the cmdlet runs.
The cmdlet is not run.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
INPUTS
TwinCAT.ISession[]
The session object represents the target session where to read/write the value.