LinkAdrRequest commands management. More...

#include "adr-component.h"

Inheritance diagram for ns3::lorawan::AdrComponent:

Collaboration diagram for ns3::lorawan::AdrComponent:

Public Member Functions
	AdrComponent ()
	Default constructor.

	~AdrComponent () override
	Destructor.

void	BeforeSendingReply (Ptr< EndDeviceStatus > status, Ptr< NetworkStatus > networkStatus) override
	Function called as a downlink reply is about to leave the NetworkServer application.

void	OnFailedReply (Ptr< EndDeviceStatus > status, Ptr< NetworkStatus > networkStatus) override
	Method that is called when a packet cannot be sent in the downlink.

void	OnReceivedPacket (Ptr< const Packet > packet, Ptr< EndDeviceStatus > status, Ptr< NetworkStatus > networkStatus) override
	Function called as a new uplink packet is received by the NetworkServer application.

Public Member Functions inherited from ns3::lorawan::NetworkControllerComponent
	NetworkControllerComponent ()
	Default constructor.

	~NetworkControllerComponent () override
	Destructor.

virtual void	BeforeSendingReply (Ptr< EndDeviceStatus > status, Ptr< NetworkStatus > networkStatus)=0
	Function called as a downlink reply is about to leave the NetworkServer application.

virtual void	OnFailedReply (Ptr< EndDeviceStatus > status, Ptr< NetworkStatus > networkStatus)=0
	Method that is called when a packet cannot be sent in the downlink.

virtual void	OnReceivedPacket (Ptr< const Packet > packet, Ptr< EndDeviceStatus > status, Ptr< NetworkStatus > networkStatus)=0
	Function called as a new uplink packet is received by the NetworkServer application.

Public Member Functions inherited from ns3::Object
	Object ()
	Constructor.

	~Object () override
	Destructor.

void	AggregateObject (Ptr< Object > other)
	Aggregate two Objects together.

void	Dispose ()
	Dispose of this Object.

AggregateIterator	GetAggregateIterator () const
	Get an iterator to the Objects aggregated to this one.

TypeId	GetInstanceTypeId () const override
	Get the most derived TypeId for this Object.

template<typename T >
Ptr< T >	GetObject () const
	Get a pointer to the requested aggregated Object.

template<>
Ptr< Object >	GetObject () const
	Specialization of () for objects of type ns3::Object.

template<typename T >
Ptr< T >	GetObject (TypeId tid) const
	Get a pointer to the requested aggregated Object by TypeId.

template<>
Ptr< Object >	GetObject (TypeId tid) const
	Specialization of (TypeId tid) for objects of type ns3::Object.

void	Initialize ()
	Invoke DoInitialize on all Objects aggregated to this one.

bool	IsInitialized () const
	Check if the object has been initialized.

void	UnidirectionalAggregateObject (Ptr< Object > other)
	Aggregate an Object to another Object.

Public Member Functions inherited from ns3::SimpleRefCount< Object, ObjectBase, ObjectDeleter >
	SimpleRefCount ()
	Default constructor.

	SimpleRefCount (const SimpleRefCount &o)
	Copy constructor.

uint32_t	GetReferenceCount () const
	Get the reference count of the object.

SimpleRefCount &	operator= (const SimpleRefCount &o)
	Assignment operator.

void	Ref () const
	Increment the reference count.

void	Unref () const
	Decrement the reference count.

Public Member Functions inherited from ns3::ObjectBase
virtual	~ObjectBase ()
	Virtual destructor.

void	GetAttribute (std::string name, AttributeValue &value) const
	Get the value of an attribute, raising fatal errors if unsuccessful.

bool	GetAttributeFailSafe (std::string name, AttributeValue &value) const
	Get the value of an attribute without raising errors.

virtual TypeId	GetInstanceTypeId () const =0
	Get the most derived TypeId for this Object.

void	SetAttribute (std::string name, const AttributeValue &value)
	Set a single attribute, raising fatal errors if unsuccessful.

bool	SetAttributeFailSafe (std::string name, const AttributeValue &value)
	Set a single attribute without raising errors.

bool	TraceConnect (std::string name, std::string context, const CallbackBase &cb)
	Connect a TraceSource to a Callback with a context.

bool	TraceConnectWithoutContext (std::string name, const CallbackBase &cb)
	Connect a TraceSource to a Callback without a context.

bool	TraceDisconnect (std::string name, std::string context, const CallbackBase &cb)
	Disconnect from a TraceSource a Callback previously connected with a context.

