Helper class for configuring and installing the LorawanMac class on devices and gateways. More...

#include "lorawan-mac-helper.h"

Collaboration diagram for ns3::lorawan::LorawanMacHelper:

Public Types
enum	DeviceType { GW , ED_A }
	Define the kind of device. More...

enum	Regions { EU , US , China , EU433MHz , Australia , CN , AS923MHz , SouthKorea , SingleChannel , ALOHA }
	Define the operational region. More...

Public Member Functions
	LorawanMacHelper ()
	Default constructor.

Ptr< LorawanMac >	Create (Ptr< Node > node, Ptr< NetDevice > device) const
	Create the LorawanMac instance and connect it to a device.

void	Set (std::string name, const AttributeValue &v)
	Set an attribute of the underlying MAC object.

void	SetAddressGenerator (Ptr< LoraDeviceAddressGenerator > addrGen)
	Set the address generator to use for creation of these nodes.

void	SetDeviceType (enum DeviceType dt)
	Set the kind of MAC this helper will create.

void	SetRegion (enum Regions region)
	Set the region in which the device is to operate.

Static Public Member Functions
static std::vector< int >	SetSpreadingFactorsGivenDistribution (NodeContainer endDevices, NodeContainer gateways, std::vector< double > distribution)
	Randomly initialize the end devices' data rate parameter according to the given distribution.

static std::vector< int >	SetSpreadingFactorsUp (NodeContainer endDevices, NodeContainer gateways, Ptr< LoraChannel > channel)
	Initialize the end devices' data rate parameter.

Private Member Functions
void	ApplyCommonAlohaConfigurations (Ptr< LorawanMac > lorawanMac) const
	Apply configurations that are common both for the GatewayLorawanMac and the ClassAEndDeviceLorawanMac classes.

void	ApplyCommonEuConfigurations (Ptr< LorawanMac > lorawanMac) const
	Apply configurations that are common both for the GatewayLorawanMac and the ClassAEndDeviceLorawanMac classes.

void	ApplyCommonSingleChannelConfigurations (Ptr< LorawanMac > lorawanMac) const
	Apply configurations that are common both for the GatewayLorawanMac and the ClassAEndDeviceLorawanMac classes.

void	ConfigureForAlohaRegion (Ptr< ClassAEndDeviceLorawanMac > edMac) const
	Perform region-specific configurations for the ALOHA band.

void	ConfigureForAlohaRegion (Ptr< GatewayLorawanMac > gwMac) const
	Perform region-specific configurations for the ALOHA band.

void	ConfigureForEuRegion (Ptr< ClassAEndDeviceLorawanMac > edMac) const
	Perform region-specific configurations for the 868 MHz EU band.

void	ConfigureForEuRegion (Ptr< GatewayLorawanMac > gwMac) const
	Perform region-specific configurations for the 868 MHz EU band.

void	ConfigureForSingleChannelRegion (Ptr< ClassAEndDeviceLorawanMac > edMac) const
	Perform region-specific configurations for the SINGLECHANNEL band.

void	ConfigureForSingleChannelRegion (Ptr< GatewayLorawanMac > gwMac) const
	Perform region-specific configurations for the SINGLECHANNEL band.

Private Attributes
Ptr< LoraDeviceAddressGenerator >	m_addrGen
	Pointer to the address generator to use.

enum DeviceType	m_deviceType
	The kind of device to install.

ObjectFactory	m_mac
	MAC-layer object factory.

enum Regions	m_region
	The region in which the device will operate.

Detailed Description

Helper class for configuring and installing the LorawanMac class on devices and gateways.

The user must set all parameters before calling Install on nodes.

Definition at line 44 of file lorawan-mac-helper.h.

Member Enumeration Documentation

◆ DeviceType

enum ns3::lorawan::LorawanMacHelper::DeviceType

Define the kind of device.

Can be either GW (Gateway) or ED (End Device).

Enumerator
GW
ED_A

Definition at line 50 of file lorawan-mac-helper.h.

◆ Regions

enum ns3::lorawan::LorawanMacHelper::Regions

Define the operational region.

Enumerator
EU
US
China
EU433MHz
Australia
CN
AS923MHz
SouthKorea
SingleChannel
ALOHA

Definition at line 59 of file lorawan-mac-helper.h.

Constructor & Destructor Documentation

◆ LorawanMacHelper()

ns3::lorawan::LorawanMacHelper::LorawanMacHelper ( )

Default constructor.

Definition at line 35 of file lorawan-mac-helper.cc.

Member Function Documentation

