TM

Spirent TestCenter Automation

Programmer’s Guide
January 2008

P/N 71-003850 REV A

Spirent Communications, Inc.
26750 Agoura Road
Calabasas, CA
91302 USA

Copyright
© 2007 Spirent Communications, Inc. All Rights Reserved.
All of the company names and/or brand names and/or product names referred to in this document, in particular, the
name “Spirent” and its logo device, are either registered trademarks or trademarks of Spirent plc and its subsidiaries,
pending registration in accordance with relevant national laws. All other registered trademarks or trademarks are the
property of their respective owners. The information contained in this document is subject to change without notice
and does not represent a commitment on the part of Spirent Communications. The information in this document is
believed to be accurate and reliable, however, Spirent Communications assumes no responsibility or liability for any
errors or inaccuracies that may appear in the document.

Limited Warranty
Spirent Communications, Inc. (“Spirent”) warrants that its Products will conform to the description on the face of
order, that it will convey good title thereto, and that the Product will be delivered free from any lawful security interest
or other lien or encumbrance.
Spirent further warrants to Customer that hardware which it supplies and the tangible media on which it supplies
software will be free from significant defects in materials and workmanship for a period of twelve (12) months, except
as otherwise noted, from the date of delivery (the “Hardware Warranty Period”), under normal use and conditions.
To the extent the Product is or contains software (“Software”), Spirent also warrants that, if properly used by Customer
in accordance with the Software License Agreement, the Software which it supplies will operate in material
conformity with the specifications supplied by Spirent for such Software for a period of ninety (90) days from the date
of delivery (the “Software Warranty Period”). The “Product Warranty Period” shall mean the Hardware Warranty
Period or the Software Warranty Period, as applicable. Spirent does not warrant that the functions contained in the
Software will meet a specific requirement or that the operation will be uninterrupted or error free. Spirent shall have no
warranty obligations whatsoever with respect to any Software which has been modified in any manner by Customer or
any third party.
Defective Products and Software under warranty shall be, at Spirent's discretion, repaired or replaced or a credit issued
to Customer's account for an amount equal to the price paid for such Product provided that: (a) such Product is
returned to Spirent after first obtaining a return authorization number and shipping instructions, freight prepaid, to
Spirent's location in the United States; (b) Customer provides a written explanation of the defect or Software failure
claimed by Customer; and (c) the claimed defect actually exists and was not caused by neglect, accident, misuse,
improper installation, improper repair, fire, flood, lightning, power surges, earthquake, or alteration. Spirent will ship
repaired Products to Customer, freight prepaid, based on reasonable best efforts after the receipt of defective Products.
Except as otherwise stated, any claim on account of defective materials or for any other cause whatsoever will
conclusively be deemed waived by Customer unless written notice thereof is given to Spirent within the Warranty
Period. Spirent reserves the right to change the warranty and service policy set forth above at any time, after
reasonable notice and without liability to Customer.
TO THE EXTENT PERMITTED BY APPLICABLE LAW, ALL IMPLIED WARRANTIES, INCLUDING BUT
NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS
FOR A PARTICULAR PURPOSE, ARE HEREBY EXCLUDED, AND THE LIABILITY OF SPIRENT, IF ANY,
FOR DAMAGE RELATING TO ANY ALLEGEDLY DEFECTIVE PRODUCT SHALL BE LIMITED TO THE
ACTUAL PRICE PAID BY THE CUSTOMER FOR SUCH PRODUCT. THE PROVISIONS SET FORTH ABOVE
STATE SPIRENT'S ENTIRE RESPONSIBILITY AND CUSTOMER'S SOLE AND EXCLUSIVE REMEDY WITH
RESPECT TO ANY BREACH OF ANY WARRANTY.
Contents
About this Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Related Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
How to Contact Us . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Spirent TestCenter API Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Object, Attribute, and Relation References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Spirent TestCenter Automation API Functions . . . . . . . . . . . . . . . . . . . . . . . 19
Chassis Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Chassis Connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
The PhysicalChassisManager Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Module Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Chassis Disconnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Spirent TestCenter Script Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Return Status and Error Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Test Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Chassis Connection, Port Reservation and Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Text Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Script Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
The Spirent TestCenter Command Sequencer . . . . . . . . . . . . . . . . . . . . . . . . 65
Using the Sequencer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Sequencer Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Sequencer / Command States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Sequencer Example (Basic) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Sequencer Example (Advanced). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Spirent TestCenter Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Paged Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
End-of-Test Results Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP . . . . . . . . . . 113
PGA Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Using Spirent TestCenter Automation for PGA Tests . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Packet Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Test Analysis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Point-to-Point Protocol over Ethernet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
PPPoE Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Using Spirent TestCenter Automation for PPPoE Tests . . . . . . . . . . . . . . . . . . . . . . . . 142
PPPoE Example (Tcl) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Unicast Routing - Border Gateway Protocol (BGP). . . . . . . . . . . . . . . . . . . 173
BGP Test Configuration Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Spirent TestCenter Automation Programmer’s Guide | 3

Contents

BGP Communication in the Spirent TestCenter Environment . . . . . . . . . . . . . . . . . . . . 175

BGP Example (Tcl) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

4 | Spirent TestCenter Automation Programmer’s Guide

About this Guide
In About this Guide...
• Introduction . . . . 6

• Related Documentation . . . . 7

• How to Contact Us . . . . 8

Spirent TestCenter Automation Programmer’s Guide | 5

About this Guide

Introduction
This manual provides information about the Spirent TestCenter Automation API syntax
and functions. It also provides descriptions of how to use the API along with examples of
creating and running test configurations.
This manual is intended for users who wish to use the Spirent TestCenter Automation API
to perform tests using the features of one of the Spirent TestCenter Automation packages
(such as the Multicast base package or the RFC 2544 test package). It is assumed that
users of this manual have the following knowledge and experience:
• Familiarity with the operating system environment on your PC or workstation
(Microsoft® Windows® or Linux®/Unix®).
• Moderate familiarity with Spirent TestCenter equipment
• Working knowledge of data communications theory and practice
• Ability to program with the Tcl scripting language.
The following table provides a brief description of the sections in this manual.

Manual Section Description

Spirent TestCenter API Syntax Provides information about the API syntax.

Spirent TestCenter Automation API Functions Descriptions of the API functions.

Chassis Management Provides information about accessing a Spirent

TestCenter chassis.

Spirent TestCenter Script Template Provides an example script that demonstrates the basic
elements that every Spirent TestCenter Automation
script uses to create and run tests.

The Spirent TestCenter Command Sequencer Describes the Spirent TestCenter Sequencer and
provides Tcl examples of using the Sequencer.

Spirent TestCenter Results Provides information about using Spirent TestCenter

Automation to retrieve test results.

Packet Generator and Analyzer – Ethernet, IP, Describes how to write scripts to generate and analyze
TCP, and UDP network traffic.

Point-to-Point Protocol over Ethernet Provides information about using Spirent TestCenter
Automation to test PPPoE, including a Tcl example that
creates a PPPoE test configuration and runs the test.

Unicast Routing - Border Gateway Protocol Describes how to use Spirent TestCenter Automation to
(BGP) test BGP, including a Tcl example that creates a BGP
test configuration and runs the test.

6 | Spirent TestCenter Automation Programmer’s Guide

 About this Guide

Related Documentation
Additional documentation items that are related to this manual are listed below.
• Spirent TestCenter Automation Object Reference. Contains reference information
about the objects in the Spirent TestCenter data model.
• Spirent TestCenter Automation Programmer’s Guide. Describes the Spirent
TestCenter Automation functions and contains information about using the API to
write Tcl scripts for specific protocols and particular elements of network
performance testing.
• External Time Reference (GPS/CDMA) User Guide. Describes the GPS/CDMA kits
available from Spirent Communication, explains GPS/CDMA theory of operation,
and describes how to set up GPS/CDMA for use with Spirent TestCenter and
SmartBits equipment.
• Getting Started with Spirent TestCenter. Provides details on how to install Spirent
TestCenter chassis and modules and how to obtain license keys.
• Spirent TestCenter System Reference Manual. Describes the Spirent TestCenter
chassis, modules, accessories, and software applications. General information is also
provided on system administration functions, testing procedures, and diagnostics.
In addition to these manuals, all Spirent TestCenter software applications include detailed,
context-sensitive online Help systems.
A glossary of Spirent TestCenter terminology is available in each Spirent TestCenter
online Help file.

Spirent TestCenter Automation Programmer’s Guide | 7

About this Guide

How to Contact Us
To obtain technical support for any Spirent Communications product, please contact our
Support Services department using any of the following methods:

Americas
E-mail: [email protected]
Web: http://support.spirentcom.com
Toll Free: +1 800-SPIRENT (+1 800-774-7368) (US and Canada)
Phone: +1 818-676-2616
Fax: +1 818-880-9154
Hours: Monday through Friday, 05:30 to 16:30, Pacific Time

Europe, Africa, Middle East

E-mail: [email protected]
Web: http://support.spirentcom.com
Phone: +33 (0) 1 61 37 22 70
Fax: +33 (0) 1 61 37 22 51
Hours: Monday through Thursday, 09:00 to 18:00, Friday, 09:00 to 17:00, Paris Time

Asia Pacific
E-mail: [email protected]
Web: http://support.spirentcom.com.cn
Phone: 400 810 9529 (mainland China)
Phone: +86 400 810 9529 (outside China)
Fax: +86 10 8233 0022
Hours: Monday through Friday, 09:00 to 18:00, Beijing Time
The latest versions of user manuals, application notes, and software and firmware updates
are available on the Spirent Communications Customer Service Center websites at
http://support.spirentcom.com and http://support.spirentcom.com.cn (China).
Information about Spirent Communications and its products and services can be found on
the main company websites at http://www.spirentcom.com and
http://www.spirentcom.com.cn (China).

Company Address
Spirent Communications, Inc.
26750 Agoura Road
Calabasas, CA 91302
USA

8 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Syntax

Spirent TestCenter API Syntax

The Spirent TestCenter Automation API provides a powerful syntax that allows you to
combine object and attribute references to create and manipulate your test configuration.
The syntax for a call to a Spirent TestCenter Automation function uses one of the
following formats:
functionName objectReference [–attributeReference [...]]
functionName [value [...]]
The following table provides an overview of the API syntax elements. For more
information, see Object, Attribute, and Relation References.

Syntax Element Description

functionName One of the function names defined for the API.

Examples:
create
get
config

objectReference objectType – An object type name.

Example:
One of the following: stc::create Project

objectType objectHandle – The handle of an existing object.

or Example:
objectHandle stc::get $project_handle
or For more information, see Referencing Objects: Object Handles.
DDNpath
DDNpath – A Direct-Descendant Notation (DDN) path name that identifies a set of
object types or an object.
Examples:
stc::create Project.Port
stc::get $project_handle.Port
For more information, see Direct-Descendant Notation (DDN).

Spirent TestCenter Automation Programmer’s Guide | 9

Spirent TestCenter API Syntax

Syntax Element Description

attributeReference attributeName – The name of an object attribute. To retrieve attribute values, specify the
object handle and one or more attribute names. Attribute names must start with a dash
character (–):
One of the following:
Examples:
attributeName
stc::get $port -location
or stc::get $port -active -location
attrNameValue attrNameValue – Attribute name-value pairs identify an object property and supply a
or value for that property. The attribute name must start with a dash character (–). The
attribute value is separated from the name by a space. In a sequences of name-value
DANpath [Value]
pairs, one pair is separated from the next by a space.
or
Example:
relationReference stc::config $port -active false -location "//10.1.1.1/1/1"

DANpath [Value] – Descendant-Attribute Notation (DAN) path name; a DAN attribute

reference is a path name that begins with a dash (–), followed by a sequence of one or
more object type names, and ends with an attribute name; the names are separated by
dots. A DAN attribute reference may also include a value.
Examples:
stc::create $streamblock -under $port -frameconfig "" \
-ethernet.EthernetII.etherType 880B
stc::config $project -Port.active false
stc::get $project -Port.active
For more information, see Descendant-Attribute Notation (DAN).

relationReference – A relation reference provides access to the object(s) at one side of

the relation connection.
Example:
stc::get $port1 -children
For more information, see Relation References.

value A value may be an IP address, host name, chassis/slot/port tuple, integer, or a string
value.
Examples:
stc::connect //172.168.1.1
stc::reserve //172.168.1.1/1/1
stc::sleep 5

10 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Syntax

NOTES:
• Use the Spirent TestCenter namespace “stc” to identify Spirent TestCenter
Automation functions (for example, stc::create).
• Spirent TestCenter Automation functions names are case-sensitive. Function
names are specified using lower-case characters. Object and attribute names
are case-insensitive.

Object, Attribute, and Relation References

API function calls contain references that identify objects, object attributes, and relations.
Depending on the circumstance, use one of the following syntax elements:
• Creating Objects: Object Type Names and Paths
• Referencing Objects: Object Handles
• Referencing Objects: Object Paths
• Relation References

Creating Objects: Object Type Names and Paths

When you create Spirent TestCenter objects, you specify the type of object to be created.
For example:
set myProject [stc::create Project]
This call to create produces a single object (type Project) and returns a handle to that
object.
You can also create a set of objects in a single call to the create function by specifying an
object type path name. Path names are sequences of object type names, separated by dots.
To use a path name with the create function, you must create the new objects under an
existing object. For example:
set router [stc::create Router.BgpRouterConfig -under $proj]
This call to create produces two objects, one for each object type in the path. Note that the
object types in the path must represent valid parent-child relationships in correct
descending order. The create function returns the handle of the object corresponding to
the first type in the list (in this case, the Router object). To obtain information about the
descendant object(s) (the BgpRouterConfig object), use the get function to retrieve the
object handles:
set routerChildren [stc::get $router -children]
The get function returns the children of the Router object – in this case, the handle to the
BgpRouterConfig object.
You can also use a path name in an attribute reference to create a set of objects:

Spirent TestCenter Automation Programmer’s Guide | 11

Spirent TestCenter API Syntax

set streamBlock [stc::create StreamBlock -under $port(1) \

-frameconfig "" -ethernet:EthernetII.etherType 880B ]

The call to the create function creates a StreamBlock object. Spirent TestCenter uses the
path specification in the attribute reference to create an additional object, in this case, an
EthernetII header object as a child of the newly created StreamBlock object. Spirent
TestCenter sets the etherType attribute when it creates the EthernetII object. For more
information about using path names, see Referencing Objects: Object Paths.

Referencing Objects: Object Handles

In many cases, when you call Spirent TestCenter Automation functions, you either
provide or obtain an object handle. A handle is a string value that identifies a Spirent
TestCenter Automation object. Object handles are the links between your application and
the object hierarchy maintained by Spirent TestCenter Automation. The following
sections describe how to create and use object handles.

NOTE: In some circumstances, Spirent TestCenter will create objects on your behalf.
Each object description in the Spirent TestCenter Automation Object Reference lists the
associated automatic objects.

Creating Object Handles

Spirent TestCenter Automation creates handles when it creates the objects in your object
hierarchy. When you call the create function, the object handle is the return value from the
function:
set project_handle [stc::create Project -name “BGPTest”]
When the create function returns, the variable project_handle is set to the value of the
object handle for the newly created Project object. Your application then uses the object
handle in other calls to Spirent TestCenter Automation functions.

Using Object Handles

You use object handles in the following circumstances:

• To identify the parent for a new object. With the exception of the Project object, you
must specify a parent when you create an object. For example:

set port_handle [stc::create Port -under $project_handle]

In this example, the -under attribute specifies the Project object handle as the parent
for the new Port object. The create function returns the handle for the Port object;
you use this object handle as the parent for StreamBlock objects or other objects that
are children of a Port object.
• To gain access to object attributes. You provide a handle when you call get to retrieve
an attribute value, or when you call config to modify an attribute value. You may also

12 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Syntax

use handles when you execute a command with the perform function (if the command
requires access to an object).

Referencing Objects: Object Paths

You can use path name notation to reference objects and object attributes in your test
hierarchy. The path name references shorten the command line and reduce the need to
obtain handles to access objects.
When you use the Spirent TestCenter Automation API, a function call identifies an object,
or it identifies an object and one (or more) of its attributes. For example:
stc::delete $port
stc::config $port -location “//10.100.0.1/1/1”
The API supports the use of path names for both object and attribute identification; the
context determines the type of notation. To specify a path name, use one of the following
notations:
• Direct-Descendant Notation (DDN)
• Descendant-Attribute Notation (DAN)
• Indexed Notation (DDN and DAN)

Direct-Descendant Notation (DDN)

Use Direct-Descendant Notation (DDN) as an object reference in a function call to

identify an object without having to retrieve its handle. DDN is a dotted path name
sequence beginning with an object handle, followed by one or more object type names.
handle.type[.type...]
The object types in the sequence must represent objects in a valid parent-child descendant
path in your test hierarchy (extending from the object associated with the object handle).
For example:
stc::config $project.Port -location "//mychassis1/1/2"
The $project.Port object reference identifies the first Port child of the $project
object; the -location value is applied to the Port object. (See Indexed Notation (DDN and
DAN) for information about identifying one of multiple children of the same type.)
DDN is particularly useful when changing multiple attributes for a single descendant
object:
stc::config $project.Port -active false -location "//10.1.1.1/1/1"

In the example above, both -active and -location attribute values are applied to the Port
child of the $project object.

Spirent TestCenter Automation Programmer’s Guide | 13

Spirent TestCenter API Syntax

Descendant-Attribute Notation (DAN)

Use Descendant-Attribute Notation (DAN) to identify attributes of descendant objects.

DAN combines both object and attribute portions of a function call to resolve the attribute
reference. The object portion identifies the beginning of the descendant path. The attribute
specification is a dotted path name beginning with a dash (–), followed by a sequence of
one or more object types, and ending with an attribute name. A DAN reference uses the
following syntax:
-type[.type...].attribute
The first name of the sequence must specify a type of one of the children of the object part
of the function call. For example:
stc::config $project -Port.active false
Using DAN, the attribute path name (-port.active) identifies the active attribute for the
Port child of the $project object.
DAN is particularly useful when changing an attribute in two or more different
descendants:
stc::config $project -port(1).active false -port(2).active false

In the example above, the attribute references (-port(1).active and -port(2).active)

specify the active attribute for two Port children of the $project object. The example
uses indexed notation to identify the descendant objects. See the following section for
information about indexed notation.
You can also use DAN to create a set of objects:
set streamBlock [stc::create StreamBlock -under $port(1) \
-frameconfig "" -ethernet:EthernetII.etherType 880B ]

The call to the create function creates a StreamBlock object. The call also contains a
DAN path specification as part of the etherType attribute reference. Spirent TestCenter
uses the DAN path specification to create the objects identified in the attribute reference,
in this case, an EthernetII header object as a child of the newly created StreamBlock
object.

Indexed Notation (DDN and DAN)

Both direct-descendant and descendant-attribute notations support indexing to identify

one of a set of descendants of the same type. Under a particular parent, for a set of child
objects of the same type, Spirent TestCenter assigns sequential indices starting with the
index value 1. In the following function call, the reference to the Port object identifies the
first port created. (A reference without an index identifies the first object of the specified
type.)
stc::config $project.Port -location “//mychassis1/1/2”

14 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Syntax

To identify one of multiple children of the same type, specify the index of the desired child
in parenthesis. The following examples show the use of indices in both DDN and DAN
paths.
stc::config $project.Port(2) -location “//mychassis1/1/2”
set enabled [stc::get $port1 \
-StreamBlock(2).enableControlPlane]

Relation References
Relations are connections between objects in your test configuration. For example,
relations are used to define the parent-child connection between objects, or to define the
connection between a stream and a port. When you create your test configuration, Spirent
TestCenter creates some relations on your behalf; in some cases, you create additional
relations to define additional connections.
A relation reference consists of a side name and an optional handle list:
-sideName [handleList]
-DANPath.sideName [handleList]
A side name is a single name that identifies both the relation and one side of the relation.
For example:
stc::get $port1 -children
The following sections provide more information about relation references.

Relation Definitions

A relation definition:
• Specifies two sides to the connection, identifying the object types that can be used as
sources and targets.
• Specifies side names. Use side names to reference the objects in a relation.
• For the parent-child relation, the side names are “parent” and “children.”
• See the relation tables in the object descriptions for additional side names defined
for particular relation types.

Spirent TestCenter Automation Programmer’s Guide | 15

Spirent TestCenter API Syntax

Side Name References

A relation reference includes a side name to indicate both the relation type and the side of
the relation. A side name specification can be one of the following:
-sideName
-DANPath.sideName
For example:
stc::get $port1 -children
stc::get $project -Port(1).children
stc::config $pppoeCBD -UsesIf "$ipv4If $pppoeIf"

Retrieving Object Handles

When you use a relation reference in a call to the get function, Spirent TestCenter returns
one or more object handles. For example:
stc::get $port1 -children
This function call returns a list containing the object handles for all of the children of the
specified Port object.
When you use a relation to retrieve the handles of child objects, you can specify an object
type to filter the set of objects. Spirent TestCenter supports filtering of child relations only.
For example:
stc::get $port1 -children-StreamBlock
This function call returns the handle(s) for the StreamBlock child object(s) of the
$port1 object.

Modifying a Relation

When you modify a relation (change the object that is the source or target of a relation),
you provide one or more object handles for the specified side of the relation. To modify a
relation, use a side name and a list containing one or more handles:
-sideName handleList
-DANPath.sideName handleList
For example:
stc::config $port1 -affiliatedPortSource $host1
Although you can use relation references to modify a relation and to retrieve object
handles for remote objects defined by a relation, you cannot use a relation reference to get
or set an attribute for the resulting object(s). In order to manipulate attributes in a remote
object, you must first obtain the handle, then use the handle to directly access the attribute.
For example:

16 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Syntax

set stream1 [stc::get $port1 -expectedRxSource]

set stream1State [stc::get $stream1 -state]

The first call to the get function retrieves the handle to the StreamBlock object at the
source side of the ExpectedRx relation. The second call retrieves the value of the State
attribute from the StreamBlock object.

Relation References - Full Specification

You can also use the full specification of a relation reference. This form may be
deprecated at some time in the future. A full specification for a relation reference includes
both the relation type and the side of the relation:
-relationType-side
-DANPath-relationType-side
Specify the side of the relation (“sources” or “targets”) explicitly. For example:
stc::get $port1 -ParentChild-targets
stc::get $project -Port(1).ParentChild-targets
stc::config $pppoeCBC -UsesIf-targets "$ipv4If $pppoeIf"
It is easier to use the shorter, simpler side names in relation references. The side name
takes the place of a -relationType-side combination. For example:
stc::get $port1 -children
stc::config $pppoeCBD -UsesIf "$ipv4If $pppoeIf"

Spirent TestCenter Automation Programmer’s Guide | 17

18 | Spirent TestCenter Automation Programmer’s Guide
 Spirent TestCenter Automation API Functions

Spirent TestCenter Automation API Functions

Spirent TestCenter Automation provides an Application Programming Interface (API) that
you use to create and run tests.
• The API functions are designed to create and manipulate test configurations based on
the Spirent TestCenter data model. For detailed information about the data model, see
the Spirent TestCenter Automation Object Reference.
• The API defines specific commands that you use to execute your test. For information
about using Spirent TestCenter Automation commands, see the description of the
perform function and the section that describes how to use The Spirent TestCenter
Command Sequencer.
• For information about syntax, see Spirent TestCenter API Syntax.
The functions for the Spirent TestCenter API are:

• apply • log

• config • perform

• connect • release

• create • reserve

• delete • sleep

• disconnect • subscribe

• get • unsubscribe

• help • waitUntilComplete

Spirent TestCenter Automation Programmer’s Guide | 19

Spirent TestCenter API Functions

apply

Description Sends a test configuration to the Spirent TestCenter chassis.

Syntax apply

Comments The apply function sends a test configuration to the connected chassis (see the description
of the connect function). Spirent TestCenter applies those objects for which the value of
the active attribute is True. (An object active attribute is set to True by default.) Note that
if an object active attribute is set to False, Spirent TestCenter does not apply the
configuration for that object, and it does not apply any of its descendants either, regardless
of a descendant’s active setting.
If you are running your test by executing individual test steps, then you must apply your
test configuration before you execute any test steps (such as starting router
communication or starting traffic).You also use the apply function to activate any changes
that you have made to your test configuration. If you call apply when your test is
executing, Spirent TestCenter applies the configuration immediately, which will affect the
running test in real-time.

Return Value None. Errors are raised as exceptions encoded as string values describing the error
condition.

Example stc::apply

Parameters None.

20 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Functions

config

Description Sets or modifies one or more object attributes, or a relation.

Syntax config handle -attr value [[-attr value] ...]

config handle -DANPath value [[-DANPath value] ...]
config DDNPath -attr value [[-attr value] ...]
config DDNPath -DANPath value [[-DANPath value] ...]
config handle1 | DDNPath -relationRef handleList

Comments The config function sets or modifies the value of one or more object attributes. You can
also use the config function to modify relations. Note that if you attempt to modify an
attribute for a read-only object, the config function raises an exception.
• When you modify object attributes, use name-value pairs and specify the attribute
name with a dash (-) prefix. For example:
stc::config port1 -location 10.100.0.0/1/1
• You can use Direct Descendant Notation (DDN) to identify the object, and
Descendant Attribute Notation (DAN) to identify the attribute. For example:
stc::config $project.port -location "mychassis1/1/2"
stc::config $project -port.active false
A DDN path is a dotted path name sequence. The sequence begins with an object
handle, followed by one or more object type names. The path must identify a valid
sequence of objects in your test hierarchy.
A DAN path is a dotted path name beginning with a dash (–), followed by a sequence
of one or more object types, and ending with an attribute name. Spirent TestCenter
combines the handle (or the DDNPath) with the DANPath to resolve the attribute
reference. The path must identify a valid sequence of objects in your test hierarchy.
In both DDN and DAN paths, an object type name may have an index suffix (an
integer in parenthesis) to reference one of multiple children of the same type.
For more information about these notations, see Referencing Objects: Object Paths.
• When you modify a relation, you can set either the source or target of the relation. Use
a side name for the relation reference. A side name represents both the relation type
and the side of the relation (source or target). For example:
stc::config $port1 -AffiliatedPortSource router2
stc::config $port -children $stream1 $stream2 $stream3
The relation reference requires a handle list as a value. The handle list identifies one
or more objects for the referenced side of the relation. In the first example above, the
config statement sets router2 as the source of the AffiliationPort relation defined for
$port1. The second example establishes three StreamBlock children for $port.

Return Value None. Errors are raised as exceptions encoded as string values describing the error
condition.

Spirent TestCenter Automation Programmer’s Guide | 21

Spirent TestCenter API Functions

Example stc::config $bgpSessHandle -connectionRetryInterval 1000

stc::config $port1 -AffiliatedPortSource router2
stc::config $project.Port(2) -location 10.0.0.1/1/1

Parameters
Parameter Type Description

handle handle The string value of the object handle that

(string) identifies the object to be modified.

-attr value name-value pair An attribute name-value pair. The -attr portion
of the pair is the name of the attribute to be
modified. The attribute name must start with a
dash (-). The value portion specifies the new
value. You can specify one or more name-value
pairs in a single function call. The attribute
name and value must be separated by a space;
each name-value pair in a sequence must be
separated by a space.

DDNPath string A dotted path name sequence that begins with

an object handle, followed by one or more
object type names. The path must identify a
valid sequence of objects in your test hierarchy.
Spirent TestCenter returns data for the object
identified by the last name in the sequence.
Use index values to identify one of a set of
children of the same type. Index values are
assigned in order of creation. An unqualified
type name (a name with no index value)
indicates the first child object of that type for
the parent.

DANPath string A dotted path name beginning with a sequence

of one or more object types, and ending with an
attribute name. Spirent TestCenter combines the
objectHandle (or the directDescendantPath)
with the descendantAttributePath to resolve
the attribute reference.

22 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Functions

Parameter Type Description

-relationRef handleList handle(s) Specifies a relation reference and one or more

object handles. relationRef specifies the relation
type and side of the relation. The relation
reference must start with a dash (–). The
relation type and side elements are separated by
a dash (–relationType–side). The relation
reference can include a DAN path
(-DANPath.relationType-side). relationRef can
be a side name, which implies the same
information. For information about relation
syntax, see Relation References. The specified
object(s) replace(s) the existing object(s) on the
specified side of the relation (relationRef).

Spirent TestCenter Automation Programmer’s Guide | 23

24 | Spirent TestCenter Automation Programmer’s Guide
 Spirent TestCenter API Functions

connect

Description Establishes a connection with a Spirent TestCenter chassis.

Syntax connect chassis-address | chassis-host-name

Comments The connect function establishes a connection between the management system that is
running the Spirent TestCenter software and a Spirent TestCenter chassis. Spirent
TestCenter Automation uses port number 40004.
You can specify either an IP address or a Domain Name Service (DNS) host name.

Return Value None. Errors are raised as exceptions encoded as string values describing the error
condition.

Example stc::connect 172.168.1.1

stc::connect myChassis1

Parameters
Parameter Type Description

chassis-address IP address An IP address or a DNS host name that identifies a

or Spirent TestCenter chassis.
chassis-host-name string

Spirent TestCenter Automation Programmer’s Guide | 25

Spirent TestCenter API Functions

create

Description Creates one or more Spirent TestCenter Automation objects.

Syntax create Project [[-attr value] ...]

create objectType -under handle [[-attr value] ...]
create objectTypePath -under handle [[-attr value] ...]
create objectType -under handle [[-DANpath value] ...]
create type | path -under handle1 –relationRef handleList

Comments The create function creates one or more Spirent TestCenter Automation objects. When
you call the create function, you specify the type(s) of one or more objects to be created.
You can specify:
• An object type name (such as the Project object or the Port object). For example:
stc::create Project
stc::create Port -under $hProject
• An object type path. To specify a path name, use dotted notation. A path name is a
sequence of object types that form valid parent-child relationships in your test
hierarchy, extending from the object identified by handle. Spirent TestCenter creates
the set of objects specified in the path. In the following example, Spirent TestCenter
creates a Router object and a BGPRouterConfig object as its child.
stc::create Router.BGPRouterConfig -under $hPort
For information about path name specification, see Object, Attribute, and Relation
References.
Usually, when you create an object, you must specify the -under attribute to supply a
parent for the newly created object. (The Project object, shown in the syntax specification
above, is the exception to this rule.) The value of the -under attribute is the object handle
returned by the create call that created the parent object, or a handle retrieved by calling
get. The parent object must be the correct type for the object that you create. (If you
specify an object type path, the parent object must be the correct type for the first object
type in the path sequence.)
When you create an object, you can also set the object attributes at the same time. To set
attributes, specify one or more attribute name-value pairs.
• If you specify name-value pairs when you also specify an object type path, Spirent
TestCenter applies the attribute values to the object associated with the last name
specified in the object type path. In the following example, Spirent TestCenter creates
a Router object and a BGPRouterConfig object as a child of the newly created
Router object. When Spirent TestCenter creates the BGPRouterConfig object, it sets
the -initiate attribute to FALSE.
stc::create Router.BGPRouterConfig -under $hPort \
-initiate FALSE

26 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Functions

• You can specify a Descendant Attribute Notation (DAN) path as part of the attribute
reference. Spirent TestCenter uses the specified object type to create the primary
object, and the DAN path to create any additional objects. The path must specify a
valid descendant path extending from the primary object. Spirent TestCenter will
create the primary object, the objects identified in the path, and then set the referenced
attribute of the last object in the path. In the following example, Spirent TestCenter
creates a Port object (the primary object), then the StreamBlock and EthernetII
objects. When Spirent TestCenter creates the EthernetII object, it also sets the
-etherType attribute.
stc::create Port -under $hProject \
-StreamBlock.ethernet:EthernetII.etherType 880B \
-frameconfig ""
For information about path name specification, see Object, Attribute, and Relation
References.
• When you create an object, you can also create a relation between the newly created
object and an existing object. In this case, you specify the object to be created, the
handle for its parent (handle1), a relation reference, and the handle for one or more
objects on the other side of the connection (handleList). In the following example,
Spirent TestCenter creates a Router object and establishes an AffiliatedPort relation
between the new Router object and an existing Port object.
set hRouter2 [stc::create Router -under $hProject \
-AffiliatedPort $hPort]
For information about specifying relations, see Relation References.

Return Value The create function returns a unique string value that is the object handle for the object
specified in the function call. (The create function returns only the handle for the primary
object that is created. To obtain the handles for any decendant objects that are created, use
the get function to retrieve the child objects.)

Examples set hProject [stc::create Project -name “project1”]

set hPort [stc::create Port -under $hProject]
set hRouter1 [stc::create Router.BGPRouterConfig -under $hPort]
set streamblock [stc::create Port -under $hProject \
-StreamBlock.ethernet:EthernetII.etherType 880B \
-frameconfig "" ]
set hRouter2 [stc::create Router -under $hProject \
-AffiliatedPort $hPort]

Spirent TestCenter Automation Programmer’s Guide | 27

Spirent TestCenter API Functions

Parameters
Table 1-1.

Parameter Type Description

Project string Specify the Project object type to create the root
of your test hierarchy. A Project object has no
parent, so you do not specify the -under attribute
in the function call.

objectType string The name of the type of object(s) to be created.

(For the names of the objects, see the diagram of
or
the Spirent TestCenter object hierarchy.)
objectTypePath
You can specify a path name in place of a single
object type name. The path name is a sequence of
object types, separated by dots (“.”). The
sequence must describe valid parent-child
relationships in your test hierarchy. When you
specify a path name, Spirent TestCenter creates all
of the objects specified in the path sequence. For
more information, see Object, Attribute, and
Relation References.

-under handle handle Specifies the handle of the parent for the newly
(string) created object. The type of object that you create
must be appropriate for the parent object. You
must specify the -under attribute when you create
any object except the Project object.
When you specify an object type path, use the -
under attribute to specify the parent of the first
object type in the path.

