LoRaMAC  4.4.6
Documentation of the API
Common region implementation

Region independent implementations which are common to all regions. More...

Data Structures

struct  RegionCommonRxBeaconSetupParams_t
 
struct  RegionCommonCountNbOfEnabledChannelsParams_t
 
struct  RegionCommonIdentifyChannelsParam_t
 
struct  RegionCommonSetDutyCycleParams_t
 
struct  RegionCommonGetNextLowerTxDrParams_t
 
struct  RegionNvmDataGroup1_t
 
struct  RegionNvmDataGroup2_t
 

Macros

#define REGION_COMMON_DEFAULT_RECEIVE_DELAY1   1000
 
#define REGION_COMMON_DEFAULT_RECEIVE_DELAY2   ( REGION_COMMON_DEFAULT_RECEIVE_DELAY1 + 1000 )
 
#define REGION_COMMON_DEFAULT_JOIN_ACCEPT_DELAY1   5000
 
#define REGION_COMMON_DEFAULT_JOIN_ACCEPT_DELAY2   ( REGION_COMMON_DEFAULT_JOIN_ACCEPT_DELAY1 + 1000 )
 
#define REGION_COMMON_DEFAULT_ADR_ACK_LIMIT   64
 
#define REGION_COMMON_DEFAULT_ADR_ACK_DELAY   32
 
#define REGION_COMMON_DEFAULT_MAX_FCNT_GAP   16384
 
#define REGION_COMMON_DEFAULT_ACK_TIMEOUT   2000
 
#define REGION_COMMON_DEFAULT_ACK_TIMEOUT_RND   1000
 
#define REGION_COMMON_DEFAULT_RX1_DR_OFFSET   0
 
#define REGION_COMMON_DEFAULT_DOWNLINK_DWELL_TIME   0
 
#define REGION_COMMON_DEFAULT_PING_SLOT_PERIODICITY   7
 
#define REGION_NVM_MAX_NB_CHANNELS   8
 
#define REGION_NVM_MAX_NB_BANDS   1
 
#define REGION_NVM_CHANNELS_MASK_SIZE   1
 

Functions

uint8_t RegionCommonValueInRange (int8_t value, int8_t min, int8_t max)
 Verifies, if a value is in a given range. This is a generic function and valid for all regions. More...
 
bool RegionCommonChanVerifyDr (uint8_t nbChannels, uint16_t *channelsMask, int8_t dr, int8_t minDr, int8_t maxDr, ChannelParams_t *channels)
 Verifies, if a datarate is available on an active channel. This is a generic function and valid for all regions. More...
 
bool RegionCommonChanDisable (uint16_t *channelsMask, uint8_t id, uint8_t maxChannels)
 Disables a channel in a given channels mask. This is a generic function and valid for all regions. More...
 
uint8_t RegionCommonCountChannels (uint16_t *channelsMask, uint8_t startIdx, uint8_t stopIdx)
 Counts the number of active channels in a given channels mask. This is a generic function and valid for all regions. More...
 
void RegionCommonChanMaskCopy (uint16_t *channelsMaskDest, uint16_t *channelsMaskSrc, uint8_t len)
 Copy a channels mask. This is a generic function and valid for all regions. More...
 
void RegionCommonSetBandTxDone (Band_t *band, TimerTime_t lastTxAirTime, bool joined, SysTime_t elapsedTimeSinceStartup)
 Sets the last tx done property. This is a generic function and valid for all regions. More...
 
TimerTime_t RegionCommonUpdateBandTimeOff (bool joined, Band_t *bands, uint8_t nbBands, bool dutyCycleEnabled, bool lastTxIsJoinRequest, SysTime_t elapsedTimeSinceStartup, TimerTime_t expectedTimeOnAir)
 Updates the time-offs of the bands. This is a generic function and valid for all regions. More...
 
uint8_t RegionCommonParseLinkAdrReq (uint8_t *payload, RegionCommonLinkAdrParams_t *parseLinkAdr)
 Parses the parameter of an LinkAdrRequest. This is a generic function and valid for all regions. More...
 
