LoRaMAC  4.4.5
Documentation of the API
LoRaMac.h File Reference

LoRa MAC layer implementation. More...

#include <stdint.h>
#include <stdbool.h>
#include "utilities.h"
#include "timer.h"
#include "systime.h"
#include "radio.h"
#include "LoRaMacTypes.h"
#include "region/Region.h"

Go to the source code of this file.

Data Structures

union  DrRange_t
 
struct  DrRange_t::sFields
 
struct  ChannelParams_t
 
struct  RxChannelParams_t
 
struct  LoRaMacCtxs_t
 
struct  LoRaMacParams_t
 
union  PingSlotInfo_t
 
struct  PingSlotInfo_t::sInfoFields
 
struct  BeaconInfo_t
 
struct  BeaconInfo_t::sGwSpecific
 
union  LoRaMacFlags_t
 
struct  LoRaMacFlags_t::sMacFlagBits
 
struct  RequestReturnParam_t
 
struct  McpsReqUnconfirmed_t
 
struct  McpsReqConfirmed_t
 
struct  McpsReqProprietary_t
 
struct  McpsReq_t
 
union  McpsReq_t::uMcpsParam
 
struct  McpsConfirm_t
 
struct  McpsIndication_t
 
struct  MlmeReqJoin_t
 
struct  MlmeReqTxCw_t
 
struct  MlmeReqPingSlotInfo_t
 
struct  MlmeReqDeriveMcKEKey_t
 
struct  MlmeReqDeriveMcSessionKeyPair_t
 
struct  MlmeReq_t
 
union  MlmeReq_t::uMlmeParam
 
struct  MlmeConfirm_t
 
struct  MlmeIndication_t
 
union  MibParam_t
 
struct  MibParam_t::sLrWanVersion
 
struct  MibRequestConfirm_t
 
struct  LoRaMacTxInfo_t
 
struct  LoRaMacPrimitives_t
 
struct  LoRaMacCallback_t
 

Macros

#define MAX_ACK_RETRIES   8
 
#define UP_LINK   0
 
#define DOWN_LINK   1
 
#define LORA_MAC_MLME_CONFIRM_QUEUE_LEN   5
 
#define LORAMAC_CRYPTO_MULTICAST_KEYS   127
 

Enumerations

enum  ActivationType_t { ACTIVATION_TYPE_NONE = 0, ACTIVATION_TYPE_ABP = 1, ACTIVATION_TYPE_OTAA = 2 }
 
enum  LoRaMacRxSlot_t {
  RX_SLOT_WIN_1, RX_SLOT_WIN_2, RX_SLOT_WIN_CLASS_C, RX_SLOT_WIN_CLASS_C_MULTICAST,
  RX_SLOT_WIN_CLASS_B_PING_SLOT, RX_SLOT_WIN_CLASS_B_MULTICAST_SLOT, RX_SLOT_NONE
}
 
enum  LoRaMacEventInfoStatus_t {
  LORAMAC_EVENT_INFO_STATUS_OK = 0, LORAMAC_EVENT_INFO_STATUS_ERROR, LORAMAC_EVENT_INFO_STATUS_TX_TIMEOUT, LORAMAC_EVENT_INFO_STATUS_RX1_TIMEOUT,
  LORAMAC_EVENT_INFO_STATUS_RX2_TIMEOUT, LORAMAC_EVENT_INFO_STATUS_RX1_ERROR, LORAMAC_EVENT_INFO_STATUS_RX2_ERROR, LORAMAC_EVENT_INFO_STATUS_JOIN_FAIL,
  LORAMAC_EVENT_INFO_STATUS_DOWNLINK_REPEATED, LORAMAC_EVENT_INFO_STATUS_TX_DR_PAYLOAD_SIZE_ERROR, LORAMAC_EVENT_INFO_STATUS_DOWNLINK_TOO_MANY_FRAMES_LOSS, LORAMAC_EVENT_INFO_STATUS_ADDRESS_FAIL,
  LORAMAC_EVENT_INFO_STATUS_MIC_FAIL, LORAMAC_EVENT_INFO_STATUS_MULTICAST_FAIL, LORAMAC_EVENT_INFO_STATUS_BEACON_LOCKED, LORAMAC_EVENT_INFO_STATUS_BEACON_LOST,
  LORAMAC_EVENT_INFO_STATUS_BEACON_NOT_FOUND
}
 
