Triple-F Sniffer manual

Juan Diez Perez Stanislas Pinte Darius Blasband

Triple-F Sniffer manual
by Juan Diez Perez, Stanislas Pinte, and Darius Blasband Copyright © 2005, 2006 ERTMS Solutions

Table of Contents
Introduction ............................................................................................................. vii 1. Concepts and definitions ........................................................................................... 1 Profibus ............................................................................................................................ 1 Euroradio .......................................................................................................................... 1 SLL .................................................................................................................................. 1 STL .................................................................................................................................. 1 HDLC ............................................................................................................................... 1 T.70 ................................................................................................................................. 1 X.224 ............................................................................................................................... 1 Application Layer ............................................................................................................... 1 traffic capture file ................................................................................................................ 2 Packet ............................................................................................................................... 2 Message ............................................................................................................................ 2 2. First steps ............................................................................................................... 3 3. User interface components ......................................................................................... 4 Main Window .................................................................................................................... 4 Additional Instance Mode ..................................................................................................... 4 File Menu .......................................................................................................................... 4 Navigation Menu ................................................................................................................ 4 Tools Menu ....................................................................................................................... 5 Report Menu ...................................................................................................................... 5 SpyBox Menu .................................................................................................................... 5 Euroradio Menu .................................................................................................................. 5 Help menu ......................................................................................................................... 6 Message Options ................................................................................................................. 6 Dual Bus Settings ................................................................................................................ 7 Regular Expression filter ...................................................................................................... 7 Message List ...................................................................................................................... 8 Message Columns ............................................................................................................... 9 Column Selection .............................................................................................................. 10 Protocol Verifications ........................................................................................................ 12 Details Tree ..................................................................................................................... 12 Status Bar ........................................................................................................................ 13 Message Filters ................................................................................................................. 13 Layers Selections .............................................................................................................. 15 Connection Colors Management .......................................................................................... 15 Time Settings ................................................................................................................... 16 Time Display ................................................................................................................... 16 Time Base ....................................................................................................................... 17 Local Reference Time Computation ...................................................................................... 17 Connection Management .................................................................................................... 17 Preferences Dialog ............................................................................................................ 17 CRC Verifications ............................................................................................................. 18 FFFIS STM Report Dialog .................................................................................................. 19 Record Dialog .................................................................................................................. 21 SpyBox Administration Dialog ............................................................................................ 23 Export Dialog ................................................................................................................... 26 Euroradio Quality Of Service Dialog .................................................................................... 26 Euroradio Key Management Dialog ...................................................................................... 27 Euroradio SpyCable Dialog ................................................................................................. 28 4. Recording PROFIBUS traffic with the SpyBox hardware .............................................. 29 First steps ........................................................................................................................ 29 Recording filters ............................................................................................................... 29 iv

Triple-F Sniffer manual

Recording session detection ................................................................................................ 29 5. Scripting .............................................................................................................. 30 Introduction ..................................................................................................................... 30 High-level Architecture ...................................................................................................... 30 Python language and .Net class libraries ................................................................................ 31 Scripting interface ............................................................................................................. 31 Scripting API Reference ..................................................................................................... 32 init_session(fileNamePrefix) .............................................................................. 32 handle_message(message, bus) .............................................................................. 33 start_recording(message, bus) ............................................................................ 33 record_message(message, bus) .............................................................................. 33 stop_recording(message, bus) .............................................................................. 33 end_session() ............................................................................................................ 33 idle() .......................................................................................................................... 33 Structure of the message parameter ....................................................................................... 33 How to run your first script ................................................................................................. 34 Complex scripting example: Server mode implementation ........................................................ 34 6. JRU Messages Decoding Plugin ............................................................................... 36 Introduction ..................................................................................................................... 36 How to activate the JRU plugin? .......................................................................................... 36 JRU Plugin Screenshots ..................................................................................................... 37 7. Euroradio Plugin ................................................................................................... 38 Introduction ..................................................................................................................... 38 Serial modem recording specifics ......................................................................................... 38 SpyCable design ............................................................................................................... 38 8. Command-line interface .......................................................................................... 40 Command-line manual ....................................................................................................... 40 9. Configuration files ................................................................................................. 42 Session Settings Config ...................................................................................................... 42 Devices And Connections Configuration ............................................................................... 42 Index ...................................................................................................................... 44

v

List of Examples
5.1. A simple example ................................................................................................ 32

vi

