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< SpectrumChannel >	m_channel
	Pointer to spectrum channel object. More...

ObjectFactory	m_factory
	Object factory for attribute setting. More...

Ptr< UniformRandomVariable >	m_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:

TvSpectrumTransmitterHelper tvTransHelper;
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

enum ns3::TvSpectrumTransmitterHelper::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

enum ns3::TvSpectrumTransmitterHelper::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

streamNum first 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

region	the region that the transmitters are in
density	the 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.
originLatitude	origin point latitude in degrees
originLongitude	origin point longitude in degrees
maxAltitude	maximum altitude in meters above earth's surface with which random points can be generated
maxRadius	max 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

startFrequencies	array containing all channel start frequencies for a particular region
startFrequenciesLength	number of elements in startFrequencies array
density	the 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

density	the density (high, medium, or low) of the location being simulated
numChannels	the 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

nodes a 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

nodes	a container containing the node(s) which the TV transmitter(s) will be attached to
region	the region of which the transmitter(s) will be characterized
channelNumber	the 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

nodes a 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

nodes	a container containing the node(s) which the TV transmitter(s) will be attached to
region	the region of which the transmitter(s) will be characterized
channelNumber	the 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

region	the region that the transmitters are in
transmitterIndicesToCreate	a list containing the channel number indices (for region's start frequencies array) that transmitters will be created for; this is returned from GenerateRegionalTransmitterIndices()
transmitterLocations	a 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().