28 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Functions

Table 1-1.

Parameter Type Description

-attr value name-value An attribute name-value pair. The -attr portion of

pair the pair is the name of the attribute to be modified.
or
The attribute name must start with a dash (–). The
or
-DANPath.attr value value portion specifies the new value. You can
DANPath- specify one or more name-value pairs in a single
value pair function call. The attribute name and value must
be separated by a space; each name-value pair in a
sequence must be separated by a space.
You can specify a Descendant Attribute Notation
(DAN) path ending in an attribute name-value
pair. The path name is a sequence of object types
(ending with an attribute name), separated by dots
(“.”). The sequence must describe valid parent-
child relationships in your test hierarchy, ending
with the name of an attribute for the last object in
the path. When you specify a path name, Spirent
TestCenter creates all of the objects specified in
the path sequence and sets the attribute.
For more information about path specification, see
Object, Attribute, and Relation References. For
detailed information on object definitions
including the valid parent-child relations, see the
Spirent TestCenter Automation Object Reference.

-relationRef handleList handle(s) Specifies a relation reference and one or more

object handles. relationRef specifies the relation
type and side of the relation. The relation
reference must start with a dash (–). The relation
type and side elements are separated by a dash (–
relationType–side). (relationRef can be a side
name, which implies the same information.) For
information about relation syntax, see Relation
References.

Spirent TestCenter Automation Programmer’s Guide | 29

Spirent TestCenter API Functions

delete

Description Deletes the specified object.

Syntax delete handle

Comments Deletes the object identified by objectHandle. Spirent TestCenter also deletes all
descendants of the specified object (if any).

Return Value None. Errors are raised as exceptions encoded as string values describing the error
condition.

Example stc::delete $hPort

Parameters
Parameter Type Description

handle handle The object handle that identifies the object to be deleted.

30 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Functions

disconnect

Description Removes a connection with a Spirent TestCenter chassis.

Syntax disconnect chassisAddress | chassisHostName

Comments The disconnect function removes an established connection between the management
system that is running the Spirent TestCenter software and a Spirent TestCenter chassis.
You can specify either an IP address or a Domain Name Service (DNS) host name. Note
that when you call disconnect, you must use the same type of value (address or name) that
you used in the call to connect.

Return Value None. Errors are raised as exceptions encoded as string values describing the error
condition.

Example Using an IP address:

connect 172.168.1.1
.....
disconnect 172.168.1.1

Using a host name:

connect myChassis1
.....
disconnect myChassis1

Parameters
Parameter Type Description

chassis-address IP address An IP address or a DNS host name that identifies a

or Spirent TestCenter chassis.
chassis-host-name string

Spirent TestCenter Automation Programmer’s Guide | 31

Spirent TestCenter API Functions

get

Description Returns the value(s) of one or more object attributes or a set of object handles.

Syntax get handle [-attributeName [...]]

get handle [-DANPath [...]]
get DDNPath -attributeName [...]
get DDNPath -DANPath [...]
get handle | DDNPath -relationRef [...]
get handle | DDNPath -children-type

Comments The get function returns the value of one or more object attributes, or, in the case of
relation references, one or more object handles.
• The handle identifies the object from which data will be retrieved. If you do not
specify any attributes, Spirent TestCenter returns the values for all attributes defined
for the object. (Note that if you specify a DDN path, you must specify one or more
attributes.)
• The attributeName identifies an attribute for the specified object.
• The DANPath (Descendant Attribute Notation path) is is a dotted path name
beginning with a dash (–), followed by a sequence of one or more object types, and
ending with an attribute name. An object type name may have an index suffix (an
integer in parenthesis) to reference one of multiple children of the same type. Spirent
TestCenter combines the handle (or the DDNPath) with the DANPath to resolve the
attribute reference. The path must identify a valid sequence of objects in your test
hierarchy. For example:
stc::config $project -port.active false
Spirent TestCenter combines the object and attribute specifications to retrieve the
value of the active attribute for the first Port object child of $project.
• The DDNPath (Direct Descendant Notation path) is a dotted path name sequence. The
sequence begins with an object handle, followed by one or more object type names.
The path must identify a valid sequence of objects in your test hierarchy. When you
use DDN, you must specify one or more attributes. Spirent TestCenter returns data for
the object identified by the last name in the sequence. For example:
stc::get $port1.EthernetCopper -AutoNegotiation
In this case, Spirent TestCenter returns the value of the -AutoNegotiation attribute for
the first EthernetCopper child of the specified Port object.

32 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Functions

If there is more than one instance of a particular object type as children of the
specified object, use index notation. (In the example above, the index value 1 is
implied.) Spirent TestCenter assigns index values in order of object creation. For
example:
stc::get $project.port(2)
Spirent TestCenter returns the attributes for the second Port object child of the
specified Project object.
• When you use a relation reference with the get function, it provides access to one or
more objects connected to the object identified by handle (or DDNPath). Specify a
side name for the relation reference, using one of the following relation-reference
formats:
-sideName
-DANPath.sideName
A side name represents both the relation type and the side of the relation (source or
target).
• When you use a relation to retrieve the handles of child objects, you can specify an
object type to filter the set of objects. Spirent TestCenter supports filtering of child
relations only. For example:
stc::get $port1 -children-StreamBlock
This function call returns the handle(s) for the StreamBlock child object(s) of the
$port1 object.

Return Value When you retrieve one or more attributes, get returns a string containing a single attribute
value or a set of name-value pairs. If you do not specify any attributes, the get function
can return either a single attribute value or a list of name-value pairs (depending on the
definition of the object).
When the get function returns a list of name-value pairs, Spirent TestCenter returns a
single string containing the list. Each attribute name and its value is separated by a space,
and the name-value pairs are separated by a space:
-attr1 value1 -attr2 value2 .. -attrN valueN
When you specify a relation reference, the get function returns one or more handles.
Errors are raised as exceptions encoded as string values describing the error condition.

Spirent TestCenter Automation Programmer’s Guide | 33

Spirent TestCenter API Functions

Examples stc::get $port -location

stc::get $port -StreamBlock(1).state -StreamBlock(2).state
stc::get $port -children
stc::get $project.Port(2) -children

34 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Functions

Parameters

Parameter Type Description

handle handle Identifies the object from which data will be retrieved.

-attributeName string Identifies an attribute for the specified object. The

attribute name must begin with a dash (-).

DDNPath string A dotted path name sequence that begins with an

object handle, followed by one or more object type
names. The path must identify a valid sequence of
objects in your test hierarchy. Spirent TestCenter
returns data for the object identified by the last name
in the sequence.
Use index values to identify one of a set of children of
the same type. Index values are assigned in order of
creation. An unqualified type name (a name with no
index value) indicates the first child object of that type
for the parent.

DANPath string A dotted path name beginning with a sequence of one

or more object types, and ending with an attribute
name. Spirent TestCenter combines the handle (or the
DDNPath) with the DANPath to resolve the attribute
reference.

relationRef string Specifies specifies the relation type and side of the
relation. The relation type must be defined for the
object referenced by handle or DDNPath.
The relation reference must start with a dash (–). The
relation type and side elements are separated by a dash
(–relationType–side). The relation reference can
include a DAN path (-DANPath.relationType-side).
relationRef can be a side name, which implies the
same information. For information about relation
syntax, see Relation References.

Spirent TestCenter Automation Programmer’s Guide | 35

Spirent TestCenter API Functions

help

Description Displays help about the Spirent TestCenter Automation API and data model.

Syntax help
help commands
help command
help handle (documentation, not data)
help objectType

Comments The help function provides information about Spirent TestCenter Automation. You can
display the following type of information:
• An overview of the help that is available
(stc::help)
• An overview of the functions (create, config, etc.)
(stc::help commands)
• Information about a specific function or command
(stc::help command, for example – stc::help create or stc::help SaveAsTcl)
• Information about an object type
(stc::help handle or stc::help objectType, for example – stc::help $port or
stc::help Port)

Return Value None. (The function displays the results of the help request.)

Example stc::help
stc::help commands
stc::help create
stc::help SaveAsTcl
stc::help Port

Parameters
Parameter Type Description

none – Displays an overview of the help facility.

commands string Displays a list of the API functions.

command string Displays information about the specified function or

command.

handle handle Displays information about the object type for the
specified handle.

objectType string Displays information about the specified object type.

36 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Functions

log

Description Writes a diagnostic message to a log file or to standard output.

Syntax log logLevel message

Comments The log function writes a diagnostic message to a log file or to standard output. Spirent
TestCenter Automation provides this function so that your application can insert a
message into the log file.
The log capability uses the values defined for the AutomationOptions object to
determine its behavior. By modifying the AutomationOptions attributes, you can:
• Set the default log level for system messages.
• Send the output to a file. (By default, messages are directed to standard output.)
• Suppress Tcl errors (change the error mechanism from raised exceptions to returned
errors).

Return Value None. Errors are raised as exceptions encoded as string values describing the error
condition.

Example log INFO “Starting traffic”

Parameters

Name Type Description

logLevel enum Identifies the severity of the message. The log level can be one
of the following:
INFO
WARN
ERROR
FATAL
These values correspond to the logLevel enumerated type
values defined for the AutomationOptions object.

message string A text string containing the message.

Spirent TestCenter Automation Programmer’s Guide | 37

Spirent TestCenter API Functions

perform

Description Executes a command.

Syntax perform command [[-parameter value] ...]

Comments The perform function executes a command. See the Spirent TestCenter Automation Object
Reference for a complete list of commands.

Return Value The perform function returns an array containing name-value pairs corresponding to the
complete set of attributes defined for the command object. The values are encoded as
strings. Errors are raised as exceptions encoded as string values describing the error
condition.

Example stc::perform SaveAsXml -config $project -filename project.xml

stc::perform LoadFromXml -filename project.xml

Parameters
Parameter Type Description

command string The command name.

-parameter value string One or more name/value pairs that may be defined for the
command. The parameter names correspond to the names of
attributes defined for the command object.

38 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Functions

release

Description Terminates the reservation of one or more port groups.

Syntax release portList

Comments release terminates the reservation for one or more ports. The portList parameter specifies
one or more chassis-slot-port tuples. You can release only those ports that you have
reserved. For information about port reservations and the syntax for identifying ports, see
the description of the reserve function.
If a port is part of a port group, releasing the port will release all of the ports in the group.
Note that you must release every port that you have reserved. Failure to do this can put the
module(s) into a state that requires rebooting.

Return Value None. Errors are raised as exceptions encoded as string values describing the error
condition.

Example set slot1 0

set port1 2
set chassisAddr 10.0.0.1
stc::connect $chassisAddr]

# create the ports

...
# Reserve ports
stc::reserve $chassisAddr/$slot1/$port1

...[test creation and execution]

# Release ports
stc::release $chassisAddr/$slot1/$port1

Spirent TestCenter Automation Programmer’s Guide | 39

Spirent TestCenter API Functions

Parameters
Parameter Data Type Description

portList : (c) chassis IP One or more chassis-slot-port specifications.

or host name
c/s/p | //c/s/p [...] • The chassis specification is the chassis IP
(s) integer
address or the chassis host name.
(p) integer
• The slot specification is the slot number of the
Spirent TestCenter module. Slot numbers start at
one (1).
• The port specification is the port index on the
module. Port indices start at one (1).
Use one of the following formats for a chassis-slot-
port specification:
• c/s/p
• //c/s/p
Multiple c/s/p specifications must be separated by
spaces.

40 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Functions

reserve

Description Reserves one or more port groups.

Syntax reserve portList

Comments The reserve function reserves one or more ports on one or more Spirent TestCenter
chassis. When you reserve a port, your test session has exclusive access to that port for the
purpose of running a test.
To identify a port, specify a chassis-slot-port tuple.
• The chassis specification is the chassis IP address or chassis host name.
• The slot number identifies the slot.
• The port number identifies a port on a module in a chassis. Spirent TestCenter
modules are single-port or multi-port. On a single-port module, a port group consists
of one port. On a multi-port module, each port group contains two ports. A port
reservation is automatically extended to include any other ports in the group. (That is,
when you reserve a port on a multi-port module, both ports in the group are reserved.)
Note that with a multi-port module, you must explicitly reserve both ports in a group
so that Spirent TestCenter will perform the appropriate setup for each port. If you
reserve only one of the two ports in the group, the second port is locked, preventing
others from reserving it, but you must also reserve the second port explicitly in order
to use it.
To specify a chassis-slot-port tuple, use the forward-slash character (/) as a separator:
chassisIP/slot/port
You can also use a double slash prefix:
//chassis-hostname/slot/port
In a list of port groups, use a space to separate tuples:
stc::reserve c/s/p //c/s/p c/s/p
To use a port, you must also create an associated port object and specify its location when
you create or configure the object (see the description of the -location attribute for the
port object). At the end of a test, you must release every port that you reserve. Failure to
do this can put the module(s) into a state that requires rebooting. (See the description of
the release function).

Return Value None. Errors are raised as exceptions encoded as string values describing the error
condition.

Example # Set the chassis, slot, and port variables

set slotNum 0
set portNum 2
set chassisAddr 10.0.0.1
stc::connect $chassisAddr

Spirent TestCenter Automation Programmer’s Guide | 41

Spirent TestCenter API Functions

#create the ports

...
# Reserve ports
stc::reserve $chassisAddr/$slotNum/$portNum

Parameters
Parameter Data Type Description

portList : (c) chassis IP One or more chassis-slot-port specifications.

or host name
c/s/p | //c/s/p [...] • The chassis specification is the chassis IP
(s) integer
address or the chassis host name.
(p) integer
• The slot specification is the slot number of the
Spirent TestCenter module. Slot numbers start at
one (1).
• The port specification is the port index on the
module. Port indices start at one (1).
Use one of the following formats for a chassis-slot-
port specification:
• c/s/p
• //c/s/p
Multiple c/s/p specifications must be separated by
spaces.

42 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Functions

sleep

Description Suspends Tcl application execution.

Syntax sleep duration

Comments The sleep function suspends your application for the specified duration (expressed as the
number of seconds). This does not suspend the Tcl event loop; Spirent TestCenter internal
processing will continue, regardless of the state of the Tcl event loop.

Return Value None. Errors are raised as exceptions encoded as string values describing the error
condition.

Example # Wait-loop. Wait till all sessions are up

set up 0
while {$up != 1} {
puts "Waiting for BGP sessions to be established..."

set s1 [get bgp_session_state -from $bgp_s1_handle]

set s2 [get bgp_session_state -from $bgp_s2_handle]

if {$s1 == "Established" && $s2 == "Established"} {

set up 1
}
stc::sleep 1; #wait 1 second before checking again
}

Parameters
Parameter Type Description

duration integer The number of seconds to suspend application execution.

Spirent TestCenter Automation Programmer’s Guide | 43

Spirent TestCenter API Functions

subscribe

Description Enables real-time result collection.

Syntax subscribe -Parent handle

-ResultType resultType
-ConfigType resultParentType
[-FilenamePrefix filenamePrefix]
[-ResultParent resultRootType-list]
[-Interval seconds]
[-ViewAttributeList attrList]
[-ViewName name]

Comments Spirent TestCenter maintains a set of real-time counters through periodic updates. Use the
subscribe function to enable result collection and to write the results data to a file. The
results file uses comma-separated value format (csv).
When you call subscribe, you provide the following information:
• A handle to the Project object in your test configuration (specified as the value to the
-parent parameter).
• The object type for the results data (the -resultType parameter). The result type
determines the data to be collected. You do not create results data objects; Spirent
TestCenter creates results data objects as needed. You must establish individual
subscriptions for each result type. The results type objects are:

AnalyzerPortResults IptvChannelResults PppoePortResults

ArpNdResults IptvStbBlockResults PppoeSessionResults
BgpRouterResults IptvViewingProfileResults PppProtocolResults
BridgePortResults IptvTestResults RipRouterResults
Dhcpv4PortResults IsisRouterResults RsvpLspResults
Dhcpv4BlockResults LacpPortResults RsvpRouterResults
Dhcpv4SessionResults LdpLspResults SonetResults
Dhcpv6PortResults LdpRouterResults SonetAlarmsResults
Dhcpv6BlockResults MldGroupMembershipResults RxCpuPortResults
Dhcpv6SessionResults MldHostResults RxPortPairResults
DiffServResults MldPortResults RxStreamBlockResults
FilteredStreamResults MldRouterResults RxStreamSummaryResults
GeneratorPortResults MulticastPortResults RxTrafficGroupResults
IgmpGroupMembershipResults Ospfv2RouterResults TxCpuPortResults
IgmpHostResults Ospfv3RouterResults TxPortPairResults
IgmpPortResults OverflowResults TxStreamBlockResults
IgmpRouterResults PimRouterResults TxStreamResults
IptvPortResults PortAvgLatencyResults TxTrafficGroupResults

• The object type for the parent(s) of the result objects (the -resultParent parameter).

44 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Functions

• The configuration object type (the -configType parameter). This object type is
defined as the source element of a ResultChild relationship that is defined for the
resultType object.
• A file name prefix for the .cvs output file. (The -filenamePrefix parameter).
Although Spirent TestCenter will collect results for a subscription, you must provide a
file name prefix to direct results output to a file. Spirent TestCenter generates one file
per result type.
• The object(s) in your test configuration that Spirent TestCenter will use to collect
results (-resultParent). A result parent identifies the set of objects for which Spirent
TestCenter will collect results. The specified result root object type is treated as a
parent, under which Spirent TestCenter collects results (-resultType) for configuration
objects (-configType).
• The rate at which Spirent TestCenter updates the subscription data and writes out
results (the -interval parameter). By default, the interval between write operations is
one second; you can specify a different value (in seconds).
• Result filtering through the use of views and view attribute lists.
The subscribe function operates in a synchronous fashion. When it returns, the test
configuration in memory has been updated with a current copy of the subscribed data.
Spirent TestCenter updates the subscription based on the value of the -interval parameter.
Approximately 2000 data elements can be subscribed before the system starts to discard
data due to throughput limitations.

Return Value The subscribe function returns a handle to a ResultDataSet object. Save this handle for
use with the unsubscribe function. You also use the ResultDataSet object to manage
paged results (see Paged Results).

Example subscribe -parent $project \

-configType Analyzer \
-resultType AnalyzerPortResults \
-filenamePrefix analyzer_port_counter

Parameters
Parameter Type Description

-configType resultParentType string The possible configType objects are the

source elements identified in the ResultChild
relation defined for the results object.

-filenamePrefix filenamePrefix string Specifies a prefix for the .csv output file.
The -filenamePrefix parameter is optional,
but you must specify a prefix to generate
results output files.

Spirent TestCenter Automation Programmer’s Guide | 45

Spirent TestCenter API Functions

Parameter Type Description

-interval seconds integer The number of seconds between subscription

updates and updates to the CSV file. At each
update to the CSV file, Spirent TestCenter
writes the latest values from the resultType
objects in your test configuration. The default
interval is one second.

-parent handle handle The handle for the Project object.

-resultParent resultRootType-List string A result root identifies the set of objects for
which Spirent TestCenter will collect results.
A result root object type is treated as a parent,
under which Spirent TestCenter collects
results (-resultType) for configuration objects
(-configType).
If you do not specify -resultParent, Spirent
TestCenter will use the -parent Project object.

-resultType resultType object Specifies a results object type. The results

type object type determines the set of results to be
collected. Spirent TestCenter creates results
objects automatically to hold results data.

viewAttributeList string Defines the list of attributes (results) to be

(list) written to the .csv file. The list is based on the
set of attributes defined for the results object
type (-resultType).

viewName string The name of a view. (A view defines a set of

results.)
Note: This is not supported in this release.

46 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter API Functions

unsubscribe

Description Removes a previously established subscription.

Syntax unsubscribe handle

Comments The unsubscribe function removes a subscription and stops the corresponding file output.
To stop a subscription, you specify the ResultDataSet handle that was returned by the
subscribe function.

Return Value None. Errors are raised as exceptions encoded as string values describing the error
condition.

Example stc::unsubscribe $rdsHandle

Parameters
Parameter Type Description

handle handle The handle for the ResultDataSet object

associated with the subscription. (The handle is
returned by the subscribe function.)

Spirent TestCenter Automation Programmer’s Guide | 47

Spirent TestCenter API Functions

waitUntilComplete

Description Blocks your application until the test has finished.

Syntax waitUntilComplete

Comments The waitUntilComplete function blocks your application until the sequencer has
completed its operation. Once the sequencer has finished, the function returns control to
your application.

Return Value The current state of the Command Sequencer (the value of the State attribute for the
Sequencer object).

Example stc::waitUntilComplete

Parameters None.

48 | Spirent TestCenter Automation Programmer’s Guide

 Chassis Management

Chassis Management
Spirent TestCenter defines the following set of objects to represent a Spirent TestCenter
chassis and its components:
• PhysicalChassis – represents a connected chassis.
• PhysicalChassisManager – parent to the physical chassis objects.
• PhysicalChassisFan – represents a fan on the connected chassis.
• PhysicalChassisThermal – represents a thermal sensor on the connected chassis.
• PhysicalChassisSyncTopology – represents a chassis in the sync topology chain to
which the connected chassis belongs.
• PhysicalPort – represents a single port on a module.
• PhysicalPortGroup – represents a port group on a module.
• PhysicalTestModule – represents a module on a chassis.
Spirent TestCenter creates these objects automatically. The objects are organized into a
sub-hierarchy descending from the pre-defined object system1. The following figure
shows the parent-child hierarchy for the chassis-related objects.

system1

PhysicalChassisManager

PhysicalChassis

PhysicalChassisFan

PhysicalChassisThermal

PhysicalChassisSyncTopology

PhysicalTestModule

PhysicalPortGroup

PhysicalPort

In order to use any of these objects, use the get function to retrieve the object handles and
then use the object handles to retrieve attribute values for the chassis data. The following
sections describe a script that connects to a chassis and displays module information.
• Chassis Connection
• The PhysicalChassisManager Object
• Module Information
• Chassis Disconnection

Spirent TestCenter Automation Programmer’s Guide | 49

Chassis Management

Chassis Connection
To run any Spirent TestCenter Automation test, you must connect to a Spirent TestCenter
chassis. The following code fragment shows a call to the connect function.

NOTE: You must create a Project object in order to connect to a chassis.

package require SpirentTestCenter

set chassisAddr 10.6.2.68

# Create the "root" project object

set project1 [stc::create Project]

# Connect to the chassis

puts "Connecting to chassis $chassisAddr"
set chassis [ stc::connect $chassisAddr ]
if { $chassis == -1 } {
puts "Connection to chassis failed"
exit
}

The PhysicalChassisManager Object

You can establish connections with multiple Spirent TestCenter chassis. Spirent
TestCenter defines the PhysicalChassisManager object; this object is the parent of the
PhysicalChassis object(s) that represent(s) the connected chassis. To gain access to the
chassis objects:
• Retrieve the PhysicalChassisManager object. The PhysicalChassisManager object
is a child of the pre-defined system root object system1. Spirent TestCenter creates
the system1 object automatically. (“system1” is a pre-defined name that is reserved
for this object.) To retrieve the chassis manager object, call the get function,
specifying the system1 object and the -children sidename with the
PhysicalChassisManager object type filter. The get function will return the handle to
the PhysicalChassisManager object.
• Retrieve the PhysicalChassis children of the chassis manager object. Call the get
function, specifying the handle to the chassis manager object ($chassisHandle) and
the -children sidename with the PhysicalChassis object type filter. The get function
will return a list of chassis objects, representing the connected chassis.
The following code fragment shows the calls to retrieve the handles to the chassis
manager and chassis objects:

# Get the handle to the physical chassis

set chassisHandle [stc::get system1 -children-PhysicalChassisManager]
set mgrHandleList [stc::get $chassisHandle -children-PhysicalChassis]

50 | Spirent TestCenter Automation Programmer’s Guide

 Chassis Management

Module Information
The code fragment on page 52 displays module, port group, and port information for a
Spirent TestCenter chassis. The code loops through the set of PhysicalChassis objects.
For each chassis object, the script:
• Retrieves the handles for the PhysicalTestModule children of the PhysicalChassis
object, then retrieves and displays the module attributes. The code uses the -children
sidename with the -PhysicalTestModule object type filter to retrieve the handles.
• For each test module object, it retrieves the handles for the PhysicalPortGroup
children of the PhysicalTestModule object, then retrieves and displays the port group
attributes. The code uses the -children sidename with the -PhysicalPortGroup
object type filter to retrieve the handles.
• For each port group object, it retrieves the handles for the PhysicalPort children of
the PhysicalPortGroup object, then retrieves and displays physical port attributes.
The code uses the -children sidename with the -PhysicalPort object type filter to
retrieve the handles.

Spirent TestCenter Automation Programmer’s Guide | 51

Chassis Management

# Display test module info

foreach mgrHandle $mgrHandleList {

set modHandleList [stc::get $mgrHandle \

-children-PhysicalTestModule]

foreach modHandle $modHandleList {

array set mEntry [stc::get $modHandle ]

puts "Card($mEntry(-Index)) $mEntry(-ProductId):$mEntry(-Serial-
Num):$mEntry(-FirmwareVersion):$mEntry(-Status):$mEntry(-Descrip-
tion)"

set pgroupList [stc::get $modHandle -children-physicalportgroup ]

foreach pg $pgroupList {

array set pgEntry [stc::get $pg]

puts "\t$pgEntry(-Name) $pgEntry(-OwnershipState) $pgEntry(-
Status) Reserved:(-ReservedByUser) $pgEntry(-OwnerUserId) $pgEntry(-
OwnerHostname)"

set portList [stc::get $pg -children-physicalport]

foreach ptEntry $portList {
array set pEntry [stc::get $ptEntry]
puts "\t\t$pEntry(-Name) $pEntry(-Location)"
}
}
}
}

Chassis Disconnection
At the end of your test, you should disconnect any connected chassis. The following code
fragment shows a call to the ChassisDisconnectAll command.

puts "Disconnecting from chassis $chassisAddr"

array set cmdResp [ stc::perform ChassisDisconnectAll ]

52 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Script Template

Spirent TestCenter Script Template

Every Spirent TestCenter Automation script uses a set of basic elements that provide
standard operations that are necessary for Spirent TestCenter tests. These operations are:
• Initialization
• Connecting to a chassis
• Port reservation and mapping
• Exception handling
• Termination
The following sections describe a script that includes these elements. The script uses a
simple back-to-back test configuration that uses two ports, one port generating traffic to
the other port.
• Return Status and Error Handling
• Initialization
• Test Configuration
• Chassis Connection, Port Reservation and Mapping
• Script Termination

Spirent TestCenter Automation Programmer’s Guide | 53

Spirent TestCenter Script Template

Return Status and Error Handling

This example uses a set of statements to check the return status and handle errors from
calls to the Spirent TestCenter Automation API. These statements are written as a
procedure that gets used repeatedly.
Procedure CRS uses the Tcl commands eval and catch to execute the Spirent
TestCenter function call and handle any exceptions that may occur. If the function
executes successfully, the procedure returns the function return value to the main stream
of execution. If an exception occurs, the procedure displays an error message and stops the
test.
#################################################################
#Name: CRS
#Purpose: Check the returned status of the called STC function
#Input: the function and accompanied attributes
#Output: the returned status
#################################################################

proc CRS {args} {

upvar evalResult evalResult
upvar cmdReturn cmdReturn
variable ::errorInfo
set status 1
set cmd "$args"

if {[catch {eval $cmd} cmdReturn] } {

if {([regexp "STCERROR" $errorInfo] == 1) || ([regexp "stcerror" $errorInfo] == 1)}
{
puts "Command $cmd failed!"
puts "Error text is $errorInfo"
exit
} else {
#Tcl Crash
puts "Command crashed. TCL error message was:"
puts $cmdReturn
puts $errorInfo
exit
}
} else {
set evalResult $cmdReturn
} ;# end if-else statement
return $evalResult
} ;# end procedure

54 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Script Template

Initialization
Every Spirent TestCenter Automation Tcl script must load the Spirent TestCenter package
before it can use the API. The following code fragment loads the package, and it also
defines variables that will be used later in the script.

set scriptName "priorityBasedScheduling.tcl"

set testName "priorityBasedScheduling"
puts "Start running $scriptName"
#################################################################
puts " Loading SpirentTestCenter..."
package require SpirentTestCenter
###################################################################
set chassisAddress "10.100.20.56"
set slotPort1 "1/1"
set slotPort2 "1/3"
set portCount "2"

Test Configuration
The following sections contain code fragments that create objects, configure traffic, and
establish subscriptions for test results.
• Project and Port Objects
• Traffic
• Generator and Analyzer
• Subscription

Project and Port Objects

This test uses two ports on the Spirent TestCenter chassis. The following code fragment:
• Creates the Project object that will serve as the root of the test configuration object
hierarchy.
• Creates two Port objects as children of the Project object.
• Identifies the port locations.
• To define the Ethernet copper interface, it creates EthernetCopper objects as
children of the Port objects.

Spirent TestCenter Automation Programmer’s Guide | 55

Spirent TestCenter Script Template

###################################################################
puts " Creating project..."
set project [stc::create project]
puts " project ($project) created"

#############################
### Create the ports under the project
#############################
puts "Creating the ports..."
set port(1) [CRS stc::create port -under $project]
set port(2) [CRS stc::create port -under $project]

#############################
### Configure the ports under the project
#############################
set portReturn [CRS stc::config $port(1) -location "//$chassisAddress/$slotPort1"]
set portReturn [CRS stc::config $port(2) -location "//$chassisAddress/$slotPort2"]

#############################
### Create the port type (copper) under the port object.
#############################
set ethernetCopper(1) [CRS stc::create "EthernetCopper" \
-under $port(1) \
-Name "ethernetCopper 1" ]

set ethernetCopper(2) [CRS stc::create "EthernetCopper" \

-under $port(2) \
-Name "ethernetCopper 2" ]

puts "Port configuration complete"

56 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Script Template

Traffic
The following code fragment creates two StreamBlock objects for the transmitting port
($port(1)). This example does not configure frame headers, so Spirent TestCenter will use
the default values in the automatically created EthernetII and IPv4 header objects.

######################################
###### Create stream blocks (one per port)
######################################
puts "Creating/configuring the streamblocks on the ports..."
set StreamBlock1 [stc::create "StreamBlock" \
-under $port(1) \
-FrameLengthMode "FIXED" \
-FixedFrameLength "222" \
-LoadUnit "INTER_BURST_GAP" \
-Load "20000000.000000" \
-Priority "2" ]

set StreamBlock2 [stc::create "StreamBlock" \

-under $port(1) \
-FrameLengthMode "FIXED" \
-FixedFrameLength "1500" \
-LoadUnit "INTER_BURST_GAP" \
-Load "200000000.000000" \
-Priority "0" ]
puts "Streamblock creation completed"

Generator and Analyzer

The code fragment on page 58 configures the generator for the transmitting port and the
analyzer for the receiving port. Spirent TestCenter creates the generator and analyzer
objects automatically, so the script must retrieve the handles of the objects in order to
perform the configuration. The code fragment:
• Retrieves the handle to the Generator object from its parent Port object (port 1) and
then sets the name of the object.
• Retrieves the handle to the GeneratorConfig object from its parent Generator
object. It then uses the GeneratorConfig handle to set the scheduling mode and
duration mode attributes.
• Retrieves the handle to the Analyzer object from its parent Port object (port 2) and
then sets the name of the object.
• Retrieves the handle to the AnalyzerConfig object from its parent Analyzer object. It
then uses the AnalyzerConfig handle to set the analyzer attributes.

Spirent TestCenter Automation Programmer’s Guide | 57

Spirent TestCenter Script Template

#############################
### Configure the generator attributes
#############################
puts "Configuring the generator on port 1"
set generator1 [stc::get $port(1) -children-Generator]
stc::config $generator1 -Name "Generator 1"
set generatorConfig1 [stc::get $generator1 -children-GeneratorConfig]
stc::config $generatorConfig1 \
-SchedulingMode "PRIORITY_BASED" \
-DurationMode "CONTINUOUS"

puts "Generator(1) configuration completed"

#############################
### Configure the analyzer attributes
#############################
puts "Configuring the analyzer on port 2"
set analyzer2 [stc::get $port(2) -children-Analyzer]
stc::config $analyzer2 -Name "Analyzer 2"
set analyzerConfig2 [stc::get $analyzer2 -children-AnalyzerConfig]
stc::config $analyzerConfig2 \
-TimestampLatchMode "END_OF_FRAME" \
-JumboFrameThreshold "1500" \
-OversizeFrameThreshold "2000" \
-UndersizeFrameThreshold "64" \
-AdvSeqCheckerLateThreshold "1000" \
-Name "AnalyzerConfig 2"

puts "Analyzer configuration completed"

Note that the script uses the filtered sidename syntax to retrieve the appropriate child
object handles:
stc::get $port(1) -children-Generator
stc::get $generator1 -children-GeneratorConfig
stc::get $port(2) -children-Analyzer
stc::get $analyzer2 -children-AnalyzerConfig

The sidename -children identifies the ParentChild relationship. The appended object
type name (-GeneratorConfig, for example) acts as a filter to limit the returned list to the
desired type.

Subscription
The code fragment on page 59 establishes subscriptions for both the stream block on the
transmitting port and the analyzer on the receiving port.

58 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Script Template

The code fragment:

