LoRaMAC  4.5.2
Documentation of the API
Quick-Start Guide

Overview

This quick start guide provides a short introduction into important operations of the LoRaMAC layer. Full examples for the different device classes are available in the example section.


Initialization

The initialization function of the LoRaMAC layer is LoRaMacInitialization( LoRaMacPrimitives_t *primitives, LoRaMacCallback_t *callbacks, LoRaMacRegion_t region ). The function has three parameters, LoRaMacPrimitives_t, LoRaMacCallback_t and LoRaMacRegion_t. The LoRaMAC layer utilizes primitives and callbacks, which must be provided by the upper layer. The data structure LoRaMacPrimitives_t contains function pointers to the Confirm and Indication primitives. The LoRaMAC layer will call the primitives to provide operation status information to the upper layers. The data structure LoRaMacCallback_t contains function pointers to procedures that should provide information for the LoRaMAC layer. E.g. the battery level of the device. The data type LoRaMacRegion_t specifies on which region the LoRaMAC layer shall operate.

The following code snippet provides an example for the initialization:

static void McpsConfirm( McpsConfirm_t *mcpsConfirm )
{
// Implementation of the MCPS-Confirm primitive
}
static void McpsIndication( McpsIndication_t *mcpsIndication )
{
// Implementation of the MCPS-Indication primitive
}
static void MlmeConfirm( MlmeConfirm_t *mlmeConfirm )
{
// Implementation of the MLME-Confirm primitive
}
static void MlmeIndication( MlmeIndication_t *mlmeIndication )
{
// Implementation of the MLME-Indication primitive
}
static void OnMacProcessNotify( void )
{
// Mac notification. Process run function
}
LoRaMacPrimitives_t LoRaMacPrimitives;
LoRaMacCallback_t LoRaMacCallbacks;
int main( void )
{
LoRaMacPrimitives.MacMcpsConfirm = McpsConfirm;
LoRaMacPrimitives.MacMcpsIndication = McpsIndication;
LoRaMacPrimitives.MacMlmeConfirm = MlmeConfirm;
LoRaMacPrimitives.MacMlmeIndication = MlmeIndication;
LoRaMacCallbacks.GetBatteryLevel = BoardGetBatteryLevel;
LoRaMacCallbacks.GetTemperatureLevel = NULL; // apply board specific temperature reading
LoRaMacCallbacks.NvmContextChange = NvmCtxMgmtEvent;
LoRaMacCallbacks.MacProcessNotify = OnMacProcessNotify;
// Initialization for the region EU868
Status = LoRaMacInitialization( &LoRaMacPrimitives, &LoRaMacCallbacks, LORAMAC_REGION_EU868 );
if( Status == LORAMAC_STATUS_OK )
{
// Initialization successful
}
}

Over-The-Air Activation (OTAA)

The LoRaMAC layer provides a MLME-Request to perform the over-the-air activation (LoRaMacMlmeRequest( MlmeReq_t *mlmeRequest )). The LoRaMAC layer creates the join-request message and reports the status of the operation with the MacMlmeConfirm primitive. Please note that the credentials are stored in the file se-identity.h for the related secure element.

The following code snippet provides an example:

static void MlmeConfirm( MlmeConfirm_t *mlmeConfirm )
{
if( mlmeConfirm->Status == LORAMAC_EVENT_INFO_STATUS_OK )
{
switch( mlmeConfirm->MlmeRequest )
{
case MLME_JOIN:
{
// Status is OK, node has joined the network
break;
}
{
// Check DemodMargin
// Check NbGateways
break;
}
default:
break;
}
}
}
int main( void )
{
MlmeReq_t mlmeReq;
// This comment is a placeholder for the initialization of the LoRaMAC layer
// Setup the request type
mlmeReq.Type = MLME_JOIN;
// Fill the join parameters
mlmeReq.Req.Join.Datarate = DR_0;
status = LoRaMacMlmeRequest( &mlmeReq );
if( status == LORAMAC_STATUS_OK )
{
// Join request was send successfully
}
}

Activation By Personalization (ABP)

The activation by personalization procedure requires to store important information on the LoRaMAC node:

  • LoRaWAN version
  • Network Identifier
  • Device Address
  • Activation

The application must configure those parameters to perform a personalized activation. In addition, the application has to enable the LoRaWAN network itself. Please note that the credentials are stored in the file se-identity.h for the related secure element.

The following code snippet provides an example:

int main( void )
{
uint32_t DevAddr;
// This comment is a placeholder for the initialization of the LoRaMAC layer
// Choose a random device address
DevAddr = randr( 0, 0x01FFFFFF );
mibReq.Param.AbpLrWanVersion.Value = 0x01000300;
return;
mibReq.Type = MIB_NET_ID;
mibReq.Param.NetID = 0x000000;
return;
mibReq.Type = MIB_DEV_ADDR;
mibReq.Param.DevAddr = DevAddr;
return;
return;
// LoRaWAN node has joined the network
}

Region Selection

The LoRaMAC Stack supports different regional setups. In general, it is possible to specify multiple regions such that it is possible to switch between them during runtime. A specific region can be enabled by defining the related symbol in the preprocessor options. E.g. to enable the EU868 region, please define REGION_EU868. If the LoRaMAC layer shall support more than one region at once, please define the corresponding symbol in addition.

