The lower-layer Tcl API provides an object-oriented Tcl interface to the ByteBlower client API. By interacting with the various API objects, a Tcl script controls the ByteBlower server in a direct way.

All server functionality is made available to the user through the client API. Each API call corresponds with a single action on the server, such as setting the MAC address of a network host, starting a traffic stream or performing DHCP.

On the other hand, the API is the only way to configure the server. This means many higher-level concepts such as a traffic flow or a latency measurement do not exist in the API, because they do not exist on the server.

For example, setting up a typical latency measuring scenario involves:

Creating and configuring two ByteBlower ports (ByteBlowerPort), which represent end hosts.
Setting up a timestamped traffic stream (Tx.Stream) on the first port.
Setting up an incoming traffic processor for latency calculations (Rx.Latency.Basic) on the second port.
Starting the traffic and doing an (active) wait until all traffic should have arrived.
Reading the latency values calculated on the server from the incoming traffic processor API object.

Note that the mapping of concepts such as flow and latency measurement to the steps described above is exactly what happens in the higher-layer API. That API maps declarative scenario configurations to sequences of API calls. Such a mapping also occurs in back-end of the ByteBlower GUI when the users runs a scenario!

Object-oriented programming in Tcl

The object-oriented Tcl API is built on TOOP (Tcl object-oriented programming). TOOP is a Tcl library that enhances the Tcl language with object-oriented facilities and is developed in-house at Excentis.

Using the TOOP facilities, a script can interact with Tcl API objects as follows:

1 set returnValue [ $object Method.Name $arg1Value $arg2Value ]

For example, the statement above will execute Method.Name on the object referenced by the variable object. The arguments and the return value may either be API objects of their own or regular Tcl string or list values.

API structure

The ByteBlower Tcl API becomes available in a Tcl shell by loading the following package:

1 package require ByteBlower

The complete API is constructed in a hierarchical way with the ByteBlower object at the top. The ByteBlower object is a singleton and acts as an entry point to the API. To retrieve the object, call the following (static) method of the ByteBlower class:

1 set bb [ ByteBlower Instance.Get ]

The ByteBlower object can contain one or more ByteBlowerServer objects. By calling ByteBlower::Server.Add, the client connects to the specified server. A server API object is created and returned:

1 set server1 [ $bb Server.Add "byteblower-22.lab.mycompany.com" ]

Note: For backwards compatibility, all methods of the ByteBlower singleton object are also available as static methods of the ByteBlower class. For example, the following method call creates a server object just as well!
1 set server2 [ ByteBlower Server.Add "byteblower-23.lab.mycompany.com" ]

The server API object in turn allows the script to create a (theoretically) infinite amount of ByteBlowerPort objects. Such ByteBlower ports represent network hosts and are the cornerstone of the API.

Such a port is created by calling ByteBlowerServer::Port.Create. The physical interface on which the port must be created is passed as an argument to the method:

1 set port1 [ $server1 Port.Create trunk-2-48 ]

In this example, a network host is created on the 48th physical interface of the ByteBlower switch connected to the 2nd trunking interface. This physical location determines where the host will be created within the network under test.

Note: Similarly, a ByteBlowerPort can be created on a server interface without a ByteBlower switch attached (a so called non-trunking interface). Simply adjust the physical location agrument accordingly:
1 set port2 [ $server Port.Create nontrunk-3 ]

By configuring these ByteBlower ports they can participate in the system under test. Check out the documented examples or the API reference to see what kind of actions can be performed on ByteBlowerPort objects. This functionality mainly consist of:

Configuring the network settings of the host (MAC address, IPv4 or IPv6 settings, VLAN, ...).
Setting up network traffic streams (TX side) to blast traffic and incoming packet processors (RX side) to count frames or measure latency.
Creating and running network applications, such as starting an HTTP server or scheduling a Telnet session.

Synchronous API

The ByteBlower Tcl API is completely synchronous: each API call immediately affects the server state and only returns once it is finished. If an error occurs at either the client or server software, this is immediatly reported back in the form of an exception.

Having a synchronous API means that the server cannot notify the script of events, such as a tcp flow that has finished. Therefore scripts may need to check the server state periodically, to see if some condition (e.g. tcp connection status value is 'finished') is already met.

Such concepts and techniques are explained in the examples page of this documentation. The example scripts that are packaged with the ByteBlower software show them in action as well!