comm package¶
Submodules¶
Module contents¶
This package provides three modules:
transceiver: it contains a number of transceiver classes suitable for various scenarios. When constructing a node, the node should ideally add a transceiver to enable communication. A transceiver must pair with an appropriate channel to function correctly.
channel: it contains various channel models. The purpose of a channel is to describe signal propagation. Various models use different propagation model to capture the signal attenuation during the propagation.
signal: it acts as the data structure for transceiver and channel to communicate. When a user performs a transmission using a transceiver, the transceiver prepares the signal and passes it to the channel to perform propagation. The channel modify or write information on the signal to describe the propagation. After which, the transceiver passes the propagated signal to the receiving side for detection. The receiver transceiver then reads the signal to decide whether the received signal can be decoded successfully.
For example, using Transceiver, DiscModel as the channel model, and QualityBasedSignal as the signalwave, the procedure of a transmission can be described as follows:
User Simulation creates a signal
| and sends to Sender Transceiver for transmission
| |
| V
| Sender Transceiver writes `distance` to the signal
| | and passes the signal to the channel for propagation
| | |
| | V
| | The channel reads `distance` and compare to its coverage radius,
| | ^ The channel writes `quality` to the signal accordingly
| | | | and returns back to Sender Transceiver
| | | | |
| | | | V
| | | | Sender Transceiver passes the signal to Receiver Transceiver
| | | | |
| | | | V
| | | | Receiver Tranceiver reads `quality` and returns the outcome
| | | | ^ of decodeability to Sender Tranceiver
| | | | | |
| | | | | V
| | | | | Sender Transceiver processes Receiver's outcome
V V | V | and inform User Simulation the final outcome
[=====QualityBasedSignal=====]
-------------------------------------------------------------------------------> time
The transmission process at the Sender Transceiver:
def multicast(self, signal:QualityBasedSignal, node_list):
'''This method allows a node to perform a multicast on the channel,
and the method returns a list of tuple (node,received_signal)
that the multicast signal can be decoded, or None if no node can
decode the signal.
Note that this method can be used for unicast by putting a single node
in `node_list`.
Parameters
----------
signal : :class:`comm.signalwave.QualityBasedSignal`
The signal to be transmitted. Use `create_signal()` method to create one.
node_list : a list of :class:`node.node.BaseNode` subclass
The list containing the nodes to receive the multicast signal
Returns
-------
A list of tuple (:class:`node.node.BaseNode`, :class:`comm.signalwave.QualityBasedSignal`)
It returns a list of (node,signal) that the node can decode the
signal.
'''
receiver_list = []
for destination in node_list:
sent_signal = signal.copy()
source_loc = self._node.get("location")
dest_loc = destination.get("location")
sent_signal.distance = source_loc.distance_to(dest_loc)
sent_signal.LOS_dir = source_loc.azimuth_to(dest_loc)
self._channel.do_propagation(sent_signal)
if destination.get("transceiver").can_detect(sent_signal):
receiver_list.append((destination,sent_signal))
return receiver_list
The DiscModel channel propagation model:
def do_propagation(self, signal:QualityBasedSignal) -> QualityBasedSignal:
'''This method derives the received signal after its propagation.
In this implementation, `signal` is used as the data structure for inputs
and outputs. `signal` contains `distance` and `LOS_dir` class properties
for this method to read and derive the propagation. It also contains
`quality` class property for this method to recorded the signal quality
after the propagation.
In this class, the quality of the signal is related to the distance
between the sender and the receiver, and normalized to 1.
When receiver is located at the sender, signal quality is 1 (i.e. the best),
and when the receiver is at or outside the edge of the radiation disc,
the signal quality is 0 (i.e. no connection).
Parameters
----------
signal : :class:`comm.signalwave.QualityBasedSignal`
The transmitted signal. This instance will be modified appropriately
within this method. The modification describes how the signal would
be attenuated and distorted.
Returns
-------
comm.signalwave.QualityBasedSignal
The received `signal` instance. The `quality` property contains a value
between 0 and 1 indicating the signal quality. The value is linear to the
distance between the transmitter and receiver, 1 being zero distance and 0
being the distance that the signal can no longer reach the receiver.
'''
if signal.distance>self._radius: # too far
signal.quality = 0
else:
signal.quality = 1 - (signal.distance/self._radius)
return signal
The detection process at the Receiver Transceiver:
def can_detect(self, signal) -> bool:
'''See also the base class for description, this method allows a receiving node to
check if a receiving signal can be successfully detected and decoded. In this
implementation, it checks if the signal quality is zero for failed decoding, and
any non-zero positive value for successful decoding.'''
if signal.freq==self._freq and signal.quality>0: # 0 is the quality threshold
return True
return False
The following modules can be imported directly from comm package:
from comm import Transceiver, TransceiverDir
from comm import UserTransceiver
from comm import DiscModel
Note
There are other advanced transceiver modules in the package, we’ll let users import corresponding ones based on the need.