comm.transceiver module

Module transceiver contains Transceiver class which interacts with a channel. Each transceiver must carry a Channel. The operations related to a transmission that a transceiver can do includes:

  • create_signal(): to create a signal for transmission. It is an abstract method in the base class.

  • multicast(): to multicast a created signal from this transceiver. This method can also be used for unicast. It is an abstract method in the base class.

  • can_detect(): to check if an arriving signal can be detected and decoded. It is an abstract method in the base class.

  • broadcast(): to broadcast a created signal from this transceiver.

  • unicast(): to unicast a created signal from this transceiver to another node. by the receiving transceiver.

Note

  • Created by: CH Foh (2021)

List of Classes

BaseTransceiver

This is the base transceiver. It provides specification and several useful methods.

Transceiver

This is a simple omnidirectional transceiver design. It uses comm.signalwave.QualityBasedSignal.

TransceiverDir

This is a simple directional transceiver design. It uses comm.signalwave.QualityBasedSignal.

UserTransceiver

This is a user-defined transceiver design. It allows the user to specify a callback function to perform the signal propagation and detection logic at the user simulation level.

class comm.transceiver.BaseTransceiver(node, freq, channel)

Bases: abc.ABC

This is a class providing functions to simulate transceiver operations.

Methods

broadcast(signal)

This method allows a node to perform a broadcast on the channel, and the method returns a list of tuple (node,received_signal) that the broadcast signal can be decoded, or None if no node can decode the signal.

can_detect(signal)

This method allows a receiving node to check if a receiving signal can be successfully detected and decoded.

create_signal()

Create a signal for transmission.

get_carrier_freq()

Return the carrier frequency used by the channel.

get_property([property])

The method returns the property of the transceiver.

get_type()

This method returns the type of the transceiver.