◆ ApplyCommonAlohaConfigurations()

void ns3::lorawan::LorawanMacHelper::ApplyCommonAlohaConfigurations ( Ptr< LorawanMac > lorawanMac ) const

private

Apply configurations that are common both for the GatewayLorawanMac and the ClassAEndDeviceLorawanMac classes.

Parameters

lorawanMac Pointer to the MAC layer to configure.

Definition at line 206 of file lorawan-mac-helper.cc.

References ns3::lorawan::LogicalLoraChannelHelper::AddChannel(), ns3::lorawan::LogicalLoraChannelHelper::AddSubBand(), and NS_LOG_FUNCTION_NOARGS.

Referenced by ConfigureForAlohaRegion().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ApplyCommonEuConfigurations()

void ns3::lorawan::LorawanMacHelper::ApplyCommonEuConfigurations ( Ptr< LorawanMac > lorawanMac ) const

private

Apply configurations that are common both for the GatewayLorawanMac and the ClassAEndDeviceLorawanMac classes.

Parameters

lorawanMac Pointer to the MAC layer to configure.

Definition at line 312 of file lorawan-mac-helper.cc.

References ns3::lorawan::LogicalLoraChannelHelper::AddChannel(), ns3::lorawan::LogicalLoraChannelHelper::AddSubBand(), and NS_LOG_FUNCTION_NOARGS.

Referenced by ConfigureForEuRegion(), and ConfigureForSingleChannelRegion().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ApplyCommonSingleChannelConfigurations()

void ns3::lorawan::LorawanMacHelper::ApplyCommonSingleChannelConfigurations ( Ptr< LorawanMac > lorawanMac ) const

private

Apply configurations that are common both for the GatewayLorawanMac and the ClassAEndDeviceLorawanMac classes.

Parameters

lorawanMac Pointer to the MAC layer to configure.

Definition at line 424 of file lorawan-mac-helper.cc.

References ns3::lorawan::LogicalLoraChannelHelper::AddChannel(), ns3::lorawan::LogicalLoraChannelHelper::AddSubBand(), and NS_LOG_FUNCTION_NOARGS.

Referenced by ConfigureForSingleChannelRegion().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ConfigureForAlohaRegion() [1/2]

void ns3::lorawan::LorawanMacHelper::ConfigureForAlohaRegion ( Ptr< ClassAEndDeviceLorawanMac > edMac ) const

private

Perform region-specific configurations for the ALOHA band.

Parameters

edMac Pointer to the device MAC layer to configure.

Definition at line 140 of file lorawan-mac-helper.cc.

References ApplyCommonAlohaConfigurations(), and NS_LOG_FUNCTION_NOARGS.

Referenced by Create().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ConfigureForAlohaRegion() [2/2]

void ns3::lorawan::LorawanMacHelper::ConfigureForAlohaRegion ( Ptr< GatewayLorawanMac > gwMac ) const

private

Perform region-specific configurations for the ALOHA band.

Parameters

gwMac Pointer to the gateway MAC layer to configure.

Definition at line 177 of file lorawan-mac-helper.cc.

References ApplyCommonAlohaConfigurations(), ns3::Object::GetObject(), NS_LOG_DEBUG, and NS_LOG_FUNCTION_NOARGS.

Here is the call graph for this function:

◆ ConfigureForEuRegion() [1/2]

void ns3::lorawan::LorawanMacHelper::ConfigureForEuRegion ( Ptr< ClassAEndDeviceLorawanMac > edMac ) const

private

Perform region-specific configurations for the 868 MHz EU band.

Parameters

edMac Pointer to the device MAC layer to configure.

Definition at line 237 of file lorawan-mac-helper.cc.

References ApplyCommonEuConfigurations(), and NS_LOG_FUNCTION_NOARGS.

Referenced by Create().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ConfigureForEuRegion() [2/2]

void ns3::lorawan::LorawanMacHelper::ConfigureForEuRegion ( Ptr< GatewayLorawanMac > gwMac ) const

private

Perform region-specific configurations for the 868 MHz EU band.

Parameters

gwMac Pointer to the gateway MAC layer to configure.

Definition at line 274 of file lorawan-mac-helper.cc.

References ApplyCommonEuConfigurations(), ns3::Object::GetObject(), NS_LOG_DEBUG, and NS_LOG_FUNCTION_NOARGS.

Here is the call graph for this function:

◆ ConfigureForSingleChannelRegion() [1/2]

void ns3::lorawan::LorawanMacHelper::ConfigureForSingleChannelRegion ( Ptr< ClassAEndDeviceLorawanMac > edMac ) const