• Establishes a subscription for TxStreamBlockResults data. The call to the subscribe
function specifies:
• The Project object handle.
• The object handle of the aggregation point for the automatically created results
objects (-resultParent). Statistics are collected for all objects of the specified
type that exists under the -resultParent object.
• The set of results (-resultType).
• The object type of the source object in the ResultChild relationship with the con-
figuration type object (-configType). In this case, the StreamBlock object is
the source object and the TxStreamBlockResults object is the target.
• Establishes a subscription for AnalyzerPortResults data.The call to the subscribe
function specifies:
• The Project object handle.
• The object handle of the aggregation point for the automatically created results
objects (-resultParent). Statistics are collected for all objects of the specified
type that exists under the -resultParent object. The result parent for this subscrip-
tion is the Project object
• The set of results (-resultType).
• The object type of the source object in the ResultChild relationship with the con-
figuration type object (-configType). In this case, the Analyzer object is the
source object and the AnalyzerPortResults object is the target.

#############################
### Subscribing to results
#############################
puts "Subscribing to results..."
set sbResult [CRS stc::subscribe -Parent $project \
-ResultParent $port(1) \
-ConfigType StreamBlock \
-resulttype TxStreamBlockResults \
-filenameprefix streamBlock${testName}]

set analyzerResult [CRS stc::subscribe -Parent $project \

-ResultParent $project \
-ConfigType Analyzer \
-resulttype AnalyzerPortResults \
-filenameprefix analyzer${testName}]

puts "Results subscription complete"

Spirent TestCenter Automation Programmer’s Guide | 59

Spirent TestCenter Script Template

Chassis Connection, Port Reservation and Mapping

After creating the test configuration, it is necessary to connect to a Spirent TestCenter
chassis, and then reserve and map the ports that the test uses. The following code
fragment:
• Specifies the IP address of the chassis in a call to the connect function.
• Reserves the ports, specifying the chassis, slot, and port values.
• Executes the SetupPortMappings command to establish the connection between the
logical port representation (the Port objects) and the physical ports on the chassis.
The SetupPortMappings command uses the chassis/slot/port information from the
Port object to create the mapping.
• Applies the test configuration, sending the test configuration data to the chassis.

Notes: • The chassis-slot-port specification identifies the group to which the port
belongs. In this example, ports 1 and 2 belong to the same group. It is
necessary to explicitly reserve both ports in a group so that Spirent
TestCenter will perform the appropriate initialization for each port. For more
information about port groups, see the description of the reserve function.
• When you reserve a port, you establish exclusive access to the port.
• Port numbering begins at 1.
• The code fragment on page 61 demonstrates connection, reservation, and
mapping as three separate operations. Spirent TestCenter also provides a
single command (AttachPorts) that you can execute to perform these
operations.

60 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Script Template

#############################
# Connect to the chassis
#############################
puts "Connecting to the chassis..."
set resultReturn [CRS stc::connect $chassisAddress]
puts "Chassis connnection complete"

#############################
# Reserve ports
#############################
puts "Reserving the ports..."
set resultReturn [CRS stc::reserve "//$chassisAddress/$slotPort1"]
set resultReturn [CRS stc::reserve "//$chassisAddress/$slotPort2"]
puts "Port reservation complete"

#############################
# Setup logical <-> physical port mappings
#############################
puts "Logical to physical port mappings started..."
set resultReturn [CRS stc::perform setupPortMappings]
puts "Logical to physical port mapping complete"

#############################
### Apply the previously created configuration
#############################
puts "Applying configuration..."
set resultReturn [CRS stc::apply]

puts "Configuration applied successfully"

Text Execution
Once the configuration has been applied, the test can be run. The following sections show
the different aspects of test execution:
• Start traffic (Start Analyzers and Generators).
• After the time for the test has expired, Stop Traffic generation.
• Get the Frame Count.

Spirent TestCenter Automation Programmer’s Guide | 61

Spirent TestCenter Script Template

Start Analyzers and Generators

The following code fragment starts the traffic for the test by executing the AnalyzerStart
and GeneratorStart commands. Once traffic is being generated, the script executes a
loop, calling the sleep function inside the loop to suspend script execution for the duration
of the test.

###################################################################
puts " Starting analyzers..."
#############################
### Start analyzers
#############################

set analyzerCurrent [stc::get $port(2) -children-analyzer]

stc::perform analyzerStart -analyzerList $analyzerCurrent
puts " Analyzers started"

#############################
### Generate traffic
#############################
puts " Starting traffic generation..."
set generatorCurrent [stc::get $port(1) -children-generator]
stc::perform generatorStart -generatorList $generatorCurrent
puts " Traffic generation started"

###################################################################

set testTime 20
# Sleep for $testTime seconds
puts " Pausing for $testTime seconds..."
puts -nonewline " "
for {set elapsedTime 1} \
{$elapsedTime <= $testTime} \
{incr elapsedTime} \
{
stc::sleep 1
puts -nonewline "| $elapsedTime"
flush stdout
}

puts ""
puts "Pause time expired"

62 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Script Template

Stop Traffic
The following code fragment stops the generator and analyzer. Although the test was
configured for unidirectional traffic (using the generator on the first port and the analyzer
on the second port), this code stops all of the generators and analyzers. The stop operation
has no effect on any generators or analyzers that were not used.

###################################################################
# Stop traffic
puts " Stopping traffic generation..."
for {set portIndex 1} {$portIndex <= $portCount} {incr portIndex} {
set portCurrent $port($portIndex)
set generatorCurrent [stc::get $port($portIndex) -children-generator]
set analyzerCurrent [stc::get $port($portIndex) -children-analyzer]

stc::perform generatorStop -generatorList $generatorCurrent

stc::perform analyzerStop -analyzerList $analyzerCurrent
}
puts " Traffic generation stopped"

Get the Frame Count

Once the traffic is stopped, the script retrieves the frame count. The following code
fragment:
• Retrieves the handle for the Analyzer object.
• Retrieves the handle for the target object of the ResultChild relation extending from
the Analyzer object. (The type of result child object was established by the analyzer
subscription.)
• Retrieves the value of the FrameCount attribute.

#############################
### Validate
#############################
puts "Validating..."
puts "get individual stream block results here";

set analyzerCurrent [stc::get $port(2) -children-analyzer]

set portResultsHnd [stc::get $analyzerCurrent -resultchild]

set Fcount [stc::get $portResultsHnd -Ipv4FrameCount]

puts "FrameCount value = $Fcount";

puts "Test run completed"

Spirent TestCenter Automation Programmer’s Guide | 63

Spirent TestCenter Script Template

Script Termination
After the test has completed, your script should do the following:
• Release any reserved port groups. You must release all the port groups that you have
reserved. Note that a port group may contain more than one port; any attempt to use a
port handle after it has been released will result in an error. (For a description of the
release function, see the online Help for Spirent TestCenter Automation.)
• Disconnect from the chassis.
• Delete the Project object to release any resources accumulated through use of the
API.
The following code fragment shows an example of the function calls that you use to
perform cleanup.

################################################################
# Release hardware
puts "Releasing hardware..."

# Release ports
puts " Releasing ports..."
for {set portIndex 1} {$portIndex <= $portCount} {incr portIndex} {
set portCurrent $port($portIndex)
stc::release [stc::get $portCurrent -location]
}

# Disconnect from chassis

puts " Disconnecting from $chassisAddress..."
stc::disconnect $chassisAddress
puts " Disconnect from $chassisAddress completed"

puts "Hardware release completed"

#################################################################
# Clean up
puts "Cleaning up..."

puts "Deleting objects..."

stc::delete $project
puts "Objects deleted"

#################################################################

puts "Clean up finished"

puts "Finished running $scriptName"

64 | Spirent TestCenter Automation Programmer’s Guide

 The Spirent TestCenter Command Sequencer

The Spirent TestCenter Command Sequencer

Spirent TestCenter Automation defines a set of commands that you use to execute
different aspects of test logic. For example, you can use the following commands for a
BGP test:

BgpStopKeepalive BgpResumeTcpSession BgpWithdrawRoute

BgpResumeKeepalive BgpRestartRouter BgpViewRoutes
BgpBreakTcpSession BgpReadvertiseRoute BgpImportRouteTable

There are two methods of executing commands:

• You can use the perform function to execute a command. When you call the perform
function, you specify the name of the command and any parameters that are required.
For example:
stc::perform CaptureStart -captureProxyId $capture1
The set of attributes defined for the command object determine the possible
parameters.
• You can use the Command Sequencer to organize and execute a set of commands.
When you use the Sequencer, you create command objects, then use the perform
function to invoke Sequencer commands that organize and run the test.

NOTES: Command object type names and sequenceable commands:

• The name of a command object type is formed by adding the suffix
“Command” to a command name. For example, use the name of the
command CaptureStart with the perform function; use the object type
name CaptureStartCommand with the Command Sequencer.
• You can use only sequenceable commands with the Command Sequencer. A
sequenceable command is identified in its command object description (see
the Spirent TestCenter Automation Object Reference). Most of the commands
that manipulate the Sequencer directly are not sequenceable. (An example of
a command that you can use only with the perform function is the
SequencerStart command.)
The following sections provide information about the Spirent TestCenter Command
Sequencer.
• Using the Sequencer
• Sequencer Commands
• Sequencer / Command States
• Sequencer Example (Basic)
• Sequencer Example (Advanced)

Spirent TestCenter Automation Programmer’s Guide | 65

The Spirent TestCenter Command Sequencer

Using the Sequencer

The command Sequencer is represented by the Sequencer object. Spirent TestCenter
creates the Sequencer object automatically. To use the Sequencer:
• Create the command objects for the protocol(s) that you are testing.
• Use the SequencerInsert command to add commands to the Sequencer. The order of
command execution is determined by the order of insertion.You can also set the
position of a command within a sequence by specifying the InsertAfter and
InsertIndex attributes when you invoke SequencerInsert. Note that you can modify
the command sequence by invoking the SequencerMove, SequencerRemove,
SequencerReplace, or SequencerClear commands.
• Use the SequencerStart command to execute the command sequence. Spirent
TestCenter will execute the command sequence until completion, or until it
encounters a break point or you invoke the SequencerPause command.

IMPORTANT: You can insert commands or modify the execution order only when the
Sequencer is in the IDLE state. (For information see Sequencer / Command States.)

Sequencer Commands
The following table provides an overview of the Sequencer commands:

Purpose Command Description

Creating and modifying a SequencerInsert Adds commands to the Sequencer. The

command sequence commands will be executed in the order in
which they are inserted. You can insert
commands only when the Sequencer is in
the IDLE state (see Sequencer / Command
States).

SequencerRemove Removes commands from the Sequencer.

SequencerClear Removes all commands from the Sequencer.

SequencerReplace Replaces one command with another.

SequencerMove Changes the order of sequenced commands.

66 | Spirent TestCenter Automation Programmer’s Guide

 The Spirent TestCenter Command Sequencer

Purpose Command Description

Running a command sequence SequencerStart Starts command execution. The Sequencer

executes commands in the order that they
were inserted. Command execution
continues until one of the following occurs:
– The command sequence has finished.
– The Sequencer encounters a breakpoint.
– You invoke SequencerPause or
SequencerStop.
The SequencerStart command returns
control to script execution quickly, and the
Sequencer keeps running in the background.
While the Sequencer executes the command
sequence, your script can do other things,
including checking on Sequencer status.
Note that you should not modify your test
configuration while the Sequencer is
running. After you invoke the
SequencerStart command, you should only
use the get function to retrieve information
until the Sequencer stops for one of the
reasons listed above.

SequencerPause Pauses the Sequencer. If you execute

SequencerPause while a command is
running, the sequencer will pause after that
command has finished. When the Sequencer
is paused, and you invoke SequencerStep or
SequencerStart, Spirent TestCenter
resumes command execution from the place
that execution was paused.

SequencerStep Executes a single command, then pauses.

When the Sequencer is paused, and you
invoke SequencerStep or SequencerStart,
Spirent TestCenter resumes command
execution from the place that execution was
paused.

SequencerStop Stops the Sequencer after the currently

running command has finished. After
stopping a sequence, you can only start a
sequence again from the beginning of the
sequence. (You cannot resume a stopped
sequence.)

Spirent TestCenter Automation Programmer’s Guide | 67

The Spirent TestCenter Command Sequencer

Purpose Command Description

Sequencer control SequencerInsertBreakpoint Adds one or more breakpoints. A breakpoint

identifies a command. When the Sequencer
encounters a breakpoint, it pauses before
running the command associated with the
breakpoint. When you use breakpoints, you
must insert them when the Sequencer is idle
(see Sequencer States).

SequencerRemoveBreakpoint Removes a breakpoint.

SequencerDisable Disables a sequenced command. When the

Sequencer encounters a disabled command,
it skips the command and executes the next
command in the sequence.

SequencerEnable Enables a command.

SequencerLoop Performs a loop of commands. To set up a

command loop, use SequencerInsert to add
command objects to the loop object, and add
iteration objects to the loop to define the
loop parameters (for example, the
IterateFrameSizeCommand object).

SequencerBreakLoop Breaks out of the currently executing loop.

Sequencer / Command States

Spirent TestCenter defines a set of Sequencer states; it also defines a set of states for each
command. The following sections provide information about sequencer and command
states:
• Sequencer States
• Command States

Sequencer States
The Sequencer operates in one of following states:
• IDLE - The Sequencer is stopped.
• INIT - The Sequencer goes through an initialization state whenever it goes from IDLE
to RUNNING.
• RUNNING - The Sequencer is executing a command.
• WAIT - The Sequencer is waiting for a command to finish executing.
• PAUSE - The Sequencer is paused

68 | Spirent TestCenter Automation Programmer’s Guide

 The Spirent TestCenter Command Sequencer

You can determine the state of the sequencer by retrieving the value of the State attribute
for the Sequencer object:
stc::get system1.sequencer -state
In the function call above, the specification system1.sequencer uses path notation to
identify the Sequencer child of the system1 object. (Spirent TestCenter creates the
system1 object automatically.) For more information about using path notation for object
and attribute references, see Referencing Objects: Object Paths.
The following figure indicates the Sequencer states, along with the commands and
conditions that promote a change in state.

IDLE
- Before SequencerStart or SequencerStep
(if starting in step mode)
- After SequencerStop

SequencerStart
SequencerStep
SequencerStop
or
INIT
- Sequencer initializing command sequence finished

RUNNING
- Sequencer executing

SequencerStart
start
command SequencerPause SequencerStep
finish
execution command or
execution breakpoint

WAIT PAUSED
- Command executing - After SequencerPause
- After stepped command execution

IMPORTANT: Once you start a command sequence (by invoking the SequencerStart
command), you should not modify your test configuration. You may use the get function
to retrieve information, but you should consider the test configuration “locked” until the
command sequence is finished or the Sequencer pauses.

Spirent TestCenter Automation Programmer’s Guide | 69

The Spirent TestCenter Command Sequencer

Command States
Spirent TestCenter defines individual command states:
• INIT
• START
• RUNNING
• PAUSED
• PRECOMPLETE
• COMPLETED
• FAILED
• VALIDATION_ERROR
To determine the state of a command, retrieve the value of the State attribute for the
command object:
set durationState [stc::get $DurationCommand -State]

Sequencer Example (Basic)

The following sections describe a simple Sequencer example:
• Test Configuration
• Initialization
• Port and Traffic Configuration
• Command Sequence
• Test Execution

Test Configuration
The figure on page 71 shows the object hierarchy for the basic Sequencer example. The
generator, analyzer, and analyzer port result objects are shown in red, indicating that
Spirent TestCenter creates these objects automatically.

70 | Spirent TestCenter Automation Programmer’s Guide

 The Spirent TestCenter Command Sequencer

StreamBlock
Port 1 Generator

Analyzer AnalyzerPortResults
Project

Port 2 Analyzer AnalyzerPortResults

This example uses two ports on a Spirent TestCenter chassis. The first port will send
traffic to the second port. During the test, the script will monitor the sequencer status.
Once the sequence is complete, the script retrieves the total frame count.

Initialization
Every Spirent TestCenter Automation Tcl script must load the Spirent TestCenter package
before it can use the API. The following code fragment loads the package, and it also
defines the location and test duration variables that will be used later in the script.

# Load Spirent TestCenter

package require SpirentTestCenter

set chassisAddress "10.100.20.5"

set slotPort1 "2/1"
set slotPort2 "2/2"
set runtime 5

Port and Traffic Configuration

The code fragment on page 72:
• Creates the test configuration objects:
• The Project object is the root of the test configuration object hierarchy.
• The Port objects represent physical ports on the Spirent TestCenter chassis. Port
objects are children of the Project object.
• The StreamBlock object defines the traffic for the test. The StreamBlock object
is a child of the first Port object.
• Executes the attachPorts command to connect to the chassis, then reserve and map
the ports.
• Applies the configuration.
• Establishes a subscription for analyzer port results to collect the total frame count.

Spirent TestCenter Automation Programmer’s Guide | 71

The Spirent TestCenter Command Sequencer

set project [stc::create project]

set port(1) [stc::create port -under $project \

-location "$chassisAddress/$slotPort1"]
set port(2) [stc::create port -under $project \
-location "$chassisAddress/$slotPort2"]

set streamBlock [stc::create streamBlock -under $port(1) \

-EnableStreamOnlyGeneration TRUE \
-frameConfig "" \
-FixedFrameLength 128 \
-load 100]

puts "Connect, reserve ports, setup port mappings"

stc::perform attachPorts -portList "$port(1) $port(2)" \
-autoConnect TRUE

puts "Apply the configuration to the test instruments"

stc::apply

puts "Enable analyzer results"

set resultDataSet1 [stc::subscribe -Parent $project \
-ConfigType Analyzer \
-viewAttributeList "TotalFrameCount" \
-resulttype AnalyzerPortResults ]

Command Sequence
The script for this example uses the following command objects, in the sequence shown:
1 AnalyzerStartCommand
2 GeneratorStartCommand
3 WaitCommand
4 GeneratorStopCommand
5 AnalyzerStopCommand
To use command objects with the Sequencer, you create command objects and insert them
into the Sequencer. The Sequencer object and the command objects are children of the
Spirent TestCenter system object (system1). Spirent TestCenter creates the system1
object automatically.

72 | Spirent TestCenter Automation Programmer’s Guide

 The Spirent TestCenter Command Sequencer

The following code fragment creates the command objects for the example configuration
and inserts them into the Sequencer.

puts "Get the Sequencer"

set sequencer [stc::get system1 -children-sequencer]

puts "Setup the commands"

set commands ""
set analyzers "[stc::get $port(1) -children-analyzer] \
[stc::get $port(2) -children-analyzer]"
lappend commands [stc::create analyzerStartCommand \
-under system1 \
-analyzerList $analyzers]
set generators "[stc::get $port(1) -children-generator]"
lappend commands [stc::create generatorStartCommand \
-under system1 \
-generatorList $generators]
lappend commands [stc::create waitCommand -under system1 \
-WaitTime $runtime]
lappend commands [stc::create generatorStopCommand \
-under system1 \
-generatorList $generators]
lappend commands [stc::create analyzerStopCommand \
-under system1 \
-analyzerList $analyzers]

puts "Add the commands to the Sequencer: $commands"

stc::perform sequencerInsert -commandList "$commands"

The code fragment above:

• Retrieves the handle to the Sequencer object for use during monitoring (see Test
Execution to see the code that monitors the Sequencer state). Note that the get
function call uses the -children side name for the relation reference, with the object
type filter (-Sequencer) to retrieve only the Sequencer object handle.
• Retrieves the handles to the Analyzer objects for each port. As in the call to retrieve
the handle to the Sequencer object, the calls to the get function use the ParentChild
side-name/type-filter relation reference to retrieve the handles (in this case -children-
analyzer).
• Creates the AnalyzerStartCommand object, setting the -AnalyzerList attribute to
provide the list of handles to the Analyzer objects.
• Retrieves the handle to the Generator object for the first port. (The call to the get
function uses the ParentChild side–name/type–filter relation reference to retrieve the
handles.)

Spirent TestCenter Automation Programmer’s Guide | 73

The Spirent TestCenter Command Sequencer

• Creates the GeneratorStartCommand object, setting the -GeneratorList attribute to

provide the list of handles to the Generator object.
• Creates the WaitCommand object, specifying the wait time to set the time that traffic
will be generated.
• Creates the GeneratorStopCommand object (setting the -GeneratorList attribute).
• Creates the AnalyzerStopCommand object (setting the -AnalyzerList attribute).
• As each command is created, the returned command object handle is appended to the
command list. Once the script has finished creating the command objects, it executes
the sequencerInsert command to add the commands to the Sequencer. The
Sequencer will execute the commands in the order they occur in the list.

Test Execution
The following code fragment runs the test. The test execution consists of the following
operations:
• Start the sequencer – the sequencer will execute the commands in the order in which
they were inserted into the sequencer. The time established for the WaitCommand
determines the amount of time that Spirent TestCenter will generate traffic.
• Wait until the sequence is complete. The waituntilcomplete function checks the
Sequencer state and returns control to the script when the Sequencer pauses or
becomes idle.
• Retrieve the frame count for both the transmitting and receiving ports – the script
retrieves the handle to the AnalyzerPortResult object for each port, and then uses
those handles to retrieve (and display) the total frame count.
• Disconnect from the chassis.

puts "Start the Sequencer running"

stc::perform sequencerStart

stc::waituntilcomplete

puts "Print counters"

for {set i 1} {$i <= 2} {incr i} {
set analyzerCounters [stc::get $port($i).analyzer \
-children-analyzerPortResults]
puts "Port $i total frame count: [stc::get $analyzerCounters -totalFrameCount]"
}

puts "Disconnect"
stc::perform chassisDisconnectAll

74 | Spirent TestCenter Automation Programmer’s Guide

 The Spirent TestCenter Command Sequencer

Sequencer Example (Advanced)

The following sections describe a more complex Sequencer example:
• Initialization
• Test Configuration
• Traffic Configuration
• Attaching Ports
• Sequencer Configuration and Execution

Initialization
Every Spirent TestCenter Automation Tcl script must load the Spirent TestCenter package
before it can use the API. The following code fragment loads the package, and it also
defines variables that will be used later in the script.
set scriptName "Advanced2PortSequencer.tcl"
puts "Start running $scriptName"

# Load Spirent TestCenter

package require SpirentTestCenter

set chassisAddress "10.100.20.51"

set slotPort1 "1/1"
set slotPort2 "1/2"
set runtime 30

Test Configuration
The figure on page 76 shows the test configuration object hierarchy for the example script.
The advanced Sequencer example script uses two ports on a Spirent TestCenter chassis.
The ports use Ethernet copper connections to a DUT running at autonegotiated speeds.

Spirent TestCenter Automation Programmer’s Guide | 75

The Spirent TestCenter Command Sequencer

EthernetCopper
ethernet:EthernetII
Port StreamBlock
ipv4:IPv4
Generator

EthIIIf
Host
Ipv4If
Project

EthernetCopper
ethernet:EthernetII
Port StreamBlock
ipv4:IPv4
Generator

EthIIIf
Host
Ipv4If

The advanced Sequencer example uses the following objects:

• The Project object is the root of the test configuration object hierarchy.
• The Port objects represent physical ports on the Spirent TestCenter chassis.
• The EthernetCopper objects define the Ethernet copper interface for the ports.
• The Host objects represent emulated hosts within the emulated network created by
Spirent TestCenter.
• The EthIIIf and Ipv4If objects define the Ethernet and IPv4 interfaces for the hosts.
• The StreamBlock, EthernetII, and IPv4 objects define the traffic streams for the
test.
• The Generator objects (shown in red to indicate that Spirent TestCenter creates these
objects automatically) define traffic generation for the ports.
These objects represent the emulated network configuration. The lines between the objects
indicate the parent-child relations that connect the objects. (Spirent TestCenter creates
parent-child relations automatically.) To complete the test configuration, the script creates
additional relations and command objects to execute the test. (See Additional Relations
and Sequenced Commands.)
The following sections contain the code fragments that create the test configuration:
• Project, Port, and EthernetCopper Objects
• Hosts and Host Interfaces
• Additional Relations

76 | Spirent TestCenter Automation Programmer’s Guide

 The Spirent TestCenter Command Sequencer

Project, Port, and EthernetCopper Objects

The following code fragment creates the Project, Port, and EthernetCopper objects.
• The Project object is the root of the test configuration hierarchy.
• The Port objects represent the physical ports on the Spirent TestCenter chassis.
• The EthernetCopper objects define the type of port connection, including duplex
and auto-negotiation settings.
puts " Creating project..."
set project [stc::create Project]
puts " project ($project) created"

# Set log parameters

# -logTo values: stdout/filename
# -logLevel values: DEBUG/INFO/WARN/ERROR
stc::config automationoptions -logTo stdout -logLevel WARN

#############################
### Create the ports under the project
#############################
puts "Creating the ports..."
set port(1) [stc::create Port \
-under $project \
-Location "//$chassisAddress/$slotPort1" \
-Name "Port //$slotPort1"]

set port(2) [stc::create Port \

-under $project \
-Location "//$chassisAddress/$slotPort2" \
-Name "Port //$slotPort2"]
#############################
### Create the port type under the port object. In this case the port type is copper
#############################
set ethernetCopper(1) [stc::create EthernetCopper \
-under $port(1) \
-Duplex "FULL" \
-AutoNegotiation "TRUE" \
-AutoNegotiationMasterSlave "MASTER" \
-Name "ethernetCopper 1"]

set ethernetCopper(2) [stc::create EthernetCopper \

-under $port(2) \
-Duplex "FULL" \
-AutoNegotiation "TRUE" \
-AutoNegotiationMasterSlave "MASTER" \
-Name "ethernetCopper 2"]

Spirent TestCenter Automation Programmer’s Guide | 77

The Spirent TestCenter Command Sequencer

Hosts and Host Interfaces

Host objects represent host systems in the emulated network environment. Host objects
are children of the Project object; they are associated with ports on Spirent TestCenter
chassis with the AffiliationPort relation. (See Additional Relations for an example of
creating an AffiliationPort relation.) Host objects also provide the configuration of the
interface stack through the definition of interface objects. The example script uses
Ethernet and IPv4 interfaces. The interface objects (EthIIIf and Ipv4If objects) are
children of the Host objects.
The following code fragments show the creation of the Host and interface objects. (The
first code fragment creates the Host and EthIIIf objects; the second fragment creates the
Ipv4If objects.) Once these objects have been created, the stacking order of the interfaces
is determined by creating the appropriate relations (see Additional Relations).
#############################
### Create the hosts that will be used as sources for the streamblocks
#############################
set host(1) [stc::create Host \
-under $project \
-Name "Host 1"]

set host(2) [stc::create Host \

-under $project \
-Name "Host 2"]

puts "Host creation complete"

puts "Creating/configuring the host's EthernetII interface..."

#############################
### Create/configure the Ethernet II interface for the hosts
#############################
set ethIIIf(1) [stc::create EthIIIf \
-under $host(1) \
-SourceMac "00:00:01:00:00:02" \
-Name "EthIIIf 1"]

set ethIIIf(2) [stc::create EthIIIf \

-under $host(2) \
-SourceMac "00:01:01:00:00:02" \
-Name "EthIIIf 2"]

puts "Host EthernetII interface creation/configuration complete"

78 | Spirent TestCenter Automation Programmer’s Guide

 The Spirent TestCenter Command Sequencer

The following code fragment creates the IPv4 interface objects, one for each host.
puts "Creating/configuring the host's IPv4 interface..."
set ipv4If(1) [stc::create Ipv4If \
-under $host(1) \
-Address "30.0.0.3" \
-PrefixLength "24" \
-UsePortDefaultIpv4Gateway "FALSE" \
-Gateway "30.0.0.1" \
-ResolveGatewayMac "TRUE" \
-Name "Ipv4If 1"]

set ipv4If(2) [stc::create Ipv4If \

-under $host(2) \
-Address "30.1.0.3" \
-PrefixLength "24" \
-UsePortDefaultIpv4Gateway "FALSE" \
-Gateway "30.1.0.1" \
-ResolveGatewayMac "TRUE" \
-Name "Ipv4If 2"]

puts "Host IPv4 interface creation/configuration complete"

Additional Relations

When you create objects (with the exception of the Project object), you specify a parent
when you call the create function (stc::create -under parent). Spirent TestCenter
automatically creates the ParentChild relations for newly created objects. A test
configuration requires additional relations between objects to establish connections that
are not available through the ParentChild relation.
The example script establishes the following relations for each port/host combination:
• The AffiliationPort relation defines the association between an emulated host and a
port on a Spirent TestCenter chassis.
• The TopLevelIf relation identifies the initial interface in the host interface stacking
order.
• The PrimaryIf relation identifies the top level interface (TopLevelIf) that faces the
DUT.
• StackedOnEndpoint relations define the stacking order of the interfaces on an
emulated host.

Spirent TestCenter Automation Programmer’s Guide | 79

The Spirent TestCenter Command Sequencer

The following figure shows the relations that the example script creates in addition to the
automatically created ParentChild relations. In the figure, the additional relations are
shown with arrows, with the arrow pointing at the target of the relation.

Port

AffiliationPort
StackedOnEndpoint

EthIIIf

Host

Ipv4If

TopLevelIf
Project
PrimaryIf

Port

AffiliationPort
StackedOnEndpoint

EthIIIf

Host

Ipv4If

TopLevelIf

PrimaryIf

80 | Spirent TestCenter Automation Programmer’s Guide

 The Spirent TestCenter Command Sequencer

The following code fragment shows the calls to the config function to establish the
relations. Each call to config specifies the local object to be configured and a relation
specification. For example, the following call to config establishes the AffiliationPort
relation between the first host and the first port.
stc::config $host(1) -AffiliatedPort $port(1)
The relation specification uses the relation type side name (-AffiliatedPort) and the
remote object that completes the relation – $port(1). The AffiliatedPort side name
represents the remote side of the AffiliationPort relation (-targets).

puts "Setting up the relations for the hosts to the port objects..."

#############################
### Setup the relations from port level objects
### to host objects and interfaces
#############################
stc::config $host(1) -AffiliatedPort $port(1)
stc::config $host(1) -TopLevelIf $ipv4If(1)
stc::config $host(1) -PrimaryIf $ipv4If(1)
stc::config $ipv4If(1) -StackedOn $ethIIIf(1)
stc::config $host(2) -AffiliatedPort $port(2)
stc::config $host(2) -TopLevelIf $ipv4If(2)
stc::config $host(2) -PrimaryIf $ipv4If(2)
stc::config $ipv4If(2) -StackedOn $ethIIIf(2)
puts "Host relation configuration complete"

Traffic Configuration
The sequencer example generates traffic from each emulated host. The following code
fragment creates the StreamBlock, EthernetII, and IPv4 objects to define the traffic
streams.
• A StreamBlock object is a child of a Port object. The example creates one
StreamBlock object under each Port object in the configuration. The script also
clears the frame configuration. This is necessary to take advantage of the host
interface configuration (see Traffic Bindings).
• The EthernetII and IPv4 objects are children of the StreamBlock objects. Each
StreamBlock object has one EthernetII and one IPv4 child.

NOTE: PDU specification:

• The example code shows the specification of the EthernetII and IPv4 objects
as follows:
ethernet:EthernetII
ipv4:IPv4
When you use Protocol Data Unit (PDU) objects that are children of
StreamBlock objects, you must use the PDU library name prefix for the

Spirent TestCenter Automation Programmer’s Guide | 81

The Spirent TestCenter Command Sequencer

object. Only use the PDU library prefix for StreamBlock children, not for
any other PDU objects.
• When you specify a StreamBlock child, you must use the character case
shown (ethernet:EthernetII, for example).

###### Create stream blocks (one per port)

set streamBlock(1) [stc::create streamBlock -under $port(1)]
set streamBlock(2) [stc::create streamBlock -under $port(2)]

###### Clear the frame configuration for the stream blocks

set streamBlockConfig(1) [stc::config $streamBlock(1) -frameconfig ""]
set streamBlockConfig(2) [stc::config $streamBlock(2) -frameconfig ""]

#### Create/configure the Ethernet II interface for the first streamblock

set strBlkEthII(1) [stc::create ethernet:EthernetII \
-under $streamBlock(1) \
-name "eth_sb1" \
-srcMac 00:00:00:01:00:01]

### Create/configure the IPv4 interface for the first streamblock

set strBlkIpv4(1) [stc::create ipv4:IPv4 \
-under $streamBlock(1) \
-name "ipv4_sb1" \
-sourceAddr 30.0.0.11 \
-destAddr 30.1.0.11 \
-gateway 30.0.0.1]

#### Create/configure the Ethernet II interface for the second streamblock

set strBlkEthII(2) [stc::create ethernet:EthernetII \
-under $streamBlock(2) \
-name "eth_sb2" \
-srcMac 00:00:00:01:00:02]

### Create/configure the IPv4 interface for the second streamblock

set strBlkIpv4(2) [stc::create ipv4:IPv4 \
-under $streamBlock(2) \
-name "ipv4_sb2" \
-sourceAddr 30.1.0.11 \
-destAddr 30.0.0.11 \
-gateway 30.1.0.1]

82 | Spirent TestCenter Automation Programmer’s Guide

 The Spirent TestCenter Command Sequencer

Traffic Bindings

The following figure shows the source and destination bindings that are established
between the StreamBlock objects and the Ipv4If objects associated with the hosts. These
relations set the traffic streams from one port to the other.

Port StreamBlock

SrcBinding

Host
Ipv4If DstBinding
Project DstBinding

Port StreamBlock

SrcBinding

Host
Ipv4If

The following code fragment shows the function calls to establish the bindings. Each call
to config specifies the local object to be configured (the StreamBlock object) and a
relation specification for the source or destination binding. For example, the following call
to config establishes the SrcBinding relation between the StreamBlock and the Ipv4If
objects associated with the first host.
stc::config $streamBlock(1) -SrcBinding $ipv4If(1)
The relation specification uses the relation type side name (-SrcBinding) and the remote
object that completes the relation – $ipvrIf(1). The SrcBinding side name represents the
remote side of the SrcBinding relation (-targets)