bool	TraceDisconnectWithoutContext (std::string name, const CallbackBase &cb)
	Disconnect from a TraceSource a Callback previously connected without a context.

Static Public Member Functions
static TypeId	GetTypeId ()
	Register this type.

Static Public Member Functions inherited from ns3::lorawan::NetworkControllerComponent
static TypeId	GetTypeId ()
	Register this type.

Static Public Member Functions inherited from ns3::Object
static TypeId	GetTypeId ()
	Register this type.

Static Public Member Functions inherited from ns3::ObjectBase
static TypeId	GetTypeId ()
	Get the type ID.

Private Types
enum	CombiningMethod { AVERAGE , MAXIMUM , MINIMUM }
	Available policies for combining radio metrics in packet history. More...

Private Member Functions
void	AdrImplementation (uint8_t newDataRate, uint8_t newTxPower, Ptr< EndDeviceStatus > status)
	Implementation of the default Adaptive Data Rate (ADR) procedure.

double	GetAverageSNR (EndDeviceStatus::ReceivedPacketList packetList, int historyRange)
	Get the average Signal to Noise Ratio (SNR) of the received packet history.

double	GetAverageTxFromGateways (EndDeviceStatus::GatewayList gwList)
	Get the average RSSI (dBm) of gateways receiving the same transmission.

double	GetMaxSNR (EndDeviceStatus::ReceivedPacketList packetList, int historyRange)
	Get the max Signal to Noise Ratio (SNR) of the receive packet history.

double	GetMaxTxFromGateways (EndDeviceStatus::GatewayList gwList)
	Get the max RSSI (dBm) among gateways receiving the same transmission.

double	GetMinSNR (EndDeviceStatus::ReceivedPacketList packetList, int historyRange)
	Get the min Signal to Noise Ratio (SNR) of the receive packet history.

double	GetMinTxFromGateways (EndDeviceStatus::GatewayList gwList)
	Get the min RSSI (dBm) among gateways receiving the same transmission.

double	GetReceivedPower (EndDeviceStatus::GatewayList gwList)
	Get RSSI metric for a transmission according to chosen gateway aggregation policy.

int	GetTxPowerIndex (int txPower)
	Get the LoRaWAN protocol TXPower configuration index from the Equivalent Isotropically Radiated Power (EIRP) in dBm.

double	RxPowerToSNR (double transmissionPower) const
	Convert reception power values [dBm] to Signal to Noise Ratio (SNR) values [dB].

uint8_t	SfToDr (uint8_t sf)
	Convert spreading factor values [7:12] to respective data rate values [0:5].

Private Attributes
const int	B = 125000
	Bandwidth (Hz)

enum CombiningMethod	historyAveraging
	Received SNR history policy.

int	historyRange
	Number of previous packets to consider.

bool	m_toggleTxPower
	Whether to control transmission power of end devices or not.

const int	max_transmissionPower = 14
	Maximum transmission power (dBm) (Europe)

const int	min_spreadingFactor = 7
	Spreading factor lower limit.

const int	min_transmissionPower = 2
	Minimum transmission power (dBm) (Europe)

const int	NF = 6
	Noise Figure (dB)

double	threshold [6]
	Vector containing the required SNR for the 6 allowed spreading factor levels ranging from 7 to 12 (the SNR values are in dB).

enum CombiningMethod	tpAveraging
	TX power from gateways policy.

Additional Inherited Members
Protected Member Functions inherited from ns3::Object
	Object (const Object &o)
	Copy an Object.

virtual void	DoDispose ()
	Destructor implementation.

virtual void	DoInitialize ()
	Initialize() implementation.

virtual void	NotifyNewAggregate ()
	Notify all Objects aggregated to this one of a new Object being aggregated.

Protected Member Functions inherited from ns3::ObjectBase
void	ConstructSelf (const AttributeConstructionList &attributes)
	Complete construction of ObjectBase; invoked by derived classes.

virtual void	NotifyConstructionCompleted ()
	Notifier called once the ObjectBase is fully constructed.

Related Functions inherited from ns3::ObjectBase
static TypeId	GetObjectIid ()
	Ensure the TypeId for ObjectBase gets fully configured to anchor the inheritance tree properly.

Detailed Description

LinkAdrRequest commands management.

Definition at line 40 of file adr-component.h.

Member Enumeration Documentation

◆ CombiningMethod

enum ns3::lorawan::AdrComponent::CombiningMethod

private

Available policies for combining radio metrics in packet history.

Enumerator
AVERAGE
MAXIMUM
MINIMUM

