Integrating The Structural Simulator with TOSSIM

Requirements:

* TinyOS 1.1.0
NOTE: There are quiet a few differences between TinyOS 1.1.0 and currently available beta versions and hence the code might not be compatible with the latest versions of the TinyOS installations.
* MATLAB 6.3 or higher.
* Structural Control Tool Box in Matlab.

1. Installation Instructions:

a) Download the tar file SHM.tar from here
b) For Installation on Linux follow: Instructions for Installation on Linux .
c) For Installation on Windows follow:Instruction for Installation on Windows.

# Installation instructions for Linux:
* Untar the file SHM.tar.
* Run install.sh as follows:
./install.sh "Tiny OS installation directory" e.g.
./install.sh /opt/tinyos-1.x
* Go to "Tiny OS installation directory"/tools/java/net/tinyos/sim and type "make". This should compile the plugin into TinyViz.
* Run TinyViz you should see a plugin of the name "SHM ADC Readings".
* Go to "Tiny OSinstallation directory"/apps/Sense and type "make pc"
* Ensure that "Tiny OS installation directory"/tools/java is present in your CLASSPATH variable
NOTE: This is an important step since the JAVA server used by MATLAB, resides in this path.
* Copy the MATLAB files from the untarred SHM.tar to a matlab work folder.
* The installation is complete.

# Installation instructions for Windows:
* The windows installation will be done under the Cygwin environment, (Cygwin is installed with the TinyOS installation).
* Open a cygwin command prompt and follow the instructions for the linux installation.

2. Usage:

The figure illustrates the various components that are involved in the integration of a network and environment simulator. The three main components are:

TOSSIM: The Tiny OS network simulator.
TinyViz: The Java visulaizer component of TOSSIM.
Structural Control Tool Box in MATLAB.

Figure 1. The components involved in integration of Environment and Network Simulator.

Figure 1. Giving the various components involved in the integration of Network and Environment Simulators

The usage of the integrated Network and Environment simulator is as follows:

Start MATLAB and go to the working directory where you had copied the MATLAB scripts that came with the installation. Run "mainSHM.m", this would go block on a JAVA server, that will be listening to TCP/IP port 6200.
Start TinyViz and enable the "SHM ADC Readings" plugin
In the file menu choose the input parameter file, we have provided one in the matlab folder "inputParam.m", that comes with the installation script ( During installation you must have copied these files to the MATLAB workign directory).
Click on "start SHM", this will make TinyViz invoke a client, which would generate an input file in the MATLAB working folder, and ask the JAVA server on which MATLAB had been blocked to shutdown. MATLAB would take the input file and generate a corresponding output and again block on the JAVA server. Meanwhile the TinyViz client would be polling for this server. On seeing the server up, it would presume that an ouptput file has been created in the MATLAB working folder, and TinyViz would now process this output file waiting for a node in TOSSIM to ask for samples.
Open a cygwin prompt and export the variable "DBG" as follows:
"export DBG=temp,usr1"
Go to "Tiny OS installation directory"/apps/Sense/build/pc, (Remember to have compiled the Sense application after installation) and run the following command:
"./main.exe -gui 10"
This asks TOSSIM to wait for the GUI/TinyViz to connect to TOSSIM and run a simulation of 10 nodes.
On TinyViz, click on the connect button so that TinyViz connects to TOSSIM and begins the simulation.
You will observe in the TOSSIM window an series of debug statements where each of the 10 nodes requests an ADC sample from TinyViz. After every 200 samples the nodes generate an actuation.
On MATLAB the output that would be observed, will be in the format of a plot. Initially when the MATLAB has just started, this is a single shot case and is shown in Figure 2. Figure 3 depicts the response of MATLAB in a multishot mode.

Figure 2. MATLAB response for single shot mode.

Figure 3. MATLAB response for multi shot mode.

3. Trouble Shooting:

On Windows, ensure that in the windows explorer under Tools->Folder Options->view->"Hide file extensions" is disabled. This affects the file chooser in JAVA for TinyViz since the SHM plugin file chooser (which you would require to use in order to choose the "inputParam.m" file in the MATLAB directory.) is not able to detect the correct file name when the option has been enabled.
The code might be unstable if the following sequence of operations are not performed, MATLAB script should be started first, than the TinyViz plugin should be activated in order to connect to MATLAB and lastly TOSSIM should be launched. We are currently working on fixing certain edge conditions that might arise due to the change in sequence of operation. (Although this does not affect the normal operation of the integration, due to certain undetected conditions TinyViz might not work properly).

For further information, please contact Avinash Sridharan (asridhar@usc.edu), Bhaskar Krishnamachari (bkrishna@usc.edu)