The following symbols are supported:

  • REGION_EU868
  • REGION_US915
  • REGION_CN779
  • REGION_RU864
  • REGION_EU433
  • REGION_AU915
  • REGION_CN470
  • REGION_AS923
  • REGION_KR920
  • REGION_IN865

When multiple regions are selected during the build of the LoRaWAN Stack, it is possible to switch the region during runtime. To perform a region switch it is necessary to initialize the LoRaWAN Stack with the function LoRaMacInitialization( LoRaMacPrimitives_t *primitives, LoRaMacCallback_t *callbacks, LoRaMacRegion_t region ) again. When the node performs a switch of the region, the LoRaWAN Stack will restore all default values.


MIB_ABP_LORAWAN_VERSION
Definition: LoRaMac.h:1731
LoRaMacStatus_t
LoRaMacStatus_t
Definition: LoRaMac.h:2269
MlmeConfirm_t::MlmeRequest
Mlme_t MlmeRequest
Definition: LoRaMac.h:1250
LoRaMacPrimitives_t
Definition: LoRaMac.h:2385
MlmeReqJoin_t::Datarate
uint8_t Datarate
Definition: LoRaMac.h:1139
LoRaMacPrimitives_t::MacMcpsIndication
void(* MacMcpsIndication)(McpsIndication_t *McpsIndication)
MCPS-Indication primitive.
Definition: LoRaMac.h:2398
MIB_DEV_ADDR
Definition: LoRaMac.h:1436
MlmeIndication_t
Definition: LoRaMac.h:1286
LoRaMacPrimitives_t::MacMlmeIndication
void(* MacMlmeIndication)(MlmeIndication_t *MlmeIndication)
MLME-Indication primitive.
Definition: LoRaMac.h:2410
LoRaMacPrimitives_t::MacMlmeConfirm
void(* MacMlmeConfirm)(MlmeConfirm_t *MlmeConfirm)
MLME-Confirm primitive.
Definition: LoRaMac.h:2404
MibRequestConfirm_t::Type
Mib_t Type
Definition: LoRaMac.h:2242
MibRequestConfirm_t::Param
MibParam_t Param
Definition: LoRaMac.h:2247
MibParam_t::NetworkActivation
ActivationType_t NetworkActivation
Definition: LoRaMac.h:1816
MlmeReq_t
Definition: LoRaMac.h:1202
MlmeReq_t::uMlmeParam::Join
MlmeReqJoin_t Join
Definition: LoRaMac.h:1217
MIB_NETWORK_ACTIVATION
Definition: LoRaMac.h:1400
MlmeReq_t::Type
Mlme_t Type
Definition: LoRaMac.h:1207
LoRaMacCallback_t::GetBatteryLevel
uint8_t(* GetBatteryLevel)(void)
Measures the battery level.
Definition: LoRaMac.h:2426
LORAMAC_REGION_EU868
Definition: LoRaMac.h:538
LoRaMacCallback_t::MacProcessNotify
void(* MacProcessNotify)(void)
Will be called each time a Radio IRQ is handled by the MAC layer.
Definition: LoRaMac.h:2446
LORAMAC_EVENT_INFO_STATUS_OK
Definition: LoRaMac.h:399
MibRequestConfirm_t
Definition: LoRaMac.h:2237
MlmeConfirm_t::Status
LoRaMacEventInfoStatus_t Status
Definition: LoRaMac.h:1254
MLME_JOIN
Definition: LoRaMac.h:1045
LoRaMacPrimitives_t::MacMcpsConfirm
void(* MacMcpsConfirm)(McpsConfirm_t *McpsConfirm)
MCPS-Confirm primitive.
Definition: LoRaMac.h:2392
LoRaMacCallback_t::GetTemperatureLevel
float(* GetTemperatureLevel)(void)
Measures the temperature level.
Definition: LoRaMac.h:2432
MlmeConfirm_t
Definition: LoRaMac.h:1245
ACTIVATION_TYPE_ABP
Definition: LoRaMac.h:176
LoRaMacCallback_t
Definition: LoRaMac.h:2416
MibParam_t::DevAddr
uint32_t DevAddr
Definition: LoRaMac.h:1852
MLME_LINK_CHECK
Definition: LoRaMac.h:1063
DR_0
#define DR_0
Definition: LoRaMacTypes.h:77
McpsConfirm_t
Definition: LoRaMac.h:893
LoRaMacMlmeRequest
LoRaMacStatus_t LoRaMacMlmeRequest(MlmeReq_t *mlmeRequest)
LoRaMAC MLME-Request.
LORAMAC_STATUS_OK
Definition: LoRaMac.h:2274
MibParam_t::NetID
uint32_t NetID
Definition: LoRaMac.h:1846
MIB_NET_ID
Definition: LoRaMac.h:1430
McpsIndication_t
Definition: LoRaMac.h:936
LoRaMacInitialization
LoRaMacStatus_t LoRaMacInitialization(LoRaMacPrimitives_t *primitives, LoRaMacCallback_t *callbacks, LoRaMacRegion_t region)
LoRaMAC layer initialization.
LoRaMacMibSetRequestConfirm
LoRaMacStatus_t LoRaMacMibSetRequestConfirm(MibRequestConfirm_t *mibSet)
LoRaMAC MIB-Set.