Orbit > Tutorial > Writing Experiment Scripts

Developing the Script for an Experiment

A script is used to run an ORBIT Radio Grid Testbed experiment. The script contains the configuration of the experiment, specifies its application and operating system software, describes its initialization and any parameters, and describes each phase of its operation.

ORBIT Radio Grid Testbed scripts are written in Ruby, an easily understood, extensible, dynamic, object-oriented scripting language. Ruby has been extended into the testbed user's domain with a number of methods. Besides its extensibility and object-orientation, Ruby is concise and consistent. An ORBIT script therefore is written in Ruby primarily using ORBIT-specific methods. Users are encouraged to take look at following resources

• Ruby Resources
• ORBIT Specific Ruby Methods

ORBIT-specific Methods

Four ORBIT-specific methods are available for debugging help: error( ), warn( ), info( ), and debug( ). How do they work? Like assertions? What arguments do they take? Besides these debugging methods, there are three classes of ORBIT-specific methods discussed below: implicit, Experiment, and NodeSet.

Among the implicit methods two are used to define resources:

      defProperty(name, value, description)
      defNodes(setName, nodeList) {}

Some ORBIT-specific methods work with node sets to specify a set of nodes for each member of which the associated block of code is executed:

      nodes(setName) {}
      allNodes {}
      nodes("_ALL_") {}

Other ORBIT-specific methods use events which delay execution of the associated block of code and sequential execution until that event is true:

	whenAll(setTest, nodeTest, interval = 5) {}
      whenAllInstalled()
      whenAll("_ALL_", "apps/app/status[text()='INSTALLED.OK']") {}
      wait time_in_sec

The Experiment methods and properties are ORBIT-specific methods and properties associated with the Experiment object. They have the form Experiment.method. These methods include:

      name = "tutorial-1a"
      project = "orbit:tutorial"
      props.propName = ""
      Done

It is anticipated that the 'Experiment' prefix will be removed in future versions.

Other ORBIT-specific methods are NodeSet methods that set properties for the specified set of nodes. They have the form

NodeSet ( nodes(setName).method )
      image =
      pxeImage =
      prototype(name) {|node| 
}
      onNodesUp {|node| 
}
      startApplication(appName), startApplications
      stopApplication(appName), stopApplications
      resource
      net.if_name

The defNodes method declares the nodes used in the experiment:

      defNodes(setName:string, nodeList) {}

There are various ways to declare node list:

      A single node: [x,y]
      multiple nodes: [[x1,y1], [x2, y2], [x3, y3]]
      ranges of nodes: [x1..x2, y1..y2]
      the entire grid: [1..20, 1..20]
      with other node sets: [‘nodeSet1’, ‘nodeSet2’]

These methods are useful for declaring common functionality over multiple sets. The various network parameters that may be configured within a defNodes or allNodes block are shown in Figure 9 below, here the first and second Ethernet interfaces are e0 and e1, and the first and second wireless interfaces are w0 and w1.

• net
	– e0, e1
		• arp = true|false En/disable ARP
		• forward = true|false Enable forwarding
		• ip = address/netmask IP address of interface
		• up = true|false En/disable interface
		• route
	– w0, w1
		• All the above
		• channelI = 1..11; 36, 40, 44, 48, 52, 56, 60, 64, 149, 153, 157, 161
		• essid = string
		• frequencyI = 2.412 – 2.462 (5 Mhz steps); 5.18Ghz (20Mhz steps)
		• mode = master|managed|ad-hocI|monitorI
		• rtsA = packetSizeThreshold [bytes]
		• rateI = 1, 5, 11; 6, 9, 12, 18, 24, 36, 48, 54
		• tx_power = -12 .. 15 dBm (intel), 0 .. 20 dBm (atheros)
		• type = a/b/g

Figure 9. Configurable Network Parameters

ORBIT Script Coding Techniques

There are many known techniques for defining an experiment with parameters that do not change over the course of the experiment and for controlling experiments with parameters that change while the experiment runs. These techniques are available in the standard scripts for the baseline ORBIT experiments [where?]. It is also possible to change parameters based on the experiment's own measured behavior, e.g., to run until the observed packet error rate exceeds a given value, see ​''ORBIT Testbed Software Architecture: Supporting Experiments as a Service''.

Developing Application Software