enum  Mcps_t { MCPS_UNCONFIRMED, MCPS_CONFIRMED, MCPS_MULTICAST, MCPS_PROPRIETARY }
 LoRaMAC data services. More...
 
enum  Mlme_t {
  MLME_UNKNOWN, MLME_JOIN, MLME_REJOIN_0, MLME_REJOIN_1,
  MLME_LINK_CHECK, MLME_TXCW, MLME_TXCW_1, MLME_SCHEDULE_UPLINK,
  MLME_DERIVE_MC_KE_KEY, MLME_DERIVE_MC_KEY_PAIR, MLME_DEVICE_TIME, MLME_BEACON,
  MLME_BEACON_ACQUISITION, MLME_PING_SLOT_INFO, MLME_BEACON_TIMING, MLME_BEACON_LOST
}
 LoRaMAC management services. More...
 
enum  Mib_t {
  MIB_DEVICE_CLASS, MIB_NETWORK_ACTIVATION, MIB_DEV_EUI, MIB_JOIN_EUI,
  MIB_SE_PIN, MIB_ADR, MIB_NET_ID, MIB_DEV_ADDR,
  MIB_APP_KEY, MIB_NWK_KEY, MIB_J_S_INT_KEY, MIB_J_S_ENC_KEY,
  MIB_F_NWK_S_INT_KEY, MIB_S_NWK_S_INT_KEY, MIB_NWK_S_ENC_KEY, MIB_APP_S_KEY,
  MIB_MC_KE_KEY, MIB_MC_KEY_0, MIB_MC_APP_S_KEY_0, MIB_MC_NWK_S_KEY_0,
  MIB_MC_KEY_1, MIB_MC_APP_S_KEY_1, MIB_MC_NWK_S_KEY_1, MIB_MC_KEY_2,
  MIB_MC_APP_S_KEY_2, MIB_MC_NWK_S_KEY_2, MIB_MC_KEY_3, MIB_MC_APP_S_KEY_3,
  MIB_MC_NWK_S_KEY_3, MIB_PUBLIC_NETWORK, MIB_CHANNELS, MIB_RX2_CHANNEL,
  MIB_RX2_DEFAULT_CHANNEL, MIB_RXC_CHANNEL, MIB_RXC_DEFAULT_CHANNEL, MIB_CHANNELS_MASK,
  MIB_CHANNELS_DEFAULT_MASK, MIB_CHANNELS_NB_TRANS, MIB_MAX_RX_WINDOW_DURATION, MIB_RECEIVE_DELAY_1,
  MIB_RECEIVE_DELAY_2, MIB_JOIN_ACCEPT_DELAY_1, MIB_JOIN_ACCEPT_DELAY_2, MIB_CHANNELS_DEFAULT_DATARATE,
  MIB_CHANNELS_DATARATE, MIB_CHANNELS_TX_POWER, MIB_CHANNELS_DEFAULT_TX_POWER, MIB_SYSTEM_MAX_RX_ERROR,
  MIB_MIN_RX_SYMBOLS, MIB_ANTENNA_GAIN, MIB_DEFAULT_ANTENNA_GAIN, MIB_NVM_CTXS,
  MIB_ABP_LORAWAN_VERSION, MIB_LORAWAN_VERSION, MIB_BEACON_INTERVAL, MIB_BEACON_RESERVED,
  MIB_BEACON_GUARD, MIB_BEACON_WINDOW, MIB_BEACON_WINDOW_SLOTS, MIB_PING_SLOT_WINDOW,
  MIB_BEACON_SYMBOL_TO_DEFAULT, MIB_BEACON_SYMBOL_TO_EXPANSION_MAX, MIB_PING_SLOT_SYMBOL_TO_EXPANSION_MAX, MIB_BEACON_SYMBOL_TO_EXPANSION_FACTOR,
  MIB_PING_SLOT_SYMBOL_TO_EXPANSION_FACTOR, MIB_MAX_BEACON_LESS_PERIOD, MIB_PING_SLOT_DATARATE
}
 
