--- a/src/uan/doc/uan.h Tue May 24 22:59:41 2011 -0700
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,203 +0,0 @@
-/* -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- */
-/*
- * Copyright (c) 2009 University of Washington
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation;
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- *
- * Author: Leonard Tracy <lentracy@gmail.com>
- */
-
-/**
- * \defgroup UAN UAN Models
- *
- * \section UanOverview UAN Framework Overview
- *
- * The main goal of the UAN Framework is to enable researchers to
- * model a variety of underwater network scenarios. The UAN model
- * is broken into four main parts: The channel, PHY, MAC and
- * Autonomous Underwater Vehicle (AUV) models.
- *
- *
- * \section UanPropOverview UAN Propagation Models
- *
- * Modelling of the underwater acoustic channel has been an active
- * area of research for quite some time. Given the complications involved,
- * surface and bottom interactions, varying speed of sound, etc..., the detailed
- * models in use for ocean acoustics research are much too complex
- * (in terms of runtime) for use in network level simulations. We have
- * attempted to provide the often used models as well as make an attempt to bridge, in part, the gap between
- * complicated ocean acoustic models and network level simulation. The three propagation
- * models included are the ideal channel model, the Thorp propagation model and
- * the Bellhop propagation model (Available as an addition).
- *
- * All of the Propagation Models follow the same simple interface in ns3::UanPropModel.
- * The propagation models provide a power delay profile (PDP) and pathloss
- * information. The PDP is retrieved using the GetPdp method which returns type UanPdp.
- * ns3::UanPdp utilises a tapped delay line model for the acoustic channel.
- * The UanPdp class is a container class for Taps, each tap has a delay and amplitude
- * member corresponding to the time of arrival (relative to the first tap arrival time)
- * and amplitude. The propagation model also provides pathloss between the source
- * and receiver in dB re 1uPa. The PDP and pathloss can then be used to find the
- * received signal power over a duration of time (i.e. received signal power in
- * a symbol duration and ISI which interferes with neighbouring signals). Both
- * UanPropModelIdeal and UanPropModelThorp return a single impulse for a PDP.
- *
- * a) Ideal Channel Model ns3::UanPropModelIdeal
- *
- * The ideal channel model assumes 0 pathloss inside a cylindrical area with bounds
- * set by attribute. The ideal channel model also assumes an impulse PDP.
- *
- * b) Thorp Propagation Model ns3::UanPropModelThorp
- *
- * The Thorp Propagation Model calculates pathloss using the well-known Thorp approximation.
- * This model is similar to the underwater channel model implemented in ns2 as described here:
- *
- * Harris, A. F. and Zorzi, M. 2007. Modeling the underwater acoustic channel in ns2. In Proceedings
- * of the 2nd international Conference on Performance Evaluation Methodologies and Tools
- * (Nantes, France, October 22 - 27, 2007). ValueTools, vol. 321. ICST (Institute for Computer
- * Sciences Social-Informatics and Telecommunications Engineering), ICST, Brussels, Belgium, 1-8.
- *
- * The frequency used in calculation however, is the center frequency of the modulation as found from
- * ns3::UanTxMode. The Thorp Propagation Model also assumes an impulse channel response.
- *
- * c) Bellhop Propagation Model ns3::UanPropModelBh (Available as an addition)
- *
- * The Bellhop propagation model reads propagation information from a database. A configuration
- * file describing the location, and resolution of the archived information must be supplied via
- * attributes. We have included a utility, create-dat, which can create these data files using the Bellhop
- * Acoustic Ray Tracing software (http://oalib.hlsresearch.com/).
- *
- * The create-dat utility requires a Bellhop installation to run. Bellhop takes
- * environment information about the channel, such as sound speed profile, surface height
- * bottom type, water depth, and uses a gaussian ray tracing algorithm to determine
- * propagation information. Arrivals from Bellhop are grouped together into equal length
- * taps (the arrivals in a tap duration are coherently summed). The maximum taps are then
- * aligned to take the same position in the PDP. The create-dat utility averages together
- * several runs and then normalizes the average such that the sum of all taps is 1. The same
- * configuration file used to create the data files using create-dat should be passed via
- * attribute to the Bellhop Propagation Model.
- *
- * The Bellhop propagation model is available as a patch. The link address will be
- * made available here when it is posted online. Otherwise email lentracy@gmail.com
- * for more information.
- *
- *
- * \section UanPhyOverview UAN PHY Model Overview
- *
- * The PHY has been designed to allow for relatively easy extension
- * to new networking scenarios. We feel this is important as, to date,
- * there has been no commonly accepted network level simulation model
- * for underwater networks. The lack of commonly accepted network simulation
- * tools has resulted in a wide array of simulators and models used to report
- * results in literature. The lack of standardization makes comparing results
- * nearly impossible.
- *
- * The main component of the PHY Model is the generic
- * PHY class, ns3::UanPhyGen. The PHY class's general responsibility
- * is to handle packet acquisition, error determination, and forwarding of successful
- * packets up to the MAC layer. The Generic PHY uses two models for determination
- * of signal to noise ratio (SINR) and packet error rate (PER). The
- * combination of the PER and SINR models determine successful reception
- * of packets. The PHY model connects to the channel via a Transducer class.
- * The Transducer class is responsible for tracking all arriving packets and
- * departing packets over the duration of the events. How the PHY class and the PER and SINR models
- * respond to packets is based on the "Mode" of the transmission as described by the ns3::UanTxMode
- * class.
- *
- * When a MAC layer sends down a packet to the PHY for transmission it specifies a "mode number" to
- * be used for the transmission. The PHY class accepts, as an attribute, a list of supported modes. The
- * mode number corresponds to an index in the supported modes. The UanTxMode contains simple modulation
- * information and a unique string id. The generic PHY class will only acquire arriving packets which
- * use a mode which is in the supported modes list of the PHY. The mode along with received signal power,
- * and other pertinent attributes (e.g. possibly interfering packets and their modes) are passed to the SINR
- * and PER models for calculation of SINR and probability of error.
- *
- * Several simple example PER and SINR models have been created.
- * a) The PER models
- * - Default (simple) PER model (ns3::UanPhyPerGenDefault): The Default PER model tests the packet against a threshold and
- * assumes error (with prob. 1) if the SINR is below the threshold or success if the SINR is above
- * the threshold
- * - Micromodem FH-FSK PER (ns3::UanPhyPerUmodem). The FH-FSK PER model calculates probability of error assuming a
- * rate 1/2 convolutional code with constraint length 9 and a CRC check capable of correcting
- * up to 1 bit error. This is similar to what is used in the receiver of the WHOI Micromodem.
- *
- * b) SINR models
- * - Default Model (ns3::UanPhyCalcSinrDefault), The default SINR model assumes that all transmitted energy is captured at the receiver
- * and that there is no ISI. Any received signal power from interferes acts as additional
- * ambient noise.
- * - FH-FSK SINR Model (ns3::UanPhyCalcSinrFhFsk), The WHOI Micromodem operating in FH-FSK mode uses a predetermined hopping
- * pattern that is shared by all nodes in the network. We model this by only including signal
- * energy receiving within one symbol time (as given by ns3::UanTxMode) in calculating the
- * received signal power. A channel clearing time is given to the FH-FSK SINR model via attribute.
- * Any signal energy arriving in adjacent signals (after a symbol time and the clearing time) is
- * considered ISI and is treated as additional ambient noise. Interfering signal arrivals inside
- * a symbol time (any symbol time) is also counted as additional ambient noise
- * - Frequency filtered SINR (ns3::UanPhyCalcSinrDual). This SINR model calculates SINR in the same manner
- * as the default model. This model however only considers interference if there is an overlap in frequency
- * of the arriving packets as determined by UanTxMode.
- *
- * In addition to the generic PHY a dual phy layer is also included (ns3::UanPhyDual). This wraps two
- * generic phy layers together to model a net device which includes two receivers. This was primarily
- * developed for UanMacRc, described in the next section.
- *
- *\section UanMAC UAN MAC Model Overview
- *
- * Over the last several years there have been a myriad of underwater MAC proposals
- * in the literature. We have included three MAC protocols with this distribution:
- * a) CW-MAC, a MAC protocol which uses a slotted contention window similar in nature to
- * the IEEE 802.11 DCF. Nodes have a constant contention window measured in slot times (configured
- * via attribute). If the channel is sensed busy, then nodes backoff by randomly (uniform distribution) choose
- * a slot to transmit in. The slot time durations are also configured via attribute. This MAC was described in
- *
- * Parrish N.; Tracy L.; Roy S. Arabshahi P.; and Fox, W., System Design Considerations for Undersea Networks:
- * Link and Multiple Access Protocols , IEEE Journal on Selected Areas in Communications (JSAC), Special
- * Issue on Underwater Wireless Communications and Networks, Dec. 2008.
- *
- * b) RC-MAC (ns3::UanMacRc ns3::UanMacRcGw) a reservation channel protocol which dynamically divides
- * the available bandwidth into a data channel and a control channel. This MAC protocol
- * assumes there is a gateway node which all network traffic is destined for. The current
- * implementation assumes a single gateway and a single network neighborhood (a single hop network).
- * RTS/CTS handshaking is used and time is divided into cycles. Non-gateway nodes transmit RTS packets
- * on the control channel in parallel to data packet transmissions which were scheduled in the previous cycle
- * at the start of a new cycle, the gateway responds on the data channel with a CTS packet which includes
- * packet transmission times of data packets for received RTS packets in the previous cycle as well as bandwidth
- * allocation information. At the end of a cycle ACK packets are transmitted for received data packets.
- *
- * When a publication is available it will be cited here.
- *
- * c) Simple ALOHA (ns3::UanMacAloha) Nodes transmit at will.
- *
- * \section UanAUV UAN AUV Model Overview
- *
- * Since AUVs are one of the main components of an underwater networking application, we have included
- * two models of the most used AUVs, the Seaglider and the REMUS.
- *
- * An AUV model includes a mobility model that reproduces the navigation capabilities of the AUV, two energy model
- * that reproduce the energy consumption of the AUV and the communication device.
- *
- * a) mobility models are ns3::RemusMobilityModel and ns3::GliderMobilityModel
- *
- * b) auv energy models are ns3::RemusEnergyModel and ns3::GliderEnergyModel. Those models, interacting
- * with the associated mobility models, keep track of an AUV navigation energy consumption. The energy
- * consumption varies accordingly to the navigation parameter such as speed (in case of REMUS) and
- * buoyancy and vertical speed (in case of Seaglider)
- *
- * c) transducer energy model is ns3::AcousticModemEnergyModel, it keeps track of the energy consumed
- * by the acoustic transducer accordingly to its state. The specific energy consumption values are the ones of
- * the WHOI Micro Modem.
- *
- * For a complete description of AUV mobility models, energy models, energy sources and examples please refer to
- * the <a href="http://www.nsnam.org/wiki/index.php/GSOC2010UANFramework">wiki page</a>
- *
- */
--- a/src/uan/doc/uan.rst Tue May 24 22:59:41 2011 -0700
+++ b/src/uan/doc/uan.rst Tue May 24 23:24:56 2011 -0700
@@ -1,12 +1,15 @@
UAN Framework
-------------
-Underwater Acoustics Networks is a research field that, in the last year, is gathering attention from researchers all over the world. In fact, the need for underwater wireless communications exists in applications such as remote control in offshore oil industry [1]_, pollution monitoring in environmental systems, speech transmission between divers, mapping of the ocean floor, mine counter measures [4]_, seismic monitoring of ocean faults as well as climate changes monitoring. Unfortunately, making on-field measurements is very expensive and there are no commonly accepted standard to base on. Hence, the priority to make research work going on, it is to realize a complete simulation framework that researchers can use to experiment, make tests and make performance evaluation and comparison.
+The main goal of the UAN Framework is to enable researchers to
+model a variety of underwater network scenarios. The UAN model
+is broken into four main parts: The channel, PHY, MAC and
+Autonomous Underwater Vehicle (AUV) models.
+
+The need for underwater wireless communications exists in applications such as remote control in offshore oil industry [1]_, pollution monitoring in environmental systems, speech transmission between divers, mapping of the ocean floor, mine counter measures [4]_, seismic monitoring of ocean faults as well as climate changes monitoring. Unfortunately, making on-field measurements is very expensive and there are no commonly accepted standard to base on. Hence, the priority to make research work going on, it is to realize a complete simulation framework that researchers can use to experiment, make tests and make performance evaluation and comparison.
The NS-3 UAN module is a first step in this direction, trying to offer a reliable and realistic tool. In fact, the UAN module offers accurate modelling of the underwater acoustic channel, a model of the WHOI acoustic modem (one of the widely used acoustic modems)[6]_ and its communications performance, and some MAC protocols.
-This project integrates the efforts of UAN module, extending it to make a simulation framework that researchers will be able to use for their aims. The extension consists of an Autonomous Underwater Vehicle (AUV) simulator (navigation and movement) along with an implementation of AUV batteries. Moreover, it will be implemented, a power model for a generic acoustic modem and, the physicals layers will be modified to use such model. For the moment, the UAN module can be used to make some sort of performance comparisons of the available MAC protocols, or tests the communication channel. With this extension, researchers will be able to use the framework to develop and evaluate their "applications". An application, is intended as a more complete concept, including each parts of the UAN module integrated with the framework's extensions. Then, the final result is a complete simulation stack for underwater network applications.
-
Model Description
*****************
@@ -26,8 +29,155 @@
Design
======
-The development of the UAN Framework for ns-3 is composed by three consecutive steps. The first one is the development of the AUV simulator, the second one is the development of the UAN energy models and the third one is the integration of such components with the existing modules, UAN module and Energy Model. The module is implemented into the ``/src/uan`` folder for the part regarding acoustic modem energy model and the part regarding the AUV simulator.
+UAN Propagation Models
+######################
+Modelling of the underwater acoustic channel has been an active
+area of research for quite some time. Given the complications involved,
+surface and bottom interactions, varying speed of sound, etc..., the detailed
+models in use for ocean acoustics research are much too complex
+(in terms of runtime) for use in network level simulations. We have
+attempted to provide the often used models as well as make an attempt to bridge, in part, the gap between
+complicated ocean acoustic models and network level simulation. The three propagation
+models included are the ideal channel model, the Thorp propagation model and
+the Bellhop propagation model (Available as an addition).
+
+All of the Propagation Models follow the same simple interface in ``ns3::UanPropModel``.
+The propagation models provide a power delay profile (PDP) and pathloss
+information. The PDP is retrieved using the GetPdp method which returns type UanPdp.
+``ns3::UanPdp`` utilises a tapped delay line model for the acoustic channel.
+The UanPdp class is a container class for Taps, each tap has a delay and amplitude
+member corresponding to the time of arrival (relative to the first tap arrival time)
+and amplitude. The propagation model also provides pathloss between the source
+and receiver in dB re 1uPa. The PDP and pathloss can then be used to find the
+received signal power over a duration of time (i.e. received signal power in
+a symbol duration and ISI which interferes with neighbouring signals). Both
+UanPropModelIdeal and UanPropModelThorp return a single impulse for a PDP.
+
+a) Ideal Channel Model ``ns3::UanPropModelIdeal``
+
+The ideal channel model assumes 0 pathloss inside a cylindrical area with bounds
+set by attribute. The ideal channel model also assumes an impulse PDP.
+
+b) Thorp Propagation Model ``ns3::UanPropModelThorp``
+
+The Thorp Propagation Model calculates pathloss using the well-known Thorp approximation.
+This model is similar to the underwater channel model implemented in ns2 as described here:
+
+Harris, A. F. and Zorzi, M. 2007. Modeling the underwater acoustic channel in ns2. In Proceedings
+of the 2nd international Conference on Performance Evaluation Methodologies and Tools
+(Nantes, France, October 22 - 27, 2007). ValueTools, vol. 321. ICST (Institute for Computer
+Sciences Social-Informatics and Telecommunications Engineering), ICST, Brussels, Belgium, 1-8.
+
+The frequency used in calculation however, is the center frequency of the modulation as found from
+ns3::UanTxMode. The Thorp Propagation Model also assumes an impulse channel response.
+
+c) Bellhop Propagation Model ``ns3::UanPropModelBh`` (Available as an addition)
+
+The Bellhop propagation model reads propagation information from a database. A configuration
+file describing the location, and resolution of the archived information must be supplied via
+attributes. We have included a utility, create-dat, which can create these data files using the Bellhop
+Acoustic Ray Tracing software (http://oalib.hlsresearch.com/).
+
+The create-dat utility requires a Bellhop installation to run. Bellhop takes
+environment information about the channel, such as sound speed profile, surface height
+bottom type, water depth, and uses a gaussian ray tracing algorithm to determine
+propagation information. Arrivals from Bellhop are grouped together into equal length
+taps (the arrivals in a tap duration are coherently summed). The maximum taps are then
+aligned to take the same position in the PDP. The create-dat utility averages together
+several runs and then normalizes the average such that the sum of all taps is 1. The same
+configuration file used to create the data files using create-dat should be passed via
+attribute to the Bellhop Propagation Model.
+
+The Bellhop propagation model is available as a patch. The link address will be
+made available here when it is posted online. Otherwise email lentracy@gmail.com
+for more information.
+
+UAN PHY Model Overview
+######################
+
+The PHY has been designed to allow for relatively easy extension
+to new networking scenarios. We feel this is important as, to date,
+there has been no commonly accepted network level simulation model
+for underwater networks. The lack of commonly accepted network simulation
+tools has resulted in a wide array of simulators and models used to report
+results in literature. The lack of standardization makes comparing results
+nearly impossible.
+The main component of the PHY Model is the generic
+PHY class, ``ns3::UanPhyGen``. The PHY class's general responsibility
+is to handle packet acquisition, error determination, and forwarding of successful
+packets up to the MAC layer. The Generic PHY uses two models for determination
+of signal to noise ratio (SINR) and packet error rate (PER). The
+combination of the PER and SINR models determine successful reception
+of packets. The PHY model connects to the channel via a Transducer class.
+The Transducer class is responsible for tracking all arriving packets and
+departing packets over the duration of the events. How the PHY class and the PER and SINR models
+respond to packets is based on the "Mode" of the transmission as described by the ``ns3::UanTxMode``
+class.
+
+When a MAC layer sends down a packet to the PHY for transmission it specifies a "mode number" to
+be used for the transmission. The PHY class accepts, as an attribute, a list of supported modes. The
+mode number corresponds to an index in the supported modes. The UanTxMode contains simple modulation
+information and a unique string id. The generic PHY class will only acquire arriving packets which
+use a mode which is in the supported modes list of the PHY. The mode along with received signal power,
+and other pertinent attributes (e.g. possibly interfering packets and their modes) are passed to the SINR
+and PER models for calculation of SINR and probability of error.
+
+Several simple example PER and SINR models have been created.
+a) The PER models
+ - Default (simple) PER model (``ns3::UanPhyPerGenDefault``): The Default PER model tests the packet against a threshold and
+ assumes error (with prob. 1) if the SINR is below the threshold or success if the SINR is above
+ the threshold
+ - Micromodem FH-FSK PER (``ns3::UanPhyPerUmodem``). The FH-FSK PER model calculates probability of error assuming a
+ rate 1/2 convolutional code with constraint length 9 and a CRC check capable of correcting
+ up to 1 bit error. This is similar to what is used in the receiver of the WHOI Micromodem.
+
+b) SINR models
+- Default Model (``ns3::UanPhyCalcSinrDefault``), The default SINR model assumes that all transmitted energy is captured at the receiver
+ and that there is no ISI. Any received signal power from interferes acts as additional
+ ambient noise.
+- FH-FSK SINR Model (``ns3::UanPhyCalcSinrFhFsk``), The WHOI Micromodem operating in FH-FSK mode uses a predetermined hopping
+ pattern that is shared by all nodes in the network. We model this by only including signal
+ energy receiving within one symbol time (as given by ``ns3::UanTxMode``) in calculating the
+ received signal power. A channel clearing time is given to the FH-FSK SINR model via attribute.
+ Any signal energy arriving in adjacent signals (after a symbol time and the clearing time) is
+ considered ISI and is treated as additional ambient noise. Interfering signal arrivals inside
+ a symbol time (any symbol time) is also counted as additional ambient noise
+- Frequency filtered SINR (``ns3::UanPhyCalcSinrDual``). This SINR model calculates SINR in the same manner
+ as the default model. This model however only considers interference if there is an overlap in frequency
+ of the arriving packets as determined by UanTxMode.
+
+In addition to the generic PHY a dual phy layer is also included (``ns3::UanPhyDual``). This wraps two
+generic phy layers together to model a net device which includes two receivers. This was primarily
+developed for UanMacRc, described in the next section.
+
+UAN MAC Model Overview
+######################
+
+Over the last several years there have been a myriad of underwater MAC proposals
+in the literature. We have included three MAC protocols with this distribution:
+a) CW-MAC, a MAC protocol which uses a slotted contention window similar in nature to
+the IEEE 802.11 DCF. Nodes have a constant contention window measured in slot times (configured
+via attribute). If the channel is sensed busy, then nodes backoff by randomly (uniform distribution) choose
+a slot to transmit in. The slot time durations are also configured via attribute. This MAC was described in
+
+Parrish N.; Tracy L.; Roy S. Arabshahi P.; and Fox, W., System Design Considerations for Undersea Networks:
+Link and Multiple Access Protocols , IEEE Journal on Selected Areas in Communications (JSAC), Special
+Issue on Underwater Wireless Communications and Networks, Dec. 2008.
+
+b) RC-MAC (``ns3::UanMacRc`` ``ns3::UanMacRcGw``) a reservation channel protocol which dynamically divides
+the available bandwidth into a data channel and a control channel. This MAC protocol
+assumes there is a gateway node which all network traffic is destined for. The current
+implementation assumes a single gateway and a single network neighborhood (a single hop network).
+RTS/CTS handshaking is used and time is divided into cycles. Non-gateway nodes transmit RTS packets
+on the control channel in parallel to data packet transmissions which were scheduled in the previous cycle
+at the start of a new cycle, the gateway responds on the data channel with a CTS packet which includes
+packet transmission times of data packets for received RTS packets in the previous cycle as well as bandwidth
+allocation information. At the end of a cycle ACK packets are transmitted for received data packets.
+
+When a publication is available it will be cited here.
+
+c) Simple ALOHA (``ns3::UanMacAloha``) Nodes transmit at will.
AUV mobility models
###################
--- a/src/uan/model/uan-net-device.h Tue May 24 22:59:41 2011 -0700
+++ b/src/uan/model/uan-net-device.h Tue May 24 23:24:56 2011 -0700
@@ -35,6 +35,12 @@
class UanTransducer;
/**
+ * \defgroup uan UAN Models
+ * This section documents the API of the ns-3 UAN module. For a generic functional description, please refer to the ns-3 manual.
+ */
+
+/**
+ * \ingroup uan
* \class UanNetDevice
*
* \brief Net device for UAN models