uint8_t RegionCommonLinkAdrReqVerifyParams (RegionCommonLinkAdrReqVerifyParams_t *verifyParams, int8_t *dr, int8_t *txPow, uint8_t *nbRep)
 Verifies and updates the datarate, the TX power and the number of repetitions of a LinkAdrRequest. This depends on the configuration of ADR also. More...
 
uint32_t RegionCommonComputeSymbolTimeLoRa (uint8_t phyDr, uint32_t bandwidthInHz)
 Computes the symbol time for LoRa modulation. More...
 
uint32_t RegionCommonComputeSymbolTimeFsk (uint8_t phyDrInKbps)
 Computes the symbol time for FSK modulation. More...
 
void RegionCommonComputeRxWindowParameters (uint32_t tSymbolInUs, uint8_t minRxSymbols, uint32_t rxErrorInMs, uint32_t wakeUpTimeInMs, uint32_t *windowTimeoutInSymbols, int32_t *windowOffsetInMs)
 Computes the RX window timeout and the RX window offset. More...
 
int8_t RegionCommonComputeTxPower (int8_t txPowerIndex, float maxEirp, float antennaGain)
 Computes the txPower, based on the max EIRP and the antenna gain. More...
 
void RegionCommonRxBeaconSetup (RegionCommonRxBeaconSetupParams_t *rxBeaconSetupParams)
 Sets up the radio into RX beacon mode. More...
 
void RegionCommonCountNbOfEnabledChannels (RegionCommonCountNbOfEnabledChannelsParams_t *countNbOfEnabledChannelsParams, uint8_t *enabledChannels, uint8_t *nbEnabledChannels, uint8_t *nbRestrictedChannels)
 Counts the number of enabled channels. More...
 
LoRaMacStatus_t RegionCommonIdentifyChannels (RegionCommonIdentifyChannelsParam_t *identifyChannelsParam, TimerTime_t *aggregatedTimeOff, uint8_t *enabledChannels, uint8_t *nbEnabledChannels, uint8_t *nbRestrictedChannels, TimerTime_t *nextTxDelay)
 Identifies all channels which are available currently. More...
 
int8_t RegionCommonGetNextLowerTxDr (RegionCommonGetNextLowerTxDrParams_t *params)
 Selects the next lower datarate. More...
 
int8_t RegionCommonLimitTxPower (int8_t txPower, int8_t maxBandTxPower)
 Limits the TX power. More...
 
uint32_t RegionCommonGetBandwidth (uint32_t drIndex, const uint32_t *bandwidths)
 Gets the bandwidth. More...
 

Detailed Description

Region independent implementations which are common to all regions.


Data Structure Documentation

◆ RegionCommonLinkAdrParams_t

struct RegionCommonLinkAdrParams_t
Data Fields
uint8_t NbRep

Number of repetitions.

int8_t Datarate

Datarate.

int8_t TxPower

Tx power.

uint8_t ChMaskCtrl

Channels mask control field.

uint16_t ChMask

Channels mask field.

◆ RegionCommonLinkAdrReqVerifyParams_t

struct RegionCommonLinkAdrReqVerifyParams_t
Data Fields
Version_t Version

LoRaWAN specification Version

uint8_t Status

The current status of the AdrLinkRequest.

bool AdrEnabled

Set to true, if ADR is enabled.

int8_t Datarate

The datarate the AdrLinkRequest wants to set.

int8_t TxPower

The TX power the AdrLinkRequest wants to set.

uint8_t NbRep

The number of repetitions the AdrLinkRequest wants to set.

int8_t CurrentDatarate

The current datarate the node is using.

int8_t CurrentTxPower

The current TX power the node is using.

int8_t CurrentNbRep

The current number of repetitions the node is using.

uint8_t NbChannels

The number of channels.

uint16_t * ChannelsMask

Pointer to the first element of the channels mask.

int8_t MinDatarate

The minimum possible datarate.

int8_t MaxDatarate

The maximum possible datarate.

ChannelParams_t * Channels

Pointer to the channels.

int8_t MinTxPower

The minimum possible TX power.

int8_t MaxTxPower

The maximum possible TX power.

◆ RegionCommonRxBeaconSetupParams_t

struct RegionCommonRxBeaconSetupParams_t
Data Fields
const uint8_t * Datarates

A pointer to the available datarates.

uint32_t Frequency

Frequency

uint8_t BeaconSize

The size of the beacon frame.