enum  LoRaMacStatus_t {
  LORAMAC_STATUS_OK, LORAMAC_STATUS_BUSY, LORAMAC_STATUS_SERVICE_UNKNOWN, LORAMAC_STATUS_PARAMETER_INVALID,
  LORAMAC_STATUS_FREQUENCY_INVALID, LORAMAC_STATUS_DATARATE_INVALID, LORAMAC_STATUS_FREQ_AND_DR_INVALID, LORAMAC_STATUS_NO_NETWORK_JOINED,
  LORAMAC_STATUS_LENGTH_ERROR, LORAMAC_STATUS_REGION_NOT_SUPPORTED, LORAMAC_STATUS_SKIPPED_APP_DATA, LORAMAC_STATUS_DUTYCYCLE_RESTRICTED,
  LORAMAC_STATUS_NO_CHANNEL_FOUND, LORAMAC_STATUS_NO_FREE_CHANNEL_FOUND, LORAMAC_STATUS_BUSY_BEACON_RESERVED_TIME, LORAMAC_STATUS_BUSY_PING_SLOT_WINDOW_TIME,
  LORAMAC_STATUS_BUSY_UPLINK_COLLISION, LORAMAC_STATUS_CRYPTO_ERROR, LORAMAC_STATUS_FCNT_HANDLER_ERROR, LORAMAC_STATUS_MAC_COMMAD_ERROR,
  LORAMAC_STATUS_CLASS_B_ERROR, LORAMAC_STATUS_CONFIRM_QUEUE_ERROR, LORAMAC_STATUS_MC_GROUP_UNDEFINED, LORAMAC_STATUS_ERROR
}
 
enum  LoRaMacRegion_t {
  LORAMAC_REGION_AS923, LORAMAC_REGION_AU915, LORAMAC_REGION_CN470, LORAMAC_REGION_CN779,
  LORAMAC_REGION_EU433, LORAMAC_REGION_EU868, LORAMAC_REGION_KR920, LORAMAC_REGION_IN865,
  LORAMAC_REGION_US915, LORAMAC_REGION_RU864
}
 
enum  LoRaMacNvmCtxModule_t {
  LORAMAC_NVMCTXMODULE_MAC, LORAMAC_NVMCTXMODULE_REGION, LORAMAC_NVMCTXMODULE_CRYPTO, LORAMAC_NVMCTXMODULE_SECURE_ELEMENT,
  LORAMAC_NVMCTXMODULE_COMMANDS, LORAMAC_NVMCTXMODULE_CLASS_B, LORAMAC_NVMCTXMODULE_CONFIRM_QUEUE
}
 

Functions

LoRaMacStatus_t LoRaMacInitialization (LoRaMacPrimitives_t *primitives, LoRaMacCallback_t *callbacks, LoRaMacRegion_t region)
 LoRaMAC layer initialization. More...
 
LoRaMacStatus_t LoRaMacStart (void)
 Starts LoRaMAC layer. More...
 
LoRaMacStatus_t LoRaMacStop (void)
 Stops LoRaMAC layer. More...
 
bool LoRaMacIsBusy (void)
 Returns a value indicating if the MAC layer is busy or not. More...
 
void LoRaMacProcess (void)
 
LoRaMacStatus_t LoRaMacQueryTxPossible (uint8_t size, LoRaMacTxInfo_t *txInfo)
 Queries the LoRaMAC if it is possible to send the next frame with a given application data payload size. The LoRaMAC takes scheduled MAC commands into account and reports, when the frame can be send or not. More...
 
LoRaMacStatus_t LoRaMacChannelAdd (uint8_t id, ChannelParams_t params)
 LoRaMAC channel add service. More...
 
LoRaMacStatus_t LoRaMacChannelRemove (uint8_t id)
 LoRaMAC channel remove service. More...
 
LoRaMacStatus_t LoRaMacMcChannelSetup (McChannelParams_t *channel)
 LoRaMAC multicast channel setup service. More...
 
LoRaMacStatus_t LoRaMacMcChannelDelete (AddressIdentifier_t groupID)
 LoRaMAC multicast channel removal service. More...
 
uint8_t LoRaMacMcChannelGetGroupId (uint32_t mcAddress)
 LoRaMAC multicast channel get groupId from MC address. More...
 
LoRaMacStatus_t LoRaMacMcChannelSetupRxParams (AddressIdentifier_t groupID, McRxParams_t *rxParams, uint8_t *status)
 LoRaMAC multicast channel Rx parameters setup service. More...
 
LoRaMacStatus_t LoRaMacMibGetRequestConfirm (MibRequestConfirm_t *mibGet)
 LoRaMAC MIB-Get. More...
 
LoRaMacStatus_t LoRaMacMibSetRequestConfirm (MibRequestConfirm_t *mibSet)
 LoRaMAC MIB-Set. More...
 
