A Discrete-Event Network Simulator
API
Public Types | Public Member Functions | Private Member Functions | Private Attributes | Friends | List of all members
ns3::TvSpectrumTransmitterHelper Class Reference

Helper class which uses TvSpectrumTransmitter class to create customizable TV transmitter(s) that transmit PSD spectrum specified by user-set attributes. More...

#include "tv-spectrum-transmitter-helper.h"

Public Types

enum  Density { DENSITY_LOW, DENSITY_MEDIUM, DENSITY_HIGH }
 density of location that TV transmitters are being set up in More...
 
enum  Region { REGION_NORTH_AMERICA, REGION_JAPAN, REGION_EUROPE }
 geographical region that TV transmitters are being set up in More...
 

Public Member Functions

 TvSpectrumTransmitterHelper ()
 Default constructor. More...
 
virtual ~TvSpectrumTransmitterHelper ()
 Destructor. More...
 
int64_t AssignStreams (int64_t streamNum)
 Assigns the stream number for the uniform random number generator to use. More...
 
void CreateRegionalTvTransmitters (Region region, Density density, double originLatitude, double originLongitude, double maxAltitude, double maxRadius)
 Generates and installs (starts transmission on the spectrum channel) a random number of TV transmitters with channel frequencies corresponding to the given region at random locations on or above earth. More...
 
NetDeviceContainer Install (NodeContainer nodes)
 Set up and start the TV Transmitter's transmission on the spectrum channel. More...
 
NetDeviceContainer Install (NodeContainer nodes, Region region, uint16_t channelNumber)
 Set up and start the TV Transmitter's transmission on the spectrum channel. More...
 
NetDeviceContainer InstallAdjacent (NodeContainer nodes)
 Set up and start the TV Transmitter's transmission on the spectrum channel. More...
 
NetDeviceContainer InstallAdjacent (NodeContainer nodes, Region region, uint16_t channelNumber)
 Set up and start the TV Transmitter's transmission on the spectrum channel. More...
 
void SetAttribute (std::string name, const AttributeValue &val)
 Set attribute for each TvSpectrumTransmitter instance to be created. More...
 
void SetChannel (Ptr< SpectrumChannel > c)
 Set the spectrum channel for the device(s) to transmit on. More...
 

Private Member Functions

std::list< int > GenerateRegionalTransmitterIndices (const double startFrequencies[], const int startFrequenciesLength, Density density)
 Generates random indices of given region frequency array (ignoring indices referring to invalid channels). More...
 
int GetRandomNumTransmitters (Density density, uint32_t numChannels)
 Randomly generates the number of TV transmitters to be created based on given density and number of possible TV channels. More...
 
void InstallRandomRegionalTransmitters (Region region, std::list< int > transmitterIndicesToCreate, std::list< Vector > transmitterLocations)
 Installs each randomly generated regional TV transmitter. More...
 

Private Attributes

Ptr< SpectrumChannelm_channel
 Pointer to spectrum channel object. More...
 
ObjectFactory m_factory
 Object factory for attribute setting. More...
 
Ptr< UniformRandomVariablem_uniRand
 Object to generate uniform random numbers. More...
 

Friends

class ::TvHelperDistributionTestCase
 

Detailed Description

Helper class which uses TvSpectrumTransmitter class to create customizable TV transmitter(s) that transmit PSD spectrum specified by user-set attributes.

Has functionality to create TV transmitter(s) with actual frequencies of specific geographic regions. Provides method to create a random set of transmitters within a given region and location.

Here is an example of how to use this class:

