Telestra 3 App Note

Controlling a Telestra 3 MBV Platform via XML-RPC (#66)

I. Introduction

XML-RPC is a remote procedure call that allows software running on different operating systems or different environments to make procedure calls over the Internet. It uses HTTP as the transport and XML as the encoding. XML-RPC is designed to be a simple as possible, while allowing complex data structures to be transmitted, processed and returned. Only a few basic datatypes are supported so it's not equivalent to most other RPC systems such as CORBA.

Traditionally to change system configuration parameters from a remote host, the user needed to create a configuration file on the host and transfer it to the Telestra platform. This mechanism has a number of disadvantages. Most notable, it requires the user to have an intimate knowledge of the Telestra file system structure, configuration file formats, and organization of the running system.

A better mechanism for managing various Telestra operations is to have a well defined interface between the host and Telestra. This interface is defined by XML-RPC and has the following advantages over the traditional mechanism:

  1. Reliable
  2. Less or no maintenance required on host side to manage the configurations
  3. Supported in many programming environments

II. The Telestra Command-Line Interface

The telestra command-line tool uses XML-RPC interfaces to let you control the Telestra servers from the Unix shell. The telestra command takes the name of a subcommand as its first argument. If the subcommand requires arguments, they are supplied after the subcommand. (If you're familiar with the CVS or SVN commands, they have a similar structure.)

If no subcommand is provided, the model status subcommand is executed.

If you remember only one subcommand, remember this one: telestra help will print a list of the available subcommands.

The location of the script can be found at /usr/local/asti/bin/telestra. The current list of subcommands is:

Legal commands are:
        help: Display list of available commands
        hla: View/modify HLA settings
        hla-backchannel: View/modify HLA backchannel settings
        hla-backchannel-signal: View/modify HLA backchannel signal settings
        hla-join: Join HLA federation
        hla-resign: Resign from HLA federation
        hla-rti: Display RTI settings
        hla-statistics:  Display values of HLA counters
        hla-status: Display status of HLA subsystem
        model-load: Load default model on Telestra machine
        model-select: Select a new default model for a particular user
        model-start: Start model running
        model-status: Display status of Telestra machine
        model-stop: Stop model
        reboot: Reboot system
        shutdown: Shut down system

Examples:

#  Prints list of models
telestra model-list

#  Deletes a model belonging to "mbvuser"
telestra model-delete mbvuser model1

You can use the --host setting to specify the hostname of the Telestra server to act upon. If the --host setting is not supplied, the script checks for the TELESTRA environment variable, and uses the value of this variable if it's set. This can be used to avoid having to retype --host repeatedly when issuing a series of commands. The following code can be used to set the host for any Telestra on the network:

telestra --host=

# The syntax of setting environment variables depends upon the shell you use.
# The following syntax is correct for sh/bash-derived shells.
export TELESTRA=

# Display system status
telestra
# Stop the currently running model
telestra model-stop

If the environment variable isn't set, the default host used is "localhost".

III. List of Current Methods

Telestras currently support about 20 different XML-RPC methods. The list of methods will vary based on your Telestra software version. Rather than including them all, the interface can be found at "http://<telestra-ip-address>/test/rpc". You can point a web browser at this URL to get a formatted list of the methods that exist for your software version. The list will include the parameters of each method and a short description of each one.

The methods are currently grouped into five sections based on their functionality:

  • Host Methods
  • Model Methods
  • DIS Methods
  • HLA Methods
  • System Methods

IV. Using XML-RPC

XML-RPC works by creating a small XML document that contains the name of a method to be called and the arguments to the method. This chunk of XML is then sent to a server using HTTP, the same protocol used by web browsers. The server processes the request and returns the results as the HTTP response.

For example, there's a service that returns the current time via XML-RPC located at http://time.xmlrpc.com/RPC2. It takes three lines of Python code to call it:

user@telestra: ~/$ python
Python 2.4.2 (#2, Sep 30 2005, 21:19:01)
>>> import xmlrpclib
>>> s = xmlrpclib.Server('http://time.xmlrpc.com/RPC2')
>>> s.currentTime.getCurrentTime()
<DateTime u'20060310T14:52:12 at -481d7114>
>>>

Watching the HTTP transaction going over the network, you would see the following traffic. First, the client sends the request to the server:

POST /RPC2 HTTP/1.0
Host:  time.xmlrpc.com
User-Agent:  xmlrpclib.py/1.0.1 (by www.pythonware.com)
Content-Type:  text/xml
Content-Length:  120

<?xml version='1.0'?>
<methodCall>
  <methodName>currentTime.getCurrentTime</methodName>
<params></params>
</methodCall>
The server then returns the result of the call:
HHTP/1.1 200 OK
Content-Length:  183
Content-Type: text/xml
Date:  Fri, 10 Mar 2006 19:54:27 GMT
Server:  UserLand Frontier/9.0.1-WinNT

<?xml version="1.0"?>
<methodResponse>
 <params>
    <param>
      <value>

<dateTime.iso8601>20060310T14:54:27</dateTime.iso8601>
      </value>
    </param>
  </params>
</methodResponse>

For more information about XML-RPC, see "Programming Web Services with XML-RPC" by Simon St. Laurent, Joe Johnston, Edd Dumbill, O'Reilly, 2001, or "XML-RPC HOWTO" by Eric Kidd at http://tldp.org/HOWTO/XML-RPC-HOWTO/index.html.

For example, rebooting a Telestra is simple (example in Python):

s = xmlrpclib.Server('http://telestra.example.com/test/rpc')
s.telestra.reboot()

Most methods that perform an action return a string as their result. The result is the string 'ok' if there were no problems, or a message describing any problems that occurred. This message can usually be printed out to help a user figure out what's going wrong.

V. Examples

All of the following examples use Python.

A. Changing Host Interface Settings

In this example, we set some properties of a UDP host interface and then reload the model so that it will use the new property values.

s = xmlrpclib.ServerProxy('http://192.42.172.62/test/rpc')
s.host.set_tx('/Assets/Telestra/UDP_RX', '192.168.100.130', 12001)
path, owner = s.model.get_current()
s.model.load(owner)
B. Changing Radio Server Settings

This example sets the DIS packet address and the Site ID, and restarts the radio subsystem to make the new configuration active.

s = xmlrpclib.ServerProxy('http://192.42.172.62/test/rpc')
s.radio.dis.set_config('DIS', '192.42.172.255:53000:0', 'DIS_Site', 6)
time.sleep(1)
C. Model Operation
import xmlrpclib
s = xmlrpclib.ServerProxy('http://192.42.172.62/test/rpc')

# Upload a model present on host box. Say,
model_path = '/home/usera/testmodel.tgz'
## Read contents of .tgz file containing model
model_path = '/home/usera/testmodel.tgz'
data = open(model_path, 'rb').read()

## Upload the model stored on host box onto the Telestra, with model name 'sample_model'
print s.model.load('sample_model', 'mbvuser')

print s.model.set_default('sample_model', 'mbvuser')
print s.model.stop()
print s.model.start()
print s.model.get_current()