The experimenter may need to develop application software, for example, to emulate the operation of a new network protocol. An ORBIT Radio Grid Testbed application operates in the environment shown in Figure 10 below. An application needs to be integrated into this application harness. Once an application is developed it needs to have an application description developed and to be loaded onto an application server and assigned an id. The process for developing this application description and loading the application software is as follows ?.

Figure 10. Experiment Execution Architecture (see page 12 of ​http://www.orbit-lab.org/doc/tutorial).

Development Tools for Application Software

Three major tools are provided to the ORBIT experimenter to develop an application in C on Linux: ORBIT Traffic Generator/Receiver (OTG/OTR), Libmac and the ORBIT Measurement Framework (OML). The ORBIT traffic generator/receiver (OTG/OTR) illustrated in Figure 11 below is a modular traffic generator/receiver that is integrated with OML and Libmac. OTG/OTR has pluggable traffic models and transport protocols, see ​''ORBIT Measurements Framework and Library (OML): Motivations, Design, Implementation, and Features''.

Figure 11. ORBIT Traffic Generator/Receiver (OTG/OTR)(on page 53 of ​http://www.orbit-lab.org/doc/tutorial).

Libmac is a user-space C library that brings the wireless driver application program interface (API) into user space allowing one to get or set values of driver parameters. This library supports operation for a variable number of parameters per call. The call mac_get_params(struct mac_params *h, struct mac_ifinfo_list *if_ptr, int argc, ) requests the wireless device driver to GET parameter information. The call mac_set_params(struct mac_params *h, struct mac_ifinfo_list *if_ptr, int argc, ) requests device driver to SET parameter information.

The ORBIT Measurement Framework (OML) was discussed in the first section of this tutorial as one of the ORBIT Services. It is a distributed software framework enabling real-time collection of data, and, as such, has a client application programming interface (API). A developer can use this client API through a web interface to define the measurement points and parameters for his or her application. Measurement points and their frequency of collection are an important part of ones experimental plan.

The definition of a measurement point is illustrated in Figure 12 below. Measurement point definitions are saved as an XML-based configuration file, and source code for the measurement client is automatically generated that contains application-specific methods that handle type-safe data collection. This source code can be compiled and linked with the application as illustrated by a Makefile in Figure 13 and sample application code in Figure 14 below.

<measurement-points>
<measurement-point id="group-1">
<metric id="rssi" type="float"/>
<metric id="noise" type="float"/>
</measurement-point>
<measurement-point id="group-2">
<metric id="throughput" type="int"/>
</measurement-point>
</measurement-points>

Figure 12. Defining Measurement Points

Makefile:
$(INC_DIR)/oml_%.h : $(ETC_DIR)/%.xml
mkdir -p $(INC_DIR)
wget -q http://www.orbit-lab.org/oml/client_wrapper\
--post-file $< -O - \
| tar -C $(BUILD_DIR) -xzf –
oml_foo.h:
int oml_group1(float rssi, float noise);
int oml_group2(int throughput);

Figure 13. Makefile and include file for Measurement Points

oml_init(&argc, &argv, NULL);


if (r_data->send_option == 1) {
buffer->rssi = recv_packet_params.rssi ;
buffer->noise = recv_packet_params.noise;
oml_group1(buffer->rssi, buffer->noise);
} else {
log(LOG_ERR, "Unknown receive option! \n");
}
lost_packets = pck_id.seqnum - old - 1;
oml_group2(lost_packets);

Figure 14. Application Code Sample

Because not all measurements are needed and not all measurement samples are needed, OML supports preprocessing or filtering at source to reduce the amount of reported and recorded data. Filters are defined by experimenter, and experimenter-provided filters are supported. Figure 15 below illustrates the client-side data flow. Collection of and access to the recorded data requires the use of a database schema. OML automatically generates the appropriate schema as diagrammed in Figure 16 below.

Figure 15. Client-side Data Flow (see page 66 of ​http://www.orbit-lab.org/doc/tutorial).

Figure 16. Server-side DB Schema Generation (see page 67 of ​http://www.orbit-lab.org/doc/tutorial).

Developing Device Drivers

A possibly difficult aspect of having to develop a completely new application would be to have to develop a device driver for Linux or for another operation system to support a new communications device. Even a simple modification to an existing device driver requires extensive testing. Once a device driver has been developed it needs to be loaded onto an application server. The process for loading a device driver is as follows ?.