tvTransHelper.SetChannel (channel); // provided that user has a Ptr<SpectrumChannel> ready.
tvTransHelper.SetAttribute ("StartFrequency", DoubleValue (524e6));
tvTransHelper.SetAttribute ("ChannelBandwidth", DoubleValue (6e6));
tvTransHelper.SetAttribute ("StartingTime", TimeValue (Seconds (0)));
tvTransHelper.SetAttribute ("TransmitDuration", TimeValue (Seconds (0.2)));
tvTransHelper.SetAttribute ("BasePsd", DoubleValue (22.22));
tvTransHelper.SetAttribute ("TvType", EnumValue (TvSpectrumTransmitter::TVTYPE_8VSB));
tvTransHelper.SetAttribute ("Antenna", StringValue ("ns3::IsotropicAntennaModel"));
tvTransHelper.Install (tvTransmitterNode); // provided that user has a NodeContainer ready.

Definition at line 67 of file tv-spectrum-transmitter-helper.h.

Member Enumeration Documentation

◆ Density

density of location that TV transmitters are being set up in

Enumerator
DENSITY_LOW 
DENSITY_MEDIUM 
DENSITY_HIGH 

Definition at line 86 of file tv-spectrum-transmitter-helper.h.

◆ Region

geographical region that TV transmitters are being set up in

Enumerator
REGION_NORTH_AMERICA 
REGION_JAPAN 
REGION_EUROPE 

Definition at line 76 of file tv-spectrum-transmitter-helper.h.

Constructor & Destructor Documentation

◆ TvSpectrumTransmitterHelper()

ns3::TvSpectrumTransmitterHelper::TvSpectrumTransmitterHelper ( )

Default constructor.

Definition at line 98 of file tv-spectrum-transmitter-helper.cc.

References m_factory, NS_LOG_FUNCTION, and ns3::ObjectFactory::SetTypeId().

◆ ~TvSpectrumTransmitterHelper()

ns3::TvSpectrumTransmitterHelper::~TvSpectrumTransmitterHelper ( )
virtual

Destructor.

Definition at line 106 of file tv-spectrum-transmitter-helper.cc.

References m_channel, m_uniRand, and NS_LOG_FUNCTION.

Member Function Documentation

◆ AssignStreams()

int64_t ns3::TvSpectrumTransmitterHelper::AssignStreams ( int64_t  streamNum)

Assigns the stream number for the uniform random number generator to use.

Parameters
streamNumfirst stream index to use
Returns
the number of stream indices assigned by this helper

Definition at line 340 of file tv-spectrum-transmitter-helper.cc.

References m_uniRand, and ns3::RandomVariableStream::SetStream().

◆ CreateRegionalTvTransmitters()

void ns3::TvSpectrumTransmitterHelper::CreateRegionalTvTransmitters ( Region  region,
Density  density,
double  originLatitude,
double  originLongitude,
double  maxAltitude,
double  maxRadius 
)

Generates and installs (starts transmission on the spectrum channel) a random number of TV transmitters with channel frequencies corresponding to the given region at random locations on or above earth.

The generated transmitters are located at randomly selected points within a given altitude above earth's surface centered around a given origin point (on earth's surface) within a given distance radius, corresponding to a uniform distribution. Distance radius is measured as if all points are on earth's surface (with altitude = 0). Assumes earth is a perfect sphere. The given region's channel numbers that the generated TV transmitters' frequency spectra are modeled after are uniformly selected at random. These channel numbers are never repeated. The number of transmitters generated is uniformly random based on given density. Each transmitter has BasePsd and TvType set from SetAttribute(), which should be set before calling this method.

