Notes on the documentation

This description is only intended for the use of trained specialists in control and automation engineering who are familiar with the applicable national standards.
It is essential that the following notes and explanations are followed when installing and commissioning these components.

The responsible staff must ensure that the application or use of the products described satisfy all the requirements for safety, including all the relevant laws, regulations, guidelines and standards.

Disclaimer

The documentation has been prepared with care. The products described are, however, constantly under development.
For that reason the documentation is not in every case checked for consistency with performance data, standards or other characteristics.
In the event that it contains technical or editorial errors, we retain the right to make alterations at any time and without warning.
No claims for the modification of products that have already been supplied may be made on the basis of the data, diagrams and descriptions in this documentation.

Trademarks

Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE® and XFC® are registered trademarks of and licensed by Beckhoff Automation GmbH.
Other designations used in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owners.

Patent Pending

The TwinCAT Technology is covered, including but not limited to the following patent applications and patents:
EP0851348, US6167425 with corresponding applications or registrations in various other countries.

Copyright

© Beckhoff Automation GmbH & Co. KG, Germany.
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without express authorization are prohibited.
Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a patent, utility model or design.


TwinCAT ADS Monitor: Übersicht

TwinCAT ADS Monitor

Overview

The TwinCAT ADS Monitor is divided into the two applications AMS logger (TcAmsLog.exe) and AMS viewer (TcAmsAdsViewe.exe). The logger is responsible for recording the AMS commands and the AMS/ADS viewer for displaying this data. Furthermore the logger can be controlled remotley by the viewer via TCP/IP. The following diagram shows the relationship between the individual components.


TwinCAT AMS Logger: Übersicht

TwinCAT ADS Monitor- AMS Logger

Overview

The AMS logger(TcAmsLog.exe) is responsible for recording AMS messages. The logger is configured with the help of an XML file, that can be loaded with Load Configuration. Among other things one can specify the maximal size of the file and if a ring buffer should be used. After starting the application an attempt is made to load a configuration file named TcAmsLogger.xml from the executable path.

As soon as Start is clicked, the logger starts to record the AMS messages. The capture process can be stopped with the Stop button. By default the captured AMS commands are saved in the file ..\TwinCAT\Boot\Current.cap. The name of this file can be changed in the XML configuration file. But it is not possible to change the path. The AMS/ADSViewer can load and analyze the AMS commands stored in this file.

Following tags can be use in the XML configuratio file:

Tags | Description | Default
<FileSize> | Max size of the capture file. | 1MB
<AutoSave> | If <AutoSave> is false, the AMS messages are stored in a temporary file. After the capture is stopped the file is deleted. This configuration only makes sense if the logger is controlled remotely by the viewer. If <AutoSave> is true, the messages are stored in the TwinCAT Boot folder. The name of this file can be set with the Tag <AutoSaveName> | true
<AutoSaveName> | Name of the capture file. | Current.cap
<RingBuffer> | Specifies the behavior when the maximal file size (set with <FileSize>) is reached. If this value is set to false, the capture process is stopped. Otherwise a ring buffer is used. Here the captured messages are stored in two or more files. If all files are full, the oldest file is overwritten. The number of files can be set with <RingBufferFiles>. The size of one file is the maximum file size(<FileSize>) divided by the number of files (<RingBufferFiles>). | true
<RingBufferFiles> | Number of files used for the ring buffer (see <RingBuffer>) | 2
<OverwriteExisting> | If <OverwriteExisting> is true, an existing capture file is overwritten. Otherwise the new messages are appended to the existing file. | true

Controlling the logger remotely with the AMS/ADS Viewer

It is also possible to control the logger remotely with the AMS/ADS Viewer. As soon as the Logger application is executed, the logger waits for a connection attempt from the viewer. In this case the text Viewer Connected is displayed in the bottom area of the logger window. Now the viewer can start, stop and configure the logger.


TwinCAT AMS/ADS Viewer: Übersicht

TwinCAT ADS Monitor - AMS/ADS Viewer

Overview