uint8_t BeaconDatarate

The datarate of the beacon.

uint8_t BeaconChannelBW

The channel bandwidth of the beacon.

uint32_t RxTime

The RX time.

uint16_t SymbolTimeout

The symbol timeout of the RX procedure.

◆ RegionCommonCountNbOfEnabledChannelsParams_t

struct RegionCommonCountNbOfEnabledChannelsParams_t
Data Fields
bool Joined

Set to true, if the device is joined.

uint8_t Datarate

The datarate to count the available channels.

uint16_t * ChannelsMask

A pointer to the channels mask to verify.

ChannelParams_t * Channels

A pointer to the channels.

Band_t * Bands

A pointer to the bands.

uint16_t MaxNbChannels

The number of available channels.

uint16_t * JoinChannels

A pointer to the bitmask containing the join channels. Shall have the same dimension as the ChannelsMask with a number of MaxNbChannels channels.

◆ RegionCommonIdentifyChannelsParam_t

struct RegionCommonIdentifyChannelsParam_t
Data Fields
TimerTime_t AggrTimeOff

Aggregated time-off time.

TimerTime_t LastAggrTx

Time of the last aggregated TX.

bool DutyCycleEnabled

Set to true, if the duty cycle is enabled, otherwise false.

uint8_t MaxBands

Maximum number of bands.

SysTime_t ElapsedTimeSinceStartUp

Elapsed time since the start of the node.

bool LastTxIsJoinRequest

Joined Set to true, if the last uplink was a join request

TimerTime_t ExpectedTimeOnAir

Expected time-on-air

RegionCommonCountNbOfEnabledChannelsParams_t * CountNbOfEnabledChannelsParam

Pointer to a structure of RegionCommonCountNbOfEnabledChannelsParams_t.

◆ RegionCommonSetDutyCycleParams_t

struct RegionCommonSetDutyCycleParams_t
Data Fields
TimerTime_t DutyCycleTimePeriod

Duty cycle period.

uint8_t MaxBands

Number of bands available.

Band_t * Bands

A pointer to the bands.

◆ RegionCommonGetNextLowerTxDrParams_t

struct RegionCommonGetNextLowerTxDrParams_t
Data Fields
int8_t CurrentDr
int8_t MaxDr
int8_t MinDr
uint8_t NbChannels
uint16_t * ChannelsMask
ChannelParams_t * Channels

◆ RegionNvmDataGroup1_t

struct RegionNvmDataGroup1_t

Region specific data which must be stored in the NVM.

Data Fields
Band_t Bands[REGION_NVM_MAX_NB_BANDS]

LoRaMac bands

uint32_t Crc32

CRC32 value of the Region data structure.

◆ RegionNvmDataGroup2_t

struct RegionNvmDataGroup2_t

Region specific data which must be stored in the NVM. Parameters which do not change very frequently.

Data Fields
ChannelParams_t Channels[REGION_NVM_MAX_NB_CHANNELS]

LoRaMAC channels

uint16_t ChannelsMask[REGION_NVM_CHANNELS_MASK_SIZE]

LoRaMac channels mask

uint16_t ChannelsDefaultMask[REGION_NVM_CHANNELS_MASK_SIZE]

LoRaMac channels default mask

uint32_t Crc32

CRC32 value of the Region data structure.

Macro Definition Documentation

◆ REGION_COMMON_DEFAULT_RECEIVE_DELAY1

#define REGION_COMMON_DEFAULT_RECEIVE_DELAY1   1000

Receive delay of 1 second.

◆ REGION_COMMON_DEFAULT_RECEIVE_DELAY2

#define REGION_COMMON_DEFAULT_RECEIVE_DELAY2   ( REGION_COMMON_DEFAULT_RECEIVE_DELAY1 + 1000 )

Receive delay of 2 seconds.

◆ REGION_COMMON_DEFAULT_JOIN_ACCEPT_DELAY1

#define REGION_COMMON_DEFAULT_JOIN_ACCEPT_DELAY1   5000

Join accept delay of 5 seconds.

◆ REGION_COMMON_DEFAULT_JOIN_ACCEPT_DELAY2

#define REGION_COMMON_DEFAULT_JOIN_ACCEPT_DELAY2   ( REGION_COMMON_DEFAULT_JOIN_ACCEPT_DELAY1 + 1000 )