Introduction
This document contains everthing needed to use all the functions available in the Triple-F Sniffer application. The scope of the Triple-F Sniffer application is a subset of the ERTMS specifications: to record, decode and analyze communications, going over the PROFIBUS and Euroradio interfaces, complying the FFFIS specifications. The two FFFIS interfaces are specified in UNISIG Subset-035 (FFFIS STM) and UNISIG Subset-037 (Euroradio FFFIS), available on the ERA [http://www.era.europa.eu/public/ERTMS/Approved_Documents_List_of_mandatory_Specifications.as px] website. The following features allow to conduct an in-depth analysis of FFFIS communications. • • • • • • • • PROFIBUS and Euroradio recording Message listing Message filtering Message content validation Quick navigation in message list Tree display showing all details, by protocol layer Message export in CSV/text format PDF report generation

They are discussed in details later on in the document. See section User interface components for a detailed description of each part of the User Interface.

vii

Chapter 1. Concepts and definitions
The following explains the basic concepts related to the Triple-F Sniffer application. It only provides a superficial explanation, and links to more complete information are provided at the end of this document, indicated by footnotes references. Some definitions are extracted from official ERTMS specifications, available on the ERA [http://www.era.europa.eu/public/ERTMS/Approved_Documents_List_of_mandatory_Specifications.as px] website.

Profibus
The transmission medium used to communicate between devices. Full specifications can be found here [http://www.profibus.com/]. NOTE: "FDL" is frequently used as synonim for "Profibus", in the following text.

Euroradio
The protocol stack used to communicate between the train and the track, on top of GSM-R radio transmission. This protocol stack is fully specified in UNISIG Subset-037.

SLL
Safe Link Layer, the protocol layer coming above the Profibus layer. It is fully defined in the Subset 57 of the FFFIS STM specifications.

STL
Safe Time Layer, the protocol layer coming above the SLL layer. It is fully defined in the Subset 56 of the FFFIS STM specifications.

HDLC
HDLC is the protocol layer used in Euroradio communications for the data link layer. It is specified in the ISO-7776 standard, available on the ISO website [http://www.iso.org/iso/en/ISOOnline.frontpage] with delta specifications in the UNISIG Subset-037.

T.70
T.70 a protocol layer used in Euroradio communications for the network layer. It is specified in the ITUT-70 standard, available on the ITU website [http://www.itu.int/home/index.html].

X.224
X.224 the protocol layer used in Euroradio communications for the transport layer. It is specified in the ISO-13239 standard, available on the ISO website [http://www.iso.org/iso/en/ISOOnline.frontpage].

Application Layer
1

Concepts and definitions

The protocol layer coming above the STL layer, in the case of PROFIBUS communications, or above the X.224 layer, in the case of Euroradio communications. It is fully defined in the UNISIG Subset-058 and Subset-026 (chapters 7 and 8) specifications.

traffic capture file
A file containing all messages exchanged during a finite amount of time, on a Profibus network. These files have usually the ".es3f" extension.

Packet
A packet is the unit of data routed between a source address and a destination address in any network. Packets pertain to a protocol layer. Packets can be nested: a Packet of one protocol layer can contain other Packets, pertaining to protocol layers located higher in the protocol stack.

Message
We define a message by taking the lower level protocol layer: the Profibus layer. A Message is a Profibus Packet, together with all Packets pertaining to upper protocol layers, encapsulated in the Profibus Packet.

2

Chapter 2. First steps
Procedure 2.1. Open a traffic capture file using the Triple-F Sniffer application.
To start using the Triple-F Sniffer tool, follow this procedure. 1. 2. 3. Double-click on the Triple-F Sniffer application icon on your desktop. Use the File # New ( Ctrl-n) to open a new traffic capture file. Browse to the desired file, and click on the Open button. In the application window, you will see the FFFIS-STM messages contained in the traffic capture file, or a warning showing that the traffic capture file is invalid.

3

Chapter 3. User interface components
The following provides in-depth explanation about every component making up the Triple-F Sniffer application. For each component, we have a general description, and a list of all possible user interactions. Detailed screenshots are provided when necessary.

Main Window
This window is the application entry point. It hosts menus and controls to drive all the application functions. It is divided in three zones: • • • Options cockpit. See section Message Options. The message list. See section Message List. The message details tree. See section Details Tree.

The window title bar can have different values. If a traffic capture file is currently opened, its value is file name of this traffic capture file. Otherwise, it is "APPLICATION_NAME". Example: Triple-F SnifferPRODUCT_VERSION: demo.es3f The Main Window also contains a menu bar, giving access to the functions documented below

Additional Instance Mode
If a second instance of the Triple-F Sniffer application is opened (For example by double clicking once again on the Triple-F Sniffer icon), the window title bar contains SpyBox Connections Disabled. All the features of the Triple-F Sniffer can be used as usual, excepted the SpyBox-related feature (see Record Dialog and SpyBox Administration Dialog). In this mode, the

File Menu
• • • • Open. Open a traffic capture file, and displays the messages in the Message List zone. Close. Close the currently opened file. Export. Exports message content in a specified format (CVS, TXT). Exit. Quit the application.

Navigation Menu
• Go to End. Make the Message List scroll to the last visible message of the opened traffic capture file. For a complete explanation of which messages of the traffic capture file are visible, see Message Filters and Layer Selections sections. Next in Connection. Make the Message List scroll to the next message of the opened traffic capture 4

User interface components

file, which belongs to the same SLL Connection. If there is no next Message, the message "No mathing Message found" is displayed in the Status Bar. If there is a next Message, the message "Matching Message at index: " is displayed in the Status Bar, with the index of the corresponding Message. For a complete explanation of which messages of the traffic capture file are visible, see Message Filters and Layer Selections sections. • Previous in Connection: Make the Message List scroll to the previous message of the opened traffic capture file, which belongs to the same SLL Connection. The Status Bar message is the same as in "Next in Connection". Next of type: Make the Message List scroll to the next message of the same type as the currently selected message. The Status Bar message is the same as in "Next in Connection". The type of the message is displayed in the Message Columns. See columns FDL, SLL and STL. Previous of type: Make the Message List scroll to the previous message of the same type as the currently selected message. The Status Bar message is the same as in "Next in Connection". Next error: Make the Message List scroll to next Message which fails at least one. The Protocol Verification. Previous error: Make the Message List scroll to previous Message which fails at least one . The Protocol Verification.

• • •

Tools Menu
• • • • Preferences: open the Preferences dialog. Station/Connections filters: open the Station/Connections filters dialog. Select Columns: open the Column Selection dialog. Connection Colors: open the Connection Colors selection dialog.

Report Menu
• Preferences: open the Report dialog.

SpyBox Menu
• Online Actions: open the Record Dialog. Configure and Upload: open the SpyBox Administration Dialog .

Euroradio Menu
• SpyCable capture: open the Record Dialog. Report: open the Euroradio Quality of Service Report Dialog .

5

User interface components

Key management: open the Euroradio Key Management Dialog .

Help menu
• • Help. Displays the User Documentation in the Windows Help Browser About. Displays a Dialog showing product version information and license information.

Message Options
This user interface zone groups the following controls that give access to message display options: • The Time Settings component.

The Protocol Layers Selection component.

The Connection/Station Filtering component.

The Dual bus settings component. 6

User interface components

The Regular Expression filter component.

Dual Bus Settings
The dual bus settings enable the user to control which bus will be displayed in the message list. Bus choice is mutually exclusive, i. e. you cannot display both messages from both bus at the same time.

Regular Expression filter
The Regular Expression filter enables the user to apply an additional message filter to the messages displayed in the message list. The regular expression text specified by the user will be checked against the summary (For more information about the summary field, see Message Columns) field of each message. The message are displayed only if their summaries matches the regular expression. The filter is only applied if the Enable checkbox is checked. The regular expression is evaluated after the user leaves the regular expression text field, by pressing the tab key, or focusing another user interface component with the mouse. Example: display all messages which summary field contain "STM-1":

Example: display all messages which summary field is exactly "STM-1":

7

User interface components

For a complete reference on regular [http://www.regular-expressions.info/]

expression

syntax,

please

check

this

website.

Message List

This component displays the messages in the selected traffic capture file. This component supports the following user interactions: • • • • Mouse wheel: In order to zoom the font size in and out, use the mouse wheel, combined with the Shift key. The font size will be adjusted accordingly. Left click: Click on a message to select it. Once a message is selected details are displayed in the Details Tree component. Right click: gives access to context menu, with the choice between showing a Details Tree in a new window, and showing the Adjustment factor. Double message selection: If a single message is selected, and a second message is selected using a Mouse Click with the Ctrl key pressed, the time difference between the two messages is displayed in the Status Bar component. Dragging column header: column headers can be dragged by the mouse to another location in the header row, so that they can be re-ordered. Ordering is saved when the user closes the application, 8

User interface components

and restored when the user opens the application again. • Select multiple messages: by selecting a first message using the mouse, then - while pressing the Shift key - selecting a second one, all the message range between these two messages will be selected as well. This multiple message selection can be used for message exports or reports.

Message Columns
This section details all the columns available in the Message List component. The following columns are available: • • • Index: represents the index of the message in the currently opened traffic capture file. This index is zero-based (starts with zero). Time: displays the time value according to the current Time Settings. The time format used is HH:MM:SS.mmm for relative times, and DD/MM/YYYY HH:MM:SS for absolute times. Conn: displays the SLL connection, if the message is of the SLL protocol layer, or above. This column receives a different background color for each connection. Messages belonging to the Profibus have a white background color. Note: Multicast messages, even if they are not part of any connection, do have a connection value. This value is logical, and is added to enable the users to filter (see Message Filters)Multicast packets, based on the virtual connection identifier. The format used for the connection is SA:SSAP->DA:DSAP. • • • • SA: Source Address SSAP: Source Service Access Point DA: Destination Address DSAP: Destination Service Access Point

SA and DA are replaced by a logical device name, if a suitable definition is found in the Device And Connection Configuration file. • • • • • • FDL: Profibus protocol layer packet type. SLL: SLL protocol layer packet type. STL: STL protocol layer packet type. Summary: synthetic information, specific for each packet type. The full packet message information are available in the Detail Tree component DA: Destination address STL Delay: messages that pertain to the STL protocol layer have a STL timestamp attached (with the exception of the SyncAndRefTime message, which carries time synchronization information. This timestamp was recorded at the time the message was sent from the station. Therefore, as the $APPLICATION_NAME application computes a Local Reference Time, a delay can be computed between the STL timestamp, and this Local Reference Time. SA: Source Address. 9

User interface components

Column Selection
This dialog controls which columns are displayed in the Message List component. The columns are displayed in a Tree. If you select the "Columns" node, this will select all columns. Unselecting the "Columns node" will unselect all columns. Pressing the Reset button will restore the selection at the state it was before modifying the selection. Pressing the Apply button will close the dialog, and apply the new column selection to the Message List component. Pressing the Cancel button closes the dialog, without any effect on the current column selection.

10

User interface components

11

User interface components

Protocol Verifications
This section covers all checks made for each Message, at the protocol level. Besides the checks specified below, each protocol layer is verified, to detect message format errors. Error reporting is done for each invalid protocol layer. • • • • SDA Acks: at the FDL level, the Triple-F Sniffer checks that SDA packets are directly followed by an FDL ACK packet, or an FDL SC (Short Ack) packet. Monotonic sequence numbers: at the SLL level, all packets carry a sequence number. They must be incremented by 1 for each packet in the same SLL logical connection. CRC: SLL packets carry a CRC checksum. This CRC is verified. For more details about CRC verifications, see Crc Checks Multicast doubles: the SLL specifies that each multicast packet must be sent twice. the Triple-F Sniffer checks that each packet in the same SLL logical connection is directly followed by its equivalent. HDLC FCS check. the FCS (Frame Check Sequence) described in ISO-7776 are checked. Euroradio MAC check. The MAC (Message Authentication Code) specified in Subset-037 are computed and checked. The Triple-F Sniffer is only able to check the MACs for Euroradio packets if two conditions are provided: • • The user has entered a shared authentication key using the Key Management Dialog. The X224 CR and CC packets are available in the recorded traffic. These packets contain the AU1 and AU2 authentication message, that contains necessary information to perform the MAC checks on the following Euroradio Safety Layer packets (AU3, AR and SaPDU).

• •

For more information about the MACs, see Subset-037 paragraph 7.2.2.2 (Safety Procedures).

Details Tree
This component displays the complete details of the current message (the message selected in the Message List ) component.

12

User interface components

The details are grouped by protocol layer, with a branch of the tree for each protocol layer. The details are formatted according to the underlying data type/representation: • • Raw bytes: each octet is displayed in hexadecimal format, ranging from 00 to FF. Hexadecimal: the value is displayed as an hexadecimal integer, with its integer value between parenthesis. Example: SD2: 0x68 (104) • Composed octet: If an octet contains sub-fields, that only use some bits of the given octet, all subfields are displayed in a sub-branch of the tree display. For each sub-field, the relevant bits are displayed, with a 1/0 value, and the bits pertaining to the other sub-fields are represented by a single dot. For single-bit sub-fields, the value is Set (1) or Not set (0). For multi-bits sub-fields, the integer value is specified between parenthesis, with a constant name, if such constant is available in the protocol layer specifications. Actually, single-bit fields are only relevant for the FDL protocol layer. Time (in miliseconds): formatted in HH:MM:SS.mmm format. Integer: no transformation is made. ASCII String: the octets are decoded in a legible ASCII string.

• • •

Status Bar
This zone is used to display contextual information to the user. It can display the following information: • • • Time difference between two messages in the Message List. See Time Column. Status of a Next/Previous message in Connection/of Type search. See Navigation Menu. Failed verifications details. See Protocol Verifications for the list of verifications.

Message Filters
The message filters dialog enable the user to select the filters to apply on the message visible in the Message List component. It can be very useful to restrict the visible messages to a specific Source/Destination address, or to a specific SLL Connection. A checkbox in the Options Cockpit controls filtering: if checked, the Message List component only displays the messages that comply with the defined message filter. Otherwise, message filters are ignored. Unchecked by default.

13

User interface components

The message filters dialog is split in three zones:

Global Settings: controls how message filters are applied and combined. • Combine: the logical operator used to combine the filters. If AND is selected, the messages to be displayed must match all the Devices and Connections criterias. If OR is selected, the messages to be displayed must match one or more of the Devices and Connections criterias. OK button: applies the modifications to the Message List component.

14

User interface components

• • •

Cancel button: closes the dialog, discarding all changes.

Devices: select the devices for which the Triple-F Sniffer application display Incoming (In) and Outgoing (Out) messages. Connections: select the connections of which the application display the messages

Note: If available, the logical device and connection names substitute for the devices and connection names. To change the logical name for a station, click on its label and change the name. For more explanations on how to define logical Connection names, see Device And Connection Configuration

Layers Selections
This component contains one zone for every low-level protocol layer.

• • •

FDL (see Profibus) SLL (see Safe Link Layer) STL (see Safe Time Layer)

In each protocol layer zone, there is a bold Protocol Layer checkbox, enabling or diabling the full layer. Individual checkboxes for packet types enable to show/hide specific packet types in the Message List component. Layer protocol selection is not cumulative: if you uncheck a layer which sits above another layer (E.g. uncheck STL, while FDL and STL are checked.) it has NO influence on the underlying layers.

Connection Colors Management
This dialog enable the user to customize the colors used in the Connection Column, in the MessageList.

15

User interface components

Each SLL Connection has a clickable label, which background color is the Connection's current color. To change it, click on the label, and select a new color. New selected colors will be restored after Triple-F Sniffer application shutdown/restart.

Time Settings
This group of components controls the value of the Time column in the Message List component.

The user can change the value of two variables: the time display and the time base. They are described in detail in the following paragraphs.

Time Display
This variable determines the computation of the Time column. The computation is as follows: • • Relative: The time from the first message in the current traffic capture file Absolute: The absolute time, computed as follow: The file creation date of traffic capture file plus the time from the first message in the current traffic capture file. Example: if the traffic capture file has a file creation date equals to 1/1/2004 08:12:26.345, and the Relative Message time is 00:00 02:56.789, the Absolute message time is 1/1/2004 08:15.23.134. 16

User interface components

Delta: the time difference between the current message and the previous visible message in the Message List component.

Time Base
This group of controls is only enabled when the Time Display group of control is on Relative or Absolute. It can take the following values: • • Local: The value computed according to the Time Display settings is unmodified. Reference: The value computed according to the Time Display settings is adjusted with a Dynamic Adjustment Factor. This Adjustment Factor is computed according to the STL specifications. For detailed information, see Local Reference Time

Local Reference Time Computation
The STL protocol layer defines how a station must compute the Local Reference Time in chapter 7, "Specifications of functions". The Triple-F Sniffer application keeps track of the Sync And Reference Time packets to compute an adjustment factor, between its Local Time (based on the timestamps on each message in the traffic capture file) and the Reference Clock. This adjustment factor is used to deduce the Local Reference Time. This Local Reference Time can be seen as the "Bus" time and be compared against the Local Reference Time on the devices connected to the Profibus. Technically, the adjustment factor is computed by taking a moving average of the difference between the Local Time and the Reference Time. The size used for the moving average computation is 16 elements.

Connection Management
Point-to-Point Connections are defined in the SLL protocol layer. The Triple-F Sniffer application keeps track of the Packet sequences that make up a SLL Point-to-Point Connection. SLL Packets that do not respect the normal Connection Packet sequence (For example a Data Packet arriving after a Disconnect Packet) are marked as "Out-of-connection" SLL Packets. See Message List for more details about "Out-of-connections" Packets.

Preferences Dialog

17

User interface components

The Preferences dialog contains the following global application settings. • Skip Tokens: if enabled, the application will not read FDL Tokens from the underlying traffic capture file. This option is enabled by default. Be careful when disabling this function, as FDL Tokens might account for 99% of the Profibus network traffic, and will have a high impact on Triple-F Sniffer performance. Do not read whole file: When enabled, the application will not read the full traffic capture file. Messages will be read just-in-time, when the user scrolls down the Message List, or navigates to the end of the Message List. Skip Multicast Doubles. The SLL specifies that Multicast packets must be sent twice on the Profibus bus. This option will disable the display of Multicast doubles. Subset-058 version. A dropdown component proposes the different available versions of the Subset058 specifications that can be used to decode the STM Application Layer messages. The available versions are version 2.1.1, version 2.1.4 and version 2.1.2F. For more information about the different Subset-058 versions, contact the ERTMS STM workgroup.

• •

CRC Verifications
The messages belonging to the SLL protocol layer carry a CRC checksum. This CRC checksum is computed using information contained in the SLL Packet, as well as implicit information. For a complete explanation of CRC checksum computation, look into the SLL specifications. For SLL Multicast packets, all the information needed to compute the CRC is contained in the Packet itself. For other SLL Unicast Packets, the 32 bits Connection Sequence Number must be provided. the Connection Management component keeps track of the sequences of SLL connections as well as the 18

User interface components

Connection Sequence Number, incremented for each Packet. One problem with CRC verification is that the cause of a wrong CRC can be twofold: • • Error when computing the CRC checksum, in the software that originated the Message. Error when verifying the CRC checksum, because of wrong implicit information. For example, if the traffic capture file is missing a previous SLL Packet, the Connection Management component has not been able to increment the Connection Sequence Number, therefore impacting the CRC checksum verification.

FFFIS STM Report Dialog
This dialog is used to generate PDF reports, based on traffic displayed in the analyzer. The report generator takes only the filtered traffic into account, to enable the user to filter out some messages For more information about message filtering, see Message Filters.

19

User interface components

It supports the following options: • • • Report File: specifies the file name to be used to save the generated report. Report Title: specifies the title that will be printed on the report's cover page Use relative times (D.HH:MM:SS): If checked, the times throughout the report will be printed in relative times. Otherwise, absolute times will be used.

20

User interface components

Time Range: restrict the report generation to messages whose arrival time is greater or equal to the "From" value, and smaller or equal to the "To" value. "From" and "To" are expressed in HH:MM:SS, or in absolute time, regarding the value of the "Use relative time" option. Bandwidth reporting: if checked, this option will include bandwidth usage statistics in the report. Bandwidth reporting supports the following options: • • • • Graph per Station: the report will contain a separate bandwidth graph for each station Graph per Connection: the report will contain a separate bandwidth graph for each SLL connection Average window: This is the time in seconds used to compute the average bandwidth. Fixed scale: If checked, bandwidth graphs will use a fixed scale for the Y axis, in place of a proportional scale.

Error reporting: if checked, the report will include information about detected errors in the different protocol layers. For more information, see Protocol Verification . Checkboxes allow the user to specify the protocol layers for which errors must be reported. The following options control how errors are displayed in the report: • Error Expansion: It is possible to control what information is given about each error, by chosing to show no layers (None), just content of the problematic layer (Offending Layer) and all the message content (All Layers). Error Grouping: groups the error by error Time, error source Station or error SLL Connection.

• •

Auto Preview: view the generated report in the default PDF reader after report generation.

Record Dialog

21

User interface components

This dialog is used enable the user to record Profibus and/or Euroradio network traffic using the SpyBox acquisition hardware. To record some traffic, do the following: • • • • Enter the SpyBox I.P. address or hostname Select a file for the captured traffic Optionally, specify a script file to be runned on the recorded traffic. (See Scripting For more explanations.) Enable at least one of the following: • • • • one or both PROFIBUS bus one or multiple Euroradio Modems (Available only if the Euroradio Plugin is installed)

For each bus, select a filtering level If one or more Euroradio modem is selected, specify the DATA and COMMAND baudrates, and the recording options. (See Modem Recording Specifics).

22

User interface components

Push the Record button

Once downloading, a feedback dialog is displayed, containg the following items: • • • • • • Duration: the amount of time since the beginning of the recording session Packets received: the total amount of PROFIBUS and/or Euroradio frames recorded Bytes received: the total amount of bytes recorded Scripting details: If a script file has been specified, this zone displays the standard output streams of the script. (See Scripting For more explanations.) "Open in sniffer..." checkbox: if checked, the captured traffic file will be opened in the Triple-F Sniffer Stop button: if clicked, stop the recording session

SpyBox Administration Dialog

23

User interface components

The SpyBox Administration Dialog enables you to perform the following tasks: • • • • Specify recording mode Specify storage policy Specify for each bus the filtering policy to be applied Enable one or both PROFIBUS bus for recording 24

User interface components

• •

one or multiple Euroradio Modems (Available only if the Euroradio Plugin is installed) Download (and clear) the captured traffic stored in the SpyBox

For a detailed description of the SpyBox configuration settings, see Recording

When you click on Download, a download dialog pops up. This dialog enables the user to: • • • Specify a partial download, with start and end date and time Enable session detection. When enabled, a new file will be created for each session detected by the SpyBox. Clear the captured traffic after download. The complete traffic stored in the SpyBox will be deleted, even if the user has chosen "partial download".

25

User interface components

Export Dialog

This dialog provides the ability to export the content of FDL/SLL/STL/AppLayer messages to a format suitable for external processing. Two export formats are provided: CSV and TXT. The user can restrict the messages and the protocol fields to be exported. • CSV: CSV stands for "comma separated values", and is more or less formally specified here: http://www.ietf.org/internet-drafts/draft-shafranovich-mime-csv-05.txt. The user is free to chose the field separator to be used in the CSV exported file (comma or semicolumn). TXT: raw text format, with a summary line for each message, followed by one additional line for each field and its value, for all protocol layers.

Euroradio Quality Of Service Dialog
This dialog enables the user to create a Subset-093 [http://www.era.europa.eu/public/ERTMS/ERTMS%20Documentation/Informative%20specifications/S ubset-093-v230.pdf] GSM-R Quality of Service report.

26

User interface components

This dialog enables the user to specify the following items: • • • • • File name: the file name under which the report will be saved. Report title: a title which will be inserted in the report. Report type: PDF or CSV (Comma-Separated Values). A CSV file is an easy way to import the data into a spreadsheet for further reporting. CSV separator: only enabled for the CSV report format. This separator will be used to separate the values on each line. Default is ";". The Subset-093 statistics to be included in the generated report.

Euroradio Key Management Dialog
This dialog enables the user to update the 64-bit encryption key shared between the train and the track. The key must be entered in the input text field as follows: 0A 0B 0C 01 02 03 FF FF 0A 0B 0C 01 02 03 FF FF 0A 0B 0C 01 02 03 FF FF The introduced key is saved between sessions. After having changed the key, the user must close and re27

User interface components

open the Euroradio *.es3f file to force MAC recalculation.

Euroradio SpyCable Dialog
This dialog allows to record Euroradio traffic captured from a SpyCable connected to the computer where the Triple-F Sniffer is installed. If baudrates specified for DATA and COMMAND modes are different, the state of the DCD flag is used to automatically switch between the two baudrates during recording (See Modem Recording Specifics).

28

Chapter 4. Recording PROFIBUS traffic with the SpyBox hardware
This chapter describes how to use the dedicated SpyBox hardware to record PROFIBUS traffic.

First steps
Procedure 4.1. Record some Profibus traffic using the SpyBox acquisition hardware.
1. 2. 3. Connect the SpyBox to an ethernet network using an ethernet cable, and connect the SpyBox to a Profibus network using a Profibus bus. Use the File # Record to open the Record Dialog. Browse to the desired file, enable bus 0, and click on the Record button. Once you have recorded enough traffic, click on the Stop button of the recording progress window.

Recording filters
The SpyBox enables you to filter the recorded traffic. As tokens and scans messages account for 98.5% of the PROFIBUS traffic, filtering them out enable the SpyBox to record 100 times more traffic, with the same storage space. The following filters can be used, for each bus individually: • • • Filter Off: records everything, including tokens and scans (most storage-intensive) Skip tokens: records everything but the tokens Skip scans/tokens: records everything but the tokens and the scans (most compact)

Recording session detection
The recorded traffic downloaded from the SpyBox contains end-of-session markes. This end-of-session markers are inserted automatically each time that there is no SDN or SDA traffic on both PROFIBUS buses for more than 5 seconds.

29

Chapter 5. Scripting
Introduction
The scripting facilities in the Triple-F Sniffer enable the user to add new bahaviour to the PROFIBUS/ SLL/STL/AppLayer recording process by writing short (and less short) scripts in the Python [http://www.python.org/] language. NOTE: the scripting facilities are only available in the TripleFSniffer Lab Edition. These scripts can operate in two different modes: • • Online mode: the script receives the stream of messages coming from the SpyBox. This mode is available from the Graphical User Interface and from the Command-line interface. Shell mode: the script receives the stream of messages coming from a previously recorded es3f file. This mode is only available from the Command-line interface.

Some examples of common scripting use cases: • • • • Filter out all tokens and scans in an .es3f file Sends a message on a TCP/IP socket when we see an STM-8 (Odometry) Application Packet containing V_NOM > X. Remotely control recording of es3f files. ... your imagination is the limit!

High-level Architecture
The scripting architecture is embedded in the message processing component of the Triple-F Sniffer. This message processing component is responsible for loading a stream of messages from a source (an online connection to the SpyBox, or an .es3f file), and do something with it. Currently, the Triple-F Sniffer is capable of two things: display the message stream in its graphical user interface, or record it in a file, for later analysis. With the scripting facilities, the user gets an access to the incoming message stream, and can perform specific actions with these messages. The following list of actions are possible: • • • • Custom actions before/after a scripting session. For example: initializing counters, network connections, file descriptors, resource cleanup, etc. Start/Stop message stream recording, with control over the recorded file name. Filter which messages should be recorded. Perform any action for each message. For example: if this message contains an STM-15 packet, and that the NID_STMSTATE is 6 (Hot Standby), then sends an http request to any host, with "HELLO" as content.

30

Scripting

Python language and .Net class libraries
The Triple-F Sniffer is built on top of the .Net framework. The python [http://www.python.org/] interpreter embedded in the Triple-F Sniffer gives the script programmer to the whole .Net 2.0 class library. (See here [http://msdn2.microsoft.com/en-us/library/ms306608(en-us,vs.80).aspx] for a full reference of the .Net API). Besides the full python language, and the complete .Net 2.0 class library, the scripts have access to the FFFIScom [http://www.ertmssolutions.com/fffiscom/csharpapi/] FDL/SLL/STL/ApplicationLayer encoding/decoding library, to give a native, object interface to FDL/SLL/STL/AppLayer decoded messages.

Scripting interface
Script are written in the Python [http://www.python.org/] language. The script is loaded by the Triple-F Sniffer when starting a scripting session. After script loading, the Triple-F Sniffer will check if the following functions are defined in the user script: • • • • • • • init_session(fileNamePrefix): perform initialization tasks. handle_message(message, bus): The place to put custom behavior that must happen for all specific messages. start_recording(message, bus): Returns a (True, filename) tuple to start a new recording session on the given filename, (False, None) otherwise. record_message(message, bus): when the session is currently recording, returns True if message should be recorded, False otherwise. stop_recording(message, bus): Returns True if the current recording session should be stopped, False otherwise. end_session(): perform cleanup tasks. idle(). This function is called when there is no incoming message for more than 1 second. If the user throws an exception, the current recording session will be stopped, and end_session() will be called.

After having loaded the script, the Triple-F Sniffer scripting engine will invoke the user-defined functions in the following order. It is not mandatory to define any functions, non-defined functions will be ignored by the Triple-F Sniffer. • • Once at the beginnig of session, init_session(fileNamePrefix) For each message received from the underlying message source (SpyBox or file): • • • handle_message(message, bus) If the Triple-F Sniffer is not currently recording: start_recording(message, bus). If the Triple-F Sniffer is currently recording: • • record_message(message, bus) stop_recording(message, bus) 31

Scripting

If the stop_recording(...) function has returned True, the functions start_recording(message, bus) and record_message(message, bus) are called again with the same message, so that the user can stop and directly start a new recording session on the same message.

• •

idle(...)is called each second, independently of the recording state.

Once at the end of session, end_session()

Example 5.1. A simple example
#emptytest.py #This script does nothing. def init_session(fileNamePrefix): pass def handle_message(message, bus): pass def record_message(message, bus): return False def start_recording(message, bus): return (False, None) def stop_recording(message, bus): return False def end_session(): pass def idle(): pass

Scripting API Reference
init_session(fileNamePrefix)
This function is called once at the beginning of the recording session. It receives two parameters: • fileNamePrefix: The file name entered by the user if the script has been started from the Graphical User Interface, in the SpyBox Online Actions dialog, None otherwise.

This function returns no value.

32

Scripting

handle_message(message, bus)
This function is called for each message coming from the underlying source (file or spybox). It receives as parameter the message and the bus number (0 or 1) on which this message has been captured. This function returns no value.

start_recording(message, bus)
This function is called for each message coming from the underlying source (file or spybox), when there is no active recording session. It receives as parameter the message and the bus number (0 or 1) on which this message has been captured. This function returns a tuple containing two elements in the following order: a bool value and a string. The bool value set to True indicates that the Triple-F Sniffer should start a new recording session. The string is the name of the file on which the messages will be recorded.

record_message(message, bus)
This function is called for each message coming from the underlying source (file or spybox), when there one active recording session. It receives as parameter the message and the bus number (0 or 1) on which this message has been captured. This function returns a bool value. If the value is set to True, the passed message will be recorded. If set to False, this message will be skipped. If this function is not defined, messages are recorded by default.

stop_recording(message, bus)
This function is called for each message coming from the underlying source (file or spybox), when there one active recording session. It receives as parameter the message and the bus number (0 or 1) on which this message has been captured. This function returns a bool value. The bool value set to True indicates that the Triple-F Sniffer should stop the current recording session.

end_session()
This function is called once at the end of the scripting session. It returns no value.

idle()

Structure of the message parameter
The functions called during the message processing cycle (handle_message(message, bus), record_message(message, bus), start_recording(message, bus) and stop_recording(...)) receive a message as parameter. The parameter type is FFFISStmPacket. It is instantiated by the Triple-F Sniffer message processing and contains the decoded messages for PROFIBUS/SLL/STL/Application Layer. The accessors message[Layers.PROFIBUS], message[Layers.SLL] and message[Layers.STL] give access to the respective decoded packet objects. An additional accessor, 33

Scripting

message.AppLayerContent returns the Application Layer wrapper, or None if this message[Layers.SLL] cannot be decoded as a valid Subset-058 application message. The message.AppLayerContent.Message accessor gives access to the Subset058Message [http://www.ertmssolutions.com/fffiscom/csharpapi/FFFISCOM.utils.Subset058Message.html] instance. For a complete description of the API of decoded protocol objects, take a look at the FFFIScom API documentation [http://www.ertmssolutions.com/fffiscom/csharpapi/].

How to run your first script
This section illustrates a very simple script to filter out all pure profibus traffic (tokens, scans, acks, short acks) from a previously recorded *.es3f file

#emptytest.py #This script filters out the tokens and scans from a previously recorde def start_recording(message, bus): """ we start recording at the first packet, in the filtered.es3f file """ return (True, "filtered.es3f") def record_message(message, bus): """ We accept only messages for which layer > PROFIBUS """ return (message.Layer > Layers.PROFIBUS):

Procedure 5.1. Run a simple script on an existing *.es3f file.
1. 2. 3. Open a system console, make sur the Triple-F Sniffer installation directory is your PATH. Run the TripleFShell command as follow: TripleFShell -scriptfile=simple.py --file=basic.es3f Open the filtered.es3f to check the result. --enablescript -

Complex scripting example: Server mode implementation
Because the protocols requirements will be different for each user (TCP, UDP, HTTP, ...), the Triple-F Sniffer do not ship a fixed remote control TCP/IP protocol. The purpose of this example is to show how to implement remote recording start and stop via TCP/IP, using the scripting interface.

#HttpRecordingServer.py #This script starts an HTTP server listening for HTTP POST requests, wi #"START" or "STOP" in the request body. "START" and "STOP" will turn on #packets recording. #import webserver component. 34

Scripting

#For the full API documentation of HttpListener class, #look there: http://msdn2.microsoft.com/en-us/library/34xswsd2(en-US,VS from System.Net import HttpListener from System.Text.Encoding import UTF8 from System.IO import StreamReader #declare a global HttpListener variable httpListener = HttpListener() #configure it to listen to port 8080 httpListener.Prefixes.Add("http://*:8080/") #store the desired recording state, defaulting to False recording = False def init_session(fileNamePrefix): global httpListener httpListener.Start(); #pass the function handle_http_request as HTTP requests handler, and #starts non-blocking listening httpListener.BeginGetContext(handle_http_request, None) def start_recording(message, bus): global recording return recording def stop_recording(message, bus): global recording return not recording def end_session(): global httpListener #stop listener at the end of the session. httpListener.Stop(); def handle_http_request(asyncResult): #HTTP request handler. We use .Net components #to read the request, and format an "OK" response. global httpListener, recording context = httpListener.EndGetContext(asyncResult) requestBody = StreamReader(context.Request.InputStream).ReadToEnd() #handle the command if requestBody == "START": recording = True if requestBody == "STOP": recording = False response = UTF8.GetBytes("OK") #Get a response stream and write the response to it. context.Response.ContentLength64 = response.Length context.Response.OutputStream.Write(response,0,response.Length) #You must close the output stream. context.Response.OutputStream.Close() #handle next request httpListener.BeginGetContext(handle_http_request, None)

35

Chapter 6. JRU Messages Decoding Plugin
Introduction
The JRU Messages Decoding Plugin enables the Triple-F Sniffer to decode the messages sent from the EVC to the JRU, when the following conditions apply: NOTE: the JRU Messages Decoding Plugin requires that your license.txt file includes jru plugin activation. Without that, the plugin configuration will have no effect. • The Messages sent from the EVC to the JRU comply the format specified in UNISIG Subset-027 version 2.2.10. (Check the ERA website to download [http://www.era.europa.eu/public/ERTMS/Approved_Documents_List_of_mandatory_Specification s.aspx] the Subset-027 specification) The EVC is using the SLL and STL protocol layers to connect to the JRU.

Some JRU messages contain embedded Euroradio, Eurobalise and Euroloop messages, encoded as defined in UNISIG Subset-026 (Check the ERA website to download [http://www.era.europa.eu/public/ERTMS/Approved_Documents_List_of_mandatory_Specifications.as px] the Subset-026 specification). These messages are also fully decoded in the Triple-F Sniffer.

How to activate the JRU plugin?
1: Shut down the Triple-F Sniffer 2: Open the Triple-F Sniffer session settings XML configuration file with any text editor, and insert the following XML fragment

<PluginConfig> <JruPlugin SourceAddress="..." DestinationAddress="..." Sap="..." /> </PluginConfig>

right after the Colors XML fragment:

<Colors> <Mappings> ... </Mappings> </Colors>

36

JRU Messages Decoding Plugin

3: Make sure that you match the SourceAddress, DestinationAddress and Sap attributes the ones used by the EVC to connect to the JRU. If the addresses and/or sap do not match, the JRU messages will be marked as Invalid messages by the Protocol Verification component. 4: Save the configuration file and restart the Triple-F Sniffer.

JRU Plugin Screenshots
JRU messages without the plugin configured: JRU messages with the JRU Plugin in action: Some decoding details:

37

Chapter 7. Euroradio Plugin
Introduction
The Euroradio Plugin adds the following features to the Triple-F Sniffer: • Decoding of the full Euroradio protocol stack: HDLC, T.70, X.224, Euroradio safety layer and Subset-026 application messages and packets, to decode the communications between an EVC and one or more RBCs. SpyCable recording, eliminating the need of a SpyBox hardware, for Euroradio recording using just a Triple-F Sniffer-installed PC with a SpyCable. For more information about the SpyCable design, check the SpyCable section.

Serial modem recording specifics
While recording traffic exchanged between a DTE (E.g. EVC )and a DCE (E.g. GSM-R Modem), the baudrates used for the serial link between the DCE and DTE may vary. Support is provided in the Triple-F Sniffer through the option "Change BaudRate on DCD". This option enables the user to specify different baudrates for COMMAND and DATA modes, and to configure the SpyCable recording to automatically switch baudrate when the state of the DCD flag changes.

SpyCable design
The SpyCable is a cable designed on purpose for spying the signals between a computer and a Modem, connected by an RS-232 serial cable. It will send the RX and TX signals to the RX signals in two other RS-232 cables, allowing another computer to observe the communication without any interference. • • • • A: to be connected to the cable going out of the DTE (E.g. EVC or RBC) B: to be connected to the cable going out of the DCE (I.e. modem) C: to be connected to the Triple-F Sniffer-equipped PC or SpyBox, for Upstream communication D: to be connected to the Triple-F Sniffer-equipped PC or SpyBox, for Downstream communication

The following schema sketch the design of a SpyCable, with all the necessary wire connections.

38

Euroradio Plugin

39

Chapter 8. Command-line interface
This chapter describes the Command-line interface, its usage options and its output.

Command-line manual
The application can be used in a command prompt to support traffic capture file validation, detailed dumps or scripting. SnifferShell {--file} [-v] [--strictcrc] [--keeptokensandscans] [--bus0] [--bus1] [--sllchecks] [--raw] [--enablescript] [--scriptfile] [--spyboxaddress] [--subset58version] [--euroradiomodems] [--databaudrate] [--commandbaudrate] [--baudratefollowdcd] [--detectatpricommand] • • • -t: "Text mode". If not specified, the Application will open its Graphical User Interface. --file=myfile.myext: "File". The traffic capture file to process. -v: "Verbose". Output complete Message information for each Messages. If not specified, the command will only output the following: [bin]> ./SnifferShell --file=test.trace Trace successfully decoded 137373 packets [bin]> --strictcrc: "Strict CrC": verifies the CRC. In case of invalid CRC, an error will be outputted, and processing will stop. --keeptokensandscans: "Keep tokens and scans": read Profibus Token and Scans Packets. By default, these are skipped when recording from the command-line. --bus1: Specify PROFIBUS bus 1 as the master bus to be used to read a trace file. Bus 0 is the default master bus. --sllchecks: Enforce SLL checks for command-line trace file reading. Otherwise, the SLL checks are not enforced. --raw: output the raw bytes and status of each record in the trace file. --enablescript: turn on the scripting engine, for online or trace file evaluation. --scriptfile=myscriptfile.py specifiy the path to the script file to be executed. --spyboxaddress: when doing online scripting, specify the IP address of the SpyBox. --subset58version=[1|2|3] Specify the version of the subset-058 to be used for decoding. The numbers correspond to the following subset-058 versions: • • • • • • 1: V2.1.1 2: V2.1.4 3: V2.1.2F

• • • • • • • • •

--euroradiomodems: Comma-separated list of euroradio modems to be recorded from the SpyBox. Euroradio modems have indexes going from 0 to 3. --databaudrate: Baudrate to be used for euroradio recording in DATA mode. --commandbaudrate: Baudrate to be used for euroradio recording in COMMAND mode. 40

Command-line interface

--baudratefollowdcd: If this option is specified, euroradio recording will use the baudrates specified for DATA and COMMAND according to the state of the DCD flag. (See Modem Recording Specifics). --capturescriptout: If this option is specified, the standard output streams and error streams are redirected to the Triple-F Sniffer log file, TripleFShell.log. By default, these output streams will appear on the console output.

41

Chapter 9. Configuration files
This chapter describes the various Triple-F Sniffer application configuration files.

Session Settings Config
This configuration file is located in the Triple-F Sniffer installation directory, and is called snifferconfig.xml. The session settings config file stores information about the following User Interface items: • • • • • • • • traffic capture file: the path to the currently opened traffic capture file Window settings: the position of the Main Window component, its size, and its maximized/normal state. Selected columns: the name of each selected columns. See Column Selection for more info on how to select column. Selected layers. the protocol layers selected for display. See Layer Selections for more info on how to select protocol layers. Column styles: the position and size of all columns (displayed or not). Message Filters Settings: the content of the Message Filters dialog. Connection colors: the content of the Connections Color Management dialog. Plugin configuration: the configuration of the various Protocol Plugins installed in the Triple-F Sniffer. See for instance JRU Plugin

NOTE: This configuration file is overwritten every time the application is closed. If modified by hand and invalid, its whole content will be discarded. It is created the first time the user exits the application. It is not advised to modify this file manually.

Devices And Connections Configuration
The column Connection in the Message List component contains the SLL Connection identifier. The connection identifier can be replaced by a logical connection identifier specified in the configuration file. To add a new logical device identifier, insert a new XML tag under the <DevicesMapping> element as in the following example: <Device Name="LOGICAL DEVICE NAME" Address="2"/>

To add a new logical connection identifier, insert a new XML tag under the <DevicesMapping> element such as the following example:

<LogicalConnection Name="STM-CONTROL-1" SourceDevice="2" SourcePort 42

Configuration files

43

Index

44