Sapienza University Networking framework for underwater Simulation, Emulation and real-life Testing


A Technical Description

The Sapienza University Networking framework for underwater Simulation, Emulation and real-life Testing (SUNSET) is a new solution developed to seamlessly simulate, emulate and test at sea novel communication protocols [1], which is based on the open source and well known network simulator ns-2 (and its extension ns-Miracle [2]). Using the proposed framework, anyone willing to implement its solution for simulation experiments using ns-2 can use the same code in emulation mode, adopting real acoustic modem for data transmission. The framework code has also successfully been ported on small portable devices (Gumstix, PC104 or other ARM-based systems), thus allowing us to embed it inside modem or AUV housings.
When running simulations the framework can use different underwater acoustic channel models, such as the empirical formulas (Urick book [3]) or it can use the Bellhop propagation simulator via the WOSS [4] interface, which can load real environmental parameters and provide more accurate results. In order to allow ns-2 to work correctly in an efficient way with real devices, some of the ns-2 components has been extended and improved.

  • The use of multiple threads has been introduced, thus allowing the main thread to run the protocol stack while secondary threads listen to communications from external devices.

  • A new real time scheduler has been implemented to more accurately capture the elapsed time, making it possible for secondary threads to interact with the ordered data structure of the scheduler (used by the main thread) while the main thread is waiting for the next event to be scheduled.

Moreover, additional modules have been designed to make the execution of simulation and emulation easier and more transparent to the user. A description of these modules is presented below:

Timing module

A timing module has been implemented which is used to model external device delays and overhead. When running simulation, the delays related to the use of real devices are usually ignored. These delays include: 1) Computational delay; 2) Operational delay related to internal operations of the considered device (acoustic modems, Gumstix, other external devices); 3) Delays related to the communication between different hardware components on the same node. These aspects have to be kept into account when tuning the protocols parameters before real-life tests. Moreover, it is not always true that the message sent by the external device exactly corresponds to the original size of the created message, because of coding performed by the device or constraints on the final packet sizes to be transmitted. E.g. the packet length for FSK Micro-Modem is fixed to 32 Bytes, if the length of the message to be transmitted, let's say k, is shorter than that k < 32 always 32 Bytes are transmitted in water with 32 − k Bytes filled with zero. The timing module is used to consider these delays and overhead when running both in simulation and emulation mode. If these delays are already accounted for when computing protocol stack timeouts for simulation purposes (which means a specific modem model is used for simulation and corresponding parameters are set in the timing module), no changes in the code are needed and the code is seamlessly ported to real devices and used for tests at sea or in a lab emulation environment.

Packet converter module

A new module to convert an ns-2 packet into a stream of bytes, which is provided to the external device for actual transmission, has been implemented. Usually when defining a new packet header in ns-2, several information can be added to he packet header without any particular constraints, since the packet size used in simulation is not derived from the actual sizes of the packet headers and of the payload but from the size value written in the common packet header. For this reason, in order to make the simulation analysis easier, information meant for statistic or debugging purposes could be added to the defined packet header, moreover, no attention is usually given to the specific sizes used to store the packet header parameters, 1 bytes, 2 bytes or more. In a such situation it is not useful to take an entire packet header and convert it into a stream of bytes for transmission without removing the information that are not needed and without taking care of the actual sizes required by each parameters. E.g., If a simulation packet header takes few tens of bytes when it is defined but the useful information are just source ID and destination ID, with a maximum number of node in the network less or equal to 15, 4 bits can be used for each ID reducing the converted header size to 1 Byte. On the other hand, it would be really impracticable to have packet header containing only the exact information to be transmitted and having all of them with the exact sizes when running both simulation and emulation. It would make the protocol analysis and design much harder.
To solve this problem, we have designed a new module for ns-2 packet conversion. When defining a new packet header, the methods to convert it into an stream of bytes and vice versa have to be provided. In this way who designs the packet header is also responsible for its conversion, deciding also about the subset of information to be converted and the specific sizes. The selection about information and sizes could also be performed by the user using the TCL script (such as in the packet header we have designed in our framework). The generic packet header class is responsible for the operations on the ns-2 packet for conversion and de-conversion. Such class uses the different packet header converter modules, with each module taking care of its specific packet header. When the user decides what protocol and packet header are used in the emulation, it also registers the used packet header converter to the generic packet converter. Then the generic packet converter for each packet will detect the packet header involved and will use each of them for converting an ns-2 packet into a stream of bytes for transmission and vice versa for reception.