Definition at line 45 of file adr-component.h.

Constructor & Destructor Documentation

◆ AdrComponent()

ns3::lorawan::AdrComponent::AdrComponent ( )

Default constructor.

Definition at line 76 of file adr-component.cc.

◆ ~AdrComponent()

ns3::lorawan::AdrComponent::~AdrComponent ( )

override

Destructor.

Definition at line 80 of file adr-component.cc.

Member Function Documentation

◆ AdrImplementation()

void ns3::lorawan::AdrComponent::AdrImplementation	(	uint8_t *	newDataRate,
		uint8_t *	newTxPower,
		Ptr< EndDeviceStatus >	status
	)

private

Implementation of the default Adaptive Data Rate (ADR) procedure.

ADR is meant to optimize radio modulation parameters of end devices to improve energy consuption and radio resource utilization. For more details see https://doi.org/10.1109/NOMS.2018.8406255 .

Parameters

newDataRate	[out] new data rate value selected for the end device.
newTxPower	[out] new tx power value selected for the end device.
status	State representation of the current end device.

Definition at line 180 of file adr-component.cc.

References AVERAGE, GetAverageSNR(), GetMaxSNR(), GetMinSNR(), historyAveraging, historyRange, max_transmissionPower, MAXIMUM, min_spreadingFactor, min_transmissionPower, MINIMUM, NS_LOG_DEBUG, SfToDr(), and threshold.

Referenced by BeforeSendingReply().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ BeforeSendingReply()

void ns3::lorawan::AdrComponent::BeforeSendingReply	(	Ptr< EndDeviceStatus >	status,
		Ptr< NetworkStatus >	networkStatus
	)

overridevirtual

Function called as a downlink reply is about to leave the NetworkServer application.

Parameters

status	A pointer to the status of the end device which we are sending the reply to.
networkStatus	A pointer to the NetworkStatus object.

Implements ns3::lorawan::NetworkControllerComponent.

Definition at line 96 of file adr-component.cc.

References AdrImplementation(), ns3::lorawan::LoraFrameHeader::GetAdr(), GetTxPowerIndex(), historyRange, m_toggleTxPower, NS_LOG_DEBUG, NS_LOG_ERROR, NS_LOG_FUNCTION, ns3::lorawan::LoraFrameHeader::SetAsUplink(), SfToDr(), and ns3::lorawan::LorawanMacHeader::UNCONFIRMED_DATA_DOWN.

Here is the call graph for this function:

◆ GetAverageSNR()

double ns3::lorawan::AdrComponent::GetAverageSNR	(	EndDeviceStatus::ReceivedPacketList	packetList,
		int	historyRange
	)

private

Get the average Signal to Noise Ratio (SNR) of the received packet history.

Parameters

packetList	History of received packets with reception information.
historyRange	Number of packets to consider going back in time.

Returns: Average SNR of packets as double.

Definition at line 419 of file adr-component.cc.

References GetReceivedPower(), historyRange, NS_LOG_DEBUG, and RxPowerToSNR().

Referenced by AdrImplementation().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetAverageTxFromGateways()

double ns3::lorawan::AdrComponent::GetAverageTxFromGateways ( EndDeviceStatus::GatewayList gwList )

private

Get the average RSSI (dBm) of gateways receiving the same transmission.

Parameters

gwList List of gateways paired with packet reception information.

Returns: Average RSSI of transmission as double.

Definition at line 330 of file adr-component.cc.

References NS_LOG_DEBUG.

Referenced by GetReceivedPower().

Here is the caller graph for this function:

◆ GetMaxSNR()

double ns3::lorawan::AdrComponent::GetMaxSNR	(	EndDeviceStatus::ReceivedPacketList	packetList,
		int	historyRange
	)

private

Get the max Signal to Noise Ratio (SNR) of the receive packet history.

Parameters

packetList	History of received packets with reception information.
historyRange	Number of packets to consider going back in time.

Returns: Max SNR among packets as double.

Definition at line 392 of file adr-component.cc.

References GetReceivedPower(), historyRange, NS_LOG_DEBUG, and RxPowerToSNR().

Referenced by AdrImplementation().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetMaxTxFromGateways()

double ns3::lorawan::AdrComponent::GetMaxTxFromGateways ( EndDeviceStatus::GatewayList gwList )

private

Get the max RSSI (dBm) among gateways receiving the same transmission.

Parameters

gwList List of gateways paired with packet reception information.

Returns: Max RSSI of transmission as double.

Definition at line 312 of file adr-component.cc.