private

Perform region-specific configurations for the SINGLECHANNEL band.

Parameters

edMac Pointer to the device MAC layer to configure.

Definition at line 351 of file lorawan-mac-helper.cc.

References ApplyCommonSingleChannelConfigurations(), and NS_LOG_FUNCTION_NOARGS.

Referenced by Create().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ConfigureForSingleChannelRegion() [2/2]

void ns3::lorawan::LorawanMacHelper::ConfigureForSingleChannelRegion ( Ptr< GatewayLorawanMac > gwMac ) const

private

Perform region-specific configurations for the SINGLECHANNEL band.

Parameters

gwMac Pointer to the gateway MAC layer to configure.

Definition at line 388 of file lorawan-mac-helper.cc.

References ApplyCommonEuConfigurations(), ns3::Object::GetObject(), NS_LOG_DEBUG, and NS_LOG_FUNCTION_NOARGS.

Here is the call graph for this function:

◆ Create()

Ptr< LorawanMac > ns3::lorawan::LorawanMacHelper::Create	(	Ptr< Node >	node,
		Ptr< NetDevice >	device
	)		const

Create the LorawanMac instance and connect it to a device.

Parameters

node	The node on which we wish to create a wifi MAC.
device	The device within which this MAC will be created.

Returns: A newly-created LorawanMac object.

Definition at line 77 of file lorawan-mac-helper.cc.

References ALOHA, ConfigureForAlohaRegion(), ConfigureForEuRegion(), ConfigureForSingleChannelRegion(), ns3::ObjectFactory::Create(), ED_A, EU, m_addrGen, m_deviceType, m_mac, m_region, NS_LOG_ERROR, and SingleChannel.

Referenced by ns3::lorawan::LoraHelper::Install().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Set()

void ns3::lorawan::LorawanMacHelper::Set	(	std::string	name,
		const AttributeValue &	v
	)

Set an attribute of the underlying MAC object.

Parameters

name	The name of the attribute to set.
v	The value of the attribute.

Definition at line 41 of file lorawan-mac-helper.cc.

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

Here is the call graph for this function:

◆ SetAddressGenerator()

void ns3::lorawan::LorawanMacHelper::SetAddressGenerator ( Ptr< LoraDeviceAddressGenerator > addrGen )

Set the address generator to use for creation of these nodes.

Parameters

addrGen Pointer to the address generator object.

Definition at line 63 of file lorawan-mac-helper.cc.

References m_addrGen, and NS_LOG_FUNCTION.

◆ SetDeviceType()

void ns3::lorawan::LorawanMacHelper::SetDeviceType ( enum DeviceType dt )

Set the kind of MAC this helper will create.

Parameters

dt	The device type (either gateway or end device).

Definition at line 47 of file lorawan-mac-helper.cc.

References ED_A, GW, m_deviceType, m_mac, NS_LOG_FUNCTION, and ns3::ObjectFactory::SetTypeId().

Referenced by ns3::lorawan::CreateEndDevices(), and ns3::lorawan::CreateGateways().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SetRegion()

void ns3::lorawan::LorawanMacHelper::SetRegion ( enum Regions region )

Set the region in which the device is to operate.

Parameters

region The region enum value.

Definition at line 71 of file lorawan-mac-helper.cc.

References m_region.

◆ SetSpreadingFactorsGivenDistribution()

std::vector< int > ns3::lorawan::LorawanMacHelper::SetSpreadingFactorsGivenDistribution	(	NodeContainer	endDevices,
		NodeContainer	gateways,
		std::vector< double >	distribution
	)

static

Randomly initialize the end devices' data rate parameter according to the given distribution.

This function expects a data rate (DR) distribution vector of length 6 filled with real numbers summing up to 1. The value at index is considered to be the fraction of devices to be assigned DR , for example:

distribution[0] == 0.2 -> fraction of devices to be assigned to DR5
distribution[1] == 0.1 -> fraction of devices to be assigned to DR4
distribution[2] == 0.1 -> fraction of devices to be assigned to DR3
distribution[3] == 0.1 -> fraction of devices to be assigned to DR2
distribution[4] == 0.2 -> fraction of devices to be assigned to DR1
distribution[5] == 0.3 -> fraction of devices to be assigned to DR0

Devices are then randomly assigned a DR following the provided distribution.

It returns a DR distribution vector with the following counters:

v[0] -> number of devices using DR5
v[1] -> number of devices using DR4
v[2] -> number of devices using DR3
v[3] -> number of devices using DR2
v[4] -> number of devices using DR1
v[5] -> number of devices using DR0