Utilities module

To make transparent to the users the use of the framework in simulation and emulation mode an utilities module has been implemented. It provides functionalities to check if the framework is running in simulation or emulation mode, i.e., if the standard scheduler or the real time scheduler is used. When scheduling an event the utilities module is responsible to call the specific scheduler (standard or real-time) which has to take care of event scheduling. It also takes care of removing the memory allocated for a ns-2 packet in a proper way: When running in simulation mode no actual memory is allocated for the packet payload and freeing the packet memory is enough. When running in emulation mode, instead, additional memory could have been allocated for the packet and it has to be erased when the packet is no longer needed. The utilities module also provides function to update the real-time scheduler timing according to the clock of the device running the framework.

Information Dispatcher Module

The Information Dispatcher module implements the publish-subscribe pattern. The information dispatcher allows to share information among the different layers of the protocol stack while keeping the high degree of flexibility and modularity given by the layered architecture. Each layer which wants to provide to or request information from the other layers, can register itself to the information dispatcher and inform the dispatcher about the data it can provide and the data it wants to be informed of. The dispatcher collects the information from the different modules and notifies any update to all the modules which are interested about them. All modules can also request information on demand or ask for periodic updates. Each information is timestamped in order to check its freshness. In case multiple layers are providing the same information or some layers request information which require some processing on the data provided by the other layers, the information dispatcher can take care of that, everything is inside the same module and provides a more easy and fast way to handle the different information.

Debug module

When developing and testing a novel solution, it is always useful for both developers and users to log and process debug information. We have therefore developed and implemented a debug module which allows to assign to each information to log a debug level. When the user starts the experiment it can define the debug level of the information it wants to log. If debug level k is selected, it means that only the information with an assigned debug level lower or equal to k are logged. This module also allows to change the debug level on demand thus increasing and reducing the logged information according to the user needs.

Trace module

This module is used to trace experiment information. Differently from the Debug module, the message is printed despite the debug level.

Statistics module

To allow the user to collect statistical information to evaluate the protocol performance, a statistics module has been designed. This module allows the user to collect all the information about packet transmissions and receptions, energy consumption, additional delays (backoff period, device delays, etc.) and others. The user can then easily compute all the metrics (per node or in the network) it is interested in: Packet delivery ratio, network throughput, packet latency, energy consumption, etc. Moreover, the developers can easily extend the provided statistics module to include additional information of interest. When running in simulation mode, the statistics module collects the information from all the nodes in the network and all the required metrics are available at the end of the simulation. When running in emulation mode, however, each node is an independent unit, storing its own information. For this reason, these information have to be merged together with a post processing analysis. Additional tools for data post processing have already been implemented and used.