LoRaMacStatus_t LoRaMacMlmeRequest (MlmeReq_t *mlmeRequest)
 LoRaMAC MLME-Request. More...
 
LoRaMacStatus_t LoRaMacMcpsRequest (McpsReq_t *mcpsRequest)
 LoRaMAC MCPS-Request. More...
 
LoRaMacStatus_t LoRaMacDeInitialization (void)
 LoRaMAC deinitialization. More...
 

Detailed Description

LoRa MAC layer implementation.

______ _
/ _____) _ | |
( (____ _____ ____ _| |_ _____ ____| |__
\____ \| ___ | (_ _) ___ |/ ___) _ \
_____) ) ____| | | || |_| ____( (___| | | |
(______/|_____)_|_|_| \__)_____)\____)_| |_|
(C)2013-2017 Semtech
___ _____ _ ___ _ _____ ___ ___ ___ ___
/ __|_ _/_\ / __| |/ / __/ _ \| _ \/ __| __|
\__ \ | |/ _ \ (__| ' <| _| (_) | / (__| _|
|___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___|
embedded.connectivity.solutions===============
Author
Miguel Luis ( Semtech )
Gregory Cristian ( Semtech )
Daniel Jaeckle ( STACKFORCE )
Johannes Bruder ( STACKFORCE )

Data Structure Documentation

◆ DrRange_t::sFields

struct DrRange_t::sFields

Structure to store the minimum and the maximum datarate

Data Fields
int8_t Min: 4

Minimum data rate

LoRaWAN Regional Parameters V1.0.2rB

The allowed ranges are region specific. Please refer to DR_0 to DR_15 for details.

int8_t Max: 4

Maximum data rate

LoRaWAN Regional Parameters V1.0.2rB

The allowed ranges are region specific. Please refer to DR_0 to DR_15 for details.

◆ PingSlotInfo_t::sInfoFields

struct PingSlotInfo_t::sInfoFields

Structure containing the parameters for the PingSlotInfoReq

Data Fields
uint8_t Periodicity: 3

Periodicity = 0: ping slot every second Periodicity = 7: ping slot every 128 seconds

uint8_t RFU: 5

RFU

◆ BeaconInfo_t::sGwSpecific

struct BeaconInfo_t::sGwSpecific

Data structure for the gateway specific part. The content of the values may differ for each gateway

Data Fields
uint8_t InfoDesc

Info descriptor - can differ for each gateway

uint8_t Info[6]

Info - can differ for each gateway

◆ LoRaMacFlags_t::sMacFlagBits

struct LoRaMacFlags_t::sMacFlagBits

Structure containing single access to bits

Data Fields
uint8_t McpsReq: 1

MCPS-Req pending

uint8_t McpsInd: 1

MCPS-Ind pending

uint8_t MlmeReq: 1

MLME-Req pending

uint8_t MlmeInd: 1

MLME-Ind pending

uint8_t MlmeSchedUplinkInd: 1

MLME-Ind to schedule an uplink pending

uint8_t MacDone: 1

MAC cycle done

◆ McpsReq_t::uMcpsParam

union McpsReq_t::uMcpsParam

MCPS-Request parameters

Data Fields
McpsReqUnconfirmed_t Unconfirmed

MCPS-Request parameters for an unconfirmed frame

McpsReqConfirmed_t Confirmed

MCPS-Request parameters for a confirmed frame

McpsReqProprietary_t Proprietary

MCPS-Request parameters for a proprietary frame

◆ MlmeReq_t::uMlmeParam

union MlmeReq_t::uMlmeParam

MLME-Request parameters

Data Fields
MlmeReqJoin_t Join

MLME-Request parameters for a join request

MlmeReqTxCw_t TxCw

MLME-Request parameters for Tx continuous mode request

MlmeReqPingSlotInfo_t PingSlotInfo

MLME-Request parameters for a ping slot info request

MlmeReqDeriveMcKEKey_t DeriveMcKEKey

MLME-Request to derive the McKEKey from the AppKey or NwkKey

MlmeReqDeriveMcSessionKeyPair_t DeriveMcSessionKeyPair

MLME-Request to derive a Multicast group key pair ( McAppSKey, McNwkSKey ) from McKey

◆ MibParam_t::sLrWanVersion

struct MibParam_t::sLrWanVersion
Data Fields
Version_t LoRaWan
Version_t LoRaWanRegion