#############################
### Setup the relations for the bindings in the streamblocks
### The source is the host on each port, and the destination
### is the routeblock advertised by the other port
#############################
stc::config $streamBlock(1) -SrcBinding $ipv4If(1)
stc::config $streamBlock(1) -DstBinding $ipv4If(2)
stc::config $streamBlock(2) -SrcBinding $ipv4If(2)
stc::config $streamBlock(2) -DstBinding $ipv4If(1)

puts "Streamblock configuration complete"

Spirent TestCenter Automation Programmer’s Guide | 83

The Spirent TestCenter Command Sequencer

Attaching Ports
To run the test, you must:
• Connect to the chassis.
• Reserve the ports that you intend to use.
• Map the reserved ports.
You can perform these operations by calling the connect function, and then use the
ReservePort and MapPort commands. As an alternative, you can accomplish all three
operations by using the AttachPorts command. The AttachPorts command uses the
location defined in the Port objects to connect to the chassis and reserve the ports, after
which it creates the mapping between the physical ports and their logical representation in
the test configuration. The following code fragment demonstrates the use of the
AttachPorts command, after which it applies the test configuration.

puts "Connecting to the chassis..."

#############################
# Connect, reserve, and map
#############################
stc::perform attachPorts -portList "$port(1) $port(2)" -autoConnect TRUE

puts "Logical to physical port mapping complete"

puts "Applying configuration..."

#############################
### Apply the previously created configuration
#############################
stc::apply
puts "Configuration applied successfully"

Sequencer Configuration and Execution

The advanced Sequencer example generates traffic using varying frame sizes and loads.
The sequenced operations for this example consist of the following:
• Configure the test duration (SetDurationCommand).
• Start the emulated devices (DevicesStartAllCommand).
• Define a command loop based on frame size (SequencerLoopCommand).
• Define the frame sizes for the test (IterateFrameSizeCommand).
• Define a command loop based on load size (SequencerLoopCommand).
• Define the load sizes for the test (IterateLoadSizeCommand).
• Start the Generators (GeneratorStartCommand)

84 | Spirent TestCenter Automation Programmer’s Guide

 The Spirent TestCenter Command Sequencer

• Wait (WaitCommand)
• Stop the Generators (GeneratorStopCommand)
In preparation for traffic generation, the following code fragment obtains the handles to
the Generator and StreamBlock objects.

puts "Starting to configure the sequencer..."

set generatorList ""

set streamBlockList ""
set hHostList [stc::get $hProject -children-host]
foreach portName $hPortList {
lappend generatorList [stc::get $portName -children-Generator]
set streamBlockList [concat $streamBlockList \
[stc::get $portName -children-StreamBlock]]
}

The following sections describe:

• Sequenced Commands
• Execution Hierarchy
• Insertion and Execution

Sequenced Commands

The figure on page 86 shows the set of command objects for the advanced Sequencer test.
This figure indicates the parent-child relations for this objects. Note that command objects
are children of the internal object System1. The figure shows the System1 object in red to
indicate that Spirent TestCenter creates this object automatically.

Spirent TestCenter Automation Programmer’s Guide | 85

The Spirent TestCenter Command Sequencer

System1

SetDurationCommand

DevicesStartAllCommand

SequencerLoopCommand (frame size)

SequencerLoopCommand (load)

IterateFrameSizeCommand

IterateLoadSizeCommand

GeneratorStartCommand

WaitCommand (generator stop)

GeneratorStopCommand

The following code fragment creates the command objects. The code fragment retrieves
the handle to the Sequencer object (for inserting objects into the sequencer later – see
Execution Hierarchy), and then creates the command objects as children of the system1
object.

86 | Spirent TestCenter Automation Programmer’s Guide

 The Spirent TestCenter Command Sequencer

set sequencer [stc::get system1 -children-sequencer]

set setDurationCommand [stc::create SetDurationCommand \

-under system1 \
-DurationMode "SECONDS" \
-DurationSeconds "10" \
-Name "SetDurationCommand" \
-GeneratorList "$generatorList"]

set startAllDevicesCommand [stc::create DevicesStartAllCommand \

-under system1 \
-projectHandle $hProject]

set frameSizeLoop [stc::create SequencerLoopCommand \

-under system1 \
-IterationCount "1" \
-ExecutionMode "BACKGROUND" \
-GroupCategory "REGULAR_COMMAND" \
-ContinuousMode "TRUE" \
-Name "Frame Size Loop"]

set loadLoop [stc::create SequencerLoopCommand \

-under system1 \
-IterationCount "1" \
-ExecutionMode "BACKGROUND" \
-GroupCategory "REGULAR_COMMAND" \
-ContinuousMode "TRUE" \
-Name "Load Loop"]

set iterateFrameSizeCommand [stc::create IterateFrameSizeCommand \

-under system1 \
-FrameSizeType "STEP" \
-FrameSizeStart "128" \
-FrameSizeEnd "512" \
-FrameSizeStep "128" \
-Name "IterateFrameSizeCommand" \
-StreamBlockList $streamBlockList]

set iterateLoadSizeCommand [stc::create IterateLoadSizeCommand \

-under system1 \
-LoadType "STEP" \
-LoadUnits "PERCENT_LINE_RATE" \
-LoadStart "10" \
-LoadEnd "20" \
-LoadStep "10" \
-Name "IterateLoadSizeCommand" \
-StreamBlockList $streamBlockList]

Spirent TestCenter Automation Programmer’s Guide | 87

The Spirent TestCenter Command Sequencer

set generatorStartCommand [stc::create GeneratorStartCommand \

-under system1 \
-Name "GeneratorStartCommand" \
-GeneratorList "$generatorList"]

set generatorStopCommand [CRS stc::create GeneratorStopCommand \

-under system1 \
-Name "GeneratorStopCommand"]

set generatorWaitForStop [stc::create WaitCommand \

-under system1 \
-WaitTime 30 \
-Name "Generator Wait For Stop"]

Execution Hierarchy

To generate traffic using varying frame sizes and loads, the command objects are
organized into execution loops that use iteration objects to determine the loop parameters.
The advanced Sequencer example uses two execution loops:
• The outer loop uses the IterateFrameSizeCommand object to step through a series
of frame sizes. The IterateFrameSizeCommand object defines:
• The method of setting the frame size (in this case STEP, increasing the frame size
with each iteration).
• The starting, step, and ending frame size values.
• The streams for traffic generation.
• The inner loop uses the IterateLoadSizeCommand object to step through a series of
load sizes. The IterateLoadSizeCommand object defines:
• The method of setting the load size (in this case STEP, increasing the load size
with each iteration).
• The load unit.
• The starting, step, and ending load size values.
• The streams for traffic generation.
The inner loop also executes the set of commands that generate traffic.
The figure on page 89 shows the execution hierarchy for the example. The actual structure
of the hierarchy is determined by insertion into the Sequencer. The figure indicates:
• The sequence of execution that is established by the order specified during insertion.
• The loop structure that is created by using the SequencerInsert command. You create
a command loop by specifying a SequencerLoopCommand object as the command
parent.

88 | Spirent TestCenter Automation Programmer’s Guide

 The Spirent TestCenter Command Sequencer

For example:
stc::perform SequencerInsert \
-CommandHandles "$iterateFrameSizeCommand $loadLoop"\
-CommandParent $frameSizeLoop
This command inserts the iterateFrameSize and load size SequencerLoop
commands into the frame size loop.

Sequencer

SetDurationCommand

DevicesStartAllCommand

SequencerLoopCommand (frame size)

IterateFrameSizeCommand

SequencerLoopCommand (load)

IterateLoadSizeCommand

GeneratorStartCommand

WaitCommand

GeneratorStopCommand

Insertion and Execution

The following code fragment performs the sequencer insertion operations that set up the
execution logic, and then it runs the test.
• In this example, the insertions are handled in three separate operations that reflect the
loop structure.
• After inserting the commands into the sequencer, the script starts the sequencer and
executes a simple loop to check the sequencer state. The sequencer will transistion to
the IDLE state when the command sequence has completed.
• Once the command sequence has finished, the script releases the ports and
disconnects from the chassis.

Spirent TestCenter Automation Programmer’s Guide | 89

The Spirent TestCenter Command Sequencer

#############################
### Setup the actual sequence of events...
#############################
stc::perform SequencerInsert \
-CommandHandles "$setDurationCommand $devicesStartAllCommand $frameSizeLoop"
stc::perform SequencerInsert \
-CommandHandles "$iterateFrameSizeCommand $loadLoop" \
-CommandParent $frameSizeLoop

stc::perform SequencerInsert \
-CommandHandles "$iterateLoadSizeCommand $generatorStartCommand \
$generatorWaitForStop $generatorStopCommand”
-CommandParent $loadLoop

set sequencerList "$sequencer $setDurationCommand $startAllDevicesCommand \

$frameSizeLoop $iterateFrameSizeCommand $loadLoop $iterateLoadSizeCommand \
$generatorStartCommand $generatorWaitForStop $generatorStopCommand"

puts "Sequencer configuration complete"

puts "[clock format [clock seconds] -format %A%t%m-%d-%Y%l:%M:%S%p] Starting

Sequencer..."
stc::perform sequencerStart

while {[stc::get $sequencer -state] != "IDLE"} {

puts "Waiting for sequencer to finish. Current state: [stc::get $seq -state]"
stc::sleep 1
}

puts "Releasing the ports..."

stc::release "//$chassisAddress/$slotPort1"
stc::release "//$chassisAddress/$slotPort2"
puts "Disconnecting from the chassis"
stc::perform chassisdisconnectall
puts "Disconnecting from the chassis complete"

90 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Results

Spirent TestCenter Results

Spirent TestCenter collects test results throughout the execution of a test. In order to
retrieve results values, you must establish subscriptions for sets of results. Based on the
subscriptions, Spirent TestCenter maintains test results in memory by setting the value of
result attributes for objects in the object hierarchy. During a test, you can obtain test
results by using the get function to retrieve the value of result attributes.
After the test has completed, Spirent TestCenter produces output files containing the end-
of-test results data. Spirent TestCenter Automation also produces a log file.
The following sections provide information about producing and obtaining test results:
• Overview
• Paged Results
• End-of-Test Results Database

Overview
Spirent TestCenter test results are collected for the duration of a test and, at the end of a
test run, Spirent TestCenter Automation writes the test results to files. To enable the
collection of test results, you must establish subscriptions for results.
The following sections provide information about:
• Log Files: The Automation Options Object
• Subscriptions
• Result Files
• Using the API to Retrieve Test Results

Log Files: The Automation Options Object

Spirent TestCenter defines the AutomationOptions object to store settings for logging
diagnostic messages. The object has the following attributes:
• LogLevel - Defines the minimum severity level of logged diagnostic messages.
• LogTo - Specifies the output destination for diagnostic messages.
Spirent TestCenter creates the AutomationOptions object automatically. To set
automation options, first retrieve the handle for the object, and then call the config
function to set the values. For example:
set hOptions [stc::get system1 -children-AutomationOptions]
stc::config $hOptions -LogLevel ERROR

The call to config specifies that Spirent TestCenter will report ERROR level messages
only.

Spirent TestCenter Automation Programmer’s Guide | 91

Spirent TestCenter Results

Subscriptions
To retrieve results values, you must establish subscriptions for sets of results. When you
create a subscription, you specify the following information to identify the type and scope
of results to be collected:
• The type of results to be collected (the -resultType parameter).
• The configuration object associated with the results (the -configType parameter). The
configuration object is defined as the source element of a ResultChild relationship
that is defined for the resultType object. (See the Spirent TestCenter Automation
Object Reference for the ResultChild definitions for specific result object types.)
• The root of the results collection (the -resultParent parameter). By default, the result
parent is the Project object, producing results for the entire test configuration. You
can reduce the amount of data collected by specifying a different result parent, for
example, a particular port.
Note: When you specify either the DiffServResults or the FilteredStreamResults
object type as the subscription result type (-resultType), you cannot use the default
result parent (-resultParent $project). DiffServResults and FilteredStreamResults
are associated with specific ports, so you must identify a single port as the result
parent.
For example, the following calls to the subscribe function establish subscriptions for
generatorPortResults for the transmitting port and AnalyzerPortResults for the
receiving port.

set tx_resinfo [stc::subscribe -parent $project \

-resultParent $tx_port \
-configType generator \
-resultType generatorPortResults]
set rx_resinfo [stc::subscribe -parent $project \
-resultParent $rx_port \
-configType analyzer \
-resultType analyzerPortResults]

The following figure shows the objects in the test configuration that are identified by the
subscriptions above. Based on the subscription, Spirent TestCenter will create the objects
that it needs to store result values (in this example, the ResultDataSet,
GeneratorPortResults, and AnalyzerPortResults objects).

92 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Results

-parent $project Project -resultParent $rx_port

-resultParent $tx_port
Port (tx_port) Port (rx_port)

Generator ResultDataSet Analyzer ResultDataSet

-configType generator

GeneratorPortResults AnalyzerPortResults -configType analyzer

-resultType generatorPortResults -resultType analyzerPortResults

In the figure, the automatically created objects are shown in red. Note that when you call
the subscribe function, some attributes require handle values (-parent, -resultParent)
and some attributes require object type values (-configType, -resultType). The subscribe
function returns a handle to a ResultDataSet object. Spirent TestCenter uses this object to
manage the result objects. You use the ResultDataSet object to obtain handles for the
individual result objects and to managed Paged Results.

NOTE: Analyzer filters produce results that are stored in FilteredStreamResults

objects. Any time you use an analyzer filter, regardless of the port on which it is
configured, Spirent TestCenter disables the TxStreamResults and
RxStreamSummaryResults objects on all ports. (For information about using filters, see
Analyzer Filters.)
(For more information, including additional parameters, see the description of the
subscribe function.)

Result Files
Result files contain comma-separated values (.csv file extension). These files are suitable
for display using a spreadsheet progam, for example, Microsoft Excel, OpenOffice Calc,
or Gnumeric. You must use the subscribe function to direct Spirent TestCenter
Automation to produce result files. (You can also use Spirent TestCenter to create a results
database. For information about creating and using a results database, see End-of-Test
Results Database.)
When you call the subscribe function, you identify the type of results to be collected, and
you specify the set of objects for which the results will be collected. By default, Spirent
TestCenter Automation does not produce result output. To produce an output file you must
specify the -filenamePrefix parameter. The following example shows a subscription for
port results collected from the analyzer. The results will be written to the file
APR_results.csv in the current default directory.
set rx_resinfo [stc::subscribe -parent $project \
-resultParent $rx_port \
-configType analyzer \

Spirent TestCenter Automation Programmer’s Guide | 93

Spirent TestCenter Results

-filenamePrefix “APR_results” \
-resultType analyzerPortResults]

The subscription above will generate a file containing results data for all of the attributes
defined for the AnalyzerPortResults object. To reduce the amount of data written to the
file, use the -viewAttributeList parameter to supply one or more attribute names. The
names must identify attributes defined for the -resultType object. Spirent TestCenter will
write out data for only the specified attributes. For example:
set rx_resinfo [stc::subscribe \
-parent $project \
-resultParent $rx_port \
-configType analyzer \
-filenamePrefix “APR_results” \
-resultType analyzerPortResults \
-viewAttributeList “Ipv4FrameCount TcpFrameCount UdpFrameCount” ]

For more information, see the description of the subscribe function.

Using the API to Retrieve Test Results

When you run a Spirent TestCenter test, Spirent TestCenter Automation maintains a copy
of the test results by setting the value of result attributes defined for the objects in the test
object hierarchy.
You can retrieve test results at any time during test execution, depending on when a
particular type of test result is available.
• Spirent TestCenter Automation continuously updates result attributes that reflect the
value of real-time counters or any discrete test measurement taken during test
execution. You can retrieve these values at any time. Spirent TestCenter updates result
attributes based on polling interval specified for the subscription (the -interval
parameter for the subscribe function).
• For certain types of operations, results data is available after specific commands are
executed.
• Spirent TestCenter Automation derives certain test results as statistics that reflect data
collection over time. This type of test result is available at the end of the test run.
To retrieve test result values, use the get function. The following example shows a call to
the get function that retrieves the value of the total frame count for the analyzer.
set frame_count [stc::get $analyzerResults -totalFrameCount]

NOTES: Inconsistent results and subscription limits.

• You can retrieve test results during test execution, and you can modify the
attributes of your test configuration in response to those results. When you
modify attributes during a test, you must call the apply function to activate
the changes. When you call the apply function, Spirent TestCenter
Automation sends the modifications to the chassis. The executing test is

94 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Results

modified at that point, and the result values will reflect the changes in real
time. Depending on your configuration, the type of test you are running, and
the type of modifications to the configuration, there may be a short period of
time during which your results are inconsistent.
• The subscribe function operates in a synchronous fashion. When it returns,
the test configuration in memory has been updated with a current copy of the
subscribed data. Spirent TestCenter updates the subscription based on the
value of the -interval parameter. Approximately 2000 data elements can be
subscribed before the system starts to discard data due to throughput
limitations.
The following sections provide information about accessing results data:
• The ResultsDataSet Object
• Result Report Objects (ARP/ND and Ping)
• Results From Specific Commands

The ResultsDataSet Object

When you create a subscription, the subscribe function returns a handle to a

ResultsDataSet object. Spirent TestCenter creates ResultsDataSet objects automatically,
and uses them to manage the set of result objects that it creates for a test. You can use a
ResultsDataSet object to access results objects and to manage paged result retrieval (see
Paged Results).
When Spirent TestCenter creates result objects, it also establishes relations between the
result objects and ResultDataSet objects. The following code fragment shows an example
of how to retrieve handles for the result objects associated with a subscription identified
by a ResultDataSet object ($ResultDataSet).
set resultobjlist [stc::get $ResultDataSet -resultChild]
foreach object $resultobjlist {
set mystrmblkhndl [stc::get $object -parent]
}

The call to the get function specifies the resultChild relation; the function returns a list of
handles identifying target result objects in that relation. Then, using the handle for a result
object, the example retrieves the StreamBlock parent of the result object.

Result Report Objects (ARP/ND and Ping)

ARP/ND (Address Resolution Protocol/Neighbor Discovery) and ping operations produce

results that are stored in result report objects.
• Most of the ARP/ND commands (ArpNdStart, ArpNdStartOnAllDevices,
ArpNdStartOnAllStreamBlocks, ArpNdStop, and ArpNdVerifyResolved)
produce results that are stored in the ArpNdReport object.

Spirent TestCenter Automation Programmer’s Guide | 95

Spirent TestCenter Results

• The ping commands (PingStart and PingStop) produce results that are stored in the
PingReport object.
The following code fragment shows an example of how to use an ARP command
(ArpNdStart) and retrieve the results from the ArpNdReport object. The code fragment:
• Calls the perform function, invoking the ArpNdStart command. The command
invocation identifies the ports to be used.
• Waits five seconds for the ARP communication to complete.
• Retrieves handles to the ArpNdReport result object associated with the receiving
port. The call to the get function returns the children of the port object, and specifies
the ArpNdReport object type as a filter for the -Children relation side name
(-Children-ArpNdReport) to obtain only the ArpNdReport object.
• Displays the ARP/ND results data.

# Start ArpNd
stc::perform ArpNdStart -HandleList [list $hPortRx $hPortTx]

# Wait 5 seconds for Arps to complete.

after 5000

# Display ArpNdReport.
set hArpNdReport [stc::get $hPortRx -Children-ArpNdReport]
puts "\nArpNdReport information"
foreach {szAttr szName} [stc::get $hArpNdReport] {
puts \t$szAttr\t$szName
}

Results From Specific Commands

There are a limited set of commands that produce results directly upon execution. These
commands can be divided into the following categories:
• ARP/ND
• DHCP
• PPPox
• L2tp
The following table shows the categories, the associated commands, and the
corresponding result objects that are updated.

Category Command Result Object

Arp ArpNdUpdateArpCache ArpCache

96 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Results

Category Command Result Object

DHCP Dhcpv4SessionInfo DhcpIpv4SessionResults

Dhcpv6SessionInfo DhcpIpv6SessionResults

PPPoX PppoxSessionInfo PppoeSessionResults

PppoxSessionInfo PppoL2tpv2SessionResults

L2tp L2tpSessionInfo L2tpv2SessionResults

L2tpNodeInfo L2tpv2NodeResults

L2tpTunnelInfo L2tpv2TunnelResults

For example, to retrieve the ARP cache table for a set of ports, use the
ArpNdUpdateArpCache command. The following code fragment:
• Calls the perform function, invoking the ArpNdUpdateArpCache command. The
command invocation identifies the ports for which cache table data is desired.
• Retrieves handles to the ArpCache result objects associated with the ports. The call
to the get function returns the children of the port object, and specifies the ArpCache
object type as a filter for the -Children relation side name (-Children-ArpCache) to
obtain only the ArpCache object.
• Displays the ARP cache table data.

stc::perform ArpNdUpdateArpCache -HandleList [list $hPortTx $hPortRx]

set hTxArpCacheResults [stc::get $hPortTx -Children-ArpCache]

set hRxArpCacheResults [stc::get $hPortRx -Children-ArpCache]

puts "\nArp cache table information"

puts "\tTx arp cache table [stc::get $hTxArpCacheResults -ArpCacheData]"
puts "\tRx arp cache table [stc::get $hRxArpCacheResults -ArpCacheData]"

Paged Results
For certain result types, Spirent TestCenter Automation provides a mechanism to divide
large amounts of results data into “pages”. You can use this mechanism to retrieve the
results one page at a time.
When you create a subscription, the subscribe function returns a handle to a
ResultsDataSet object. Use the ResultsDataSet object to manage paged results. You can
use the paged results support for the following results object types (specified with the
resultType parameter in the call to the subscribe function).

Spirent TestCenter Automation Programmer’s Guide | 97

Spirent TestCenter Results

AnalyzerPortResults TxPortPairResults
DiffServResults RxPortPairResults
FilteredStreamResults TxStreamBlockResults
GeneratorPortResults RxStreamBlockResults
PortAvgLatencyResults TxStreamSummaryResults
TxCpuPortResults RxStreamSummaryResults
RxCpuPortResults TxTrafficGroupResults
RxTrafficGroupResults

To define the amount of data in a page, and to identify the data to be retrieved, use the
following attributes (defined for the ResultsDataSet object).
• The RecordsPerPage attribute defines the amount of data in a page. A record
corresponds to the data associated with one result object.
• The PageNumber attribute identifies the data to be retrieved. To retrieve all of the
data produced by a subscription, set the PageNumber attribute to one, and increment
the value until it reaches the TotalPageCount value.
• The TotalPageCount attribute defines the total number of pages. (This is a read-only
attribute determined by the RecordsPerPage value.)
The following sections describe an example script that uses the paged result mechanism.
• Initialization
• Test Configuration
• Subscription
• Traffic Generation
• Retrieving Results
• Cleanup

98 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Results

Initialization
Every Spirent TestCenter Automation Tcl script must load the Spirent TestCenter package
before it can use the API. The following code fragment loads the package, and it also
defines variables that will be used later in the script.

package require SpirentTestCenter

# Equipment variables
set chassisAddr 10.100.20.5
set portCount 2
set txSlot
set txPort
set rxSlot
set rxPort 2

puts "Streams script begins"

# Emulation Variables
set txIpAddr "10.1.1.1"
set rxIpAddr "20.200.2.2"

set rxMacAddr "22.22.22.22.22.22"

Test Configuration
The example uses two ports on a single Spirent TestCenter chassis – one port for
transmitting traffic, one port for receiving traffic. This test generates Ethernet traffic with
a range of addresses.
The script creates the following objects:
• The Project object is the root of the test configuration object hierarchy.
• The Port objects represent physical ports on the Spirent TestCenter chassis. Port
objects are children of the Project object.
• The StreamBlock object defines the traffic for the test. The StreamBlock object is a
child of the first Port object.
• The EthernetII object defines the source and destination MAC addresses.
• The RangeModifier object specifies a range of addresses for the traffic stream.

Spirent TestCenter Automation Programmer’s Guide | 99

Spirent TestCenter Results

The following figure shows the test configuration object hierarchy. In the figure, the
objects that Spirent TestCenter creates automatically are shown in red. The script uses the
Generator objects on the transmitting port, and the Analyzer objects on the receiving port.
Spirent TestCenter creates result objects based on the subscriptions.

EthernetII

StreamBlock RangeModifier

RxStreamSummaryResults
Port (Tx)

Generator GeneratorConfig

AnalyzerConfig
Project
Port (Rx) Analyzer
AnalyzerPortResults

ResultsDataSet (resultType AnalyzerPortResults)

ResultsDataSet (resultType RxStreamSummaryResults)

The figure shows three object types associated with results data:
• ResultDataSet – This example uses two subscriptions, and thus, two ResultDataSet
objects. Of the two subscriptions, only the ResultsDataSet object for the
RxSTreamSummaryResult subscription can be used for paged retrieval.
• RxStreamSummaryResults – For this subscription, Spirent TestCenter collects
stream summary results for the receiving port; the script will use the paged result
mechanism for these results.
• AnalyzerPortResults – Using this subscription, the script will retrieve frame length
and count data.
The following sections describe different elements of the test configuration for the
example script:
• Project and Port Objects
• Traffic Configuration
• Generator/Analyzer Configuration

Project and Port Objects

The following code fragment creates the Project and Port objects for the test. After the
script creates the Port objects, it executes the attachPorts command to connect to the
chassis, then reserve and map the ports. Once the ports are attached, the script applies the

100 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Results

configuration. This code fragment also shows a Tcl catch statement, which begins a block
that encloses the rest of the script.

# Configuration begins

if {[catch {
# Create the root project object
set proj [stc::create project]

# Create ports
puts "Create ports"
set txPortHandle [stc::create port -under $proj \
-location //$chassisAddr/$txSlot/$txPort \
-useDefaultHost False ]
set rxPortHandle [stc::create port -under $proj \
-location //$chassisAddr/$rxSlot/$rxPort \
-useDefaultHost False ]

# Connect, reserve, and map

stc::perform attachPorts -portList "$txport $rxport" \
-autoConnect TRUE

puts "Apply configuration"

stc:apply

Traffic Configuration

In preparation for generating traffic, the script stops the generator and analyzer, so that the
test will begin in a known, initialized state.

set generator [stc::get $txPortHandle -children-Generator]

puts "Stopping Generator -current state [stc::get $generator -state]"
stc::perform GeneratorStop -GeneratorList $generator
set analyzer [stc::get $rxPortHandle -children-Analyzer]
puts "Stopping Analyzer -current state [stc::get $analyzer -state]"
stc::perform AnalyzerStop -AnalyzerList $analyzer

The paged results script uses the following objects to configure traffic:
• The StreamBlock object defines the general parameters for test traffic. The
StreamBlock object is a child of the first Port object (the transmitting port).
• The EthernetII object provides the source and destination MAC addresses.
• The script uses a RangeModifier object to generate a range of destination addresses
in the traffic stream.

Spirent TestCenter Automation Programmer’s Guide | 101

Spirent TestCenter Results

• The RangeModifier object uses the OffsetReference attribute to identify the

value that will change. In this example, the OffsetReference attribute identifies
the destination MAC attribute of the EthernetII object. The reference uses a path
notation that starts with the name value of the EthernetII object, followed by the
attribute name (sb1_eth.dstMac).
• The DataType attribute specifies a MAC address format, which the Data, Mask
and StepValue attributes must also use.
After creating the traffic objects, the script executes the StreamBlockUpdate command to
complete the stream configuration.

# Add in the stream blocks

puts "Configuring stream blocks"
set streamBlock(1) [stc::create streamBlock \
-under $txPortHandle \
-insertSig true \
-frameConfig "" \
-frameLengthMode RANDOM \
-maxFrameLength 1200 ]

# Code the length in the destination MAC for easy viewing

puts "Adding headers"
stc::create ethernet:EthernetII \
-under $streamBlock(1) \
-name sb1_eth \
-srcMac 00:00:20:00:00:00 \
-dstMac 00:00:00:00:00:40

puts "Creating Modifier on Stream Block"

set RangeModifier(1) [stc::create RangeModifier \
-under $streamBlock(1) \
-ModifierMode INCR \
-Mask "00:00:FF:FF:FF:FF" \
-StepValue "00:00:00:00:00:01" \
-RecycleCount 32767 \
-RepeatCount 0 \
-Data "00:00:10:10:10:01" \
-DataType NATIVE \
-EnableStream true \
-Offset 0 \
-OffsetReference "sb1_eth.dstMac" ]

stc::perform StreamBlockUpdate -streamBlock "$streamBlock(1)"

102 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Results

Generator/Analyzer Configuration

The following code fragment configures traffic generation.

#
# Configure generator
#
puts "Configuring Generator"
set generatorConfig [stc::get $generator -children-GeneratorConfig]

stc::config $generatorConfig \
-DurationMode BURSTS \
-BurstSize 1 \
-Duration 32767 \
-LoadMode FIXED \
-FixedLoad 100 \
-LoadUnit PERCENT_LINE_RATE \
-SchedulingMode RATE_BASED

#
# Analyzer Configuration
#
puts "Configuring Analyzer"
set analyzerConfig [stc::get $analyzer -children-AnalyzerConfig]

Subscription
The paged result example establishes two subscriptions:
• AnalyzerPortResults (non-paged) – The script will use this subscription to obtain
frame length and frame count data.
• RxStreamSummaryResults (paged) – The script will use the ResultDataSet object
associated with the stream summary results subscription to manage the paged result
retrieval. This subscription also specifies output to a file.

Spirent TestCenter Automation Programmer’s Guide | 103

Spirent TestCenter Results

The following code fragment establishes the subscriptions and applies the configuration.

#
# Subscribe to analyzer results
#
puts "Subscribe to results"
stc::subscribe -parent [stc::get system1 -children-Project] \
-resultParent [stc::get system1 -children-Project] \
-configType analyzer \
-resultType AnalyzerPortResults -interval 1

set rdsRxStreamSum \
[ stc::subscribe -parent [lindex [stc::get system1 -children-Project] 0] \
-resultParent [stc::get system1 -children-Project] \
-configType streamblock \
-resultType rxstreamsummaryresults \
-interval 1 \
-filenamePrefix "rxstreamsummaryresults-5228" ]

puts "Apply configuration"

stc::apply

Traffic Generation
To generate traffic, the script:
• Starts the Analyzer on the receiving port.
• Waits for two seconds.
• Starts the Generator on the transmitting port.
• Waits for five seconds.
• Stops the Analyzer.

104 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Results

# Start things running

puts "Start Analyzer"
stc::perform AnalyzerStart -AnalyzerList $analyzer
puts "Current analyzer state [stc::get $analyzer -state]"
stc::sleep 2
puts "Start Generator"
stc::perform GeneratorStart -GeneratorList $generator
puts "Current generator state [stc::get $generator -state]"
stc::sleep 5
puts "Current analyzer state [stc::get $analyzer -state]"
puts "Current generator state [stc::get $generator -state]"
puts "Stop Analyzer"
stc::perform AnalyzerStop -AnalyzerList $analyzer

# Give the analyzer time to stop

stc::sleep 1

Retrieving Results
In the code fragment on page 107, the script first retrieves results based on the
AnalyzerPortResults subscription. The script:
• Retrieves the handle to the AnalyzerPortResults object.
• Retrieves frame length and counts defined for the AnalyzerPortResults object
(JumboFrameCount, SigFrameCount, UndersizeFrameCount, OversizeFrameCount,
MaxFrameLength, TotalFrameCount).
After retrieving the frame data, the script uses the paged mechanism to retrieve data from
the RxStreamSummaryResults subscription. The script uses the default page size (100
records per page). The script:
• Retrieves the total page count
• Loops through the paged data:
• Sets the page number in the ResultsDataSet object (the subscribe function
returns the handle to the ResultsDataSet object).
• Applies the updated configuration.
• Retrieves the results for the page.
• Loops through the records for the retrieved page and display sthe results for each
record (object).
• Increments the page number.
• Retrieves the total page count (the total may have changed if results collection
was not complete when loop started).

Spirent TestCenter Automation Programmer’s Guide | 105

Spirent TestCenter Results

set analyzerResults [ stc::get $analyzer -children-AnalyzerPortResults ]

puts "Frames Counts"
puts -nonewline "Jumbo([stc::get $analyzerResults -JumboFrameCount]) \
Sig([stc::get $analyzerResults -sigFrameCount]) "
puts -nonewline "Under([stc::get $analyzerResults -UndersizeFrameCount]) \
Over([stc::get $analyzerResults -oversizeFrameCount]) "
puts "Max Len([stc::get $analyzerResults -MaxFrameLength]) \
Total([stc::get $analyzerResults -totalFrameCount])"

set pageNumber 1
puts "[stc::get $rdsRxStreamSum -totalPageCount]"
set totalPageCount [stc::get $rdsRxStreamSum -totalPageCount]
while { $pageNumber < $totalPageCount } {
puts "Set page $pageNumber: [time [ stc::config $rdsRxStreamSum \
-pageNumber $pageNumber ] 1 ]"
puts "Update results: [time [ array set res [ stc::apply ] ] 1 ]"

# Display RxStreamSummaryResults Children of $streamBlock(1) here

set resultObjects [stc::get $streamBlock(1) -children-RxStreamSummaryResults]
foreach summaryResult {$resultObjects} {
puts "results for $summaryResult: [stc::get $summaryResult]"
}

incr pageNumber
set totalPageCount [stc::get $rdsRxStreamSum -totalPageCount]
}

106 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Results

Cleanup
After stopping the generators and analyzers, the script:
• Releases the reserved ports. The script uses the detachPorts command to release the
ports.
• Disconnects from the chassis.
• Deletes the Project object to delete the test configuration.
The following code fragment shows an example of the function calls that you use to
perform termination.

### Release/Disconnect
puts "Releasing $chassisAddr/$txSlot/$txPort and $chassisAddr/$rxSlot/$rxPort"
stc::release "$chassisAddr/$txSlot/$txPort $chassisAddr/$rxSlot/$rxPort"

# Disconnect from a chassis

puts "Disconnecting"
stc::disconnect $chassisAddr

### Delete configuration

puts "Deleting project"
stc::delete $proj
} err] } {
puts "Error caught: $err"
}