Using the proposed framework and the additional modules presented above, the same code written for performing simulations can be re-used for emulation and at sea trials without rewriting.
The use of our framework for simulation and emulation is depicted in Figure 1. When running in simulation mode (Figure 1a), the event driven scheduler is used and the acoustic channel and propagation model are simulated (by means of Urick's formulas, Bellhop or other ray tracing models). In this case, one PC runs a single instance of ns-2 to simulate an entire network. While in emulation mode, the real time scheduler is used. The simulated channel propagation model is then replaced by the use of real hardware (Figure 1b). When emulating the network, each node is an instance of ns-2 which emulates its own behavior, based on the defined protocol stack, and it has to run on its own hardware. We can also have more instances of ns-2 running on the same machine but each of them has to be connected to its own acoustic modem and to other node components, such as sensors and AUV control system.

Energy module

The SUNSET energy module provides a more accurate model to compute the energy consumption at each node and it supports also the possibility to use different power transmission levels corresponding to a different energy consumption at the node.

Packet Error Model

The Packet Error Model Module permits to select or implement the preferred packet error model to be used when running an experiment. It is mainly meant for simulations but it could be also used when the system is running in emulation mode. Three different error models have been developed: BPSK, FSK and static. If the static model is chosen, the user can set a value for the Packet Error Rate (PER), which is then used each time a packet is received by a node. A random value will be computed and compared to the selected one in order to decide if the packet has to be dropped or not. For the other two modules instead, the SNR and SNIR values are considered and the Bit Error Rate (BER) and PER corresponding to the BPSK and FSK modulations are computed. These packet error models can be used by each of the PHY modules provided in SUNSET.

Generic Driver module

When running in emulation mode, no channel model are used but real devices, i.e., acoustic modems for underwater transmission, antennas for radio transmission, etc. A "generic driver module" has been implemented which takes care of the modem independent interactions with ns-2. The generic driver module implements the basic operations that have to be performed, packet conversion when transmitting and receiving data to and from the external device (it uses the packet converter functionalities). In this way the ns-2 simulator will always work with ns-2 packets and no modifications are needed at the upper layers. The generic driver module implements also the timing information which have to be provided to the timing module for correct timeout computation at the upper layers. Each driver for a specific external device will extend this class and will implement the different operations related to the specific driver.
The actual connection between the driver and the real device (acoustic modem, antenna, etc.) can be done in different ways depending on the hardware used to run ns-2 and the specific device which might support serial port, Bluetooth connection, Ethernet, Ethernet over USB, etc.

Channel Emulator

The Channel Emulator is a powerful tool provided by SUNSET to locally run tests emulating a real experiment using the real-time scheduler and the other emulation components. Using this module it can be possible to check if everything (i.e. timeout, packets conversion, etc.) has been set and tuned properly before running in field experiments. The channel emulator supports the usage of multiple nodes. It can be combined with the blacklist capabilities of the PHY layer and the packet error model provided by the related module permitting to emulate a multi-hop network with several nodes and variable links.
Using the provided channel emulator it is also possible to emulate node mobility updating the node position over time or when some changes occur. Everything is done in a transparent way to the user/developer.

Figure 1: SUNSET framework architecture: Simulation and emulation modes.
Simulation Mode
(a): Simulation Mode

Emulation Mode
(b): Emulation Mode


To download, install and use SUNSET two different options are provided:

  • SVN repository - It allows to download the SUNSET code, scripts and examples. All the additional software (ns-2, ns-Miracle, WOSS, cross-compile environment) have to be manually installed by the user.

  • Virtual machine - A complete virtual machine which already includes SUNSET and all the required software. It is based on a light and minimal Linux Debian distribution to reduce the overall size of the virtual environment (∼ 1.5GB). This solution is strongly recommended by SUNSET developers.

Improved and enhanced modules to run SUNSET in emulation and field testing mode have been designed and implemented by SUNSET developers in collaboration with industrial third parties. Unfortunately, these solutions CANNOT be all released open to the community. To provide these enhanced and improved modules to the users, we have decided to release them as compiled libraries. This allows anyone to freely and easily use the improved version of SUNSET when running in simulation, emulation and real-life mode.

The source code for all the modules needed when running simulations and the released network solutions is instead freely available. The modules released as libraries are: Packet converter modules in Core components; the Emulation components, with the exception of the Evologics and Micro-Modem drivers and the Debug_Emulation module.
The provided libraries have been compiled using as target machine the released Virtual machine and have been also added to the SVN repository. Additional libraries to run SUNSET on different architectures can be requested to SUNSET developers.

SVN Repository

The latest version of SUNSET (distributed for UNIX-based OS) can be downloaded from the following SVN repository:

To start the download just type:

svn checkout

If svn is not installed on your machine you need to install it. In Debian based OS you can simply run:

sudo apt-get install subversion

To install and use SUNSET, ns-2 and ns-Miracle software have to be installed.
If the Bellhop ray tracer has to be used as channel and propagation model when running simulations also the WOSS interface has to be installed. WOSS is NOT needed when running in emulation mode.

At the moment the release does not include additional modules, listed in the framework description, to control the operations of different acoustic modems, AUV navigation system and monitoring sensors.

We kindly ask researchers and developers using SUNSET for their research activities to acknowledge this paper "SUNSET: Simulation, Emulation and Real-life Testing of Underwater Wireless Sensor Networks."

We will also be glad to any developer who wants to contribute to the SUNSET framework. Read-write accounts can be provided to developers who make repeated contributions to SUNSET.

Creative Commons License

SUNSET - Sapienza University Networking framework for underwater Simulation, Emulation and real-life Testing by Roberto Petroccia (UWSN Group of SENSES Lab) is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.

All the researchers and developers using and supporting SUNSET can ask questions, solve problems and share ideas using the SUNSET user-group. Additionally details on how to register and use the group are provided HERE.

Virtual Machine

We provide also a complete virtual machine ("SUNSET.ova") that includes all the necessary tools, scripts and software to compile and run SUNSET.
You can download it from UWSN Group website at the following URL:

To login use the following credentials:

  • User: sunset
  • Password: sunset
For the root user the same password is used.

All the required software (ns-2, ns-Miracle) is provided and installed together with SUNSET for the x86 architecture.
The virtual machine includes also the WOSS interface (which is already installed). It allows to connect the Bellhop ray tracing software to model the underwater acoustic channel. The environmental files used by the Bellhop ray tracer are not provided in the ".ova" file to reduce the size of the virtual machine image, but can be downloaded following the instructions provided on the WOSS web page, which is available at

Using the provided virtual machine, it is very simple to compile and use SUNSET in simulation and emulation modes in a controlled environment to tune the network protocol parameters and to test and improve the protocol performance. Once this preparation and improvement phase is completed, the same code can be run in emulation mode on the PC or it can be cross-compiled for the target embedded device. The compiled libraries can be then copied to and executed (using the provided scripts) on the selected ARM device during lab tests or in field (at sea) experiments.

To install the provided virtual machine, your system must satisfy the following requirements:

  • Oracle VM Virtual Box installed (see or other virtualization software (e.g., other virtualization software supporting the use of .ova files).

  • CPU that supports PAE/NX functionality.

  • CPU that supports VT-x/AMD-V instructions.

At the moment the release does not include additonal modules, listed in the framework description, to control the operations of different acoustic modems, AUV navigation system and monitoring sensors. Researches and developers interested in these additional modules and possible extensions can contact the laboratory director or Roberto Petroccia.

We kindly ask researchers and developers using SUNSET for their research activities to acknowledge this paper "SUNSET version 2.0: Enhanced Framework for Simulation, Emulation and Real-life Testing of Underwater Wireless Sensor Networks."

Creative Commons License

SUNSET - Sapienza University Networking framework for underwater Simulation, Emulation and real-life Testing by Roberto Petroccia (UWSN Group of SENSES Lab) is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.

All the researchers and developers using and supporting SUNSET can ask questions, solve problems and share ideas using the SUNSET user-group. Additionally details on how to register and use the group are provided HERE.


Particularly acknowledgments go to:

for their collaboration and support during the development and validation of this framework.

A special thanks go to Chiara Petrioli, director of the SENSES Lab, which has contributed to the design of SUNSET and to Daniele Spaccini, member of the SENSES Lab, which has contributed to the development of the additional components listed in the framework description and to the releasing of the current version of the framework. Daniele Spaccini is also the author of some of the modules released in the current version of the SUNSET framework.


[1] -
C.Petrioli, R. Petroccia and D. Spaccini. "SUNSET version 2.0: Enhanced Framework for Simulation, Emulation and Real-life Testing of Underwater Wireless Sensor Networks," in Proceedings of ACM WUWNet 2013, (Kaohsiung, Taiwan), ACM, November 11--13, 2013. - [BIB] - [PDF]

[2] -
N. Baldo, F. Maguolo, M. Miozzo, M. Rossi, and M. Zorzi, "ns2-MIRACLE: A modular framework for multi-technology and cross-layer support in network simulator 2," in Proceedings of the 2nd International Conference on Performance Evaluation Methodologies and Tools, ValueTools 2007, Nantes, France, October 23–25 2007, pp. 1-8.

[3] -
R. Urick, Principles of Underwater Sound. McGraw-Hill, 1983.

[4] -
F. Guerra, P. Casari, and M. Zorzi, "World ocean simulation system (WOSS): a simulation tool for underwater networks with realistic propagation modeling," in Proceedings of the Fourth ACM International Workshop on UnderWater Networks, ser. WUWNet '09, Berkeley, California, USA, 3 November 2009, pp. 1--8.