![]() |
LoRaMAC
4.4.6
Documentation of the API
|
Region independent implementations which are common to all regions. More...
Data Structures | |
struct | RegionCommonLinkAdrParams_t |
struct | RegionCommonLinkAdrReqVerifyParams_t |
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... | |
Region independent implementations which are common to all regions.
struct RegionCommonLinkAdrParams_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. |
struct RegionCommonRxBeaconSetupParams_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. |
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. |
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. |
struct RegionCommonGetNextLowerTxDrParams_t |
Data Fields | ||
---|---|---|
int8_t | CurrentDr | |
int8_t | MaxDr | |
int8_t | MinDr | |
uint8_t | NbChannels | |
uint16_t * | ChannelsMask | |
ChannelParams_t * | Channels |
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. |
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. |
#define REGION_COMMON_DEFAULT_RECEIVE_DELAY1 1000 |
Receive delay of 1 second.
#define REGION_COMMON_DEFAULT_RECEIVE_DELAY2 ( REGION_COMMON_DEFAULT_RECEIVE_DELAY1 + 1000 ) |
Receive delay of 2 seconds.
#define REGION_COMMON_DEFAULT_JOIN_ACCEPT_DELAY1 5000 |
Join accept delay of 5 seconds.
#define REGION_COMMON_DEFAULT_JOIN_ACCEPT_DELAY2 ( REGION_COMMON_DEFAULT_JOIN_ACCEPT_DELAY1 + 1000 ) |
Join accept delay of 6 seconds.
#define REGION_COMMON_DEFAULT_ADR_ACK_LIMIT 64 |
ADR ack limit.
#define REGION_COMMON_DEFAULT_ADR_ACK_DELAY 32 |
ADR ack delay.
#define REGION_COMMON_DEFAULT_MAX_FCNT_GAP 16384 |
Maximum frame counter gap
#define REGION_COMMON_DEFAULT_ACK_TIMEOUT 2000 |
Retransmission timeout for ACK in milliseconds.
#define REGION_COMMON_DEFAULT_ACK_TIMEOUT_RND 1000 |
Rounding limit for generating random retransmission timeout for ACK. In milliseconds.
#define REGION_COMMON_DEFAULT_RX1_DR_OFFSET 0 |
Default Rx1 receive datarate offset
#define REGION_COMMON_DEFAULT_DOWNLINK_DWELL_TIME 0 |
Default downlink dwell time configuration
#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.
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.
[IN] | value Value to verify, if it is in range. |
[IN] | min Minimum possible value. |
[IN] | max Maximum possible value. |
Returns | 1 if the value is in range, otherwise 0. |
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.
[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. |
Returns | true if the datarate is supported, false if not. |
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.
[IN] | channelsMask The channels mask of the region. |
[IN] | id The id of the channels mask to disable. |
[IN] | maxChannels Maximum number of channels. |
Returns | true if the channel could be disabled, false if not. |
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.
[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 ). |
Returns | the number of active channels. |
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.
[IN] | channelsMaskDest The destination channels mask. |
[IN] | channelsMaskSrc The source channels mask. |
[IN] | len The index length to copy. |
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.
[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. |
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.
[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. |
Returns | the time which must be waited to perform the next uplink. |
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.
[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. |
Returns | the length of the ADR request, if a request was found. Otherwise, the function returns 0. |
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.
[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. |
Returns | the status according to the LinkAdrRequest definition. |
uint32_t RegionCommonComputeSymbolTimeLoRa | ( | uint8_t | phyDr, |
uint32_t | bandwidthInHz | ||
) |
Computes the symbol time for LoRa modulation.
[IN] | phyDr Physical datarate to use. |
[IN] | bandwidth Bandwidth to use. |
Returns | the symbol time in microseconds. |
uint32_t RegionCommonComputeSymbolTimeFsk | ( | uint8_t | phyDrInKbps | ) |
Computes the symbol time for FSK modulation.
[IN] | phyDr Physical datarate to use. |
Returns | the symbol time in microseconds. |
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.
[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. |
int8_t RegionCommonComputeTxPower | ( | int8_t | txPowerIndex, |
float | maxEirp, | ||
float | antennaGain | ||
) |
Computes the txPower, based on the max EIRP and the antenna gain.
[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 ) |
Returns | the physical TX power. |
void RegionCommonRxBeaconSetup | ( | RegionCommonRxBeaconSetupParams_t * | rxBeaconSetupParams | ) |
Sets up the radio into RX beacon mode.
[IN] | rxBeaconSetupParams A pointer to the input parameters. |
void RegionCommonCountNbOfEnabledChannels | ( | RegionCommonCountNbOfEnabledChannelsParams_t * | countNbOfEnabledChannelsParams, |
uint8_t * | enabledChannels, | ||
uint8_t * | nbEnabledChannels, | ||
uint8_t * | nbRestrictedChannels | ||
) |
Counts the number of enabled channels.
[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. |
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.
[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. |
Status | of the operation. |
int8_t RegionCommonGetNextLowerTxDr | ( | RegionCommonGetNextLowerTxDrParams_t * | params | ) |
Selects the next lower datarate.
[IN] | params Data structure providing parameters based on RegionCommonGetNextLowerTxDrParams_t |
The | next lower datarate. |
int8_t RegionCommonLimitTxPower | ( | int8_t | txPower, |
int8_t | maxBandTxPower | ||
) |
Limits the TX power.
[IN] | txPower Current TX power. |
[IN] | maxBandTxPower Maximum possible TX power. |
Limited | TX power. |
uint32_t RegionCommonGetBandwidth | ( | uint32_t | drIndex, |
const uint32_t * | bandwidths | ||
) |
Gets the bandwidth.
[IN] | drIndex Datarate index. |
[IN] | bandwidths A pointer to the bandwidth table. |
Bandwidth. |