Referenced by GetReceivedPower().

Here is the caller graph for this function:

◆ GetMinSNR()

double ns3::lorawan::AdrComponent::GetMinSNR	(	EndDeviceStatus::ReceivedPacketList	packetList,
		int	historyRange
	)

private

Get the min Signal to Noise Ratio (SNR) of the receive packet history.

Parameters

packetList	History of received packets with reception information.
historyRange	Number of packets to consider going back in time.

Returns: Min SNR among packets as double.

Definition at line 365 of file adr-component.cc.

References GetReceivedPower(), historyRange, NS_LOG_DEBUG, and RxPowerToSNR().

Referenced by AdrImplementation().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetMinTxFromGateways()

double ns3::lorawan::AdrComponent::GetMinTxFromGateways ( EndDeviceStatus::GatewayList gwList )

private

Get the min RSSI (dBm) among gateways receiving the same transmission.

Parameters

gwList List of gateways paired with reception information.

Returns: Min RSSI of transmission as double.

Definition at line 294 of file adr-component.cc.

Referenced by GetReceivedPower().

Here is the caller graph for this function:

◆ GetReceivedPower()

double ns3::lorawan::AdrComponent::GetReceivedPower ( EndDeviceStatus::GatewayList gwList )

private

Get RSSI metric for a transmission according to chosen gateway aggregation policy.

Parameters

gwList List of gateways paired with packet reception information.

Returns: RSSI of tranmsmission as double.

Definition at line 348 of file adr-component.cc.

References AVERAGE, GetAverageTxFromGateways(), GetMaxTxFromGateways(), GetMinTxFromGateways(), MAXIMUM, MINIMUM, and tpAveraging.

Referenced by GetAverageSNR(), GetMaxSNR(), and GetMinSNR().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetTxPowerIndex()

int ns3::lorawan::AdrComponent::GetTxPowerIndex ( int txPower )

private

Get the LoRaWAN protocol TXPower configuration index from the Equivalent Isotropically Radiated Power (EIRP) in dBm.

Parameters

txPower Transission EIRP configuration.

Returns: TXPower index as int.

Definition at line 444 of file adr-component.cc.

Referenced by BeforeSendingReply().

Here is the caller graph for this function:

◆ GetTypeId()

TypeId ns3::lorawan::AdrComponent::GetTypeId ( )

static

Register this type.

Returns: The object TypeId.

Definition at line 36 of file adr-component.cc.

References ns3::TypeId::AddConstructor(), AVERAGE, historyAveraging, historyRange, m_toggleTxPower, ns3::MakeBooleanAccessor(), ns3::MakeBooleanChecker(), ns3::MakeEnumChecker(), ns3::MakeIntegerAccessor(), MAXIMUM, MINIMUM, ns3::TypeId::SetGroupName(), and tpAveraging.

Referenced by OnFailedReply(), and OnReceivedPacket().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ OnFailedReply()

void ns3::lorawan::AdrComponent::OnFailedReply	(	Ptr< EndDeviceStatus >	status,
		Ptr< NetworkStatus >	networkStatus
	)

overridevirtual

Method that is called when a packet cannot be sent in the downlink.

Parameters

status	The EndDeviceStatus of the device to which it was impossible to send a reply.
networkStatus	A pointer to the NetworkStatus object.

Implements ns3::lorawan::NetworkControllerComponent.

Definition at line 174 of file adr-component.cc.

References GetTypeId(), and NS_LOG_FUNCTION.

Here is the call graph for this function:

◆ OnReceivedPacket()

void ns3::lorawan::AdrComponent::OnReceivedPacket	(	Ptr< const Packet >	packet,
		Ptr< EndDeviceStatus >	status,
		Ptr< NetworkStatus >	networkStatus
	)

overridevirtual

Function called as a new uplink packet is received by the NetworkServer application.

Parameters

packet	The newly received packet.
status	A pointer to the status of the end device that sent the packet.
networkStatus	A pointer to the NetworkStatus object.

Implements ns3::lorawan::NetworkControllerComponent.

Definition at line 85 of file adr-component.cc.

References GetTypeId(), and NS_LOG_FUNCTION.

Here is the call graph for this function:

◆ RxPowerToSNR()

double ns3::lorawan::AdrComponent::RxPowerToSNR ( double transmissionPower ) const

private

Convert reception power values [dBm] to Signal to Noise Ratio (SNR) values [dB].