Join accept delay of 6 seconds.

◆ REGION_COMMON_DEFAULT_ADR_ACK_LIMIT

#define REGION_COMMON_DEFAULT_ADR_ACK_LIMIT   64

ADR ack limit.

◆ REGION_COMMON_DEFAULT_ADR_ACK_DELAY

#define REGION_COMMON_DEFAULT_ADR_ACK_DELAY   32

ADR ack delay.

◆ REGION_COMMON_DEFAULT_MAX_FCNT_GAP

#define REGION_COMMON_DEFAULT_MAX_FCNT_GAP   16384

Maximum frame counter gap

◆ REGION_COMMON_DEFAULT_ACK_TIMEOUT

#define REGION_COMMON_DEFAULT_ACK_TIMEOUT   2000

Retransmission timeout for ACK in milliseconds.

◆ REGION_COMMON_DEFAULT_ACK_TIMEOUT_RND

#define REGION_COMMON_DEFAULT_ACK_TIMEOUT_RND   1000

Rounding limit for generating random retransmission timeout for ACK. In milliseconds.

◆ REGION_COMMON_DEFAULT_RX1_DR_OFFSET

#define REGION_COMMON_DEFAULT_RX1_DR_OFFSET   0

Default Rx1 receive datarate offset

◆ REGION_COMMON_DEFAULT_DOWNLINK_DWELL_TIME

#define REGION_COMMON_DEFAULT_DOWNLINK_DWELL_TIME   0

Default downlink dwell time configuration

◆ REGION_COMMON_DEFAULT_PING_SLOT_PERIODICITY

#define REGION_COMMON_DEFAULT_PING_SLOT_PERIODICITY   7

Default ping slots periodicity

Periodicity is equal to 2^REGION_COMMON_DEFAULT_PING_SLOT_PERIODICITY seconds. Example: 2^7 = 128 seconds. The end-device will open an Rx slot every 128 seconds.

Function Documentation

◆ RegionCommonValueInRange()

uint8_t RegionCommonValueInRange ( int8_t  value,
int8_t  min,
int8_t  max 
)

Verifies, if a value is in a given range. This is a generic function and valid for all regions.

Parameters
[IN]value Value to verify, if it is in range.
[IN]min Minimum possible value.
[IN]max Maximum possible value.
Return values
Returns1 if the value is in range, otherwise 0.

◆ RegionCommonChanVerifyDr()

bool RegionCommonChanVerifyDr ( uint8_t  nbChannels,
uint16_t *  channelsMask,
int8_t  dr,
int8_t  minDr,
int8_t  maxDr,
ChannelParams_t channels 
)

Verifies, if a datarate is available on an active channel. This is a generic function and valid for all regions.

Parameters
[IN]nbChannels Number of channels.
[IN]channelsMask The channels mask of the region.
[IN]dr The datarate to verify.
[IN]minDr Minimum datarate.
[IN]maxDr Maximum datarate.
[IN]channels The channels of the region.
Return values
Returnstrue if the datarate is supported, false if not.

◆ RegionCommonChanDisable()

bool RegionCommonChanDisable ( uint16_t *  channelsMask,
uint8_t  id,
uint8_t  maxChannels 
)

Disables a channel in a given channels mask. This is a generic function and valid for all regions.

Parameters
[IN]channelsMask The channels mask of the region.
[IN]id The id of the channels mask to disable.
[IN]maxChannels Maximum number of channels.
Return values
Returnstrue if the channel could be disabled, false if not.

◆ RegionCommonCountChannels()

uint8_t RegionCommonCountChannels ( uint16_t *  channelsMask,
uint8_t  startIdx,
uint8_t  stopIdx 
)

Counts the number of active channels in a given channels mask. This is a generic function and valid for all regions.

Parameters
[IN]channelsMask The channels mask of the region.
[IN]startIdx Start index.
[IN]stopIdx Stop index ( the channels of this index will not be counted ).
Return values
Returnsthe number of active channels.

◆ RegionCommonChanMaskCopy()

void RegionCommonChanMaskCopy ( uint16_t *  channelsMaskDest,
uint16_t *  channelsMaskSrc,
uint8_t  len 
)

