Underwater channel model

doc/uwsn/build.sh

@@ -0,0 +1 @@
+latexmk -bibtex -pdf -pdflatex="pdflatex -halt-on-error -interaction=nonstopmode -shell-escape" -use-make channel.tex

doc/uwsn/channel.tex

@@ -0,0 +1,137 @@
+\documentclass[a4paper]{article}
+\usepackage{amsmath}
+\usepackage[utf8]{inputenc}
+\usepackage[english]{babel}
+\usepackage{cleveref}
+\usepackage{textcomp}
+\usepackage{graphicx}
+\usepackage[style=ieee]{biblatex}
+\addbibresource{channel.bib}
+
+
+\title{Channel models for terrestrial radio and acoustic underwater links}
+\author{Bálint Áron Üveges}
+\date{\today}
+
+\begin{document}
+\maketitle
+
+\section{Castalia's path loss model}
+Castalia utilizes the Log-distance path loss model:
+\begin{equation}
+    PL_{d} = PL_{d0} + 10.0 \cdot \gamma \cdot log_{10} \left( \frac{d}{d_0} \right) +  \mathcal{N}(0,\sigma) + \frac{\mathcal{N}(0,\sigma_{b})}{2}
+\label{eq:log_d_pl}
+\end{equation}
+In \eqref{eq:log_d_pl}, $PL_{d0}$ is the path loss at the reference distance $d_{0}$; $d$ is the length of the path; $\gamma$ is the path loss exponent; $\mathcal{N}$ is the Gaussian-distribution, $\sigma$ is the standard variance of shadow fading; whereas $\sigma_{b}$ is the standard variance of bidirectional path loss jitter.
+
+\section{Underwater acoustic channel path loss model}
+According to \cite{Stojanovic_2007}, the narrowband 
+
+\section{Castalia's parameters, bits and pieces}
+\subsection{Parameters}
+defaultChannel:
+\begin{itemize}
+    \item \texttt{signalDeliveryThreshold} -- threshold in dBm above which, wireless channel module is delivering signal messages to radio modules of individual nodes.
+\end{itemize}
+
+radio:
+\begin{itemize}
+    \item \texttt{carrierFreq} -- The carrier frequency in MHz.
+    \item \texttt{rssiIntegrationTime} -- rssiIntegrationTime = symbolsForRSSI * RXmode\textrightarrow bitsPerSymbol / RXmode \textrightarrow datarate
+    \item \texttt{timeToTxPacket} -- Provided by popAndSendToWirelessChannel(), calculated as: double txTime = ((double)(end \textrightarrow getByteLength() * 8.0f)) / RXmode \textrightarrow datarate; (in seconds)
+    \item \texttt{parameter file} -- Name, dataRate(kbps), modulationType, bitsPerSymbol, bandwidth(MHz), noiseBandwidth(KHz), noiseFloor(dBm), sensitivity(dBm), powerConsumed(mW)
+    \item \texttt{SNR2BER} -- method used to calculate BER based on SNR and the actual modulation.
+\end{itemize}
+
+\subsubsection{Packet traversal}
+Castalia's packet path is relatively simple in terms of utilized objects:
+MAC \textrightarrow Radio \textrightarrow Wireless Channel \textrightarrow Radio \textrightarrow MAC.
+
+\subsubsection{MAC}
+Castalia's T-MAC implementation depends on the \texttt{TX\_TIME} function call when determining timeouts. The function is: \texttt{(phyLayerOverhead + x)*1/(1000 * phyDataRate/8.0)}, and is interpreted in seconds.
+
+\subsubsection{Radio}
+The Radio module buffers incoming MAC packets, and schedules itself for sending. Each packet is broken into two parts: a \textit{begin} and an \textit{end} message. The begin message contains the output power in dBm, the frequency, bandwidth, modulation and encoding, whereas the end message contains the actual data and the physical frame overhead (as size?). The begin message is immediately sent to the wireless channel, whereas the end message is scheduled with \texttt{txTime} delay. The delay is calculated as \texttt{(double)(end->getByteLength() * 8.0f)) / RXmode->datarate;}
+
+\subsubsection{Physical Channel}
+Once receiving the \texttt{WC\_SIGNAL\_START}, the physical channel module iterates over all cells, and collects those, which are affected by the sender based on the signal delivery threshold and the received signal strength attenuated by the path loss. A copy of the begin message is also sent with the calculated received signal strength. The \texttt{WC\_SIGNAL\_END} part of the handling iterates over the collected nodes, and sends the end message to each node.
+
+\noindent \textbf{Note:} contrary to AquaSim, in Castalia there is no delay on the wireless channel. However, a feasible solution would be to delay both the begin and the end message based on the distance between the sender and the receiver.
+
+\noindent \textbf{Note 2:} Castalia's major "weakness" is that the pathloss between each node is static for the simulation run. Whereas it is recommended do repeat a simulation scenario multiple times \cite{Ritter_2011}, a more "living" channel model would be more beneficial. A solution could be that the Gaussian noise and the asymmetric noise is recalculated in case of each \texttt{WC\_SIGNAL\_START} message in the physical channel. 
+
+\subsubsection{Radio}
+The Radio module calculates bit errors and iterates through all received signals since the last end signal. Each signal's bit error is additively updated based on BER. If bit errors are not exceeded based on encoding, the packet s forwarded to the MAC layer with \texttt{PROCESSING\_DELAY} set to $0.00001$.
+
+\section{AquaSim's parameters, bits and pieces}
+\subsection{Packet traversal}
+
+Packets generated by an AquaSim node traverses along the data path illustrated in \cref{fig:aquasim-packet-path}. From propagation perspective, it is only relevant to analyze the traversal from the MAC layer.
+
+\begin{figure}[h]
+\centering
+\includegraphics[width=\textwidth]{aqua-sim-ng-packet-path.png}
+    \caption{Path of a packet traversing between different components}
+\label{fig:aquasim-packet-path}
+\end{figure}
+
+\subsubsection{\texttt{AquaSimMac::TxProcess}}
+The \texttt{TxProcess} is a virtual method, provided by the \texttt{AquaSimMac} class. In case of the \texttt{AquaSimBroadcastMac} class, it performs backoff or drops the packet if the device is not in \texttt{NIDLE} state. In \texttt{NIDLE} state, the MAC and AquaSim headers are added, the transmission time determined, and the \texttt{SendDown} method from the parent class is called.
+
+\subsubsection{\texttt{AquaSimMac::SendDown}}
+The \texttt{SendDown} method either sends the packet directly to the Radio, via \texttt{AquaSimPhy}'s \texttt{Recv} (\texttt{IDLE} state), queues the packet (\texttt{RECV} state), or drops the packet (\texttt{SLEEP} state). The method also addds the \texttt{AquaSimPacketStamp} header and schedules the \texttt{SetTransmissionStatus} method call once the transmission is finished.
+
+\subsubsection{\texttt{AquaSimPhy::Recv}}\label{sssec:radio_recv}
+In reality, the \texttt{Recv} method is implemented in the \texttt{AquaSimPhyCmn} class, derived from the \texttt{AquaSimPhy}. Depending on the direction encoded in the packet's AquaSim header, the packet is either handed to the \texttt{PktTransmit} method (\texttt{DOWN}), or after prevalidation detailed in \cref{sssec:prevalid}, queued into the \texttt{m\_sC} (\texttt{UP}).
+
+\subsubsection{\texttt{AquaSimPhy::PktTransmit}}
+Similarly to the \texttt{Recv} method, the \texttt{PktTransmit} is also implemented in the \texttt{AquaSimPhyCmn} class. The method performs checks with regards to failure state, \texttt{SLEEP} state, and energy level. It substracts the power used to perform Tx from the battery. Stamps TX info, that is, \texttt{m\_pT}, \texttt{m\_lambda}, \texttt{m\_freq}, and \texttt{m\_transRange}. It also adjusts \texttt{EM}'s TX power accordingly. The method also schedules a timer to return to \texttt{NIDLE} state based on the delay, calculated based on modulation and size. Finally, the method notifies the corresponding channel, indicating the channel ID to the \texttt{Recv} method.
+
+One interesting thing is, that the \texttt{m\_channel} is a vector of channel pointers (smart).
+
+\subsubsection{\texttt{AquaSimChannel::Recv}}
+The \texttt{Recv} method is just simply calling the \texttt{SendUp} method. Whereas the \texttt{Recv} returns a boolean value, it is not evaluated by the callee method, \texttt{PktTransmit}.
+
+\subsubsection{\texttt{AquaSimChannel::SendUp}}
+The \texttt{SendUp} method first collects all devices that may receive the signal. It is down by calling the \texttt{{ReceivedCopies}} method, detailed in \cref{sssec:reccop}. The result is not a simple array of devices, it is also annotated with delay and received power.
+
+The method iterates over all recipients, calculates delay (once again, however it is already done by \texttt{ReceivedCopies} at this stage), and retrieves the stamp from the packet. Based on the recipient's annotated data, it adds the received power to the stamp, adds noise and distance-based propagation delay. Finally, it schedules each copy to arrive at the corresponding device's Radio, with the calculated delay.
+
+The noise is calculated by the \texttt{AquaSimNoiseGen::Noise} method. The method utilizes the noise model described in \cite{Stojanovic_2007}, in section II.B. Whereas the model uses \textit{dB}, prior to returning with the result, the method raises the result to the power of $10$.
+
+The behaviour of the Radio's \texttt{Recv} module is already explained in \cref{sssec:radio_recv}.
+
+\subsubsection{\texttt{AquaSimPropagation::ReceivedCopies}}\label{sssec:reccop}
+The \texttt{RecievedCopies} inspects the stamp header to retrieve frequency and Tx power, calculates distance of the sender and all receivers and the Rx power and delay related to the Packet as it arrives to the receiver. Interestingly, no receivers are filtered based on the transmission range.
+
+\subsubsection{\texttt{AuqaSimPhy::PrevalidateIncomingPkt}}\label{sssec:prevalid}
+The \texttt{PrevalidateIncomingPkt} method performs frequency matching and device failure check. If the device is in \texttt{RECV} mode or the received signal strength does not exceed the RX threshold, the packet is flagged with error (\texttt{SetErrorFlag}) and the collision flag is set on Radio level. Otherwise the device is set to \texttt{RECV} state (without any prior check), and a call to \texttt{SetTransmissionStatus} is scheduled. Quite ambiguously, the state change's timer is calculated via the \texttt{CalcTxTime}, utilizing the AquaSim header's \texttt{size} property. The method also takes the preamble length into account and the modulation. The time is calculated per bit.
+
+The method also updates the energy consumption, but in this case with the AquaSim header's getTxTime results. The question is: why?
+
+Finally, if the packet is not flagged with error, it schedules the \texttt{CollisionCheck} method, but returns with a null pointer. However, if the method identifies failure, it returns a pointer to the packet.
+
+Note: Both the \texttt{CollisionCheck} method and the \texttt{Recv} schedules the packet to \texttt{m\_sC} variable (signal cache) with the \texttt{AddNewPacket} method.
+
+\subsubsection{\texttt{AquaSimSignalCache::AddNewPacket}}
+The \texttt{AddNewPacket} method performs check on the AquaSim header's error flag, and casts the packet as \texttt{IncomingPacket} with adding the information. The method calls the \texttt{AddNewSubmission} method, where based on AquaSim's header size the \texttt{Expire} method id scheduled, which calls the \texttt{SubmitPkt} method.
+
+The \texttt{AddNewPacket} method stores the packet in a linked list, as the first element.
+
+The method also adjusts the power strength (\textit{this is what (s)he said}) and calls the \texttt{UpdatePacketStatus} method. The aforementioned method iterates through the linked list of packets, and calculates the noise level, as $p_{noise} = p_{total} - p_{s}$, where $p_{total}$ is set to the value of the total RX power in the \texttt{AddNewSubmission} additively (\texttt{+=} operator), and the $p_{s}$ is also set to RX power, retrieved from the energy modul (model). The method calls the Radio's \texttt{Decodable}, that is just a guard method before calling the SINR checkerwith $\frac{p_{s}}{p_{noise}}$, evaluated against \texttt{m\_decThresh}, which is set to $0$.
+
+\subsubsection{\texttt{AquaSimSignalCache::SubmitPkt}}
+The \texttt{SubmitPkt} method calls the \texttt{DeleteIncomingPacket} method, which removes the packet from the linked list. The total energy is also decreased with the TX energy, retrieved from the EM module. If the packet is not invalidated until now by the noise or by the energy level, the \texttt{SignalCacheCallback} is called.
+
+\subsubsection{\texttt{AquaSimPhy::SignalCacheCallback}}
+The \texttt{SignalCacheCallback} updates the AquaSim header with TX time set to $0.1$ s and calls the \texttt{SendPktUp} method.
+
+\subsubsection{\texttt{AquaSimPhy::SendPktUp}}
+The \texttt{SendPktUp} method dispatches the packet based on the MAC header's \texttt{m\_demuxPType}. The field is set to \texttt{UWPTYPE\_OTHER} as default, and the method calls the MAC layer's \texttt{RecvProcess} method.
+
+\subsubsection{\texttt{AquaSimMac::RecvProcess}}
+The \texttt{RecvProcess} method evaluates the AquaSim header's error flag, and either discards the packet or forwards to the upper layer (at least in case of Broadcast MAC).
+
+
+\printbibliography
+\end{document}

src/node/communication/radio/Radio.h

@@ -234,6 +234,7 @@ class Radio: public CastaliaModule {
 	double readRSSI();
 	CCA_result isChannelClear();
     PktBreakdown getStats() { return stats; };
+    double  getCarrierFrequency() { return carrierFreq;};
 };
 
 #endif				//_RADIOMODULE_H_