End-of-Test Results Database

A subscription establishes a set of result attributes that define the test result data to be
collected. When you call the subscribe function, the –ResultType parameter specifies the
results data to be collected, and the –ResultParent parameter specifies the scope of data
collection within the test configuration. (For information about using the subscribe
function, see Subscriptions.)
During the test, Spirent TestCenter collects results according to the subscription result
object types. After a test has completed, you can write the end-of-test results to an SQLlite
database. Once you have created the database, you can use Spirent TestCenter Automation
to access the database. You can also use the Results Reporter to view the contents of the
results database.
The following sections provide information about:
• Creating a Results Database
• Retrieving Results from the Database
• Results Reporter

Spirent TestCenter Automation Programmer’s Guide | 107

Spirent TestCenter Results

Creating a Results Database

There are two commands that you can use to create a results database:
• The SaveResult Command
• The EotResultsWriteIteration Command

The SaveResult Command

To create a results database, use the SaveResult command. The following example shows
a call to SaveResult. The command creates a database named “analyzer_filters.db” that
contains results for the entire test configuration.

stc::perform SaveResult -databaseConnectionString "analyzer_filters.db"

The EotResultsWriteIteration Command

You can use the EotResultsWriteIteration command to write results for the current
configuration at the end of a test iteration. For example, you can include a call to this
function at the end of a sequencer loop. The following code fragment creates an
EOTResultsWriteIterationCommand object to write out the results associated with the
specified stream block list.

set EOTResultsWriteIterationCommand [stc::create "EOTResultsWriteIterationCommand" \

-under "System1" \
-Name "EOTResultsWriteIterationCommand" \
-StreamBlockList $StreamBlockList \
-EnableDetailedResultsCollection "TRUE"]

Retrieving Results from the Database

To retrieve results from a results database, use the QueryResult command. The command
operates on views of the database that correspond to views presented by the Results
Reporter.
When you invoke the QueryResult command, you specify:
• The results database (the DatabaseConnectionString attribute).
• The database node for the query (the ResultType attribute). A node is a collection of
results. The ResultType specification is a path name extending from the root of the
database to a particular node. (The Results Reporter displays the hierarchical
organization of nodes.) By default (an empty string), QueryResult returns results for
all nodes.
The ResultType specification consists of names in the path separated by forward
slashes (/). The path names are case-sensitive and cannot contain spaces.

108 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Results

• The result attribute values (corresponding to columns in the database) to be returned

(the AttributeList attribute). By default (an empty string), QueryResult returns all
attributes.
The AttributeList specification consists of attribute names (column names) separated
by spaces. Individual names within the list are case-sensitive and cannot contain
spaces.
• The count of values to be returned (the Count attribute). The count corresponds to
rows in the database. By default (an empty string), QueryResult returns all rows,
starting at the first row for an attribute (column). You can specify a different starting
point by using the Offset attribute.
• The first value (row) to be returned (the Offset attribute). Use this with the Count
attribute to retrieve a subset of rows.
• A filter to be applied to the returned values (the Filter attribute). You can specify an
expression using the following comparison operators to reduce the number of values
returned.

== (equals)
!= (does not equal)
> (greater than)
>= (greater than or equal to)
< (less than)
<= (less than or equal to)

For example, the filter expression "TotalTxFrameCount > 50" returns the
TotalTxFrameCount values that are greater than 50. By default, QueryResult
returns all values.
The following example shows a call to the perform function to execute the QueryResult
command.

stc::perform QueryResult \
-databaseConnectionString "analyzer_filters.db" \
-attributeList "PortName TotalTxFrameCount TotalRxFrameCount" \
-resultType "SavedResult/PortTraffic/BasicTrafficCounters/BasicCounters"