Copy a channels mask. This is a generic function and valid for all regions.

Parameters
[IN]channelsMaskDest The destination channels mask.
[IN]channelsMaskSrc The source channels mask.
[IN]len The index length to copy.

◆ RegionCommonSetBandTxDone()

void RegionCommonSetBandTxDone ( Band_t band,
TimerTime_t  lastTxAirTime,
bool  joined,
SysTime_t  elapsedTimeSinceStartup 
)

Sets the last tx done property. This is a generic function and valid for all regions.

Parameters
[IN]band The band to be updated.
[IN]lastTxAirTime The time on air of the last TX frame.
[IN]joined Set to true if the device has joined.
[IN]elapsedTimeSinceStartup Elapsed time since initialization.

◆ RegionCommonUpdateBandTimeOff()

TimerTime_t RegionCommonUpdateBandTimeOff ( bool  joined,
Band_t bands,
uint8_t  nbBands,
bool  dutyCycleEnabled,
bool  lastTxIsJoinRequest,
SysTime_t  elapsedTimeSinceStartup,
TimerTime_t  expectedTimeOnAir 
)

Updates the time-offs of the bands. This is a generic function and valid for all regions.

Parameters
[IN]joined Set to true, if the node has joined the network
[IN]bands A pointer to the bands.
[IN]nbBands The number of bands available.
[IN]dutyCycleEnabled Set to true, if the duty cycle is enabled.
[IN]lastTxIsJoinRequest Set to true, if the last TX is a join request.
[IN]elapsedTimeSinceStartup Elapsed time since start up.
[IN]expectedTimeOnAir Expected time on air for the next transmission.
Return values
Returnsthe time which must be waited to perform the next uplink.

◆ RegionCommonParseLinkAdrReq()

uint8_t RegionCommonParseLinkAdrReq ( uint8_t *  payload,
RegionCommonLinkAdrParams_t parseLinkAdr 
)

Parses the parameter of an LinkAdrRequest. This is a generic function and valid for all regions.

Parameters
[IN]payload Pointer to the payload containing the MAC commands. The payload must contain the CMD identifier, following by the parameters.
[OUT]parseLinkAdr The function fills the structure with the ADR parameters.
Return values
Returnsthe length of the ADR request, if a request was found. Otherwise, the function returns 0.

◆ RegionCommonLinkAdrReqVerifyParams()

uint8_t RegionCommonLinkAdrReqVerifyParams ( RegionCommonLinkAdrReqVerifyParams_t verifyParams,
int8_t *  dr,
int8_t *  txPow,
uint8_t *  nbRep 
)

Verifies and updates the datarate, the TX power and the number of repetitions of a LinkAdrRequest. This depends on the configuration of ADR also.

Parameters
[IN]verifyParams Pointer to a structure containing input parameters.
[OUT]dr The updated datarate.
[OUT]txPow The updated TX power.
[OUT]nbRep The updated number of repetitions.
Return values
Returnsthe status according to the LinkAdrRequest definition.

◆ RegionCommonComputeSymbolTimeLoRa()

uint32_t RegionCommonComputeSymbolTimeLoRa ( uint8_t  phyDr,
uint32_t  bandwidthInHz 
)

Computes the symbol time for LoRa modulation.

Parameters
[IN]phyDr Physical datarate to use.
[IN]bandwidth Bandwidth to use.
Return values
Returnsthe symbol time in microseconds.

◆ RegionCommonComputeSymbolTimeFsk()

uint32_t RegionCommonComputeSymbolTimeFsk ( uint8_t  phyDrInKbps)

Computes the symbol time for FSK modulation.

Parameters
[IN]phyDr Physical datarate to use.
Return values
Returnsthe symbol time in microseconds.

◆ RegionCommonComputeRxWindowParameters()

void RegionCommonComputeRxWindowParameters ( uint32_t  tSymbolInUs,
uint8_t  minRxSymbols,
uint32_t  rxErrorInMs,
uint32_t  wakeUpTimeInMs,
uint32_t *  windowTimeoutInSymbols,
int32_t *  windowOffsetInMs 
)

Computes the RX window timeout and the RX window offset.