multicast(signal, 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 decoded, or an empty list if no node can decode the signal.

set_property(key, value)

Set a property to this transceiver.

unicast(signal, node)

This method allows a node to perform a unicast on the channel, and the method returns a received_signal if the signal can be decoded, or None.
__init__(node, freq, channel)

This is the constructor.

Parameters
nodenode.node.BaseNode subclass

The node that contains the transceiver.

freqfloat

Carrier frequency of the transceiver.

channelcomm.channel.BaseChannel subclass

The channel that the transceiver uses.

get_carrier_freq()

Return the carrier frequency used by the channel.

float

The frequency used by the channel.

abstract create_signal()

Create a signal for transmission. This is an abstract method to be properly implemented in the subclass.

abstract multicast(signal, 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 decoded, or an empty list if no node can decode the signal. This is an abstract method to be properly implemented in the subclass.

abstract can_detect(signal) → bool

This method allows a receiving node to check if a receiving signal can be successfully detected and decoded. In practice, a receiving signal can be decoded if its SNR passes a specific threshold.

broadcast(signal)

This method allows a node to perform a broadcast on the channel, and the method returns a list of tuple (node,received_signal) that the broadcast signal can be decoded, or None if no node can decode the signal. This method uses multicast() with all nodes in the simulation world to achieve broadcast.

unicast(signal, node)

This method allows a node to perform a unicast on the channel, and the method returns a received_signal if the signal can be decoded, or None. This method uses multicast() with a single node in the list to achieve unicast.

Returns
comm.signalwave.BaseSignal subclass

The received signal after the unicasting.

get_type()

This method returns the type of the transceiver.

Returns
str

The type of the transceiver.

get_property(property=None)

The method returns the property of the transceiver. If input property is not given it returns a dictionary containing all properties of this transceiver. Currently, it is used to store illustrative coverage that can be retrieved and illustrated on the animation during simulation.

The property list given in dict used in this module includes the following:

## default (inherited from BaseTransceiver and left unchanged)
{
    "type": "unknown",
    "freq": carrier_frequency,
}

## omni directional transmission
{
    "type": "omni",
    "freq": carrier_frequency,
    "radius": the_radius_in_pixel
}

## directional transmission
{
    "type": "directional",
    "freq": carrier_frequency,
    "radius": the_radius_in_num_of_pixel,
    "azimuth": the_pointing_direction_in_degree,
    "beam width": the_beam_width_in_degree
}

## user-defined default properties
{
    "type": "user-defined"
    "freq": carrier_frequency
}
Parameters
propertystr, optional, default=None

The property to get. If no property is given, it returns all properties in a form of dictionary.

Returns
Value or Dict

If the input property is specified, the corresponding value will be returned, or None is returned if not found. If no property is given, A dictionary containing all properties of this transceiver will be returned. The dictionary will contain a key type to describe the type used for this transceiver.

set_property(key, value)

Set a property to this transceiver. If key already exists, its value will be replaced. This property storage facilitates keeping of any information during the creation time that can be retrieved during the simulation time, for example illustrative coverage of the transceiver.

Parameters
keyany

The key to use for the property. Ideally, it should be a str.

valueany

The value for the given key.

class comm.transceiver.Transceiver(node, freq, channel)

Bases: comm.transceiver.BaseTransceiver

This is a class providing functions to simulate transceiver operations.

Methods

broadcast(signal)

This method allows a node to perform a broadcast on the channel, and the method returns a list of tuple (node,received_signal) that the broadcast signal can be decoded, or None if no node can decode the signal.

can_detect(signal)

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.

create_signal()

Create a signal for transmissioin.

get_carrier_freq()

Return the carrier frequency used by the channel.

get_property([property])

The method returns the property of the transceiver.

get_type()

This method returns the type of the transceiver.

multicast(signal, 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.

set_property(key, value)

Set a property to this transceiver.

unicast(signal, node)

This method allows a node to perform a unicast on the channel, and the method returns a received_signal if the signal can be decoded, or None.
__init__(node, freq, channel)

This is the constructor.

Parameters
nodenode.node.BaseNode subclass

The node that contains the transceiver.

freqfloat

Carrier frequency of the transceiver.

channelcomm.channel.BaseChannel subclass

The channel that the transceiver uses.

create_signal() → comm.signalwave.QualityBasedSignal

Create a signal for transmissioin.

multicast(signal: comm.signalwave.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
signalcomm.signalwave.QualityBasedSignal

The signal to be transmitted. Use create_signal() method to create one.

node_lista list of node.node.BaseNode subclass

The list containing the nodes to receive the multicast signal

Returns
A list of tuple (node.node.BaseNode, comm.signalwave.QualityBasedSignal)

It returns a list of (node,signal) that the node can decode the signal.

can_detect(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.

class comm.transceiver.TransceiverDir(node, freq, channel, beam_width, azimuth)

Bases: comm.transceiver.BaseTransceiver

This is a class providing functions to simulate transceiver operations with directional antenna. Its transmission and receiption are directional.

Methods

broadcast(signal)

This method allows a node to perform a broadcast on the channel, and the method returns a list of tuple (node,received_signal) that the broadcast signal can be decoded, or None if no node can decode the signal.

can_detect(signal)

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.

create_signal()

Create a signal for transmissioin.

get_carrier_freq()

Return the carrier frequency used by the channel.

get_property([property])

The method returns the property of the transceiver.

get_type()

This method returns the type of the transceiver.

multicast(signal, 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.

set_property(key, value)

Set a property to this transceiver.

unicast(signal, node)

This method allows a node to perform a unicast on the channel, and the method returns a received_signal if the signal can be decoded, or None.
__init__(node, freq, channel, beam_width, azimuth)

This is the constructor.

Parameters
nodenode.node.BaseNode subclass

The node that contains the transceiver.

freqfloat

Carrier frequency of the transceiver.

channelcomm.channel.BaseChannel subclass

The channel that the transceiver uses.

beam_widthfloat

The beam width (in degrees) of the sector model. Setting it to 360 will turn it to omnidirectional setup.

azimuthfloat

The pointing direction of the beam. Setting 0 degree means north pointing, the degree indicates clockwise angle from the north.

create_signal() → comm.signalwave.QualityBasedSignal

Create a signal for transmissioin.

multicast(signal: comm.signalwave.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
signalcomm.signalwave.QualityBasedSignal

The signal to be transmitted. Use create_signal() method to create one.

node_lista list of node.node.BaseNode subclass

The list containing the nodes to receive the multicast signal

Returns
A list of tuple (node.node.BaseNode, comm.signalwave.QualityBasedSignal)

It returns a list of (node,signal) that the node can decode the signal. signal.quality contains the signal quality from 0 to 1, where 0 indicates cannot be decoded, 1 indicates highest quality.

can_detect(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, for unsuccessful decoding, it checks firstly if the signal quality is zero, then checks if the travelling direction is covered by the sector covering direction.

class comm.transceiver.UserTransceiver(node, freq)

Bases: comm.transceiver.BaseTransceiver

This abstract class provides a transceiver specification allowing user to define its behaviour. This class should be extended to a subclass for actual use. Besides, this class should use a signal extended from comm.signalwave.BaseSignal. A simple choice is to use comm.signalwave.QualityBasedSignal. By default, this class provides create_signal() to create a signal of comm.signalwave.QualityBasedSignal.

The transceiver provides unicast(), multicast() and broadcast() methods for a transmitter to transmit a signal to others. The signal will be delivered to all relevant transceiver instances to process. For broadcast(), all transceivers will receive the signal. For unicast() or multicast(), only those specified as a receiver will receive the signal.

The subclass must implement the following abstract method:

def can_detect(self, signal) -> bool

The above method is a listener listening to any incoming signal. It is called when there is a signal arriving to this transceiver. The subclass must implement the signal propagation and detection logic, and eventually return a True/False to indicate whether the signal can be detected successfully. The signal input is a copy of the transmitted signal which can be modified after the propagation and detection. The signal will eventually be returned back to the user simulation for any further evaluation.

Parameters
nodenode.node.BaseNode subclass

The node that contains the transceiver.

freqfloat

Carrier frequency of the transceiver.

Methods

broadcast(signal)

This method allows a node to perform a broadcast on the channel, and the method returns a list of tuple (node,received_signal) that the broadcast signal can be decoded, or None if no node can decode the signal.

can_detect(signal)

This method allows a receiving node to check if a receiving signal can be successfully detected and decoded.

create_signal()

Create a signal for transmissioin.

get_carrier_freq()

Return the carrier frequency used by the channel.

get_property([property])

The method returns the property of the transceiver.

get_type()

This method returns the type of the transceiver.

multicast(signal, node_list)

This method allows a node to perform a multicast, 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.

set_property(key, value)

Set a property to this transceiver.

unicast(signal, node)

This method allows a node to perform a unicast on the channel, and the method returns a received_signal if the signal can be decoded, or None.
__init__(node, freq)

This is the constructor.

create_signal() → comm.signalwave.QualityBasedSignal

Create a signal for transmissioin. By default, the method creates QualityBasedSignal signal.

multicast(signal: comm.signalwave.QualityBasedSignal, node_list)

This method allows a node to perform a multicast, 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
signalany comm.signalwave.BaseSignal subclass

The signal to be transmitted.

node_lista list of node.node.BaseNode subclass

The list containing the nodes to receive the multicast signal

Returns
A list of tuple (node.node.BaseNode, comm.signalwave.QualityBasedSignal)

It returns a list of (node,signal) that the node can decode the signal. An empty list is returned if no receiver can decode the signal.