This call specifies three result attributes (PortName, TotalTxFrameCount, and

TotalRxFrameCount) that are collectively represented by the BasicCounters node.
Spirent TestCenter returns the requested values, formatted with braces to indicate rows of
data. For example, the previous call to QueryResult might return results like the
following, showing total transmitted and received frame counts for two ports on the
Spirent TestCenter chassis:
{{{Port //7/3} 100 0} {{Port //7/4} 0 100}

Spirent TestCenter Automation Programmer’s Guide | 109

Spirent TestCenter Results

Results Reporter
The Results Reporter is a tool with a Graphical User Interface (GUI) and a limited
command line interface. You can use the Results Reporter to do the following:
• View the Contents of a Results Database
• Using the Results Reporter to View a Test Configuration
• Using the Results Reporter to Produce Reports

View the Contents of a Results Database

To invoke the Results Reporter:

• If you are running Spirent TestCenter on Windows, the installation creates an icon on
your desktop for the Results Reporter. You can use the icon to invoke the Results
Reporter, or you can use the Windows batch file STCResultsReporter.bat, located in
the following directory:

C:\Program Files\Spirent communications\Spirent TestCenter\Spirent

TestCenter Application/Results Reporter

• If you are running Spirent TestCenter on a Unix system (Linux or Solaris), you can
invoke the Results Reporter from a script.

# Set the directory where Results Reporter is installed

set rrPath "/Spirent_TestCenter_2.15/Spirent_TestCenter_Application_Linux/
results_reporter"
# Provide the full path to the database
set database "/home/tests/results.db"
puts "Launching RR from $rrPath..."
exec sh $rrPath/STCResultsReporter.sh -o results.db

The actual path to the Results Reporter depends on where you have installed Spirent
TestCenter; the actual path to the database is the location that you used when you saved
the configuration results. Spirent Communications provides the shell file
STCResultsReporter.sh to run the Results Reporter.

Using the Results Reporter to View a Test Configuration

To use the Results Reporter to view a test configuration, you must run Spirent TestCenter
as a server.
• Add the following lines to the file stcbll.ini:

[msg]
serverPort=5009
serverAddress=localhost:5009

110 | Spirent TestCenter Automation Programmer’s Guide

 Spirent TestCenter Results

The stcbll.ini file is located in the following directory:

Spirent communications\Spirent TestCenter\Spirent TestCenter Application
• Run the server using this short Tcl script:
puts "Starting server..."
set env(STC_AS_SERVER) true
package require SpirentTestCenter

• Use a second Tcl script to connect to the server and display the configuration in the
Results Reporter: (The following example is based on a Linux installation.)

package require SpirentTestCenter

puts "Connected to server. stscytem1 children: [stc::get system1 -children]"
# Change the system's name
stc::config system1 -name "Test Name"

# Set the directory where Results Reporter is installed

set rrPath "/Spirent_TestCenter_2.15/Spirent_TestCenter_Application_Linux/
results_reporter"
puts "Launching Results Reporter from $rrPath..."
exec sh $rrPath/STCResultsReporter.sh -a localhost:5009 -v system1

Using the Results Reporter to Produce Reports

The Results Reporter defines a limited command line interface that you can use to produce
reports using data from the result database. To use the command line interface, execute
one of the following files:
• On Windows:
ResultsReporterCLI.bat
• On Unix:
ResultsReporterCLI.sh
For example (on Unix):
./ResultsReporterCLI.sh -o MyResults.db -f pdf -d MyResults.pdf -t
templates/CustomStats.rtp

This example generates PDF from your database file "MyResults.db", creating the file
MyResults.pdf using the template CustomStats.rtp. Templates are located in the following
directory:
Spirent TestCenter Application\Templates\System\Result Views

The Results Reporter CLI supports the following options:

Spirent TestCenter Automation Programmer’s Guide | 111

Spirent TestCenter Results

Option Description

-d file The output destination path for the

--dest file resulting file.

-f pdf|html|csv|jpeg The output format.

--format pdf|html|csv|jpeg (Note that JPEG output is currently
limited to the first page of the
template.)

-h Displays option help.

--help

-o file Open a result database at the given

--open file path.

-t file Specifies a template to be applied to

--template file the database.

112 | Spirent TestCenter Automation Programmer’s Guide

 Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

The Packet Generator and Analyzer (PGA) base package supports tests that generate and
analyze traffic using combinations of the following protocols:
• The Ethernet protocol
• The Internet Protocol (IP)
• The Transmission Control Protocol (TCP)
• The User Datagram Protocol (UDP)
The PGA package also supports the definition of VLAN sub-interfaces for Ethernet ports.
The following sections provide an overview of the protocols that you use for traffic
generation and analysis and a short Tcl example.
• PGA Protocols
• Using Spirent TestCenter Automation for PGA Tests
The following sections describe the elements of traffic generation and test analysis in
more detail:
• Packet Generation
• Test Analysis

PGA Protocols
Ethernet Protocol The Ethernet Protocol is a data link protocol for local area networks (LANs). Ethernet
communication is based on Media Access Control (MAC) addresses. An Ethernet frame
uses the MAC addresses encoded in the network adapter cards for devices attached to the
Ethernet network segment. In the Spirent TestCenter environment, you use Spirent
TestCenter software running on a Spirent TestCenter chassis to simulate large Ethernet-
based networks.

Internet Protocol The Internet Protocol supports the transmission of internet datagrams from a source to a
(IP) destination. IP supports two basic functions: addressing and fragmentation.
• Addressing: IP uses fixed-length addresses to identify both source and destination
hosts. IPv4 uses 32-bit addresses, generally represented in dotted decimal notation
(for example, 10.10.100.1). IPv6 use 128-bit addresses, normally written as eight
groups of up to four hexadecimal digits, separated by colons (for example,
1001:0ac8:11a1:02e1:2244:3a2e:8260:6443).
• Fragmentation: IP specifies a method for dividing large packets into smaller packets
at any point on a route between the source and destination. When transmitted data is
fragmented, the IP header fields provide the information that is required for the
destination host to reassemble the original transmission.

Spirent TestCenter Automation Programmer’s Guide | 113

Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

IP is limited in scope; it does not provide any transport services. IP is used with either the
Transmission Control Protocol (TCP) or the User Datagram Protocol (UDP) as a transport
protocol.

Transmission TCP provides reliable, port-based transmission of data in an IP environment. TCP

Control Protocol involves a handshake mechanism for estabishing a connection, and co-operative
(TCP) communication between peers once the connection has been established. The co-operative
nature of the communication provides the data transfer, reliability, flow control, and
multiplexing features of the protocol.

User Datagram UDP provides port-based, connectionless transmission of data. Unlike the TCP, UDP adds
Protocol (UDP) no reliability or flow-control functions to IP. Because of UDP's simplicity, UDP headers
contain fewer bytes and consume less network overhead than TCP.

Using Spirent TestCenter Automation for PGA Tests

With the Packet Generator and Analyzer package, you can generate test traffic containing
packets with Ethernet, IPv4, IPv6, TCP, and UDP headers. When you use this package to
generate traffic, you create a test configuration that describes the headers for the protocols
that you want to use, then you start the test (or start the traffic). Based on your test
configuration, Spirent TestCenter automatically handles all of the required protocol
negotiation and then starts generating traffic. In addition to providing you the means of
creating test configurations, Spirent TestCenter also provides you with various
mechanisms that support test analysis.
The following sections describe a simple Tcl script that generates traffic with Ethernet and
IPv4 headers. This example uses a back-to-back configuration consisting of two ports on a
Spirent TestCenter module – one for generating traffic and one for receiving traffic.
• Initialization
• Object Hierarchy
• Traffic Configuration
• Generator Configuration
• Subscription
• Traffic Generation
• Retrieving Results
• Test Completion

Initialization
Every Spirent TestCenter Automation Tcl script must load the Spirent TestCenter package
before it can use the API. The following code fragment:
• Loads the Spirent TestCenter package.

114 | Spirent TestCenter Automation Programmer’s Guide

 Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

• Displays the Spirent TestCenter version number. The script uses the pre-defined name
“system1” to obtain the version information.
• Creates variables for chassis, slot, and port values. The script will use these variables
to set the port location.
Note that the entire script is contained within a Tcl catch block.

if {[catch {
package require SpirentTestCenter

# Retrieve and display the current API version.

puts "SpirentTestCenter version:\t[stc::get system1 -Version]"

# Physical topology
set szChassisIp 10.100.33.30
set iTxSlot 11
set iTxPort 9
set iRxSlot 11
set iRxPort 10

Object Hierarchy
The following figure shows the test configuration object hierarchy for the example script.
The example script uses two ports on a Spirent TestCenter chassis. The ports use Ethernet
copper connections to a DUT running at autonegotiated speeds.
The generator and analyzer objects (along with the corresponding configuration and result
objects) are shown in red, indicating that Spirent TestCenter creates these objects
automatically.

EthernetCopper
ethernet:EthernetII
StreamBlock
Port ipv4:IPv4
(transmitting)
GeneratorConfig
Generator
Project GeneratorPortResults

EthernetCopper
Port
(receiving)
Analyzer AnalyzerPortResults

The example uses the following objects:

• The Project object is the root of the test configuration object hierarchy.

Spirent TestCenter Automation Programmer’s Guide | 115

Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

• The Port objects represent physical ports on the Spirent TestCenter chassis.
• The EthernetCopper objects define the type of port connection, including duplex,
line speed, and auto-negotiation settings.
• The StreamBlock, ethernet:EthernetII, and ipv4:IPv4 objects define the traffic
stream for the test. The StreamBlock is a child of a Port object; in this example, the
stream that it defines applies to the transmitting port. A StreamBlock can also be a
child of the Project object, in which case it defines streams for all ports.
The ethernet:EthernetII and ipv4:IPv4 objects are Protocol Data Unit (PDU)
objects. The PDU objects represent protocol headers for packets.
• The Generator object (shown in red to indicate that Spirent TestCenter creates this
object automatically) represents the traffic generator for the transmitting port.
• The GeneratorConfig object (shown in red to indicate that Spirent TestCenter creates
this object automatically) defines the parameters for traffic generation on the
transmitting port.
• The GeneratorPortResults object (shown in red to indicate that Spirent TestCenter
creates this object automatically) contains generator result data for the transmitting
port.
• The Analyzer object (shown in red to indicate that Spirent TestCenter creates this
object automatically) represents the Analyzer for the receiving port.
• The AnalyzerPortResults object (shown in red to indicate that Spirent TestCenter
creates this object automatically) contains analyzer result data for the receiving port.
The following code fragment creates the Project, Port, and EthernetCopper objects.
After the script creates the port configuration, it invokes the AttachPorts command.
AttachPorts accomplishes the following actions:
• Connect to the chassis (using the chassis IP address specified in the Port object
location attribute).
• Reserve the ports.
• Create the mapping between the physical ports on the chassis and their logical
representations in the test configuration.
You can perform these operations separately, by calling the connect function, and then
using the ReservePort and MapPort commands; however, the AttachPorts command is
more efficient.

116 | Spirent TestCenter Automation Programmer’s Guide

 Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

# Create the root project object

puts "Creating project ..."
set hProject [stc::create project]

# Create ports
puts "Creating ports ..."
set hTxPort [stc::create port -under $hProject \
-location //$szChassisIp/$iTxSlot/$iTxPort \
-useDefaultHost False ]
set hRxPort [stc::create port -under $hProject \
-location //$szChassisIp/$iRxSlot/$iRxPort \
-useDefaultHost False ]

# Configure physical interface.

set hTxPortPhy [stc::create EthernetCopper -under $hTxPort \
-LineSpeed SPEED_10M \
-Duplex HALF \
-AutoNegotiation FALSE]
set hRxPortPhy [stc::create EthernetCopper -under $hRxPort \
-LineSpeed SPEED_10M \
-Duplex HALF \
-AutoNegotiation FALSE ]

# Attach ports (connects to the chassis and maps the ports).

puts "Attaching Ports ..."
stc::perform attachPorts -portList [list $hTxPort $hRxPort] \
-autoConnect TRUE

Traffic Configuration
This example generates traffic from a single port. The following code fragment creates the
StreamBlock, EthernetII, and IPv4 objects to define the traffic stream.
• The script creates a StreamBlock object as a child of the transmitting Port object.
The script also clears the frame configuration because the script will create the PDU
objects explicitly.
• The EthernetII and IPv4 PDU objects are children of the StreamBlock objects.
Spirent TestCenter constructs packets using headers that correspond to the PDU
objects; the order of headers in the packets is the order in which the PDU objects were
created.

Spirent TestCenter Automation Programmer’s Guide | 117

Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

set hStreamblock [stc::create streamBlock -under $hTxPort \

-insertSig true \
-frameConfig "" \
-frameLengthMode FIXED \
-maxFrameLength 1200 \
-FixedFrameLength 256 \
-Load 10 \
-LoadUnit FRAMES_PER_SECOND]

# Add an EthernetII Protocol Data Unit (PDU) and an IPv4 PDU

puts "Adding headers"
stc::create ethernet:EthernetII -under $hStreamblock \
-srcMac 00:00:20:00:00:00 \
-dstMac 00:00:00:00:00:00

stc::create ipv4:IPv4 -under $hStreamblock \

-sourceAddr 30.0.0.11 \
-destAddr 30.1.0.12

puts "Applying configuration"

stc::apply

NOTES: PDU specification:

• The example code shows the specification of the EthernetII and Ipv4
objects as follows:

ethernet:EthernetII
ipv4:IPv4

When you use Protocol Data Unit (PDU) objects that are children of
StreamBlock objects, you must use the PDU library name prefix for the
object. Only use the PDU library prefix for StreamBlock children, not for
any other PDU objects. The Spirent TestCenter Automation Object Reference
shows the PDU library prefix for the PDU objects.
• When you specify a StreamBlock child, you must use the character case
shown (ethernet:EthernetII, for example).

Generator Configuration
Traffic generators are associated with ports; Spirent TestCenter creates Generator objects
automatically, as children of Port objects. To manage traffic generation, Spirent
TestCenter also creates GeneratorConfig and GeneratorPortResults objects as children
of Generator objects.

118 | Spirent TestCenter Automation Programmer’s Guide

 Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

To use a generator, you establish generator parameters by setting GeneratorConfig object

attributes. After the test completes, you obtain generator results by accessing the
GeneratorPortResults object.
The following code fragment:
• Retrieves handles for the Generator and Analyzer objects.
• Retrieves the handle for the GeneratorConfig object.
• Sets generator parameters. For this example, Spirent TestCenter will generate 100
frames in single-frame bursts.

# Retrieve the generator and analyzer objects.

set hTxGenerator [stc::get $hTxPort -children-Generator]
set hRxAnalyzer [stc::get $hRxPort -children-Analyzer]

# Configure generator.
puts "Configuring Generator on transmitting port"
set hTxGeneratorConfig [stc::get $hTxGenerator -children-GeneratorConfig]

stc::config $hTxGeneratorConfig -DurationMode BURSTS \

-BurstSize 1 \
-Duration 100 \
-LoadMode FIXED \
-FixedLoad 100 \
-LoadUnit PERCENT_LINE_RATE \
-SchedulingMode PORT_BASED

Note that you can set traffic parameters at both the port (GeneratorConfig) and stream
(StreamBlock) levels. The GeneratorConfig object SchedulingMode attribute setting
determines how Spirent TestCenter will use the traffic parameters.
• The scheduling mode PORT_BASED directs Spirent TestCenter to use port
parameters to generate traffic.
• The scheduling mode RATE_BASED directs Spirent TestCenter to use stream
parameters to generate traffic.
• The scheduling mode PRIORITY_BASED directs Spirent TestCenter to generate
traffic according to the setting of the StreamBlock object Priority attribute.
Set the scheduling mode before you configure the port or stream parameters.

Subscription
The following calls to the subscribe function establish subscriptions for
generatorPortResults and AnalyzerPortResults. For detailed information, see the
description of the subscribe function and the information about creating Subscriptions.

Spirent TestCenter Automation Programmer’s Guide | 119

Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

# Subscribe to realtime results.

puts "Subscribe to results"
stc::subscribe -Parent $hProject \
-ConfigType Analyzer \
-resulttype AnalyzerPortResults \
-filenameprefix AnalyzerPortResults

stc::subscribe -Parent $hProject \

-ConfigType Generator \
-resulttype GeneratorPortResults \
-filenameprefix GeneratorPortResults

# Apply configuration.
puts "Applying configuration"
stc::apply

Traffic Generation
The following code fragment starts the Analyzer and generates traffic for the test. The
generator is configured to transmit for a fixed period of time, so the script uses the
GeneratorWaitForStop command to suspend script execution before continuing. The
script also uses a Tcl “after” statement to suspend execution to allow the Analyzer time to
complete its tasks.

# puts "Start Analyzer"

# stc::perform AnalyzerStart -AnalyzerList $hRxAnalyzer

puts "Start Generator"

stc::perform GeneratorStart -GeneratorList $hTxGenerator

puts "Current analyzer state [stc::get $hRxAnalyzer -state]"

puts "Current generator state [stc::get $hTxGenerator -state]"

puts "Wait for generator to stop"

stc::perform GeneratorWaitForStop -GeneratorList $hTxGenerator
puts "Generator stopped"

puts "Wait 5 seconds for Analyzer..."

after 5000

Retrieving Results
The script uses the GeneratorPortResults and AnalyzerPortResults objects to obtain
transmitted and received frame counts. The following code fragment:

120 | Spirent TestCenter Automation Programmer’s Guide

 Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

• Retrieves the handle to the GeneratorPortResult object (child of the Generator

object).
• Retrieves the handle to the AnalyzerPortResult object (child of the Analyzer
object).
• Uses the retrieved handles to obtain frame count data.

# Display some statistics.

set hTxGeneratorResults [stc::get $hTxGenerator -children-GeneratorPortResults]
set hRxAnalyzerResults [stc::get $hRxAnalyzer -children-AnalyzerPortResults]

puts "Frame Counts (generated):"

puts "\tIpv4 frames: [stc::get $hTxGeneratorResults -generatorIpv4FrameCount]"
puts "\tSignature frames: [stc::get $hTxGeneratorResults -generatorSigFrameCount]"
puts "\tTotal: [stc::get $hTxGeneratorResults -generatorFrameCount]"

puts "Frame Count (transmitted): [stc::get $hTxGeneratorResults -totalFrameCount]"

puts "Frame Counts (received):"

puts "\tIpv4 frames: [stc::get $hRxAnalyzerResults -ipv4framecount]"
puts "\tSignature frames: [stc::get $hRxAnalyzerResults -sigFrameCount]"
puts "\tTotal frames: [stc::get $hRxAnalyzerResults -totalFrameCount]"

Test Completion
At the end of the test, the script releases the ports and disconnects from the chassis.

# Detach ports.
stc::perform detachPorts -portList [list $hTxPort $hRxPort]

# Delete configuration
puts "Deleting project"
stc::delete $hProject
} err] } {
puts "Error caught: $err"
}

Spirent TestCenter Automation Programmer’s Guide | 121

Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

Packet Generation
When you create a test configuration for traffic generation, you create one or more
StreamBlock objects, each with one or more PDU objects. When your test starts
generating traffic, Spirent TestCenter transmits packets containing protocol headers based
on the definitions of the PDU objects.
The following sections describe different aspects of packet generation:
• Starting Traffic Generators
• Packet Generation – Single Stream
• Packet Generation – Multiple Streams and Modifiers
• Using Multiple Modifiers
• Custom Headers

Starting Traffic Generators

Traffic generators are associated with ports; whenever you create a Port object, Spirent
TestCenter automatically creates a Generator object. To start traffic, use the
GeneratorStart command and specify one or more Generator handles:
set hGenerator [stc::get $hPortTx -children-Generator]
stc::perform GeneratorStart -GeneratorList $hGenerator
With a configuration that uses multiple generators, you can specify some control over how
Spirent TestCenter starts the generators referenced in a generator list. Use the
TrafficOptions object to specify the generator start characteristics. The TrafficOptions
object is a child of the Project object. Spirent TestCenter creates the TrafficOptions
object automatically when you create a Project object.
You can specify synchronous or asynchronous starting mode by setting the
-TrafficStartMode attribute. The modes are:
• SYNCHRONOUS - When you invoke GeneratorStart, Spirent TestCenter will start
all generators in the generator list at the same, after a short delay. Spirent TestCenter
uses the delay to syncronize the ports. Use the -TrafficStartInterval to set the delay.
• ASYNCHRONOUS - When you invoke GeneratorStart, Spirent TestCenter starts
all generators in the list immediately. In this case, the generators may not start at the
same time.
The following code fragment retrieves a handle to the TrafficOptions object and
establishes synchronous starting. Spirent TestCenter will start the generators after a delay
of 640 microseconds. (The TrafficStartInterval is specified in units of 64 microseconds.)
set tOpt [stc::get $project -children-TrafficOptions]
stc::config $tOpt -TrafficStartMode SYNCHRONOUS \
-TrafficStartInterval 10

122 | Spirent TestCenter Automation Programmer’s Guide

 Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

Packet Generation – Single Stream

When you create a StreamBlock with PDU objects, specifying source and destination for
the headers, Spirent TestCenter generates a single stream of packets, each with the same
source and destination values.
The figure below represents packet generation using a single source address and a single
destination address.

Spirent Ethernet header Ethernet header Ethernet header

TestCenter src: 01-01-01-01-01-01 src: 01-01-01-01-01-01 src: 01-01-01-01-01-01
Port dst: 01-01-01-01-01-03 dst: 01-01-01-01-01-03 dst: 01-01-01-01-01-03

In the traffic configuration represented above, the Ethernet header defines a single source
MAC address and a single destination MAC address. For that traffic stream, all of the
packets are sent to the same destination (and are identified as coming from a single
source).

Packet Generation – Multiple Streams and Modifiers

To use a single StreamBlock to generate multiple streams, create a modifer object as a
child of a StreamBlock. Spirent TestCenter uses modifiers to change field values in
protocol headers as it generates packets. For example, you can create a modifier that
increments an IPv4 address through a range of 100 destination addresses before restarting
the sequence.
The following sections provide information about using modifiers:
• Modifier Objects
• Modifier Example

Modifier Objects

A modifier object is a child of a StreamBlock object. A modifier identifies a protocol

header field by naming an attribute of a PDU object that is a child of the same
StreamBlock parent. Modifier objects use the -OffsetReference attribute to specify the
PDU object and attribute. The following figure shows the relationship between a
RangeModifier object and a PDU object:

Spirent TestCenter Automation Programmer’s Guide | 123

Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

EthernetII
-Name eth_hdr1
-dstMac
[...]
Project Port StreamBlock
RangeModifier
-OffsetReference eth_hdr1.dstMac
[...]

This RangeModifier object references the destination MAC field of the Ethernet header.
The -OffsetReference value (eth_hdr1.dstMac) uses the following dotted notation format:
PDU-object-name.attribute-name
The PDU-object-name portion of the reference is the value of the -Name attribute for the
PDU object. The attribute-name is the name of one of the attributes defined for the object.
The two names are separated by a dot.
Modifier objects also specify the parameters that Spirent TestCenter applies to the field
value when it generates packets. The parameters determine the set of values that will be
generated according to the type of modifier.
• The RangeModifier object defines a range of values that Spirent TestCenter uses to
modify a header field. When you use a RangeModifier, you specify a starting value,
a mask to indicate which bytes of the field are to be modified, a step value, and a limit
to the range. Range modifiers also use modifier modes to determine how the
generated values are applied (increment, decrement, or shuffle).
• The RandomModifier object uses a random set of values to modify a header field.
When you use a RandomModifer object, you specify a mask to indicate which bytes
of the the field are to be modified. Spirent TestCenter produces random field values
for the duration of traffic generation.
• The TableModifier object uses a fixed set of values to modify a header field. When
you use a TableModifier object, you specify a list of values that Spirent TestCenter
uses for the header field.
The following table provides an overview of the RangeModifier object used in the
Modifier Example. For more detail and information about the RandomModifier and
TableModifier objects, see the Spirent TestCenter Automation Object Reference.

124 | Spirent TestCenter Automation Programmer’s Guide

 Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

RangeModifier Description
Attributes

-OffsetReference Identifies the protocol header field to be modified.

-DataType The data type for the -Data, -StepValue, and -Mask attribute values.
Spirent TestCenter defines two types: NATIVE and BYTE.
NATIVE modifier values are expressed in formats to match the type
of the header field to be modified. For example, in NATIVE mode, the
-Data, -StepValue, and -Mask values that modify an IPv4 header
address must be specified in IPv4 address format (such as -StepValue
0.0.0.1). Spirent TestCenter validates the formate of NATIVE mode
values.
BYTE modifier values are expressed as hexidecimal values. BYTE
values do not require any delimiters. Spirent TestCenter does not
validate the format of BYTE mode values.

-Data The initial value for the field. Must be specified using a format that
corresponds to the data type (NATIVE or BYTE).

-StepValue The step value used for incrementing or decrementing the header field
value through the range. Must be specified using a format that
corresponds to the data type (NATIVE or BYTE).

-ModifierMode Indicates how values are to be modified. Range modifiers support

three modes: increment (INCR), decrement (DECR), and random
(SHUFFLE).

-Mask A mask indicating the bytes that will be affected. Must be specified
using a format that corresponds to the data type. The mask feature
only works with the RangeModifier when the -EnableStream
attribute is set to TRUE. The size of the mask value must match the
field to be modified, taking into account any size limitation imposed
by an offset location within the field (-Offset), if specified.

-RecycleCount The number of times the field value will change before starting again.

-Offset An offset value indicating a byte position within the field. (only used
with -DataType BYTE.) If you specify an offset, adjust the size of the
-Data and -Mask values accordingly so that they do not extend
beyond the header field.

-RepeatCount The number of times the value will be repeated.

Spirent TestCenter Automation Programmer’s Guide | 125

Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

RangeModifier Description
Attributes

-EnableStream Indicates whether to use software (stream blocks) or hardware

(Variable Field Definitions) to generate modified values. Software-
based streams support the use of unique signature fields. Hardware-
based streams support the generation of only one signature field value
for each stream block. In either case, set the StreamBlock attribute -
InsertSig to TRUE to generate signature fields. You can track packets
based on the signature field; for more information, see Tracking
Packets By Signature Field.

Modifier Example

The following figure shows the objects for a stream block with an Ethernet header and a
RangeModifier object that references the destination MAC address in the EthernetII
PDU object. The figure also shows the code fragment that creates these objects.
• The modifier specifies a range of 20 MAC addresses (-RecycleCount), starting with
the address 00:00:00:00:00:00 (-Data). The mask value indicates that the four least
significant bytes can change (-Mask 00:00:FF:FF:FF:FF).
• When Spirent TestCenter applies the modifier, it will use an increment of 1
(-ModifierMode, -StepValue) to increment the destination MAC address 20 times
before starting again with the intial value.
• The modifier is configured to use native mode (-DataType), so the -Data, -Mask, and
-StepValue values are specified in the format that the header field uses (in this
example, MAC address format).
• This example uses signature fields (StreamBlock attribute -InsertSig set to TRUE).
It also uses software stream generation (RangeModifier attribute -EnableStream set
to TRUE), so that Spirent TestCenter will generate a unique signature field value for
each stream generated from this stream block.

126 | Spirent TestCenter Automation Programmer’s Guide

 Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

EthernetII
-Name eth_hdr1
-dstMac
Project Port StreamBlock
RangeModifier
-OffsetReference eth_hdr1.dstMac

# Create a stream block.

set hStreamBlock [stc::create streamBlock -under $hPortTx \
-insertSig true \
-frameConfig "" \
-frameLengthMode FIXED \
-maxFrameLength 1200 \
-FixedFrameLength 128]

# Add an EthernetII Protocol Data Unit (PDU).

stc::create ethernet:EthernetII -under $streamBlock(1) \
-name eth_hdr1 \
-srcMac 00:00:20:00:00:00 \
-dstMac 00:00:00:00:00:40

# Create 20 trackable streams (each stream has a unique stream identifier).

puts "Creating Range Modifier on Stream Block"
set RangeModifier(1) [stc::create RangeModifier \
-under $streamBlock \
-ModifierMode INCR \
-Data "00:00:00:00:00:00" \
-Mask "00:00:FF:FF:FF:FF" \
-StepValue "00:00:00:00:00:01" \
-RecycleCount 20 \
-RepeatCount 0 \
-DataType NATIVE \
-EnableStream true \
-OffsetReference "eth_hdr1.dstMac" \
-Active true]

Using Multiple Modifiers

You can create multiple modifiers for a single StreamBlock. There are two ways to
combine modifiers:
• You can chain range modifiers and table modifiers together. When you chain
modifiers together, Spirent TestCenter applies the modifiers in sequence. Spirent
TestCenter generates packets for the extent specified by each modifier before using

Spirent TestCenter Automation Programmer’s Guide | 127

Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

the next modifier in the chain. To chain modifiers together, set the CarryChainTo
relation.
• You can stack modifiers. To stack modifiers, create multiple modifiers that reference
the same PDU field. For stacked modifiers, you must also specify -Mask values such
that the modifiers do not manipulate the same bits of the referenced field. (The -Mask
values cannot overlap.)
The following figure shows the objects and corresponding code fragment for a stream
block with Ethernet and IPv4 headers. There are three range modifiers to manipulate the
headers. After creating the objects, the modifiers are chained together. Spirent TestCenter
will use the modifiers in the chained sequence:
• Modifier 1 – Spirent TestCenter generates five packets, changing the destination
MAC address in the Ethernet header in each packet.
• Modifier 2 – Spirent TestCenter generates five packets, changing the destination
MAC address in the Ethernet header in each packet.
• Modifier 3 – Spirent TestCenter generates five packets, changing the protocol
specification in the IPv4 header in each packet.

128 | Spirent TestCenter Automation Programmer’s Guide

 Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

EthernetII
-Name sb1_ethI
-srcMac
-dstMac

Ipv4
-Name sb1_ip
-protocol

Project Port StreamBlock RangeModifier

-OffsetReference sb1_ethI.dstMac

RangeModifier
-OffsetReference sb1_ethI.srcMac

RangeModifier
-OffsetReference sb1_ip.protocol

# Create a stream block.

set hStreamBlock [stc::create streamBlock -under $hPortTx -insertSig true \
-frameConfig "" -frameLengthMode FIXED -maxFrameLength 1200 \
-FixedFrameLength 128]

# Add an EthernetII and IPv4 Protocol Data Units (PDUs)

stc::create ethernet:EthernetII -under $hStreamBlock -name sb1_eth \
-srcMac 00:00:20:00:00:00 -dstMac 00:00:00:00:00:40

stc::create ipv4:IPv4 -under $hStreamBlock -name sb1_ip \

-sourceAddr 10.0.0.2 -destAddr 192.168.1.1

# Use modifier to generate multiple streams.

puts "\nCreating Modifiers on Stream Block"
set hRangeModifer1 [stc::create RangeModifier -under $hStreamBlock \
-ModifierMode INCR -Mask "00FF" -StepValue "0001" -Data "0000" \
-RecycleCount 5 -RepeatCount 0 -DataType BYTE -EnableStream false \
-Offset 4 -OffsetReference "sb1_eth.dstMac"]

set hRangeModifer2 [stc::create RangeModifier -under $hStreamBlock \

-ModifierMode INCR -Mask "00FF" -StepValue "0001" -Data "0000" \
-RecycleCount 5 -RepeatCount 0 -DataType BYTE -EnableStream false \
-Offset 4 -OffsetReference "sb1_eth.srcMac"]

set hRangeModifer3 [stc::create RangeModifier -under $hStreamBlock \

-ModifierMode INCR -Mask "FF" -StepValue "01" -Data "00" \
-RecycleCount 5 -RepeatCount 0 -DataType BYTE -EnableStream false \
-Offset 0 -OffsetReference "sb1_ip.protocol"]

# Chain modifiers together.

stc::config $hRangeModifer1 -CarryChainTo $hRangeModifer2
stc::config $hRangeModifer2 -CarryChainTo $hRangeModifer3

Spirent TestCenter Automation Programmer’s Guide | 129

Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

Custom Headers
Spirent TestCenter Automation provides the Custom header object that you can use to
modify the contents of a packet payload. The Custom object has a single attribute
(-Pattern) which you use to specify a sequence of bytes in hexadecimal format. Spirent
TestCenter will insert the byte pattern into the packet at the location that corresponds to
the order of your PDU object creation sequence. Once you have created the Custom
object, you can create a modifer object that uses the Custom object -Name attribute value
and -Pattern reference (-OffsetReference custom-pdu-name.pattern) to identify the
payload for modification.

Test Analysis
Spirent TestCenter supports the following test analysis methods:
• Tracking Packets By Signature Field
• Analyzer Filters
• Histograms
• Capture

Tracking Packets By Signature Field

Spirent TestCenter gives you the capability of tracking streams by inserting signatures into
packets. When you use software-based streams (StreamBlock attribute
EnableStreamOnlyGeneration set to TRUE, or modifier attribute EnableStream set to
TRUE), Spirent TestCenter generates unique signature values for each stream generated
from a stream block. When you use hardware-based streams (StreamBlock attribute
EnableStreamOnlyGeneration set to False, or modifier attribute EnableStream set to
False), Spirent TestCenter generates a single signature value that it uses for all streams
generated from a stream block. Note that the stream block setting overrides the modifier
setting.
If you track streams by signature, the same test configuration will produce different stream
results according to the stream setting (software-based or hardware-based). For example,
the following code fragment:
• Establishes a subscription for RxStreamSummaryResults.
• Creates a stream block that will use signature frames.
• Creates Ethernet and IPv4 PDU objects.
• Creates a modifier that specifies software-based streams (-EnableStream TRUE) and
generates 100 different IPv4 destination addresses for the streams.

130 | Spirent TestCenter Automation Programmer’s Guide

 Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

set rds [ stc::subscribe -Parent $hProject \

-configType StreamBlock \
-resultType RxStreamSummaryResults \
-viewAttributeList [list FrameRate FrameCount] \
-filenameprefix RxStreamSummaryResults]
set hStreamBlockTx [stc::create streamBlock -under $hPortTx -insertSig true \
-frameConfig "" -frameLengthMode FIXED -maxFrameLength 1200 \
-FixedFrameLength 128]

stc::create ethernet:EthernetII -under $hStreamBlockTx -Name "ethhdr"

stc::create ipv4:IPv4 -under $hStreamBlockTx -Name "ipv4hdr"

# create a modifier
set rangemod [stc::create RangeModifier -under $hStreamBlockTx \
-enablestream TRUE \
-offsetreference ipv4hdr.destAddr \
-data 0.0.0.0 \
-stepvalue 0.0.0.1 \
-mask 0.0.0.255 \
-recyclecount 100]

When a test runs using this configuration, the results show counts for 100 separate streams
(-RecycleCount 100). If the configuration is changed to use hardware-based streams
(-EnableStream FALSE), all packets generated using that stream block will have the
same signature. The results will show the counts grouped together as if they are a single
stream, regardless of destination addresses or any other potentially differentiating field. To
track specific field values, use an Analyzer filter (see the following section).

Analyzer Filters
You can use the Analyzer to track specific field values in incoming signature-tagged
packets. There are two methods you can use to specify Analyzer filters:
• AnalyzerFrameConfigFilter and PDU Objects
• Bit Filter Objects

NOTE: Spirent TestCenter provides two independent filtering mechanisms – the

Analyzer filter and the Capture filter. The Analyzer filter does not apply when capturing
packets, and the Capture filter does not apply when analyzing streams.

AnalyzerFrameConfigFilter and PDU Objects

To track a field value in signature-tagged packets, you can use the

AnalyzerFrameConfigFilter object along with PDU objects to identify the header fields.
The following figure shows the object hierarchy for using Analyzer filters:

Spirent TestCenter Automation Programmer’s Guide | 131

Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

PDU
Project Port Analyzer AnalyzerFrameConfigFilter Objects

To use a PDU object for an Analyzer filter, set the header field to be filtered by using a
filter specification for the corresponding PDU object attribute value. The following code
fragment shows how to use PDU objects to set up filters for MAC and IP addresses. The
code fragment:
• Retrieves the handle to the Analyzer object.
• Creates an AnalyzerFrameConfigFilter object. The script also clears the frame
configuration because the script will define the filter by creating the PDU objects
explicitly.
• Creates an EthernetII PDU object with a filter specification for the source MAC
address: -srcMac 00:00:00:00:00:00/FF:FF:FF:FF:FF:FF#FF:FF:FF:FF:FF:FF
• Creates an Ipv4 PDU object with a filter specification for the destination IPv4
address: -destAddr 192.168.1.1/192.168.1.3#255.255.255.255

set hAnalyzer [stc::get $hPortB -children-Analyzer]

# Create the AnalyzerFrameConfigFilter filter.

# Clear the -FrameConfig attribute value.
set hAnalyzerFrameConfigFilter [stc::create AnalyzerFrameConfigFilter \
-under $hAnalyzer \
-FrameConfig ""]

stc::create ethernet:EthernetII \
-under $hAnalyzerFrameConfigFilter \
-name af1_eth \
-srcMac "00:00:00:00:00:00/FF:FF:FF:FF:FF:FF#FF:FF:FF:FF:FF:FF"

stc::create ipv4:IPv4 -under $hAnalyzerFrameConfigFilter \

-name af1_ip \
-destAddr "192.168.1.1/192.168.1.3#255.255.255.255"

The address field values use the following filter specification:

-attr-name min-filter-value/max-filter-value#mask
-attr-name is the PDU object attribute, specified as part of a call to the create or config
function.
min-filter-value is the minimum value for the field.
max-filter-value is the maximum value for the field.
mask identifies the bytes to be filtered.

132 | Spirent TestCenter Automation Programmer’s Guide

 Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

Specify the values in NATIVE format to match the field being filtered. The minimum and
maximum values are separated by a forward slash (/); the maximum and mask values are
separated by a number sign (#).

NOTE: Analyzer filters produce results that are stored in FilteredStreamResults

objects. Any time you use an analyzer filter, regardless of the port on which it is
configured, Spirent TestCenter disables the TxStreamResults and
RxStreamSummaryResults objects on all ports.

Bit Filter Objects

Spirent TestCenter provides 16– and 32–bit filter objects that you can apply to traffic
streams. To use a bit filter object, create the object (Analyzer16BitFilter or
Analyzer32BitFilter) as a child of the Analyzer or AnalyzerFrameConfigFilter object.
The following figure shows the bit filter objects.

Analyzer16BitFilter
AnalyzerFrameConfigFilter
Analyzer32BitFilter
Project Port Analyzer
Analyzer16BitFilter

Analyzer32BitFilter

To configure the filter, provide the following information:

• A hexadecimal mask to be used as the filter (-Mask).
• The position at which to apply the filter, specified as a starting location (-Location)
and an offset (-Offset) indicating the number of bytes from the starting location. The
starting location can be one of a set of enumerated type values that identify a logical
starting point to which the offset is applied. Examples of -Location values include:
START_OF_FRAME
START_OF_IPV4_HDR
START_OF_PAYLOAD
See the description of the bit filter objects in the Spirent TestCenter Automation
Object Reference for the -Location values you can use for each object
(Analyzer16BitFilter and Analyzer32BitFilter).
• A range of values for the masked field (-StartOfRange, -EndOfRange)
(See the Spirent TestCenter Automation Object Reference for the complete list of
attributes.)
The following code fragment creates and configures a 16-bit filter that tracks packets with
a destination MAC address between 00:00:00:00:00:00 and 00:00:00:00:FF:FF.

Spirent TestCenter Automation Programmer’s Guide | 133

Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

set hAnalyzer16BitFilter1 [stc::create Analyzer16BitFilter \

-under $hAnalyzer]
stc::config $hAnalyzer16BitFilter1 -FilterName DstMacFilter \
-Offset 4 \
-StartOfRange 0x0000 \
-EndOfRange 0xFFFF \
-Mask 0xFFFF

Histograms
Spirent TestCenter provides a histogram engine that compiles results based on stream
analysis. To use the histogram engine with Spirent TestCenter Automation, you must
configure the Analyzer to perform histogram calculations. When you use the histogram
engine, Spirent TestCenter tracks frames that contain a signature field. The StreamBlock
object attribute insertSig controls the insertion of a signature field into frames. (By
default, insertSig is set to TRUE.)
The following sections provide information about using Spirent TestCenter Automation to
perform histogram calculations on your test data.
• Histogram Calculations
• Histogram Configuration Objects
• Configuring the Histogram Engine

Histogram Calculations

Spirent TestCenter supports the following histogram calculations:

• Frame length – histogram analysis using frame lengths in bytes
• Interarrival time – uses frame inter-arrival times in 10ns units
• Jitter - tracks frame jitter times in 10ns units. Measured on in-sequence frames only.
• Latency – tracks frame transfer delay (latency) in 10ns units
• Seq diff check – tracks differences between the sequence numbers of consecutive
packets
• Seq Run Length – tracks the number of in-sequence frames received between two out-
of-sequence frames

Histogram Configuration Objects

Spirent TestCenter Automation provides the following objects for histogram

configuration. The Analyzer and histogram objects are shown in red, indicating that
Spirent TestCenter creates these objects automatically.

134 | Spirent TestCenter Automation Programmer’s Guide

 Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

FrameLengthHistogram

InterarrivalTimeHistogram

JitterHistogram
Project Port Analyzer AnalyzerConfig
LatencyHistogram

SeqDiffCheckHistogram

SeqRunLengthHistogram

To use a particular type of histogram calculation, retrieve the handle to the appropriate
histogram object and set the attributes. Histogram objects have the following attributes:
• BucketSizeList - Specifies a list of bucket size values; used when DistributionMode is
CUSTOM_MODE and ConfigMode is CONFIG_SIZE_MODE.
• ConfigMode - Bucket configuration mode; CONFIG_SIZE_MODE uses bucket
sizes, CONFIG_LIMIT_MODE uses bucket limits (-LimitList).
• DistributionMode - One of CENTERED_MODE, LEFT_MODE, RIGHT_MODE, or
CUSTOM_MODE.
• DistributionModeSize - Bucket size relative to non-custom distribution modes.
• LimitList - List of bucket limits when -ConfigMode is CONFIG_LIMIT_MODE.
• UniformDistributionSize - Size of the uniformly sized buckets.
See the Spirent TestCenter Automation Object Reference for details about the histogram
objects.

Configuring the Histogram Engine

Perform the following steps to configure the histogram engine:

1 Use signature fields in your traffic streams. (By default, the StreamBlock attribute
insertSig is set to TRUE.)
2 Set the ResultOptions attribute ResultViewMode to one of the histogram options
(HISTOGRAM, JITTER, or INTERARRIVAL). This setting determines the set of
counters available for analysis. (For lists of the counters, see the description of the
ResultOptions object in the Spirent TestCenter Automation Object Reference.) The
ResultOptions object is an automatically created child of the Project object.
3 Set the AnalyzerConfig attribute HistogramMode to the appropriate mode, one of
the following: INTERARRIVAL_TIME, LATENCY, FRAME_LENGTH,
SEQ_RUN_LENGTH, SEQ_DIFF_CHECK, or JITTER.
4 Configure the histogram object that corresponds to the selected histogram mode. The
histogram objects are children of the AnalyzerConfig object.
5 Establish a subscription for the histogram results.

Spirent TestCenter Automation Programmer’s Guide | 135

Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

The following code fragment demonstrates how to configure the histogram engine for
frame length calculations, using limits for bucket configuration.

stc::config $hProject.resultOptions -ResultViewMode HISTOGRAM \

-Active TRUE \
-Name ResultOptions1
# Configure the histogram on the analzer.
puts "\nConfiguring Analyzer"
set hAnalyzerConfig [stc::get $hAnalyzer -children-AnalyzerConfig]

stc::config $hAnalyzerConfig -HistogramMode "FRAME_LENGTH"

stc::config $hAnalyzerConfig.FrameLengthHistogram \
-ConfigMode CONFIG_LIMIT_MODE \
-LimitList "1088 2176 3264 4352 5440 6528 7616 8704 9792 10880
11968 13056 14144 15232 16384" \
-Active TRUE

# Subscribe to realtime results

stc::subscribe -Parent $hProject \

-ConfigType StreamBlock \
-resulttype RxStreamSummaryResults \
-filenameprefix FrameLengthHistogram \
-viewAttributeList "StreamIndex SigFrameCount \
HistBin1Count HistBin2Count \
HistBin3Count HistBin4Count \
HistBin5Count HistBin6Count \
HistBin7Count HistBin8Count \
HistBin9Count HistBin10Count \
HistBin11Count HistBin12Count \
HistBin13Count HistBin14Count \
HistBin15Count HistBin16Count"

Capture
You can direct Spirent TestCenter Automation to capture frame data during a test. To
capture data, your script must perform the following steps:
1 Create the test configuration.
2 Set the capture parameters. This will involve setting attributes for one or more
automatically created objects, and possibly creating additional objects to specify
detailed capture filtering. (This step is optional. You can use the default parameters to
capture all traffic, transmitted and received.)
3 Start capture.
4 Start and then stop traffic.
5 Stop capture and save the captured data.
The following sections provide information about using the capture capability.

136 | Spirent TestCenter Automation Programmer’s Guide

 Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

• Capture Data Model

• Starting Capture
• Stopping Capture
• Capture Loopback
• Capture Triggers

Capture Data Model

Spirent TestCenter defines a set of capture objects that you use to define and control
capture. The capture capability is associated with ports. The following figure shows the
capture objects. The objects shown in red indicate the objects that Spirent TestCenter
creates automatically.

CaptureFilter CaptureAnalyzerFilter

CaptureFilterStartEvent
Project Port Capture
CaptureFilterStopEvent
CaptureFilterStopE

PacketFrame

When you create a Port object, Spirent TestCenter automatically creates the following
objects:
• The Capture object manages capture operations for the port, handling settings for the
different capture modes.
• The CaptureFilter object supports pre-define capture filters that operate at the
protocol header level, and filters that use various size constraints. To filter packets at a
finer level of granularity, use the CaptureAnalyzerFilter object (see Capture
Triggers).
• The CaptureFilterStartEvent object defines events that will start capture.
• The CaptureFilterStopEvent object defines events that will stop capture.
See the Spirent TestCenter Automation Object Reference for more information about these
objects.

Starting Capture

To start capture:
• Retrieve the handle to the Capture object. Capture objects are automatically created
children of Port objects.

Spirent TestCenter Automation Programmer’s Guide | 137

Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

• Set the capture parameters. This example uses REGULAR_MODE to capture all
packets, and TX_RX_MODE to capture both transmitted and received packets.
• Invoke the CaptureStart command, specifying the handle to the Capture object as
the -CaptureProxyId attribute value.
set hCapture [stc::get $hPortRx -children-capture]
stc::config $hCapture -mode REGULAR_MODE -srcMode TX_RX_MODE
stc::perform CaptureStart -captureProxyId $hCapture

Stopping Capture

After stopping traffic, and then stopping the generator(s) and analyzer(s), invoke the
CaptureStop command and save the capture data to a file. The CaptureDataSave
command creates a PCAP file containing raw packet data.
stc::perform CaptureStop -captureProxyId $hCapture
stc::perform CaptureDataSave -captureProxyId $hCapture \
-FileName "capture.pcap"

You can use tools such as Ethereal or Wireshark to view the contents of PCAP files.

Capture Loopback

To determine what is being transmitted from a port, you can set up a local loopback in
software and then capture the received frames. To set up a configuration for a local
loopback, use the following objects that are children of the Port object associated with the
transmitting port.
• Create an EthernetCopper object and set the -DataPathMode attribute to
LOCAL_LOOPBACK. (You can also use an EthernetFiber object for this purpose.)
• Retrieve the Capture object (automatically created as a child of the Port object) and
set the -SrcMode attribute to RX_MODE).

138 | Spirent TestCenter Automation Programmer’s Guide

 Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

This configuration uses a software loopback; the effect is that the port transmits and then
receives the transmitted packets. The RX_MODE setting for the Capture object allows
Spirent TestCenter to track the packets in loopback. The following figure shows the object
hierarchy for local loopback and a representation of the software loopback connection that
is created for the port. (The Capture object is shown in red to indicate that it is
automatically created.)

EthernetCopper
-DataPathMode LOCAL_LOOPBACK

Project Port
Capture
-SrcMode RX_MODE

Spirent
TestCenter
Chassis
Port

virtual loopback

Spirent TestCenter Automation Programmer’s Guide | 139

Packet Generator and Analyzer – Ethernet, IP, TCP, and UDP

Capture Triggers

Spirent TestCenter provides a trigger as a mechanism to match a portion of received

frames and count the successful matches. You can set a trigger by using the
CaptureAnalyzerFilter object on a receiving port. The filter object identifies the protocol
header fields to be filtered (-FrameConfig). The -FrameConfig attribute uses an XML-
formatted value. The easiest method to create the frame configuration is to use the Spirent
TestCenter GUI to create a capture filter, then save it to XML, which creates an output
file. You can then copy the XML expression to your script.

NOTE: Spirent TestCenter provides two independent filtering mechanisms – the Capture
filter and the Analyzer filter. The Capture filter does not apply when analyzing streams,
and the Analyzer filter does not apply when capturing packets.

140 | Spirent TestCenter Automation Programmer’s Guide

 Point-to-Point Protocol over Ethernet

Point-to-Point Protocol over Ethernet

Spirent TestCenter provides support for using the Point-to-Point Protocol over Ethernet
(PPPoE) in a network testing environment. The following sections provide a brief
overview and information about using Spirent TestCenter Automation for PPPoE tests.
• PPPoE Overview
• Using Spirent TestCenter Automation for PPPoE Tests
• PPPoE Example (Tcl)

PPPoE Overview
The Point-to-Point Protocol (PPP) provides a method of transporting datagrams over
point-to-point links between hosts, switches, and routers. Spirent TestCenter provides
support for Point-to-Point Protocol over Ethernet (PPPoE). In PPPoE communication, a
PPPoE frame is embedded within an Ethernet Frame. The Ethernet frame headers include
an ETHER_TYPE field, which identifies the PPPoE stage (discovery or session). The
Ethernet frame payload contains headers that include a CODE field, which identifies the
PPPoE content (contained in the PPPoE frame payload). For a detailed description of
PPPoE encapsulation, see RFC 2516 - A Method for Transmitting PPP Over Ethernet
(PPPoE).
To support PPP-encapsulated data transmission over Ethernet:
• PPPoE defines a discovery stage.
• PPPoE uses the PPP session stage which consists of the following:
• A Link Control Protocol (LCP) for configuring the data-link connection.
• Network Control Protocols (NCPs) for configuring different network-layer
protocols.

PPPoE Discovery
PPPoE Discovery uses a client-server model. PPPoE clients broadcast initiation packets
and PPPoE servers send unicast offer packets. Based on the offer packets it receives, a
client will send a request packet to a server. If the request is confirmed, the client will
initiate a PPPoE session. In the course of the discovery communication, the client and
server exchange Ethernet MAC addresses and establish a unique session identifier.

Link Control Protocol

When discovery has been completed, the PPPoE peers use LCP to configure the
connection for the PPPoE session. Although PPP defines several configuration options,
PPPoE uses only the following:
• Maximum-Receive-Unit (MRU) - specifies a maximum packet size. For PPPoE, the
MRU size cannot exceed 1492.

Spirent TestCenter Automation Programmer’s Guide | 141

Point-to-Point Protocol over Ethernet

• Magic number - used for loopback detection.

• Authentication - during the LCP phase, one peer may send an authentication
challenge to the other. LCP supports two authentication protocols:
• Password Authentication Protocol (PAP). PAP is a simple authentication protocol
in which a peer sends a password in response to the challenge.
• Challenge Handshake Authentication Protocol (CHAP). CHAP is based on the
message digest concept in which the PPPoE peers share a secret password value
but do not send that value across the connection. A peer sends a challenge (con-
taining a random number value), the challenged peer uses the challenge value
together with the password to calculate a message digest value. The challenged
peer returns a response containing the message digest. If the transmitted message
digest matches the same calculation performed by the challenging peer, the con-
nection setup can continue.

Network Control Protocols

When the link has been established, the session peers perform NCP negotiation to:
• Configure network protocols. Spirent TestCenter supports the IP Control Protocol
(IPv4CP and IPv6CP).
• Assign IP addresses for the session.

Using Spirent TestCenter Automation for PPPoE Tests

When you use Spirent TestCenter to test PPPoE, you use the Spirent TestCenter
Automation software and one or more Spirent TestCenter modules to emulate devices that
act as PPPoE clients or servers. The clients and servers communicate with DUTs to create
PPPoE sessions. Once the sessions are established, you can send traffic across the PPPoE
links.
The following sections provide an overview of the Spirent TestCenter Automation API
and data model for PPPoE tests:
• PPPoE Objects and Attributes
• PPPoE Communication
• PPPoE Encapsulated Traffic

PPPoE Objects and Attributes

The following describes many of the attributes you use when you define a PPPoE test
configuration. For more information, see the description of the PppoeClientBlockConfig,
PppoeServerBlockConfig, and PppoeSession objects in the Spirent TestCenter
Automation Object Reference.

142 | Spirent TestCenter Automation Programmer’s Guide

 Point-to-Point Protocol over Ethernet

When you create a Spirent TestCenter test, you create a test configuration that defines
emulated host systems. To create a PPPoE test, you configure the host systems with PPP
interfaces and you also configure the host systems to operate as either PPP clients or PPP
servers.
A PppoeClientBlockConfig object defines the characteristics for a set of PPP clients on a
single host. (Likewise, a PppoeServerBlockConfig object defines one or more servers on
a single host.) The number of clients or servers is determined by the host device count.
The following table shows the PPPoE client and server attributes for the different PPPoE
session capabilities.

PPPoE Session Capability Attributes

Client Server
(PppoeClientBlockConfig) (PppoeServerBlockConfig)

Connection AutoRetry –
EnableAutoRetry

Session authentication – PAP, CHAP, Authentication Authentication

or AUTO (PAP or CHAP, determined Username Username
by DUT) Password Password

CHAP ChapAckTimeout ChapReplyTimeout

ChapChalRequestTimeout IncludeTxChapId
IncludeTxChapId MaxChapRequestChallengeAttempts
MaxChapRequestReplyAttempts

PAP MaxPapRequestAttempts PapPeerRequestTimeout

PapRequestTimeout

Echo requests EchoRequestGenFreq EchoRequestGenFreq

MaxEchoRequestAttempts MaxEchoRequestAttempts

Magic number negotiation (loopback EnableMagicNum EnableMagicNum

detection)

PppPos EnableMpls EnableMpls

EnableOsi EnableOsi

RelayAgent EnableRelayAgent EnableRelayAgent

IncludeRelayAgentInPadr IncludeRelayAgentInPadr
RelayAgentMacAddr RelayAgentMacAddr
RelayAgentType RelayAgentType
RemoteOrSessionId (client form) RemoteOrSessionId (server form)
CircuitId (client form) CircuitId (server form)

Spirent TestCenter Automation Programmer’s Guide | 143

Point-to-Point Protocol over Ethernet

PPPoE Session Capability Attributes

Client Server
(PppoeClientBlockConfig) (PppoeServerBlockConfig)

Encapsulation IpcpEncap IpcpEncap

EnableMruNegotiation EnableMruNegotiation
MruSize

Link Control Protocol LcpConfigRequestMaxAttempts LcpConfigRequestMaxAttempts

(LCP) LcpConfigRequestTimeout LcpConfigRequestTimeout
LcpTermRequestMaxAttempts LcpTermRequestMaxAttempts
LcpTermRequestTimeout LcpTermRequestTimeout
MaxNaks MaxNaks

Network Contro Protocol (NCP) NcpConfigRequestMaxAttempts NcpConfigRequestMaxAttempts

negotiation NcpConfigRequestTimeout NcpConfigRequestTimeout

PPPoE Discovery packets PadiMaxAttempts –

PadiTimeout
PPPoE Active Discovery Initiation
PadrMaxAttempts
(PADI)
PadrTimeout
PPPoE Active Discovery Request
(PADR)

Miscellaneous ServiceName ServiceName

TotalClients TotalClients
UsePartialBlockState UsePartialBlockState

PPPoE Communication
PPPoE communication includes discovery, LCP, and NCP messages. When you use
Spirent TestCenter Automation, you create the object hierarchy, and then, to start
communication, you only need to execute the PPPoxConnect command. Spirent
TestCenter handles discovery, LCP, and NCP negotiation, based on the attribute values of
the PppoeClientBlockConfig and PppoeServerBlockConfig objects.
Once a session is established, you can manage the session by executing Spirent TestCenter
Automation commands, and you can monitor the session by checking attribute values for
the PppoeSessionResults object (such as the SessionState attribute).
The following sections describe:
• The Connect Operation
• Session Termination
• Monitoring a Session
• Pause, Resume, and Retry Operations

144 | Spirent TestCenter Automation Programmer’s Guide

 Point-to-Point Protocol over Ethernet

The Connect Operation

Once you have created the object hierarchy, you can use the PppoxConnect or
PppoxConnectWait command to establish one or more PPPoE sessions. The connect
commands use client blocks (PppoeClientBlockConfig objects) to start sessions. For
each client block specified in the command line, Spirent TestCenter starts the number of
sessions implied by the device count for the associated host.

Session Termination

A PPPoE session may terminate for any number of reasons, for example, a connection
goes down, a session peer is unresponsive, or a peer terminates the session explicitly.
Sessions can terminate during any stage of operation - discovery, LCP or NCP
negotiation, or during the session itself. To terminate a session, Spirent TestCenter sends
the appropriate communication according to the current stage of the session. (See RFC
2516 - A Method for Transmitting PPP Over Ethernet (PPPoE) for more details.)
You can terminate a session by invoking the PppoxDisconnect or PppoxDisconnectWait
command. The disconnect commands use client blocks (PppoEClientBlockConfig
objects) to disconnect sessions. For each client block specified in the command line,
Spirent TestCenter disconnects the established sessions.
The following PppoeClientBlockConfig and PppoeServerBlockConfig attributes can
also affect session termination:
• The LcpConfigRequestTimeout attribute specifies the maximum time allowed for
configuration, at which point Spirent TestCenter will transmit another Configure-
Request packet. The LcpConfigRequestMaxAttempts attribute specifies the
maximum number of configuration requests that Spirent TestCenter will send. After
sending LcpConfigRequestMaxAttempts requests (without a corresponding
response), Spirent TestCenter assumes the peer cannot respond and it terminates the
session.
• The LcpTermRequestTimeout attribute specifies the maximum time allowed for
termination, at which point Spirent TestCenter will transmit another Terminate-
Request packet. The LcpTermRequestMaxAttempts attribute specifies the
maximum number of termination requests that Spirent TestCenter will send. After
sending LcpTermRequestMaxAttempts requests (without a corresponding
response), Spirent TestCenter assumes the peer cannot respond and it terminates the
session.
• The MaxNaks attribute specifies the maximum number of Negative-
Acknowlegments allowed during LCP and NCP configuration/negotiation. After
receiving MaxNaks messages, Spirent TestCenter terminates the session.

Spirent TestCenter Automation Programmer’s Guide | 145

Point-to-Point Protocol over Ethernet

Monitoring a Session

To monitor client or server state during a session, use the PppoeSessionResults object
attribute SessionState. The following table shows the different state values:

States Description

NONE The SessionState attribute represents the current state for all clients or
IDLE servers associated with a client or server configuration block
CONNECTING (PppoeClientBlockConfig or PppoeServerBlockConfig object). Clients
CONNECTING_FAILED and servers start in the IDLE state.
CONNECTED When you execute the PppoxConnect command, the state changes to
DISCONNECTING CONNECTING. Once all sessions have finished with NCP negotiation, the
state changes to CONNECTED. If there is an error during connection, the
state changes to CONNECTING_FAILED.
When the sessions are disconnected (as a result of executing the
PppoxDisconnect command) the client sends messages to terminate the
session, and the state changes to DISCONNECTING. (Sessions can also be
terminated due to an error, resulting in a state change to DISCONNECTING.)
Once the sessions have been disconnected or terminated, the state changes to
IDLE.
A session state of NONE indicates that the session is in an undefined state.

Pause, Resume, and Retry Operations

When you execute the PppoxConnect command, Spirent TestCenter will potentially start a
large number of sessions. Depending on the size of your test configuration, there can be a
significant amount of network traffic as PPPoE peers attempt to establish sessions. Spirent
TestCenter Automation defines a set of commands that you can use to mediate the process
of session setup:
• PppoxPauseCommand – interrupts the overall session setup process. Those sessions
that are already in the process of coming up are allowed to continue. Those sessions
that have not yet started are prevented from starting.
• PppoxResumeCommand – allows those sessions that have not yet started, to start
coming up. Once the sessions are established, the SessionState attribute value
changes to CONNECTED; if the sessions cannot be established, the attribute value
changes to CONNECTING_FAILED.
• PppoxRetryCommand and PppoxRetryWaitCommand – attempt to bring up the
failed sessions.
To get the number of failed sessions, get the value of the failedConnectCount attribute
from the PppoeSessionResults object.

146 | Spirent TestCenter Automation Programmer’s Guide

 Point-to-Point Protocol over Ethernet

PPPoE Encapsulated Traffic

To send traffic in PPPoE frames, you create a StreamBlock object. You must also create a
PppoeSession object (as a child of the StreamBlock object). To associate the traffic with
the PPPoE session, you must define the SrcBinding and DstBinding relations between
the StreamBlock and the host IP interface object. Using the IP addresses obtained from
NCP address negotiation, Spirent TestCenter sets the source and destinations addresses for
the traffic.

NOTE: When you create your test configuration, you must apply the configuration in
two stages. First, create the objects and apply the configuration. This first apply
transaction will resolve the addresses needed for the binding. After the first apply, set the
binding attributes (above), and call the apply function a second time.

PPPoE Example (Tcl)

To create a PPPoE test, write a Tcl script that performs the following test configuration
operations:
• Create emulated host systems.
• Configure a PPPoE client or server on an emulated host.
• Configure the PPP (and other) interfaces on the emulated host.
• Configure PPPoE sessions for traffic streams.
The following sections describe an example Tcl script that creates a PPPoE test
configuration and the runs the test.
• Example Test Configuration
• Initialization
• Host Emulation
• Host Relations
• Traffic Generation and Results Collection
• Attaching Ports
• Results Subscription
• PPPoE Sessions
• Test Execution

Spirent TestCenter Automation Programmer’s Guide | 147

Point-to-Point Protocol over Ethernet

Example Test Configuration

The following figure shows a representation of a simple PPPoE test configuration. This
test emulates two host systems on a single Spirent TestCenter chassis. The hosts are
configured with Ipv4, PPP, and Ethernet interfaces. The test configures multiple PPPoE
clients on each host. Each client uses the port associated with the host to establish PPPoE
sessions with a DUT. Once the sessions are established, traffic is generated, using the IP
addresses that are associated with the PPP sessions.

Spirent TestCenter Chassis

Emulated Host

Ethernet PPPoE PPP IPv4 PPPoE Sessions

Interface Interface Interface Interface Port

PPPoE Client DUT

Emulated Host

Ethernet PPPoE PPP IPv4 PPPoE Sessions

Interface Interface Interface Interface Port

PPPoE Client

The figure on page 149 shows the object hierarchy for this simple PPPoE test. The
Project object at the root of the hierarchy has Port and Host objects as children.
The test emulates two hosts with Ethernet, Ipv4 and PPP interfaces. Each host uses a
PPPoE client block to configure multiple clients. In the figure, the generator, analyzer, and
session result objects are shown in red, indicating that Spirent TestCenter creates these
objects automatically.
The figure shows the parent-child relations that Spirent TestCenter establishes
automatically when you create objects. This test configuration also uses additional
relations, such as the AffiliationPort relation. The AffiliationPort relation connects a
Host object with the Port object that identifies the physical port on the Spirent TestCenter
chassis; the emulated host system will use that port for network communication. For
information about the additional relations for this test, see Host Relations.

148 | Spirent TestCenter Automation Programmer’s Guide

 Point-to-Point Protocol over Ethernet

EthernetFiber

StreamBlock pppoe:PPPoESession
Port 1
Generator GeneratorConfig

Analyzer AnalyzerConfig

EthIIIf

PppoeIf
Host 1
PppIf

Ipv4If

Project PppoeClientBlockConfig PPPoESessionResults

EthIIIf

PppoeIf
Host 2
PppIf

Ipv4If

PppoeClientBlockConfig PPPoESessionResults

EthernetFiber

StreamBlock pppoe:PPPoESession
Port 2
Generator GeneratorConfig

Analyzer AnalyzerConfig

Initialization
Every Spirent TestCenter Automation Tcl script must load the Spirent TestCenter package
before it can use the API. The code fragment on page 150 loads the package, and it also
performs the following setup.
• Defines variables that will be used later in the script. These variables include:
• The chassis, slot, and port location.
• The test duration.
• The number of PPPoE clients to be emulated on a host.
• Creates the Project object that is the root of the object hierarchy.
• Sets automation options to send diagnostic messages to standard output and specify
the minimum severity for logged messages. (The log level is WARN, specifying that
warning and error messages are to be logged.)

Spirent TestCenter Automation Programmer’s Guide | 149

Point-to-Point Protocol over Ethernet

set scriptName "Basic2PortPPPoEwBoundStreams.tcl"

puts "Start running $scriptName"

# Load Spirent TestCenter

package require SpirentTestCenter

set chassisAddress "10.100.20.53"

set slotPort1 "1/1"
set slotPort2 "1/2"
set runtime 30
set numberOfClients 10

puts " Creating project..."

set project [stc::create Project]

puts " project ($project) created"

# Set log parameters

stc::config automationoptions -logTo stdout -logLevel WARN

Host Emulation
To emulate host systems, the example script:
• Creates Port objects to identify physical ports on Spirent TestCenter chassis.
• Creates a subtree of objects that represent a host system. A Host object is the root of
the subtree; the subtree includes interface objects (EthIIIf, Ipv4If, PppIf, and
PppoeIf objects) and a PPP configuration object (PppoeClientBlockConfig). After
the host emulation is complete, the script will configure relations to associate hosts
with ports, define the interface stacking order, and associate the PPPoE clients with
interfaces (see Host Emulation).
The following sections show example code that creates the host emulation for the PPPoE
test.
• Port Identification
• First Host System Interface Stack
• PPPoE Client Configuration
• First Host System Configuration (Descendant-Attribute Notation)
• Second Host Configuration (at Creation)

150 | Spirent TestCenter Automation Programmer’s Guide

 Point-to-Point Protocol over Ethernet

Port Identification

The following code fragment creates two Port objects and an EthernetFiber object for
each port to define the physical port interface. When you create a Port object, you specify
chassis, slot, and port location values. Spirent TestCenter will use the port location values
later on to connect to the chassis and then reserve and map the ports. (See Attaching
Ports.)

puts "Creating the ports..."

#############################
### Create the ports under the project
#############################
set port(1) [stc::create Port \
-under $project \
-Location "//$chassisAddress/$slotPort1" ]

set port(2) [stc::create Port \

-under $project \
-Location "//$chassisAddress/$slotPort2" ]

#############################
### Create the port type under the port object.
### In this case the port type is fiber.
#############################
set ethernetFiber(1) [stc::create EthernetFiber \
-under $port(1) ]

set ethernetFiber(2) [stc::create EthernetFiber \

-under $port(2) ]

puts "Port creation complete"

First Host System Interface Stack

A host system defines the set of interfaces that will be used for network communication
during the test. You emulate a host system by creating a Host object along with the
appropriate set of interface objects.
The code fragment on page 152 creates two Host objects for the test, and it creates the
interface objects for the first host. The interface objects (EthIIIf, Ipv4If, PppIf, and
PppoeIf objects) are children of Host objects. (The script will create the interface objects
for the second host later, as part of a demonstration of the different methods of configuring
the hosts.)
The script creates each Host object with a device count of 10 (the numberOfClients
value set during initialization). The device count determines the number of PPPoE clients
for the host.

Spirent TestCenter Automation Programmer’s Guide | 151

Point-to-Point Protocol over Ethernet

puts "Creating the hosts..."

#############################
### Create the hosts that will be used as sources for
### the streamblocks
### Note: The "deviceCount" attribute defines how many
### PPPoE clients are configured on the host/hostblock
#############################
set host(1) [stc::create Host \
-under $project \
-DeviceCount $numberOfClients ]

set host(2) [stc::create Host \

-under $project \
-DeviceCount $numberOfClients ]

puts "Host creation complete"

#############################
### Create all of the stack interfaces for the first host
#############################
set ethIIIf(1) [stc::create EthIIIf -under $host(1)]
set pppoeIf(1) [stc::create PppoeIf -under $host(1)]
set pppIf(1) [stc::create PppIf -under $host(1)]
set ipv4If(1) [stc::create Ipv4If -under $host(1)]

PPPoE Client Configuration

To emulate PPPoE clients, create a PppoeClientBlockConfig object as a child of a Host

object. A PppoeClientBlockConfig object defines the PPPoE client parameters that will
be used for each of the emulated clients on a host.
The code fragment on page 153 creates a PppoeClientBlockConfig object for the first
host. (After creating the host system objects, the script will connect the
PppoeClientBlockConfig object to the PPPoE and IPv4 interface objects on its host; see
Host Relations.) The call to create the object specifies the following:
• The PPP protocol type - PPPoE (the Protocol attribute).
• Authentication - The clients on the first host will use Password Authentication
Protocol (PAP) to establish PPPoE sessions (the Authentication,
PapRequestTimeout, MaxPapRequestAttempts, UserName, and Password
attributes). The script specifies username/password generation in the UserName and
Password fields.
• Handling of PPPoE Discovery packets:
• PPPoE Active Discovery Initiation (PADI) - the PadiTimeout,
PadiMaxAttempts attributes

152 | Spirent TestCenter Automation Programmer’s Guide

 Point-to-Point Protocol over Ethernet

• PPPoE Active Discovery Request (PADR) - the PadrTimeout and

PadrMaxAttempts attributes
• Encapsulation - IPv4 (the IpcpEncap attribute)
• Use of the Maximum-Receive-Unit option (the EnableMruNegotiation and
MruSize attributes)
• Link Control Protocol (LCP) magic number (the EnableMagicNum attribute)
• Echo-Request packets (the EchoRequestGenFreq and MaxEchoRequestAttempts
attributes)
For a complete list of PppoeClientBlockConfig attributes, see the Spirent TestCenter
Automation Object Reference.

puts "Creating/configuring the host's PPPoE session blocks..."

#############################
### Create/configure the PPPoE session blocks for the hosts
### The username and passwords for each of the session blocks
### are using wildcards. The wildcard @x uses values to modify
### the string : (start,count,step,zeroPadding,stutter)
### The wildcard @s uses the session index associated with
### the PPPox client
#############################
set pppoeClientBlockConfig(1) \
[stc::create "PppoeClientBlockConfig" \
-under $host(1) \
-PapRequestTimeout 3 \
-MaxPapRequestAttempts 10 \
-PadiTimeout 3 \
-PadiMaxAttempts 10 \
-PadrTimeout 3 \
-PadrMaxAttempts 10 \
-IpcpEncap IPV4 \
-Protocol PPPOE \
-EnableMruNegotiation TRUE \
-EnableMagicNum TRUE \
-Authentication PAP \
-MruSize 1500 \
-EchoRequestGenFreq 30 \
-MaxEchoRequestAttempts 0 \
-UserName "sTest@x(1,1,1,3,0)Center@x(1,10,1,2,0)" \
-Password "stc123pwd@x(1,1,1,3,0)"]

The PPPoE client configuration for the first host specifies username and password
generation with wildcards. Spirent TestCenter will use the wildcard specifications to
generate username/password combinations in sequence for PPP sessions.

Spirent TestCenter Automation Programmer’s Guide | 153

Point-to-Point Protocol over Ethernet

In the following specification, the token “@x” represents one or more characters that will
be generated according to the values in the parentheses.
stc123pwd@x(1,1,1,3,0)
The ordered values in the parentheses define the wildcard generation. Spirent TestCenter
generates an ASCII-Decimal value from the wildcard expression. The syntax of the
wildcard expression is as follows:
@x(start,count,step,pad-width,repeat-count)
• The characters “@x” are a token indicating the position at which Spirent TestCenter
will insert generated characters.
• The start value specifies the initial value for iterative wildcard generation.
• The count value is the number of unique values in the set of generated values. (The
default count is 1. A count value of 0 is limit of an of integer value.)
• The step value is the iteration step value.
• The padwidth value is the minimum width of the generated value. If necessary,
Spirent TestCenter zero fills generated values to produce the minimum width value.
• The repeatcount value defines number of times the generated value should be
repeated before applying the step.
For the example given above – stc123pwd@x(1,1,1,3,0) – the first five generated
values are:
stc123pwd001
stc123pwd001
stc123pwd001
stc123pwd001
stc123pwd001
Spirent TestCenter will repeat the generation cycle to produce as many values as required
for the number of sessions in the test. Spirent TestCenter defines a set of tokens for
wildcard substitution. For more information, see the description of the Username and
Password attributes for the PppoeClientBlockConfig and PppoeServerBlockConfig
objects in the Spirent TestCenter Automation Object Reference.
The code fragment on page 155 creates a PppoeClientBlockConfig object for the second
host, determining the characteristics of the PPP clients on the second host. (Later on, the
script will connect the PppoeClientBlockConfig object to the PPPoE and IPv4 interface
objects on its host; see Host Relations.)
The PPPoE configuration for the second host is similar to that of the first host. The
protocol type, encapsulation, MRU, LCP, and Echo-Request values are the same;
however, the clients for the second host will use the Challenge Handshake Authentication
Protocol (CHAP-MD5) to establish PPPoe sessions. For CHAP-MD5 authentication, the
script specifies the ChapCalRequestTimeout, ChapAckTimeout, and
MaxChapRequestReplyAttempts attributes.

154 | Spirent TestCenter Automation Programmer’s Guide

 Point-to-Point Protocol over Ethernet

set pppoeClientBlockConfig(2) \
[stc::create "PppoeClientBlockConfig" \
-under $host(2) \
-ChapChalRequestTimeout 3 \
-ChapAckTimeout 3 \
-MaxChapRequestReplyAttempts 10 \
-PadiTimeout 3 \
-PadiMaxAttempts 10 \
-PadrTimeout 3 \
-PadrMaxAttempts 10 \
-IpcpEncap IPV4 \
-Protocol PPPOE \
-EnableMruNegotiation TRUE \
-EnableMagicNum TRUE \
-Authentication CHAP_MD5 \
-IncludeTxChapId TRUE \
-MruSize 1384 \
-UserName sTestCenter \
-Password stc123 ]

puts "Host PPPoE Session Blocks creation/configuration complete"

First Host System Configuration (Descendant-Attribute Notation)

The following code fragment shows the use of Descendant-Attribute Notation (DAN) to
set the attributes of the interface objects. When you use DAN, you specify a path name
consisting of a sequence of one or more object type names, ending with an attribute name.
The names are separated by dots. (For more detailed information, see Descendant-
Attribute Notation (DAN).)
In the example on page 157, a single call to the config function configures all of the
interfaces for the first host (host(1)). Each attribute specification includes the object type
of the interface object and the attribute name. For example, the source MAC address for
the host is specified as follows:
-EthIIIf.SourceMac 00:10:94:00:00:02
The EthIIIf.SourceMac DAN specification, combined with the host(1) object
specification, identifies the SourceMac attribute for the EthIIIf Ethernet interface object
that is a child of the first Host object.

Spirent TestCenter Automation Programmer’s Guide | 155

Point-to-Point Protocol over Ethernet

puts "Configuring the first host using DAN notation"

#############################
### Configure the first host using the DAN notation
#############################
stc::config $host(1) \
-EthIIIf.SourceMac 00:10:94:00:00:02 \
-EthIIIf.Name "EthIIIf 1" \
-PppoeIf.SessionId 9 \
-PppoeIf.SessionIdStep 1 \
-PppoeIf.SessionResolver PppoeProtocol \
-PppoeIf.Name "PppoeIf 1" \
-PppIf.ProtocolId PPP_PROTOCOL_ID_IPV4 \
-PppIf.Name "PppIf 1" \
-Ipv4If.AddrResolver PppoeProtocol \
-Ipv4If.ResolveGatewayMac TRUE \
-Ipv4If.GatewayMacResolver default \
-Ipv4If.Name "Ipv4If 1"

puts "First host configuration complete"

156 | Spirent TestCenter Automation Programmer’s Guide

 Point-to-Point Protocol over Ethernet

Second Host Configuration (at Creation)

The following code fragment configures the second host when it creates the interface
objects for that host. The code fragment creates each interface object (EthIIIf, PPPoeIf,
PppIf, and Ipv4If), specifying the configuration values at the time of creation.
puts "Creating/configuring the second host's EthernetII interface..."

#############################
### Create/configure the Ethernet II interface for the second host
#############################
set ethIIIf(2) [stc::create EthIIIf \
-under $host(2) \
-SourceMac 00:10:94:00:01:03 ]

puts "Second host EthernetII interface creation/configuration complete"

puts "Creating/configuring the second host's PPP/PPPoE interfaces..."

#############################
### Create/configure the PPP/PPPoE interfaces for the second host
#############################
set pppoeIf(2) [stc::create PppoeIf \
-under $host(2) \
-SessionId 0 \
-SessionIdStep 1 \
-SessionResolver PppoeProtocol ]

set pppIf(2) [stc::create PppIf \

-under $host(2) \
-ProtocolId PPP_PROTOCOL_ID_IPV4 ]

puts "Second host PPP/PPPoE interfaces creation/configuration complete"

puts "Creating/configuring the second host's IPv4 interface..."

#############################
### Create/configure the IPv4 interface for the second host
#############################
set ipv4If(2) [stc::create Ipv4If \
-under $host(2) \
-AddrResolver PppoeProtocol \
-ResolveGatewayMac TRUE \
-GatewayMacResolver default ]

puts "Second host IPv4 interface creation/configuration complete"

Spirent TestCenter Automation Programmer’s Guide | 157

Point-to-Point Protocol over Ethernet

Host Relations
Up to this point, the connections between objects in the test configuration have been
defined by the parent-child relations that Spirent TestCenter automatically configures
when you create objects. Spirent TestCenter requires additional relations between objects
in order to support various operations of the test configuration.
For this test, the example script configures the following relations:
• The AffiliationPort relation defines the connection between an emulated host and the
Spirent TestCenter port that the host will use. To define this connection, you configure
an AffiliatedPort relation between a Host object and the appropriate Port object.
• The TopLevelIf relation identifies the initial interface in the host interface stacking
order.
• The PrimaryIf relation identifies the top level interface (TopLevelIf) that faces the
DUT.
• StackedOnEndpoint relations define the stacking order of the interfaces on an
emulated host.
• The UsesIf relation identifies the interfaces that the PPP client uses. To define this
type of connection, configure a UsesIf relation between a PppoEClientBlockConfig
object and the set of interface objects that it uses.
The following code fragment shows the config function calls that create these relations.
When you configure a relation, you specify the object that will act as one side of the
relation, followed by the relation specification, which identifies the other side of the
relation. For example:
stc::config $host(1) -AffiliatedPort $port(1)
This call to config specifies host(1) as the source of the relation, and port(1) as the target.

puts "Setting up the relations for the hosts to the port objects..."

stc::config $host(1) -AffiliatedPort $port(1)

stc::config $host(1) -TopLevelIf $ipv4If(1)
stc::config $host(1) -PrimaryIf $ipv4If(1)
stc::config $ipv4If(1) -StackedOn $pppIf(1)
stc::config $pppoeIf(1) -StackedOn $ethIIIf(1)
stc::config $pppIf(1) -StackedOn $pppoeIf(1)
stc::config $pppoeClientBlockConfig(1) -UsesIf "$ipv4If(1) $pppoeIf(1)"

stc::config $host(2) -AffiliatedPort $port(2)

stc::config $host(2) -TopLevelIf $ipv4If(2)
stc::config $host(2) -PrimaryIf $ipv4If(2)
stc::config $ipv4If(2) -StackedOn $pppIf(2)
stc::config $pppoeIf(2) -StackedOn $ethIIIf(2)
stc::config $pppIf(2) -StackedOn $pppoeIf(2)
stc::config $pppoeClientBlockConfig(2) -UsesIf " $ipv4If(2) $pppoeIf(2) "

puts "Host relation configuration complete"

158 | Spirent TestCenter Automation Programmer’s Guide

 Point-to-Point Protocol over Ethernet

The following figure shows the relations for the first host-port configuration. (The
relations for the second port-host configuration are identical.)

Project

Port 1

AffiliationPort

Host 1

PppoeClientBlockConfig

EthIIIf
UsesIf

StackedOnEndpoint

TopLevelIf
PppoeIf
PrimaryIf

StackedOnEndpoint

PppIf UsesIf

StackedOnEndpoint

Ipv4If

Traffic Generation and Results Collection

Spirent TestCenter uses Generator objects to manage traffic generation, and Analyzer
objects to manage results collection. When you create a Port object, Spirent TestCenter
automatically creates Generator, GeneratorConfig, Analyzer, and AnalyzerConfig

Spirent TestCenter Automation Programmer’s Guide | 159

Point-to-Point Protocol over Ethernet

objects. for the port. (See the object hierarchy diagram in Example Test Configuration to
see these objects in the hierarchy.)
The following code fragment configures the generators for each port.

puts "Configuring the attributes on each generator (per port)"

#############################
### Configure the generator attributes
#############################
stc::config $port(1).generator.generatorConfig \
-SchedulingMode PORT_BASED \
-Duration $runtime \
-DurationMode SECONDS \
-LoadUnit PERCENT_LINE_RATE \
-LoadMode FIXED \
-FixedLoad 10.000000

stc::config $port(2).generator.generatorConfig \
-SchedulingMode PORT_BASED \
-Duration $runtime \
-DurationMode SECONDS \
-LoadUnit PERCENT_LINE_RATE \
-LoadMode FIXED \
-FixedLoad 10.000000

puts "Generator configuration complete"

The calls to the config function use Direct-Descendant Notation (DDN) to set the
attributes for the GeneratorConfig object. For example:
$port(1).generator.generatorConfig
The object specification consists of the Port object handle – $port(1) – followed by a
sequence of object types (separated by periods). The sequence represents objects in the
port parent-child descendant path in the test hierarchy. Note that DDN allows you to set
multiple attributes of the GeneratorConfig object without having to retrieve the
Generator or GeneratorConfig handles.

160 | Spirent TestCenter Automation Programmer’s Guide

 Point-to-Point Protocol over Ethernet

The following code fragment also uses DDN paths to configure the analyzers on the ports.

stc::config $port(1).analyzer.analyzerConfig \
-TimestampLatchMode START_OF_FRAME \
-SigMode ENHANCED_DETECTION \
-HistogramMode INTERARRIVAL_TIME

stc::config $port(2).analyzer.analyzerConfig \
-TimestampLatchMode START_OF_FRAME \
-SigMode ENHANCED_DETECTION \
-HistogramMode INTERARRIVAL_TIME

Attaching Ports
To run the test, you must:
• Connect to chassis.
• Reserve the ports that you intend to use.
• Map the reserved ports.
You can perform these operations by calling the connect and reserve functions, and then
use the MapPort command. As an alternative, you can accomplish all three by using the
AttachPorts command. The AttachPorts command uses the location defined in the Port
objects to connect to the chassis and reserve the ports, after which it creates the mapping
between the physical ports and their logical representation in the test configuration. The
following code fragment demonstrates the use of the AttachPorts command, after which
it applies the test configuration.

puts "Connecting to the chassis/reserving the ports/mapping the ports..."

stc::perform attachPorts -portList "$port(1) $port(2)" -autoConnect TRUE

puts "Connection/reserving/mapping complete"

puts "Applying configuration..."

#############################
### Apply the previously created configuration
#############################
stc::apply

puts "Configuration applied successfully"

Spirent TestCenter Automation Programmer’s Guide | 161

Point-to-Point Protocol over Ethernet

Results Subscription
To enable the collection of test results, you must establish subscriptions for result
attributes. Use the subscribe function to establish subscriptions and to direct Spirent
TestCenter Automation to produce result files. Refer to the code fragment on page 163.
In the following calls to the subscribe function:
• The –parent parameter is required, and for its value, you must specify the handle for
the Project object in your test configuration.
• The –configType parameter determines the configuration type.
• The –resultType parameter identifies the type of results to be collected. Note that
Spirent TestCenter automatically creates result objects as needed.
• The –filenamePrefix parameter specifies the name of the results file (formatted as
comma-separated values, .csv file extension). You must specify a prefix to generate
results output files.
By default, for all the subscriptions, Spirent TestCenter will collect results for the entire
configuration. To override this default, and limit results collection, use the –resultParent
parameter. (The default is the equivalent of specifying -resultParent $project,
collecting any results associated with objects that are descendants of the Project object.)
For more information, see the description of the subscribe function.

162 | Spirent TestCenter Automation Programmer’s Guide

 Point-to-Point Protocol over Ethernet

puts "Subscribing to results..."

#############################
### Subscribing to results
#############################
set resultDataSet1 [stc::subscribe -Parent $project \
-ConfigType Analyzer \
-resulttype AnalyzerPortResults \
-filenameprefix analyzer_port_counters ]

set resultPPPoESet1 [stc::subscribe -Parent $project \

-ConfigType PPPoXPortConfig \
-resulttype PppoePortResults \
-filenameprefix pppoe_port_counters ]

set resultGeneratorDataSet [stc::subscribe -Parent $project \

-ConfigType Generator \
-resulttype GeneratorPortResults \
-filenameprefix generator_port_counters \
-Interval 2]

puts "Results subscription complete"

PPPoE Sessions
Spirent TestCenter uses the PPPoE client (or server) configuration to establish PPPoE
sessions – in this example, client configuration, defined in the PppoeClientBlockConfig
objects. Once the sessions are established, the script can configure traffic, including
PPPoE headers.
The following sections contain code examples that start PPP sessions and configure PPP
traffic.
• Establishing PPPoE Sessions
• Session State
• PPPoE Session Traffic

Spirent TestCenter Automation Programmer’s Guide | 163

Point-to-Point Protocol over Ethernet

Establishing PPPoE Sessions

The following code fragment executes the PPPoXConnect command to start the PPP
sessions. After waiting 5 seconds for the sessions to be established, the script executes the
PPPoXSessionInfo command to retrieve session data from the chassis.

puts "Connecting PPPoE sessions on all ports..."

#############################
### Connnecting PPPoE sessions
#############################
stc::perform PPPoXConnect \
-blockList "$pppoeClientBlockConfig(1) $pppoeClientBlockConfig(2)"

puts "Waiting for PPPoE sessions to connect (5 seconds)"

#############################
### Wait for a few seconds to allow the PPPoE sessions to connect
#############################
stc::sleep 5

puts "Finished waiting for PPPoE sessions to connect"

puts "Retrieving the PPPoE session information"

stc::perform PppoxSessionInfo \
-blockList "$pppoeClientBlockConfig(1) $pppoeClientBlockConfig(2)"

puts "PPPoE session results information retrieved"

Session State

Once the session data has been retrieved, the script executes a loop that performs the
following:
• Retrieves the PPPoESessionResults children of the PPPoEClientBlockConfig
object. Spirent TestCenter creates the PPPoESessionResults object automatically to
store the session data.
• For each client, the script retrieves the session state, and if the session is connected,
the script retrieves the IP address for the session.

164 | Spirent TestCenter Automation Programmer’s Guide

 Point-to-Point Protocol over Ethernet

#############################
### Retrieve the session state and IP address from the session
### results. Each session has numberOfClients defined, and as
### a result each client has a state and an IP address. There are
### many other result fields that can be retrieved.
#############################

puts ""
puts "Session State IP Address"

# For each block

for {set block 1} {$block <= 2} {incr block} {
set pppoeResultCurrent \
[stc::get $pppoeClientBlockConfig($block) \
-children-PppoeSessionResults]

# For each client in the block

for {set i 0} {$i < $numberOfClients} {incr i} {
set sessionResults [lindex $pppoeResultCurrent $i]
set sessionState [stc::get $sessionResults -SessionState]
if {$sessionState == "CONNECTED"} {
set sessionIp [stc::get $sessionResults -Ipv4Addr]
} else {
set sessionIp "N/A"
}

puts "$sessionState $sessionIp"

}

puts ""
}

PPPoE Session Traffic

To configure PPPoE session traffic for a host, the script creates a StreamBlock object and
a PppoeSession header object. After creating these objects (for both hosts), the script sets
the source and destination bindings for the streams.

NOTE: The StreamBlock source and destination bindings are established after the PPP
sessions are started. This is necessary to take advantage of the IP addresses that are
associated with the PPP sessions. (If the bindings had been established before the sessions
were started, the traffic would use the default IP addresses, which would not be part of the
PPP sessions.)

Spirent TestCenter Automation Programmer’s Guide | 165

Point-to-Point Protocol over Ethernet

The following code fragment creates StreamBlock and PppoeSession objects for each
port.

puts "Creating/configuring the streamblocks on the ports..."

######################################
###### Create stream blocks (one per port)
######################################
set streamBlock(1) [stc::create streamBlock -under $port(1)]
set streamBlock(2) [stc::create streamBlock -under $port(2)]

#############################
### Create/configure the PPPoE interface for the first streamblock
#############################
set strBlkPppoe(1) [stc::create pppoe:PPPoESession \
-under $streamBlock(1)]

#############################
### Create/configure the PPPoE interface for the second streamblock
#############################
set strBlkPppoe(2) [stc::create pppoe:PPPoESession \
-under $streamBlock(2)]

puts "Streamblock configuration complete"

The PppoeSession header is a Protocol Data Unit (PDU) object that is a child of a
StreamBlock object. To use PDU objects that are direct children of StreamBlock objects,
you must use the PDU library prefix for the object:
stc::create pppoe:PPPoESession -under $streamBlock(1)
(The PDU library name is shown as the prefix in the Spirent TestCenter Automation
Object Reference, at the top of the documentation page for PDU objects that are
StreamBlock children.)

NOTE: For the remaining traffic headers, Spirent TestCenter will use the stacked
interfaces configured on the emulated hosts to generate headers in the traffic frames.

166 | Spirent TestCenter Automation Programmer’s Guide

 Point-to-Point Protocol over Ethernet

The following code fragment creates the the source and destination bindings for the traffic
streams. The script creates SrcBinding and DstBinding relations for the StreamBlock
associated with each port, so that the two hosts will send traffic to each other. For each
host:
• The SrcBinding relation connects the local StreamBlock with the local Ipv4
interface (the Ipv4If object).
• The DstBinding relation connects the local StreamBlock with the remote Ipv4
interface (the Ipv4If object).

puts "Creating the streamblock relations"

######################################
##### Note: The streamblock relations are created after
##### the PPPoX sessions have been connected so that the bindings
##### will work corrrectly. Creating the bindings before the
##### sessions are connected will not give the correct IP addresses
######################################

#############################
### Setup the relations for the bindings in the streamblocks
### The source is the PPPoE host on each port, and the destination
### is the PPPoE host configured on the other port
#############################
stc::config $streamBlock(1) -SrcBinding $ipv4If(1)
stc::config $streamBlock(1) -DstBinding $ipv4If(2)
stc::config $streamBlock(2) -SrcBinding $ipv4If(2)
stc::config $streamBlock(2) -DstBinding $ipv4If(1)

puts "Streamblock relation configuration complete"

Spirent TestCenter Automation Programmer’s Guide | 167

Point-to-Point Protocol over Ethernet

The following figure shows the source and destination bindings for the traffic streams.

Project

Port 1

StreamBlock

pppoe:PPPoESession

DstBinding

Host 1
SrcBinding

Ipv4If

PppoeClientBlockConfig

Host 2

DstBinding

Ipv4If

PppoeClientBlockConfig

SrcBinding
Port 2

StreamBlock

pppoe:PPPoESession

168 | Spirent TestCenter Automation Programmer’s Guide

 Point-to-Point Protocol over Ethernet

Test Execution
To run a Spirent TestCenter Automation test, you must start the generator(s) to send
traffic, and the analyzer(s) to collect results. The following sections show the different
aspects of test execution:
• Generator/Analyzer Set Up
• Execution
• Termination

Generator/Analyzer Set Up

The code fragment on page 170:

• Retrieves the handles for the generators and analyzers associated with each of the
ports. The script will use these handles to start and stop the generators and analyzers.
• Before starting traffic, start the analyzers to account for whatever time lag may be
involved in starting streams of traffic. Note that before starting the analyzers, the
script stops them in order to start in a known beginning state.
• Apply the configuration again to account for any modification to the test
configuration due to subscription and establishing the PPP sessions.

Spirent TestCenter Automation Programmer’s Guide | 169

Point-to-Point Protocol over Ethernet

puts "Finding the current generator on the ports..."

#############################
### Find the current generators
#############################
set generatorCurrent(1) [stc::get $port(1) -children-generator]
set generatorCurrent(2) [stc::get $port(2) -children-generator]

puts "Found the current generator on the ports"

puts "Finding the current analyzer on the ports..."

#############################
### Find the current analyzers
#############################
set analyzerCurrent(1) [stc::get $port(1) -children-analyzer]
set analyzerCurrent(2) [stc::get $port(2) -children-analyzer]

puts "Found the current analyzer on the ports"

puts "Stopping the analyzers on all ports..."

#############################
### Stop the analyzers to put the system in a known good state
#############################
stc::perform analyzerStop -analyzerList "$analyzerCurrent(1) $analyzerCurrent(2)"

puts "All analyzers stopped on all ports"

puts "Starting the analyzers on all ports..."

#############################
### Start the analyzers
#############################
stc::perform analyzerStart -analyzerList "$analyzerCurrent(1) $analyzerCurrent(2)"

puts "All analyzers started on all ports"

puts "Applying configuration..."

#############################
### Apply the configuration after the streams have been modified
#############################
stc::apply
puts "Configuration applied successfully"

170 | Spirent TestCenter Automation Programmer’s Guide

 Point-to-Point Protocol over Ethernet

Execution

The following code fragment starts traffic generation, waits for the pre-determined time
period, and then stops the generators and analyzers.
puts "Starting traffic on all ports..."

#############################
### Start the generators
#############################
stc::perform generatorStart \
-generatorList "$generatorCurrent(1) $generatorCurrent(2)"

puts "All traffic started"

puts "************** Sleeping for $runtime seconds **************"

stc::sleep $runtime

puts "************** Finished sleeping **************"

puts "Stopping the generators on the ports..."

#############################
### Stop the generators
#############################
stc::perform generatorStop -generatorList "$generatorCurrent(1) $generatorCurrent(2)"

puts "Generators stopped on all ports"

puts "Stopping the analyzers on all the ports..."

#############################
### Stop the anyalyzers
#############################
stc::perform analyzerStop -analyzerList "$analyzerCurrent(1) $analyzerCurrent(2)"

puts "Analyzers stopped on all ports"

Termination

After stopping the generators and analyzers, the script:

• Disconnects the PPP sessions.
• Releases the reserved ports. The script uses the detachPorts command to release the
ports.
• Disconnects from the chassis.

Spirent TestCenter Automation Programmer’s Guide | 171

Point-to-Point Protocol over Ethernet

The following code fragment shows an example of the function calls that you use to
perform termination.
puts "Disconnecting PPPoE sessions on all ports..."
#############################
### Disconnecting PPPoE sessions
#############################
stc::perform PPPoXDisconnect \
-blockList "$pppoeClientBlockConfig(1) $pppoeClientBlockConfig(2)"

puts "All PPPoE stopped on all ports"

puts "Waiting for PPPoE sessions to disconnect (5 seconds)"

#############################
### Wait for a few seconds to allow the PPPoE sessions to disconnect
#############################
stc::sleep 5

puts "Finished waiting for PPPoE sessions to disconnect"

puts "Releasing the ports..."

#############################
### Release Ports
#############################
stc::perform detachPorts -portList "$port(1) $port(2)"
puts "Releasing the ports complete"

puts "Disconnecting from the chassis"

#############################
### Disconnect
#############################
stc::perform chassisdisconnectall

puts "Disconnecting from the chassis complete"

172 | Spirent TestCenter Automation Programmer’s Guide

 Unicast Routing - Border Gateway Protocol (BGP)

Unicast Routing - Border Gateway Protocol (BGP)

The Internet is a collection of autonomous systems (AS). The Border Gateway Protocol
(BGP) is an exterior gateway protocol that is used to connect these systems. Although
primarily used to connect autonomous systems, BGP is also used as an interior gateway
protocol within an AS.
Routers that use the BGP protocol are called BGP speakers. BGP speakers exchange
routing information about network reachability and AS paths. For a particular route, this
information includes a destination address and a list of AS addresses that describes a path
to the destination. Based on the exchange of information, the BGP speakers build and
maintain routing tables that contain a representation of large portions of the network
topology.
BGP communication uses the following messages:
• OPEN - When two BGP speakers establish a connection, they send OPEN messages
to start the session.
• KEEPALIVE - Throughout a session, speakers send KEEPALIVE messages to
maintain the connection.
• UPDATE - Once the connection has been accepted, and the session has been
established, each speaker sends initial UPDATE messages that contain a complete
version of its routing table. Speakers send subsequent UPDATE messages to advertise
changes to the routing tables. These changes involve the addition of new routes, the
replacement of existing routes, and the withdrawal of routes.
• NOTIFICATION - Speakers send NOTIFICATION messages to indicate error
conditions that result in closing the connection.
When you use Spirent TestCenter to test BGP, you use a Spirent TestCenter module to
emulate BGP routers. You can create test configurations in which the emulated routers and
SUTs form various combinations of external and internal BGP speakers.
To use Spirent TestCenter Automation for a BGP test, you write a script that creates an
object hierarchy. The object hierarchy supplies information that Spirent TestCenter will
use to construct BGP messages and emulate router behavior. When the test runs, your
script will control message traffic at a high level – for example, starting and stopping the
protocol or advertising and withdrawing routes. Spirent TestCenter handles all of the
corresponding message traffic.
The following sections describe an example BGP test configuration and the corresponding
Tcl script that creates and uses the configuration:
• BGP Test Configuration Objects
• BGP Communication in the Spirent TestCenter Environment
• BGP Example (Tcl)

Spirent TestCenter Automation Programmer’s Guide | 173

Unicast Routing - Border Gateway Protocol (BGP)

BGP Test Configuration Objects

The following figure shows an example BGP test configuration and the object hierarchy
for the example. The test uses two ports on a Spirent TestCenter chassis. Each port has an
associated emulated router.

Spirent
TestCenter Emulated Port A
Chassis BGP Router
DUT
Emulated
BGP Router Port B

BgpGlobalConfig

Port A Generator

EthIIIf

Ipv6If (link local address)

Router A
Ipv6If (global address)
Project
BgpRouterConfig BgpIpv6RouteConfig Ipv6NetworkBlock

Port B Analyzer

EthIIIf

Ipv6If (link local address)

Router A
Ipv6If (global address)

BgpRouterConfig BgpIpv6RouteConfig Ipv6NetworkBlock

To create a BGP test configuration:

• Create one or more Router objects.
• Create interfaces for the router(s). The example described in this documentation uses
Ethernet and IPv6 interfaces – EthIIIf and Ipv6If objects that are children of the
Router objects. As part of the router emulation, the test configuration includes Ipv6If
objects for both the link-local and external IPv6 interfaces.
• To emulate a BGP router, create a BgpRouterConfig object as a child of a Router
object.
• To define route characteristics for the interface configuration that you are using,
create additional BGP router configuration objects. For IPv6; the example object

174 | Spirent TestCenter Automation Programmer’s Guide

 Unicast Routing - Border Gateway Protocol (BGP)

configuration uses the BgpIpv6RouteConfig and corresponding Ipv6NetworkBlock

objects. (In the figure below, the Ipv6NetworkBlock objects are shown in red,
indicating that Spirent TestCenter creates these objects automatically.)
• Use the BgpGlobalConfig object to define parameters for all BGP sessions. The
BgpGlobalConfig object is shown in red, indicating that Spirent TestCenter creates
the object automatically.
In addition to creating the object hierarchy, you must also establish additional relations
between certain objects in the hierarchy (beyond the parent-child relations that are
automatically established when you create the objects). For example, you must associate a
Router object with a Port object. You must also define the order of interfaces for the
router.

BGP Communication in the Spirent TestCenter Environment

A BGP session is a periodic stream of BGP messages sent between BGP peers - an OPEN
message followed by a series of UPDATE and KEEPALIVE messages. Session
termination is indicated by a NOTIFICATION message.
The table below lists the BGP messages and describes the context in which Spirent
TestCenter will generate those messages.

BGP message Spirent TestCenter Automation context

OPEN The command ProtocolStart begins the session for each of the
emulated routers associated with the specified BgpRouterConfig
objects
In the Spirent TestCenter environment, an emulated BGP speaker
either initiates a session by sending an OPEN message, or it listens for
OPEN messages. By default, Spirent TestCenter BGP speakers
initiate sessions. To use a speaker as a listener at the beginning of a
session, set the BgpRouterConfig attribute Initiate to FALSE. (Note
that if a Spirent TestCenter BGP speaker is set to initiate a session, it
will still accept an OPEN message to start a session.)
Prior to invoking ProtocolStart, an emulated router is in the IDLE
state. As a result of starting the session, the router will transition
through the following states:
• CONNECT
• ACTIVE
• OPEN_SENT
• OPEN_CONFIRM
Once the session is confirmed by the peer, the router changes its state
to ESTABLISHED. The state is represented in the BgpRouterConfig
attribute RouterState.

Spirent TestCenter Automation Programmer’s Guide | 175

Unicast Routing - Border Gateway Protocol (BGP)

BGP message Spirent TestCenter Automation context

UPDATE Once the session is established, Spirent TestCenter sends out

UPDATE messages to transmit the routing table. Subsequent
UPDATE messages are sent when the routing table changes. Spirent
TestCenter sends UPDATE messages according to the interval set for
the BgpGlobalConfig object. To specify the time interval between
UPDATE messages, set the updateDelay attribute.

KEEPALIVE During a session, Spirent TestCenter sends out KEEPALIVE

messages according to the interval set for the BgpRouterConfig
object. To specify the time interval between KEEPALIVE messages,
set the KeepAliveInterval attribute.
You can enable and disable the generation of KEEPALIVE messages
by invoking the BgpResumeKeepalive and BgpStopKeepalive
commands. Note that it is not necessary to start KEEPALIVE
messages at the beginning of a session; once the session has been
established, Spirent TestCenter automatically starts sending
KEEPALIVE messages. If you stop the transmission of KEEPALIVE
messages, and the hold time expires (the BgpRouterConfig attribute
HoldTimeInterval), the session is terminated.

NOTIFICATION BGP speakers send NOTIFICATION messages to signal errors and

terminate a session. A BGP session will run until one of the following
occurs:
• An error occurs that causes the session to be terminated.
• You invoke the BgpStopKeepalive command, and the hold
time expires.
• You invoke the ProtocolStop command.
• The BGP peer terminates the session.
If a session is terminated, the router returns to the IDLE state. You
must invoke the ProtocolStart command to start it again.

During a session, Spirent TestCenter advertises routes based on the attributes of the
BgpRouterConfig, route configuration (for example, BgpIpv6RouteConfig), and
network block objects. The initial UPDATE messages contains all of the routes that are
defined at the start of the session. After sending the initial version of the routing table, a
speaker sends subsequent UPDATE messages only if the routing table changes. You can
make changes to the emulated router by modifying the objects. You must call the Spirent
TestCenter Automation function apply to send the changes to the module on the Spirent
TestCenter chassis. Spirent TestCenter sends an UPDATE message to communicate the
changes according to the updateDelay timing.

176 | Spirent TestCenter Automation Programmer’s Guide

 Unicast Routing - Border Gateway Protocol (BGP)

Withdrawing Routes

The changes to a BgpRouterConfig object, route configuration object, or a network block

object result in adding or withdrawing routes (including replace transactions, which
withdraw a route and add its replacement). The following methods are used to withdraw
routes:
• A BGP speaker uses the WITHDRAWN ROUTES field in the UPDATE message to
identify routes that are no longer available.
• A speaker can specify a replacement route in the Network Layer Reachability
Information (NLRI), implicitly withdrawing the previously existing route.
• The connection between speakers can be closed, withdrawing all routes (for both
speakers).
When Spirent TestCenter sends UPDATE messages to BGP peers, it uses both the
WITHDRAWN ROUTES field and the NLRI data to reflect changes to the object
hierarchy.
To test withdrawing routes by closing a connection, you can use the ProtocolStop
command. You can also use flapping commands to simulate closing (and then opening) a
connection (BgpWithdrawRoute and BgpReadvertiseRoute commands); the flapping
action will result in the withdrawal (and subsequent re-addition) of all routes.

BGP Example (Tcl)

The following sections describe a Tcl script that creates an object hierarchy for a BGP test.
(See BGP Test Configuration Objects for a representation of the object hierarchy.) The test
emulates two routers, each acting as a BGP speaker. The script also performs route
flapping.
• Initialization
• Object Hierarchy - Project and Port Objects
• Object Hierarchy - Router Configuration
• Start Capture; Subscription
• Test Execution
• Cleanup

Initialization
Every Spirent TestCenter Automation Tcl script must load the Spirent TestCenter package
before it can use the API. The following code fragment loads the package, and it also
defines variables that will be used later in the script. These variables control capture and
specify the IP address of the chassis along with the slot and port numbers. Note that the
first statement begins a Tcl catch block that contains the entire script.

Spirent TestCenter Automation Programmer’s Guide | 177

Unicast Routing - Border Gateway Protocol (BGP)

if {[catch {
package require SpirentTestCenter

set ENABLE_CAPTURE 1

# Physical topology
set szChassisIp 10.98.6.12
set iSlotA 12
set iPortA 1
set iSlotB 12
set iPortB 3

Object Hierarchy - Project and Port Objects

The following code fragment creates the Project and Port objects for the test.
• The Project object is the root of the object hierarchy.
• This configuration uses two Port objects; each will be associated with an emulated
router.
After the script creates the port configuration, it invokes the AttachPorts command.
AttachPorts accomplishes the following actions:
• Connect to the chassis (using the chassis IP address specified in the Port object
location attribute).
• Reserve the ports.
• Create the mapping between the physical ports on the chassis and their logical
representations in the test configuration.
You can perform these operations separately, by calling the connect function, and then
using the ReservePort and MapPort commands; however, the AttachPorts command is
more efficient.
The code fragment also retrieves handles to the transmitting Generator and receiving
Analyzer objects.

178 | Spirent TestCenter Automation Programmer’s Guide

 Unicast Routing - Border Gateway Protocol (BGP)

# Create the root project object

set hProject [stc::create project]

# Create ports
set hPortA [stc::create port -under $hProject \
-location //$szChassisIp/$iSlotA/$iPortA \
-useDefaultHost False ]
set hPortB [stc::create port -under $hProject \
-location //$szChassisIp/$iSlotB/$iPortB \
-useDefaultHost False ]

# Attach ports.
puts "...[clock format [clock seconds] -format %m-%d-%Y%l:%M:%S%p]
Attaching PortList ..."

stc::perform attachPorts -portList [list $hPortA $hPortB] \

-autoConnect TRUE

# Initialize generator/analyzer.
puts "...Initialize generator/analyzer..."
set hGenerator [stc::get $hPortA -children-Generator]
set hAnalyzer [stc::get $hPortB -children-Analyzer]

Object Hierarchy - Router Configuration

The following sections describe a configuration you can use to emulate BGP routers.
• Global Configuration
• BGP Interface - 1st Speaker
• Relations - 1st Speaker
• 2nd Speaker Configuration

Global Configuration

The BgpGlobalConfig object defines global values for emulated router settings. The
object attributes affect the following behavior for all emulated BGP routers represented in
the object hierarchy:
• Connection (the ConnectionRetryCount and ConnectionRetryInterval attributes)
• Session startup and shutdown (the SequentialStartup, StaggerOpen, and
StaggerClose attributes)
• Update message control (the UpdateCount and UpdateDelay attributes)
• VPLS version (the VplsDraftVersion attribute)

Spirent TestCenter Automation Programmer’s Guide | 179

Unicast Routing - Border Gateway Protocol (BGP)

See the Spirent TestCenter Automation Object Reference for details about these attributes.
The following code fragment retrieves the handle to the automatically created
BgpGlobalConfig object. The script will use the handle later, to manage route flapping
(see Route Flapping).

# BgpGlobalConfig
set hBgpGlobalConfig [stc::get $hProject -children-BgpGlobalConfig]

BGP Interface - 1st Speaker

Router configuration involves setting up interfaces for protocols. The following code
fragment creates a Router object and objects for Ethernet and IPv6 interfaces. Then it
configures the router as a BGP speaker. The test uses the following objects (see the Spirent
TestCenter Automation Object Reference for the complete definition of these objects):
• The Router object is a child of the Project object.
• The EthIIIf object specifies the MAC address(es) for the router’s Ethernet
interface(s). The EthIIIf object is a child of the Router object.
• The script creates an Ipv6If object for the router’s link-local IPv6 interface. A child of
the Router object, the Ipv6If object specifies IPv6 address(es), gateway addresses,
and other characteristics.
• The script creates an Ipv6If object for the router’s global IPv6 interface. A child of
the Router object, the Ipv6If object specifies IPv6 address(es), gateway addresses,
and other characteristics.
• The BgpRouterConfig object defines characterstics for an emulated BGP speaker. A
child of the Router object, the BgpRouterConfig object identifies the emulated
speaker (the AsNum attribute), the BGP peer (the DutIpv6Addr and PeerAs
attributes) and the IP version (the IpVersion attribute), and it specifies other speaker
characteristics.
• The BgpIpv6RouteConfig object defines characteristics for BGP IPv6 routes; for
example, AS path information (the AsPath and AsPathSegmentType attributes) and
origin information for UPDATE messages (the Origin attribute). The
BgpIpv6RouteConfig object is a child of the BgpRouterConfig object.
• The Ipv6NetworkBlock object is an automatically created child of the
BgpIpv6RouteConfig object. The script uses the network block object to define a
range of IPv6 addresses.

180 | Spirent TestCenter Automation Programmer’s Guide

 Unicast Routing - Border Gateway Protocol (BGP)

# Configure an IPv6 Router on Port A.

set hRouterA [stc::create "Router" -under $hProject -RouterId "50.0.0.3"]

# Build the router device interfaces.

set hEthIfPortA [stc::create "EthIIIf" -under $hRouterA \
-SourceMac "00:10:00:00:00:11" -SrcMacStep "00:00:00:00:00:01"]

# Ipv6If Link Local address

set hIPv6IfLinkLocalAddrPortA [stc::create "Ipv6If" -under $hRouterA \
-Address "fe80:50::3" -PrefixLength "64" \
-Gateway "2000:50::1" -GatewayMac "00:09:b6:f6:c0:08" ]

# Ipv6If IP address
set hIPv6IfGlobalAddrPortA [stc::create "Ipv6If" -under $hRouterA \
-Address "2000:50::3" -PrefixLength "64" \
-Gateway "2000:50::1" -GatewayMac "00:09:b6:f6:c0:08"]

# BgpRouterConfig
set hBgpRouterConfigPortA [stc::create "BgpRouterConfig" -under $hRouterA \
-DutIpv6Addr "2000:50::1" -IpVersion "IPV6" \
-PeerAs 65503 -AsNum 65504 -Name "Port A router"]

# BgpIpv6RouteConfig
set hBgpIPv6RouteConfigPortA [stc::create "BgpIpv6RouteConfig" \
-under $hBgpRouterConfigPortA -Origin "IGP" \
-AsPath "65504" -AsPathSegmentType "SEQUENCE" -RouteCategory "UNIQUE"]

# Ipv6NetworkBlock
set hIpv6NetworkBlockPortA [stc::get $hBgpIPv6RouteConfigPortA \
-children-Ipv6NetworkBlock]
stc::config $hIpv6NetworkBlockPortA \
-StartIpList "2000::" -PrefixLength "64" -NetworkCount "1000" \
-AddrIncrement "2" -Active "TRUE" -Name "BGP Route 2000::-2000:0:0:7ce::/64,+2"

Relations - 1st Speaker

Up to this point, the connections between objects in the test configuration have been
defined by the parent-child relations that Spirent TestCenter automatically configures
when you create objects. Spirent TestCenter requires additional, non-parent-child relations
between objects in order to support various operations on the test configuration.
For this test, the example script uses the following relations:
• The TopLevelIf relation identifies the initial interface(s) in the router interface
stacking order. In this configuration, the top level interface uses two IPv6 interfaces –
the link-local and global address interfaces.

Spirent TestCenter Automation Programmer’s Guide | 181

Unicast Routing - Border Gateway Protocol (BGP)

• The PrimaryIf relation matches the top level interface (TopLevelIf).

• StackedOnEndpoint relations (specified with the side name StackedOn) define the
stacking order of the interfaces on an emulated router. In this example, both internal
and external IPv6 interfaces are stacked on the Ethernet interface.
• The UsesIf relation identifies the interfaces that the router uses. To define this type of
connection, configure a UsesIf relation between a BgpRouterConfig object and the
set of interface objects that it uses – in this case link-local and global interfaces
(Ipv6If objects).
• The AffiliationPort relation defines the connection between an emulated router and
the Spirent TestCenter port that the router will use. To define this connection, specify
the side name AffiliatedPort to configure the relation between a Router object and
the appropriate Port object.
The following code fragment shows the config function calls that create these relations.
When you configure a relation, you specify the object that will act as one side of the
relation, followed by the relation specification, which identifies the other side of the
relation. For example:
stc::config $hRouterA -AffiliatedPort $hPortA
This call to config specifies hRouterA as the source of the AffiliatedPort relation, and
hPortA as the target.

# Configure relations for router on port A.

# Note that -TopLevelIf has two interfaces.
stc::config $hRouterA \
-TopLevelIf "$hIPv6IfLinkLocalAddrPortA $hIPv6IfGlobalAddrPortA"

# -PrimaryIf is always configured the same as the -TopLevelIf relation.

stc::config $hRouterA \
-PrimaryIf "$hIPv6IfLinkLocalAddrPortA $hIPv6IfGlobalAddrPortA"

# Both IPv6 interfaces require -StackedOn relations.

stc::config $hIPv6IfLinkLocalAddrPortA -StackedOn $hEthIfPortA
stc::config $hIPv6IfGlobalAddrPortA -StackedOn $hEthIfPortA

# Configure relations for BGP protocol on port A.

stc::config $hBgpRouterConfigPortA \
-UsesIf "$hIPv6IfLinkLocalAddrPortA $hIPv6IfGlobalAddrPortA"

# Affiliate the router with a port.

stc::config $hRouterA -AffiliatedPort $hPortA

The following figure shows the relations for the first BGP router configuration. (The
relations for the second BGP router configuration are identical.)

182 | Spirent TestCenter Automation Programmer’s Guide

 Unicast Routing - Border Gateway Protocol (BGP)

Project

Port A

AffiliatedPort

Router A

PrimaryIf

EthIIIf
StackedOn StackedOn PrimaryIf

Ipv6If (link local address)

UsesIf

Ipv6If (global address)

UsesIf

BgpRouterConfig

2nd Speaker Configuration

The following code segments repeat the configuration code for the second BGP speaker.
First, create the configuration:

Spirent TestCenter Automation Programmer’s Guide | 183

Unicast Routing - Border Gateway Protocol (BGP)

# Configure an IPv6 Router on Port B.

set hRouterB [stc::create "Router" -under $hProject -RouterId "51.0.0.3"]

# Build the router device interfaces.

set hEthIfPortB [stc::create "EthIIIf" -under $hRouterB \
-SourceMac "00:10:00:00:00:22" -SrcMacStep "00:00:00:00:00:01"]

# Ipv6If Link Local address

set hIPv6IfLinkLocalAddrPortB [stc::create "Ipv6If" -under $hRouterB \
-Address "fe80:51::3" -Gateway "2000:51::1" \
-GatewayMac "00:00:01:00:00:01" -PrefixLength "64"]

# Ipv6If IP address
set hIPv6IfGlobalAddrPortB [stc::create "Ipv6If" -under $hRouterB \
-Address "2000:51::3" -PrefixLength "64" \
-Gateway "2000:51::1" -GatewayMac "00:09:b6:f6:c0:06"]

# BgpRouterConfig
set hBgpRouterConfigPortB [stc::create "BgpRouterConfig" -under $hRouterB \
-DutIpv6Addr "2000:51::1" -IpVersion "IPV6" -PeerAs 65503 \
-AsNum 65505 -Name "Port B router"]

# BgpIpv6RouteConfig
set hBgpIPv6RouteConfigPortB [stc::create "BgpIpv6RouteConfig" \
-under $hBgpRouterConfigPortB -Origin "IGP" -AsPath "65505" \
-AsPathSegmentType "SEQUENCE" -RouteCategory "UNIQUE"]

# Ipv6NetworkBlock
set hIpv6NetworkBlockPortB [stc::get $hBgpIPv6RouteConfigPortB \
-children-Ipv6NetworkBlock]
stc::config $hIpv6NetworkBlockPortB \
-StartIpList "2000::16" -PrefixLength "64" -NetworkCount "1000" \
-AddrIncrement "2" -Active "TRUE" \
-Name "BGP Route 2000::16-2000:16:0:7ce::/64,+2"

Now the relations for the second speaker:

184 | Spirent TestCenter Automation Programmer’s Guide

 Unicast Routing - Border Gateway Protocol (BGP)

# Configure relations for router on port B.

stc::config $hRouterB \
-TopLevelIf "$hIPv6IfLinkLocalAddrPortB $hIPv6IfGlobalAddrPortB"

stc::config $hRouterB \
-PrimaryIf "$hIPv6IfLinkLocalAddrPortB $hIPv6IfGlobalAddrPortB"

stc::config $hIPv6IfLinkLocalAddrPortB -StackedOn $hEthIfPortB

stc::config $hIPv6IfGlobalAddrPortB -StackedOn $hEthIfPortB

# Configure relations for BGP protocol on port B.

stc::config $hBgpRouterConfigPortB \
-UsesIf "$hIPv6IfLinkLocalAddrPortB $hIPv6IfGlobalAddrPortB"

# Affiliate the router with a port.

stc::config $hRouterB -AffiliationPort-targets $hPortB

Start Capture; Subscription

The following code fragment handles capture and results for the BGP test. The script:
• Retrieves a handle to the capture object for port A and specifies capturing received
packets.
• Starts capture.
• Subscribes to BGP router results.

# The capture object is automatically created.

set hCapture [stc::get $hPortA -children-capture]
stc::config $hCapture -mode REGULAR_MODE -srcMode RX_MODE

stc::perform CaptureStart -captureProxyId $hCapture

# Apply the config

stc::apply

# Subscribe to realtime results.

stc::subscribe -parent $hProject \
-configType bgprouterconfig \
-resultType bgprouterresults \
-interval 1 \
-filenamePrefix "bgprouterresults"

Spirent TestCenter Automation Programmer’s Guide | 185

Unicast Routing - Border Gateway Protocol (BGP)

Test Execution
The following sections describe the elements of test execution for the BGP test:
• Starting the BGP Protocol
• Error Handling (Sessions Not Established)
• Route Flapping
• Stop Protocol; Save Capture

Starting the BGP Protocol

To start BGP sessions, use the ProtocolStart command. The command uses router
configuration object(s) – in this case, BgpRouterConfig objects – to identify the protocol
type. Spirent TestCenter will generate the appropriate messages to start and maintain the
protocol sessions (OPEN, UPDATE, and KEEPALIVE messages for BGP sessions).
The following code fragment invokes ProtocolStart and uses the WaitForRouterState
command to determine the session state for each router. WaitForRouterState will return
control to the script if either session reaches the ESTABLISHED state, or the -WaitTime
attribute setting expires. The script uses a Tcl catch statement to handle errors in
establishing sessions (see Error Handling (Sessions Not Established)).

# Start BGP Protocol.

stc::perform ProtocolStart \
-ProtocolList "$hBgpRouterConfigPortA $hBgpRouterConfigPortB"

# check to see if the protocol is up.

# Put the router config objects in a list, which will be used later in a loop.
set lstRouterConfigHandles [list $hBgpRouterConfigPortA $hBgpRouterConfigPortB]

# Use the WaitForRouterState command.

set lstResults {}
if {[catch {
set lstResults [stc::perform WaitForRouterState \
-ObjectList [list $hRouterA $hRouterB] \
-WaitRouterState PROTOCOL_UP -WaitTime 10 ]
set iNotEstablished 0
} szError] } {
puts $szError
set iNotEstablished 1
}

# Note, if the WaitForRouterState fails, the lstResults variable will be empty.

foreach {szAttribute szValue} $lstResults {
puts \t$szAttribute\t$szValue
}

186 | Spirent TestCenter Automation Programmer’s Guide

 Unicast Routing - Border Gateway Protocol (BGP)

Error Handling (Sessions Not Established)

The following code fragment handles the condition where sessions cannot be established.
The script:
• Displays the router states for failed sessions.
• Stops capture, saves the capture data to a file, and displays the captured frame count.
• Terminates the test (detaches ports and deletes the Project object), and exits.

# Verify that the routers enter the ESTABLISHED state.

if {$iNotEstablished} {
puts "Some ports failed to establish BGP sessions with peer."
foreach hRouterConfig $lstRouterConfigHandles {
puts "\t[stc::get $hRouterConfig -RouterState] for [stc::get $hRouterConfig -
Name]"
}

# Save the capture.

if { $ENABLE_CAPTURE } {
stc::perform CaptureStop -captureProxyId $hCapture
# Save captured frames to a file.
stc::perform CaptureDataSave -captureProxyId $hCapture \
-FileName "capture.pcap" -FileNameFormat PCAP -IsScap FALSE

puts "Captured frames:\t[stc::get $hCapture -PktCount]"

}

# Detach ports.
stc::perform detachPorts -portList [list $hPortA $hPortB]

# Delete configuration
puts "Deleting project"
stc::delete $hProject

return
}

Route Flapping

In normal network operation, routers advertise changes to routes; in response to the

advertised changes, routers recalculate the routes and update routing tables. A network
may become unstable; for example, routers may go down, there may be problems with
connections, or there may be some other type of problem with the network. When the
network topology changes rapidly, the repeated advertising and withdrawal of routing
information is called route flapping. When route flapping occurs, the network

Spirent TestCenter Automation Programmer’s Guide | 187

Unicast Routing - Border Gateway Protocol (BGP)

performance degrades due to the increased routing communication and due to the time it
takes for routers to reconfigure the routing tables.
The following code fragment introduces flapping into the BGP test environment. The
script uses a loop based on message timing to advertise and withdraw routes. The script:
• Uses the BgpGlobalConfig object attributes -UpdateDelay and -UpdateCount to
configure BGP Update message transmission.
• Invokes the BgpWithdrawRoute command to withdraw routes, and then uses the
WaitForRoutingEvents command to wait 30 seconds for all routing commands to
complete.
• Invokes the BgpReadvertiseRoute command to start transmitting Update messages
again, and then uses the WaitForRoutingEvents command to wait 30 seconds for all
routing commands to complete.

188 | Spirent TestCenter Automation Programmer’s Guide

 Unicast Routing - Border Gateway Protocol (BGP)

# Configure delay times between successive BGP Update messages (in milliseconds).
set lstUpdateDelayTimes [list 100 90 80 70 60 50 40 30 20 10 1]

# Withdraw, Readvertise routes.

foreach iUpdateDelayTime $lstUpdateDelayTimes {
# Configure the maximum routes per update message.
# The number of BGP update messages is set to 2000.
puts "\n\tConfiguring update delay time to $iUpdateDelayTime milliseconds"
stc::config $hBgpGlobalConfig -UpdateDelay $iUpdateDelayTime -UpdateCount 2000
stc::apply

# Time the withdraw route command.

set szTimeMicroSec [time {
stc::perform BgpWithdrawRoute \
-RouteList [list $hBgpIPv6RouteConfigPortA $hBgpIPv6RouteConfigPortB]
stc::perform WaitForRoutingEvents \
-WaitMode WAIT_FOR_ALL_ROUTING -WaitTimeout 30
}]

set fTimeSec [expr [lindex $szTimeMicroSec 0] / 1000000.]

puts "\t\ttook [format %4.3f $fTimeSec] seconds"

puts "\tReadvertise routes ..."

# Time the readvertise route command.

set szTimeMicroSec [time {
stc::perform BgpReadvertiseRoute \
-RouterList [list $hBgpRouterConfigPortA $hBgpRouterConfigPortB]
stc::perform WaitForRoutingEvents \
-WaitMode WAIT_FOR_ALL_ROUTING -WaitTimeout 30
}]

set fTimeSec [expr [lindex $szTimeMicroSec 0] / 1000000.]

puts "\t\ttook [format %4.3f $fTimeSec] seconds"
}

Stop Protocol; Save Capture

The following code fragment:

• Stops protocol communication.
• Stops capture.
• Saves the capture data to a file.

Spirent TestCenter Automation Programmer’s Guide | 189

Unicast Routing - Border Gateway Protocol (BGP)

# Stop BGP Protocol.

stc::perform ProtocolStop \
-ProtocolList "$hBgpRouterConfigPortA $hBgpRouterConfigPortB"

# Save the capture.

if { $ENABLE_CAPTURE } {
stc::perform CaptureStop -captureProxyId $hCapture
# Save captured frames to a file.
stc::perform CaptureDataSave -captureProxyId $hCapture \
-FileName "capture.pcap" -FileNameFormat PCAP -IsScap FALSE

puts "Captured frames:\t[stc::get $hCapture -PktCount]"

}

Cleanup
At the end of test execution, the script:
• Releases the reserved ports. The script uses the detachPorts command to release the
ports.
• Deletes the Project object.
The following code fragment shows an example of the function calls that you use to
perform termination. It also contains the end of the outermost Tcl catch block that
encompasses the entire script.

# Detach ports.
stc::perform detachPorts -portList [list $hPortA $hPortB]

# Delete configuration
stc::delete $hProject

} err] } {
puts "Error caught: $err"
}

190 | Spirent TestCenter Automation Programmer’s Guide

Index
A D
Access to chassis 49 DAN 14
AffiliationPort relation 79 Data capture 136
Analyzer filter 131 DDN 13
disabled results 93, 133 delete function 30
API syntax 9 Descendant-Attribute Notation 14
Descendant-Attribute Notation (DAN) 14 Direct-Descendant Notation 13
Direct-Descendant Notation (DDN) 13 Disconnect chassis 52
filtered retrieval (stc::get) 16 disconnect function 31
indexed notation 14 Dotted notation 13
object handle 12
path notation 13 E
relation reference 15 Error handling 54
apply 94 Example, Tcl
apply function 20 BGP 177
AutomationOptions 91 chassis management 49
paged results 98
B PGA 114
BGP 173 PPPoE 147
example test configuration 174 range modifier 126
flapping 177, 187 script template 53
messages in context 175 sequencer (advanced) 75
protocol overview 173 sequencer (basic) 70
router emulation 179 Exceptions 54
Tcl example 177
Bit filter objects 133 F
Filtered retrieval (stc::get) 16
C Filters
Capture 136 analyzer 131
data model 137 bit filters 133
loopback 138 CaptureAnalyzerFilter (capture trigger) 140
trigger 140 functions
Chassis apply 20
connection 50 config 21
disconnection 52 connect 25
Chassis management 49 create 26
example (Tcl) 49 delete 30
Command Sequencer 65 disconnect 31
Command states 70 get 32
config function 21 help 36
Configuring relations 81 log 37
connect function 25 perform 38
Connect to chassis 50 release 39
create 12 reserve 41
create function 26 sleep 43
Creating object handles 12 subscribe 44

Spirent TestCenter Automation Programmer’s Guide | 191

Index

unsubscribe 47 packet generation 122

waitUntilComplete 48 PDU objects 117
protocols 113
G retrieving results 120
get 12, 94 subscription 119
get function 32 Tcl example 114
test analysis 130
H traffic configuration 117
Handling errors 54 traffic generation 120
help function 36 Physical chassis objects 49
Histograms 134 PhysicalChassisManager object 50
PhysicalTestModule object 51
I PPPoE 141
Indexed notation (DDN and DAN) 14 communication 144
Initialization 55 encapsulated traffic 147
example 147
L objects and attributes 143
Loading the API 55 overview 141
Log files 91 using Spirent TestCenter Automation for 142
log function 37 PrimaryIf relation 79
Loopback (capture) 138 Protocol Data Unit 166
Protocol headers 117
M
R
Modifiers (packet generation) 123
chained 127 Random modifier 124
custom header 130 Range modifier 124
example 126 related documentation 7
stacked 128 Relation references 15
Relations
N AffiliationPort 79
configuring 81
Notation, path 13
PrimaryIf 79
StackedOnEndpoint 79
O
TopLevelIf 79
Object handle 12 traffic binding 167
creating 12 release function 39
using 12 reserve function 41
Object path 13 Result files 93
Results, paged 97
P ResultsDataSet object 98
Package, Spirent TestCenter 55 Router emulation, BGP 179
Packet generation 122
multiple stream 123 S
single stream 123 Script template example (Tcl) 53
Paged results 97 Sequencer 65
Paged results example (Tcl) 98 commands 66
Path notation 13 example (advanced) 75
PDU 166 example (basic) 70
library name prefix 118 inserting commands 66
PDU object 117 states 68
modifier 123 vs perform function 65
perform function 38 Signature fields (traffic analysis) 130
vs sequencer execution 65 histograms 134
PGA 113 sleep function 43
capture 136 Spirent Communications
generator configuration 118 company address 8
histograms 134 Spirent TestCenter package (Tcl) 55
modifiers 123 StackedOnEndpoint relation 79

192 | Spirent TestCenter Automation Programmer’s Guide

 Index

subscribe 93
subscribe function 44
Subscriptions 92
DiffServResults, FilteredStreamResults
restriction 92
example 71, 103, 119, 162, 185
result output file 93
Syntax, API 9
Descendant-Attribute Notation (DAN) 14
Direct-Descendant Notation (DDN) 13
filtered retrieval (stc::get) 16
indexed notation 14
object handle 12
path notation 13
relation reference 15

T
Table modifier 124
Tcl catch 54
Tcl error handling 91
Tcl package for Spirent TestCenter 55
Test results
paged results 97
retrieving 94
TopLevelIf relation 79
Tracking packets by signature field 130
Traffic binding (relations) 167
Traffic generators 122
Trigger (CaptureAnalyzerFilter) 140

U
unsubscribe function 47
Using object handles 12

W
waitUntilComplete function 48

Spirent TestCenter Automation Programmer’s Guide | 193