The TwinCAT AMS/ADS viewer(TcAmsAdsViewer.exe) is responsible for displaying capture file(offline mode) recorded by the TwinCAT AMS logger and for controlling the AMS logger remotely. In the offline mode(no connection to the logger) the capture AMS commands can be loaded and analyzed.


TwinCAT AMS/ADS Viewer: Laden und Analysieren

TwinCAT ADS Monitor - AMS/ADS Viewer

Loading and analyzing capture files(offline mode)

If the viewer is not connected to the logger, one can load the AMS commands captured by the AMS logger. The display is divided into three windows. The upper window is a list view containing all recorded commands. The parser view in the middle provides additional information about the command selected in the tree view. The bottom view displays a hex dump of the selected command.

Save a capture file:

To save a capture file, one has to right click the entry AmsViewer in the tree view. Then select Save Capture As... in the opened context menu. This opens the Save As Dialog:

The textboxes Range From and Range To are used to specify the range that should be saved. If the Filtered check box is checked, only the filtered AMS commands are saved. This is extremely useful for minimizing the size of large capture files.

Filter a capture file:

In offline mode one can filter the capture AMS/ADS commands. There are more much filter possibilities available than there are for capturing the AMS/ADS commands. To enter a new filter, one has to right click on the entry AmsViewer in the tree view. In the opened context menu select Set Display Filter... . This opens following dialog:

In the text box Filter the filter string can be entered. Expressions can be combined with Boolean operators(AND, OR, NOT) here. An expression is a combination of a property(e.g. TargetNetId) a relation(!=,==,<,>,>=,<) and a value(number, NetId etc.) or a property on its own. If a property is used as expression, the program checks if the property exists AMS command. If following filter string:

Ads_IndexGroup

is entered, all commands are displayed, that contain this property. In this case all ADS Write, Read, ReadWrite and AddDeviceNotification requests would be displayed. If you enter the string:

Ads_IndexGroup == 0x4020

all ADS Write, Read, ReadWrite and AddDeviceNotification requests with an IndexGroup of 0x4020 would be displayed. There are also properties, that cannot be combined with a relation. For instance the filter string:

AdsCmd

displays all ADS commands. The properties starting with Ads_ are ADS specific properties.

Following table list the supported properties:

Property | Description | Example
SenderPort | Port of the sending ADS device. | SenderPort > 800
SenderNetId | AMS-NetId of the sending ADS device. | SenderNetId == 172.16.17.5.1.1
TargetPort | Port of the target ADS device. | TargetPort == 123
TargetNetId | AMS-NetId of the target ADS device. | TargetNetId != 127.12.2.3.1.1
ErrorCode | AMS error code. 0, if no error occurred. | ErrorCode > 0
CmdId | Id of the AMS command. |
hUser | User handle | hUser == 0x12345678
cbData | Length of the data in byte. | cbData > 40
StateFlags | AMS state flags. |
Response | Is true, if the command is a response. | Response
Data | Data of the AMS command | Data == 'MAIN.Variables[10]'
AdsCmd | Is true, if the command is a ADS request or response. | AdsCmd
Ads_Read | Is true, if the command is a ADS read request or response. | Ads_Read
Ads_Write | Is true, if the command is a ADS write request or response. | Ads_Write
Ads_ReadWrite | Is true, if the command is a ADS ReadWrite request or response. | Ads_ReadWrite
Ads_ReadDeviceInfo | Is true, if the command is a ADS ReadDeviceInfo request or response. | Ads_ReadDeviceInfo
Ads_ReadState | Is true, if the command is a ADS ReadState request or response. | Ads_ReadState
Ads_WriteCtrl | Is true, if the command is a ADS WriteCtrl request or response. | Ads_WriteCtrl
Ads_AddDeviceNote | Is true, if the command is a ADS AddDeviceNote request or response. | Ads_AddDeviceNote
Ads_DelDeviceNote | Is true, if the command is a ADS DelDeviceNote request or response. | Ads_DelDeviceNote
Ads_DeviceNote | Is true, if the command is a ADS DeviceNote request or response. | Ads_DeviceNote
Ads_IndexOffset | Index-Offset of the ADS command | Ads_IndexOffset
Ads_IndexGroup | Index-Group of the ADS command. | Ads_IndexGroup
Ads_Result | Result of the command. A value not equal to 0, indicates an error. | Ads_Result
Ads_data | Data of the ADS command | Ads_data

