about_AdsSymbolProvider.help.txt
|
TOPIC
about_adssymbolprovider The AdsSymbolProvider is a PowerShell provider that binds TwinCAT target device symbolic information to a PSDrive. SHORT DESCRIPTION PowerShell provider for browsing TwinCAT target device symbols via ADS. LONG DESCRIPTION The AdsSymbolProvider is a PowerShell NavigationCmdletProvider that exposes the symbolic information (PLC variables, data types, system symbols) of a TwinCAT ADS server as a navigable PSDrive. Once a drive is created, standard PowerShell commands (Get-ChildItem, Set-Location, Get-ItemProperty) can be used to browse the symbol tree. The provider also implements IPropertyCmdletProvider to allow reading symbol properties such as data type, size, and instance path. DRIVE INITIALIZATION Unlike the AdsFileProvider, the AdsSymbolProvider does not create default drives automatically. Drives must be created manually with New-PSDrive, specifying the target route and AMS port of the symbol server. LIMITATIONS The AdsSymbolProvider is prototypic and has known limitations: - Drives are never created automatically. You must always use New-PSDrive to create a symbol drive manually. - Browsing array elements does not work reliably because the square bracket characters [ and ] clash with PowerShell wildcard syntax. PowerShell interprets these as character-range patterns, which breaks navigation into array sub-elements (e.g. MAIN.myArray[0]). - For reliable symbol access including arrays, prefer the Get-TcSymbol and Read-TcValue cmdlets over PSDrive navigation. DYNAMIC PARAMETERS When creating a new drive with New-PSDrive, the following dynamic parameters are available: - Address (string) - Route name or IP address of the target - Port (int) - AMS port of the symbol server (default: 851) - Route (IRouteAddressed) - A route object (e.g. from Get-AdsRoute) VISIBLE PORTS The provider filters available ADS server ports to those commonly hosting symbol information: - 300-303 - TwinCAT system ports - 501 - Router port - 801, 811, 821, 831 - I/O task ports - 850-855 - PLC runtime ports (PLC 1 through PLC 6) - 27905-27910 - C++ module ports STANDARD POWERSHELL CMDLETS Once a PSDrive is created, the following standard PowerShell cmdlets work transparently with AdsSymbolProvider drives: - Get-ChildItem - Browses the symbol tree - Set-Location - Navigates into symbol sub-paths - Get-Item - Gets symbol information - Get-ItemProperty - Retrieves symbol properties (data type, size, instance path) RELATED TCXAEMGMT CMDLETS These cmdlets query symbol information directly via ADS sessions (without requiring a PSDrive) and offer additional features like recursive browsing and filtering: - Get-TcSymbol - Get symbols from a TwinCAT target (supports -Recurse and -Path wildcards) - Get-TcDataType - Get data types from a TwinCAT target (supports filtering by name and category) - Read-TcValue - Read symbol values by path - Write-TcValue - Write symbol values by path PREREQUISITES - TwinCAT 3 must be installed and running on the local system - A valid ADS route to the target must be configured - The target ADS server must be in RUN or CONFIG mode - The specified AMS port must host an active symbol server (e.g. a PLC runtime on port 851) EXAMPLE 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 SEE ALSO - about_AdsFileProvider - about_TcXaeMgmt - Get-TcSymbol - Get-TcDataType |