Parameters

endDevices	The end devices to configure.
gateways	The gateways in the network (this is only a placeholder parameter).
distribution	The distribution (probability mass function) of DR assignment.

Returns: A vector containing the final number of devices per DR.

Todo:: Remove unused parameter gateways.

Definition at line 600 of file lorawan-mac-helper.cc.

References ns3::NodeContainer::Begin(), ns3::NodeContainer::End(), NS_ASSERT, NS_LOG_DEBUG, and NS_LOG_FUNCTION_NOARGS.

Here is the call graph for this function:

◆ SetSpreadingFactorsUp()

std::vector< int > ns3::lorawan::LorawanMacHelper::SetSpreadingFactorsUp	(	NodeContainer	endDevices,
		NodeContainer	gateways,
		Ptr< LoraChannel >	channel
	)

static

Initialize the end devices' data rate parameter.

The Data Rate (DR) of each device is set to the maximum possible for its transmissions to be correctly received by the gateway measuring the best RSSI from the device, mimicking the DR maximization part of the default online LoRaWAN Adaptive Data Rate (ADR) algorithm. Please note that a single RSSI measurement between each device and gateway pair is taken for the DR assignment, so the assignment may be suboptimal in scenarios with a time-varying channel.

This function uses the following convention (EU868) to compute the transmission range:

DR5 -> SF7
DR4 -> SF8
DR3 -> SF9
DR2 -> SF10
DR1 -> SF11
DR0 -> SF12

It returns a DR distribution vector with the following counters:

v[0] -> number of devices using DR5
v[1] -> number of devices using DR4
v[2] -> number of devices using DR3
v[3] -> number of devices using DR2
v[4] -> number of devices using DR1
v[5] -> number of devices using DR0, in range of at least a gateway
v[6] -> number of devices using DR0, out of range

Parameters

endDevices	The end devices to configure.
gateways	The gateways to consider for RSSI measurements.
channel	The radio channel to consider for RSSI measurements.

Returns: A vector containing the final number of devices per DR.

Definition at line 457 of file lorawan-mac-helper.cc.

References ns3::NodeContainer::Begin(), ns3::NodeContainer::End(), ns3::NodeContainer::Get(), NS_ASSERT, and NS_LOG_FUNCTION_NOARGS.

Referenced by ns3::lorawan::InitializeNetwork().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ m_addrGen

Ptr<LoraDeviceAddressGenerator> ns3::lorawan::LorawanMacHelper::m_addrGen

private

Pointer to the address generator to use.

Definition at line 258 of file lorawan-mac-helper.h.

Referenced by Create(), and SetAddressGenerator().

◆ m_deviceType

enum DeviceType ns3::lorawan::LorawanMacHelper::m_deviceType

private

The kind of device to install.

Definition at line 259 of file lorawan-mac-helper.h.

Referenced by Create(), and SetDeviceType().

◆ m_mac

ObjectFactory ns3::lorawan::LorawanMacHelper::m_mac

private

MAC-layer object factory.

Definition at line 257 of file lorawan-mac-helper.h.

Referenced by Create(), Set(), and SetDeviceType().

◆ m_region

enum Regions ns3::lorawan::LorawanMacHelper::m_region

private

The region in which the device will operate.

Definition at line 260 of file lorawan-mac-helper.h.

Referenced by Create(), and SetRegion().

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

src/lorawan/helper/lorawan-mac-helper.h
src/lorawan/helper/lorawan-mac-helper.cc

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ DeviceType

◆ Regions

Constructor & Destructor Documentation

◆ LorawanMacHelper()

Member Function Documentation

◆ ApplyCommonAlohaConfigurations()

◆ ApplyCommonEuConfigurations()

◆ ApplyCommonSingleChannelConfigurations()

◆ ConfigureForAlohaRegion() [1/2]

◆ ConfigureForAlohaRegion() [2/2]

◆ ConfigureForEuRegion() [1/2]

◆ ConfigureForEuRegion() [2/2]

◆ ConfigureForSingleChannelRegion() [1/2]

◆ ConfigureForSingleChannelRegion() [2/2]

◆ Create()

◆ Set()

◆ SetAddressGenerator()

◆ SetDeviceType()

◆ SetRegion()

◆ SetSpreadingFactorsGivenDistribution()

◆ SetSpreadingFactorsUp()

Member Data Documentation

◆ m_addrGen

◆ m_deviceType

◆ m_mac

◆ m_region