The conversion comes from the formula $P_{rx}=-174+10\log_{10}(B)+SNR+NF$ where $P_{rx}$ is the received transmission power, is the transmission bandwidth and is the noise figure of the receiver. The constant is the thermal noise [dBm] in 1 Hz of bandwidth and is influenced the temperature of the receiver, assumed constant in this model. For more details see the SX1301 chip datasheet.

Parameters

transmissionPower Value of received transmission power.

Returns: SNR value as double.

Definition at line 286 of file adr-component.cc.

References B, and NF.

Referenced by GetAverageSNR(), GetMaxSNR(), and GetMinSNR().

Here is the caller graph for this function:

◆ SfToDr()

uint8_t ns3::lorawan::AdrComponent::SfToDr ( uint8_t sf )

private

Convert spreading factor values [7:12] to respective data rate values [0:5].

Parameters

sf	The spreading factor value.

Returns: Value of the data rate as uint8_t.

Definition at line 260 of file adr-component.cc.

Referenced by AdrImplementation(), and BeforeSendingReply().

Here is the caller graph for this function:

Member Data Documentation

◆ B

const int ns3::lorawan::AdrComponent::B = 125000

private

Bandwidth (Hz)

Definition at line 177 of file adr-component.h.

Referenced by RxPowerToSNR().

◆ historyAveraging

enum CombiningMethod ns3::lorawan::AdrComponent::historyAveraging

private

Received SNR history policy.

Definition at line 171 of file adr-component.h.

Referenced by AdrImplementation(), and GetTypeId().

◆ historyRange

int ns3::lorawan::AdrComponent::historyRange

private

Number of previous packets to consider.

Definition at line 170 of file adr-component.h.

Referenced by AdrImplementation(), BeforeSendingReply(), GetAverageSNR(), GetMaxSNR(), GetMinSNR(), and GetTypeId().

◆ m_toggleTxPower

bool ns3::lorawan::AdrComponent::m_toggleTxPower

private

Whether to control transmission power of end devices or not.

Definition at line 188 of file adr-component.h.

Referenced by BeforeSendingReply(), and GetTypeId().

◆ max_transmissionPower

const int ns3::lorawan::AdrComponent::max_transmissionPower = 14

private

Maximum transmission power (dBm) (Europe)

Definition at line 175 of file adr-component.h.

Referenced by AdrImplementation().

◆ min_spreadingFactor

const int ns3::lorawan::AdrComponent::min_spreadingFactor = 7

private

Spreading factor lower limit.

Definition at line 173 of file adr-component.h.

Referenced by AdrImplementation().

◆ min_transmissionPower

const int ns3::lorawan::AdrComponent::min_transmissionPower = 2

private

Minimum transmission power (dBm) (Europe)

Definition at line 174 of file adr-component.h.

Referenced by AdrImplementation().

◆ NF

const int ns3::lorawan::AdrComponent::NF = 6

private

Noise Figure (dB)

Definition at line 178 of file adr-component.h.

Referenced by RxPowerToSNR().

◆ threshold

double ns3::lorawan::AdrComponent::threshold[6]

private

Initial value:

= {
        -20.0,
        -17.5,
        -15.0,
        -12.5,
        -10.0,
        -7.5}

Vector containing the required SNR for the 6 allowed spreading factor levels ranging from 7 to 12 (the SNR values are in dB).

Definition at line 179 of file adr-component.h.

Referenced by AdrImplementation().

◆ tpAveraging

enum CombiningMethod ns3::lorawan::AdrComponent::tpAveraging

private

TX power from gateways policy.

Definition at line 169 of file adr-component.h.

Referenced by GetReceivedPower(), and GetTypeId().

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

src/lorawan/model/adr-component.h
src/lorawan/model/adr-component.cc

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ CombiningMethod

Constructor & Destructor Documentation

◆ AdrComponent()

◆ ~AdrComponent()

Member Function Documentation

◆ AdrImplementation()

◆ BeforeSendingReply()

◆ GetAverageSNR()

◆ GetAverageTxFromGateways()

◆ GetMaxSNR()

◆ GetMaxTxFromGateways()

◆ GetMinSNR()

◆ GetMinTxFromGateways()

◆ GetReceivedPower()

◆ GetTxPowerIndex()

◆ GetTypeId()

◆ OnFailedReply()

◆ OnReceivedPacket()

◆ RxPowerToSNR()

◆ SfToDr()

Member Data Documentation

◆ B

◆ historyAveraging

◆ historyRange

◆ m_toggleTxPower

◆ max_transmissionPower

◆ min_spreadingFactor

◆ min_transmissionPower

◆ NF

◆ threshold

◆ tpAveraging