Parameters
[IN]tSymbolInUs Symbol timeout.
[IN]minRxSymbols Minimum required number of symbols to detect an Rx frame.
[IN]rxErrorInMs System maximum timing error of the receiver. In milliseconds The receiver will turn on in a [-rxErrorInMs : +rxErrorInMs] ms interval around RxOffset.
[IN]wakeUpTimeInMs Wakeup time of the system.
[OUT]windowTimeoutInSymbols RX window timeout.
[OUT]windowOffsetInMs RX window time offset to be applied to the RX delay.

◆ RegionCommonComputeTxPower()

int8_t RegionCommonComputeTxPower ( int8_t  txPowerIndex,
float  maxEirp,
float  antennaGain 
)

Computes the txPower, based on the max EIRP and the antenna gain.

Remarks
US915 region uses a conducted power as input value for maxEirp. Thus, the antennaGain parameter must be set to 0.
Parameters
[IN]txPower TX power index.
[IN]maxEirp Maximum EIRP.
[IN]antennaGain Antenna gain. Referenced to the isotropic antenna. Value is in dBi. ( antennaGain[dBi] = measuredAntennaGain[dBd] + 2.15 )
Return values
Returnsthe physical TX power.

◆ RegionCommonRxBeaconSetup()

void RegionCommonRxBeaconSetup ( RegionCommonRxBeaconSetupParams_t rxBeaconSetupParams)

Sets up the radio into RX beacon mode.

Parameters
[IN]rxBeaconSetupParams A pointer to the input parameters.

◆ RegionCommonCountNbOfEnabledChannels()

void RegionCommonCountNbOfEnabledChannels ( RegionCommonCountNbOfEnabledChannelsParams_t countNbOfEnabledChannelsParams,
uint8_t *  enabledChannels,
uint8_t *  nbEnabledChannels,
uint8_t *  nbRestrictedChannels 
)

Counts the number of enabled channels.

Parameters
[IN]countNbOfEnabledChannelsParams A pointer to the input parameters.
[OUT]enabledChannels A pointer to an array of size XX_MAX_NB_CHANNELS. The function stores the available channels into this array.
[OUT]nbEnabledChannels The number of available channels found.
[OUT]nbRestrictedChannels It contains the number of channel which are available, but restricted due to duty cycle.

◆ RegionCommonIdentifyChannels()

LoRaMacStatus_t RegionCommonIdentifyChannels ( RegionCommonIdentifyChannelsParam_t identifyChannelsParam,
TimerTime_t *  aggregatedTimeOff,
uint8_t *  enabledChannels,
uint8_t *  nbEnabledChannels,
uint8_t *  nbRestrictedChannels,
TimerTime_t *  nextTxDelay 
)

Identifies all channels which are available currently.

Parameters
[IN]identifyChannelsParam A pointer to the input parameters.
[OUT]aggregatedTimeOff The new value of the aggregatedTimeOff. The function may resets it to 0.
[OUT]enabledChannels A pointer to an array of size XX_MAX_NB_CHANNELS. The function stores the available channels into this array.
[OUT]nbEnabledChannels The number of available channels found.
[OUT]nbRestrictedChannels It contains the number of channel which are available, but restricted due to duty cycle.
[OUT]nextTxDelay Holds the time which has to be waited for the next possible uplink transmission.
Return values
Statusof the operation.

◆ RegionCommonGetNextLowerTxDr()

int8_t RegionCommonGetNextLowerTxDr ( RegionCommonGetNextLowerTxDrParams_t params)

Selects the next lower datarate.

Parameters
[IN]params Data structure providing parameters based on RegionCommonGetNextLowerTxDrParams_t
Return values
Thenext lower datarate.

◆ RegionCommonLimitTxPower()

int8_t RegionCommonLimitTxPower ( int8_t  txPower,
int8_t  maxBandTxPower 
)

Limits the TX power.

Parameters
[IN]txPower Current TX power.
[IN]maxBandTxPower Maximum possible TX power.
Return values
LimitedTX power.

◆ RegionCommonGetBandwidth()

uint32_t RegionCommonGetBandwidth ( uint32_t  drIndex,
const uint32_t *  bandwidths 
)

Gets the bandwidth.

Parameters
[IN]drIndex Datarate index.
[IN]bandwidths A pointer to the bandwidth table.
Return values
Bandwidth.