Parameters
regionthe region that the transmitters are in
densitythe density (high, medium, or low) of the location being simulated, which determines how many transmitters are created and how many channels are occupied. Low density will generate between one and one third of the number of TV channels in the given region, medium density will generate between one third and two thirds, and high density will generate between two thirds and all of the channels.
originLatitudeorigin point latitude in degrees
originLongitudeorigin point longitude in degrees
maxAltitudemaximum altitude in meters above earth's surface with which random points can be generated
maxRadiusmax distance in meters from origin with which random transmitters can be generated (all transmitters are less than or equal to this distance from the origin, relative to points being on earth's surface)

Definition at line 348 of file tv-spectrum-transmitter-helper.cc.

References ns3::europeArrayLength, ns3::europeStartFrequencies, GenerateRegionalTransmitterIndices(), InstallRandomRegionalTransmitters(), ns3::japanArrayLength, ns3::japanStartFrequencies, m_uniRand, ns3::northAmericaArrayLength, ns3::northAmericaStartFrequencies, NS_LOG_FUNCTION, ns3::GeographicPositions::RandCartesianPointsAroundGeographicPoint(), REGION_EUROPE, REGION_JAPAN, and REGION_NORTH_AMERICA.

◆ GenerateRegionalTransmitterIndices()

std::list< int > ns3::TvSpectrumTransmitterHelper::GenerateRegionalTransmitterIndices ( const double  startFrequencies[],
const int  startFrequenciesLength,
Density  density 
)
private

Generates random indices of given region frequency array (ignoring indices referring to invalid channels).

Number of indices generated (which is number of TV transmitters to be created) is random based on given density. Indices generated refer to frequencies that TV transmitters will be created with.

Parameters
startFrequenciesarray containing all channel start frequencies for a particular region
startFrequenciesLengthnumber of elements in startFrequencies array
densitythe density (high, medium, or low) of the location being simulated, which determines how many transmitters are created
Returns
a list containing the indices in startFrequencies that transmitters will be created for

Definition at line 392 of file tv-spectrum-transmitter-helper.cc.

References ns3::RandomVariableStream::GetInteger(), GetRandomNumTransmitters(), and m_uniRand.

Referenced by CreateRegionalTvTransmitters().

◆ GetRandomNumTransmitters()

int ns3::TvSpectrumTransmitterHelper::GetRandomNumTransmitters ( Density  density,
uint32_t  numChannels 
)
private

Randomly generates the number of TV transmitters to be created based on given density and number of possible TV channels.

Low density will generate a transmitter for between one (a single transmitter) and one third of the number of possible channels, medium density will generate a transmitter for between one third and two thirds, and high density will generate a transmitter for between two thirds and all of the possible channels. These ratios are approximated in the implementation, but there is no overlap possible in the number of transmitters generated between adjacent densities. For example, given 60 possible channels, for low density between 1 and 20 transmitters can be created, for medium density between 21 and 40 transmitters can be created, and for high density between 41 and 60 transmitters can be created (all inclusive).

Parameters
densitythe density (high, medium, or low) of the location being simulated
numChannelsthe number of possible TV channels in the region being simulated
Returns
the number of TV transmitters that will be created

Definition at line 440 of file tv-spectrum-transmitter-helper.cc.

References DENSITY_LOW, DENSITY_MEDIUM, ns3::RandomVariableStream::GetInteger(), and m_uniRand.

Referenced by TvHelperDistributionTestCase::DoRun(), and GenerateRegionalTransmitterIndices().

◆ Install() [1/2]

NetDeviceContainer ns3::TvSpectrumTransmitterHelper::Install ( NodeContainer  nodes)

Set up and start the TV Transmitter's transmission on the spectrum channel.

Creates one TV Transmitter for each node given as an input, with settings selected from attributes. Use SetAttribute() to select settings for the TV Transmitter(s). If multiple transmitters created, all will have same settings (frequency, PSD, etc.) except for position/location, which depends on the positions in the input NodeContainer.

Parameters
nodesa container containing the node(s) which the TV transmitter(s) will be attached to
Returns
a device container which contains all the devices created by this method

Definition at line 128 of file tv-spectrum-transmitter-helper.cc.

References ns3::NetDeviceContainer::Add(), ns3::Node::AddDevice(), ns3::NodeContainer::Begin(), ns3::ObjectFactory::Create(), ns3::NodeContainer::End(), ns3::Object::GetObject(), m_channel, m_factory, NS_ASSERT, NS_LOG_FUNCTION, and third::phy.

Referenced by InstallRandomRegionalTransmitters().

◆ Install() [2/2]

NetDeviceContainer ns3::TvSpectrumTransmitterHelper::Install ( NodeContainer  nodes,
Region  region,
uint16_t  channelNumber 
)

Set up and start the TV Transmitter's transmission on the spectrum channel.

Creates one TV Transmitter for each node given as an input, with settings selected from attributes. Use SetAttribute() to select settings for the TV Transmitter(s). Transmitter(s) will be created with frequencies corresponding to the user-selected channel number of the user-selected region. If multiple transmitters created, all will have same settings (frequency, PSD, etc.) except for position/location, which depends on the positions in the input NodeContainer.

Parameters
nodesa container containing the node(s) which the TV transmitter(s) will be attached to
regionthe region of which the transmitter(s) will be characterized
channelNumberthe TV channel number in the selected region that the transmitter frequencies will be modeled after
Returns
a device container which contains all the devices created by this method

Definition at line 157 of file tv-spectrum-transmitter-helper.cc.

References ns3::NetDeviceContainer::Add(), ns3::Node::AddDevice(), ns3::NodeContainer::Begin(), ns3::ObjectFactory::Create(), ns3::NodeContainer::End(), ns3::europeArrayLength, ns3::europeEndFrequencies, ns3::europeStartFrequencies, ns3::Object::GetObject(), ns3::japanArrayLength, ns3::japanEndFrequencies, ns3::japanStartFrequencies, m_channel, m_factory, ns3::northAmericaArrayLength, ns3::northAmericaEndFrequencies, ns3::northAmericaStartFrequencies, NS_ASSERT, NS_ASSERT_MSG(), NS_LOG_FUNCTION, third::phy, REGION_EUROPE, REGION_JAPAN, and REGION_NORTH_AMERICA.

◆ InstallAdjacent() [1/2]

NetDeviceContainer ns3::TvSpectrumTransmitterHelper::InstallAdjacent ( NodeContainer  nodes)

Set up and start the TV Transmitter's transmission on the spectrum channel.

Consecutively created transmitters (consecutive in input NodeContainer) will have adjacent channels, i.e. a transmitter's frequency spectrum will border (but not overlap) the frequency spectrum of the transmitter created directly before it and the transmitter created directly after it. Creates one TV Transmitter for each node given as an input, with settings selected from attributes. Use SetAttribute() to select settings for the TV Transmitter(s). If multiple transmitters created, they will have same settings except for frequency and position/location. For each node, start frequency will be incremented by the channel bandwidth that is set. For example, if two nodes are given as inputs to InstallAdjacent with start frequency set to 500 MHz and channel bandwidth set to 6 MHz, the first node will be a transmitter ranging from 500 MHz to 506 MHz and the second node will be a transmitter ranging from 506 MHz to 512 MHz.

Parameters
nodesa container containing the node(s) which the TV transmitter(s) will be attached to
Returns
a device container which contains all the devices created by this method

Definition at line 228 of file tv-spectrum-transmitter-helper.cc.

References ns3::NetDeviceContainer::Add(), ns3::Node::AddDevice(), ns3::NodeContainer::Begin(), ns3::ObjectFactory::Create(), ns3::NodeContainer::End(), ns3::DoubleValue::Get(), ns3::Object::GetObject(), m_channel, m_factory, NS_ASSERT, NS_LOG_FUNCTION, and third::phy.

◆ InstallAdjacent() [2/2]

NetDeviceContainer ns3::TvSpectrumTransmitterHelper::InstallAdjacent ( NodeContainer  nodes,
Region  region,
uint16_t  channelNumber 
)

Set up and start the TV Transmitter's transmission on the spectrum channel.

Consecutively created transmitters (consecutive in input NodeContainer) will have adjacent channels, with the frequency spectrum and bandwidth of each channel determined by the user-selected region. Creates one TV Transmitter for each node given as an input, with settings selected from attributes. Use SetAttribute() to select settings for the TV Transmitter(s). The first created transmitter will have frequencies corresponding to the user-selected channel number of the user-selected region. Each subsequently created transmitter will have its frequencies modeled after the channel number (of the user-selected region) following the previous one; for example if the first created transmitter is modeled after channel 1, the next one created will be modeled after channel 2, and the following one will be modeled after channel 3. If multiple transmitters created, they will have same settings except for frequency and position/location.

Parameters
nodesa container containing the node(s) which the TV transmitter(s) will be attached to
regionthe region of which the transmitter(s) will be characterized
channelNumberthe TV channel number in the selected region that the first created transmitter's frequencies will be modeled after
Returns
a device container which contains all the devices created by this method

Definition at line 265 of file tv-spectrum-transmitter-helper.cc.

References ns3::NetDeviceContainer::Add(), ns3::Node::AddDevice(), ns3::NodeContainer::Begin(), ns3::ObjectFactory::Create(), ns3::NodeContainer::End(), ns3::europeArrayLength, ns3::europeEndFrequencies, ns3::europeStartFrequencies, ns3::Object::GetObject(), ns3::japanArrayLength, ns3::japanEndFrequencies, ns3::japanStartFrequencies, m_channel, m_factory, ns3::northAmericaArrayLength, ns3::northAmericaEndFrequencies, ns3::northAmericaStartFrequencies, NS_ASSERT, NS_ASSERT_MSG(), NS_LOG_FUNCTION, third::phy, REGION_EUROPE, REGION_JAPAN, and REGION_NORTH_AMERICA.

◆ InstallRandomRegionalTransmitters()

void ns3::TvSpectrumTransmitterHelper::InstallRandomRegionalTransmitters ( Region  region,
std::list< int >  transmitterIndicesToCreate,
std::list< Vector >  transmitterLocations 
)
private

Installs each randomly generated regional TV transmitter.

Parameters
regionthe region that the transmitters are in
transmitterIndicesToCreatea list containing the channel number indices (for region's start frequencies array) that transmitters will be created for; this is returned from GenerateRegionalTransmitterIndices()
transmitterLocationsa list containing the vectors (x, y, z location) of each TV transmitter to be generated; this is returned from RandGeographicCoordsAroundPoint()

Definition at line 461 of file tv-spectrum-transmitter-helper.cc.

References ns3::NodeContainer::Create(), Install(), and third::mobility.

Referenced by CreateRegionalTvTransmitters().

◆ SetAttribute()

void ns3::TvSpectrumTransmitterHelper::SetAttribute ( std::string  name,
const AttributeValue val 
)

Set attribute for each TvSpectrumTransmitter instance to be created.

Parameters
namethe name of the attribute to set
valthe value of the attribute to set

Definition at line 121 of file tv-spectrum-transmitter-helper.cc.

References m_factory, and ns3::ObjectFactory::Set().

◆ SetChannel()

void ns3::TvSpectrumTransmitterHelper::SetChannel ( Ptr< SpectrumChannel c)

Set the spectrum channel for the device(s) to transmit on.

Parameters
ca pointer to the spectrum channel

Definition at line 114 of file tv-spectrum-transmitter-helper.cc.

References m_channel, and NS_LOG_FUNCTION.

Friends And Related Function Documentation

◆ ::TvHelperDistributionTestCase

friend class ::TvHelperDistributionTestCase
friend

Definition at line 71 of file tv-spectrum-transmitter-helper.h.

Member Data Documentation

◆ m_channel

Ptr<SpectrumChannel> ns3::TvSpectrumTransmitterHelper::m_channel
private

Pointer to spectrum channel object.

Definition at line 260 of file tv-spectrum-transmitter-helper.h.

Referenced by Install(), InstallAdjacent(), SetChannel(), and ~TvSpectrumTransmitterHelper().

◆ m_factory

ObjectFactory ns3::TvSpectrumTransmitterHelper::m_factory
private

Object factory for attribute setting.

Definition at line 323 of file tv-spectrum-transmitter-helper.h.

Referenced by Install(), InstallAdjacent(), SetAttribute(), and TvSpectrumTransmitterHelper().

◆ m_uniRand

Ptr<UniformRandomVariable> ns3::TvSpectrumTransmitterHelper::m_uniRand
private

The documentation for this class was generated from the following files: