Back

Measurements Collection

As introduced in the testbed overview, the ORBIT Measurement Framework (OML) is a distributed client-server software framework, which enables real-time collection of data from the various applications being executed during an experiment. Figure 1 illustrates this framework.

Figure 1. OML Framework

On the experimenter's side, the Node Handler starts an instance of the OML Collection Server, which will listen and collect experimental results from the various nodes involved in the experiment. It then archives these data in a SQL database.

On each experimental node, the OML Collection Client interfaces with each experimental applications. It will collect any required measurements or outputs from these applications, optionally apply some filter/processing to these measurements/outputs, and then sends them to the OML Server. The communication from the multiple OML Clients on all the experimental nodes towards the OML Server on the experimenter side is currently done over one multicast channel per experiment (for logical segregation of data and for scalability).

There are two alternative methods for the user to implement this interface between their experimental applications and the OML Collection Clients. These two alternative methods are:

• Method based on dynamic OML client library
  This method is the appropriate one for experimenters who write their own experimental application in C or C++.

• Method based on OML client daemon
  This method is the appropriate one for experimenters who use existing applciations with no access to their source code, or who develop their own experimental applications in another language than C/C++.
  — NOTE: this method is currently under development, and will be available soon —

1. Interface using OML Client Dynamic Library

This Interface scheme assumes that the experimenter is developing its own experimental application(s) in C or C++. This method is illustrated in figure 2.

Figure 2. Interface Application/OML Client using Dynamic Library

Within this scheme, the user defines in a XML format the measurement points and frequencies he/she is interested to collect from his/her application. Using this XML definition, an ORBIT web service will then automatically generates the source and compiled code for a specific OML Measurement API. This specific API provides specific methods that the user can call within its C/C++ application code, whenever he/she wants to pass on measurement data to the OML collection service.

, 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 shown below.

<application id="foo">
<measurement-points>
  <measurement-point id="group1">
    <metric id="rssi" type="float"/>
    <metric id="noise" type="float"/>
  </measurement-point>
  <measurement-point id="group2">
    <metric id="throughput" type="int"/>
  </measurement-point>
</measurement-points>
</application>

Measurement point definitions are saved as an XML-based configuration file as shown above. The source code for the measurement client is automatically generated by the web-based OML service that accepts the xml file shown above and returns the autogenerated client API. This API 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 and sample application code below.

The OML service returns a file called "wrapper" which is a tar+gzipped file containing the src,include and lib directories for the OML client API. The src directory need not be used as we already create a static library for the API (see lib directory). In the Makefile, note that the autogenerated filenames include the application id (foo) from the xml file above. Also note how we use the include and lib directories in CFLAGS and LDFLAGS and then link to the oml_client and the client_api libs in LIBS variable. The oml_client library is installed on the gateway machine and is part of the baseline image.

Makefile and include file for Measurement Points

Sample Makefile:
APP = foo
CC  = gcc
CFLAGS  = -g -Wall -I./include
LDFLAGS = -L./lib/i386-linux
LIBS    = -loml_client -loml_$(APP)
SRCS = app.c

app: $(SRCS) oml_$(APP).h
        $(CC) -o app $(CFLAGS) $(SRCS) $(LDFLAGS) $(LIBS)

oml_$(APP).h: $(APP)-def.xml
        wget -q http://oml.orbit-lab.org/generator/wrapper --post-file $< -O -\
        | tar -xzf -

---------------- End of Makefile --------------------

./include/oml_foo.h:
	int oml_group1(float rssi, float noise);
	int oml_group2(int throughput);

Application Code Sample

// needs to be called only once
initialize_oml(&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);

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 1. 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 2 below.

Figure 1. Client-side Data Flow.

Figure 2. Server-side DB Schema Generation.

The Collection Server collects experimental results. There is one instance of the Collection Server per experiment. The Berkeley database is used for scalability, and an SQL database is used for persistent data archiving. One multicast channel per experiment is used for logical segregation of data and for scalability.

Besides ORBIT Services, other ORBIT-developed software includes Libmac and the ORBIT Measurement Framework. Each provides procedures that may be called in user-developed applications. Libmac is a user-space C library that allows applications to inject and capture MAC layer frames, manipulate wireless interface parameters at both aggregate and per-frame levels, and communicate wireless interface parameters over the air on a per-frame level.

The ORBIT Measurement Framework (OML) has a client/server architecture illustrated in Figure 4 below. OML uses IP multicast to send data to the measurement server as it is collected. OML includes 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. Such 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.

Figure 4. OML component architecture.

User-developed software includes the script for the experiment, the application(s) and any modifications to system software. The user-developed script for the experiment contains three static components: the configuration of nodes, the configuration of the application software, and the configuration of the ORBIT Measurements Framework and Library (OML). The application is one or more programs that implement the intended behavior of the active nodes in the experiment. Modified system software may include modified Linux components or custom device drivers. Each of these types of user-developed software is covered in more detail in the Testbed Experiments section of this tutorial.