To make the entry of expressions easier the Filter Expression Dialog can be opened with Add Expression .... In the left list box all supported properties are listed. If a property is selected, the Relation list box displays all possible relations. The value of the property can be entered in the textbox Value.

If the dialog is comfirmed with OK, the expression is added to the Filter text box.

Example 1:

Display all AMS commands sent or received from an ADS device with the AMS-NetId 172.16.7.70.1.1:

sendernetid == 172.16.7.70.1.1 OR targetnetid == 172.16.7.70.1.1

Next we want reduce this set to all ADS write commands:

    (sendernetid == 172.16.7.70.1.1 OR targetnetid == 172.16.7.70.1.1) AND ads_write

Example 2:

Find the string 'MAIN.Values' in the ADS data:

    ads_data contains 'MAIN.Values'

Example 3:

Find the byte pattern '01 25 a0':

    ads_data contains '01 25 a0'


TwinCAT AMS/ADS Viewer: Fernsteuern

TwinCAT ADS Monitor - AMS/ADS Viewer

Remote control of the logger(online mode)

The Viewer can control the AMS Logger remotely. As s consequence the logger can be started, stopped and configured from a remote computer.

Connect to the AMS logger:

1.Open the menu Connection and select the entry Connect. This opens the Connect dialog:

2. Choose the computer that contains the AMS Logger you want to connect to and confirm the dialog.

Applying a filter in online mode:

In the online mode you are able to set a filter, to reduce the amount of AMS/ADS commands to be recorded. Therefore you have to select the entry Set Capture Filter... in the context menu of the tree view item AmsViewer. This opens the Set Filter dialog:

If the ADS Message button is checked, only ADS commands are captured. If the Response with Error button is checked, only the erroneous AMS/ADS commands are captured.

If the Included Addresses button is checked, you can specify a list of ADS devices, whose messages you want to record.

With Excluded Addresses you can specify a list of ADS devices, whose messages you do not want to record.

Starting/Stopping the capture:

The capture can be started with the <F5> key or with the displayed button in the toolbar.

The capture can be stopped with the shortcut <Shift> + <F5> or by clicking the display button in the toolbar. To view the captured AMS/ADS message, you have to select the entry Display Captured Packets... in the context menu of the tree view item AmsViewer.


Overview

The ADS test monitor enables configuration of test signals for testing the functionality of the ADS server.

Establishing a connection to the ADS server:

Select TCATAdsTest in the main window to specify the Ams Net Id and the configured Ams port.

Via an existing connection configurable signals can be sent to the ADS server.

Sample signals:

  • Read command
  • Write command


Read command

Right-click on TCATAdsTest to generate a test signal via the Append Command... context dialog.

Creating test signals:

A dialog for configuring the signal opens:

Assign a name, select the command Extended Read Request and confirm the entry with OK.

Example configuration for an extended read command:

In main window specify the Index Group and the Index Offset for the ADS server:

The data to be read can be added the context menu Append Item (right-click).

In the following dialog the Type of the read value can be entered:

Please note that the data length (Length) must match the received data. The Repeat parameter defines how often the data are created. Confirm the entry with OK.

The signal is sent via the Transfer button.


Write command

Right-click on TCATAdsTest to generate a test signal via the Append Command... context dialog.

Creating a test signal:

A dialog for configuring the signal opens:

Assign a name, select the command Extended Write Request and confirm the entry with OK.

Example configuration for an extended write command:

In main window specify the Index Group and the Index Offset for the ADS server:

The data to be written can be added the context menu Append Item (right-click).

In the following dialog the Type and content (Data) of the data can be specified:

Please note that your ADS server supports the data length (Length). The Repeat parameter defines how often the data are created. Confirm the entry with OK.

The signal is sent via the Transfer button.