LoRaMAC  4.4.6
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:1705
LoRaMacStatus_t
LoRaMacStatus_t
Definition: LoRaMac.h:2227
MlmeConfirm_t::MlmeRequest
Mlme_t MlmeRequest
Definition: LoRaMac.h:1234
LoRaMacPrimitives_t
Definition: LoRaMac.h:2343
MlmeReqJoin_t::Datarate
uint8_t Datarate
Definition: LoRaMac.h:1123
LoRaMacPrimitives_t::MacMcpsIndication
void(* MacMcpsIndication)(McpsIndication_t *McpsIndication)
MCPS-Indication primitive.
Definition: LoRaMac.h:2356
MIB_DEV_ADDR
Definition: LoRaMac.h:1418
MlmeIndication_t
Definition: LoRaMac.h:1270
LoRaMacPrimitives_t::MacMlmeIndication
void(* MacMlmeIndication)(MlmeIndication_t *MlmeIndication)
MLME-Indication primitive.
Definition: LoRaMac.h:2368
LoRaMacPrimitives_t::MacMlmeConfirm
void(* MacMlmeConfirm)(MlmeConfirm_t *MlmeConfirm)
MLME-Confirm primitive.
Definition: LoRaMac.h:2362
MibRequestConfirm_t::Type
Mib_t Type
Definition: LoRaMac.h:2200
MibRequestConfirm_t::Param
MibParam_t Param
Definition: LoRaMac.h:2205
MibParam_t::NetworkActivation
ActivationType_t NetworkActivation
Definition: LoRaMac.h:1786
MlmeReq_t
Definition: LoRaMac.h:1186
MlmeReq_t::uMlmeParam::Join
MlmeReqJoin_t Join
Definition: LoRaMac.h:1201
MIB_NETWORK_ACTIVATION
Definition: LoRaMac.h:1382
MlmeReq_t::Type
Mlme_t Type
Definition: LoRaMac.h:1191
LoRaMacCallback_t::GetBatteryLevel
uint8_t(* GetBatteryLevel)(void)
Measures the battery level.
Definition: LoRaMac.h:2384
LORAMAC_REGION_EU868
Definition: LoRaMac.h:520
LoRaMacCallback_t::MacProcessNotify
void(* MacProcessNotify)(void)
Will be called each time a Radio IRQ is handled by the MAC layer.
Definition: LoRaMac.h:2404
LORAMAC_EVENT_INFO_STATUS_OK
Definition: LoRaMac.h:381
MibRequestConfirm_t
Definition: LoRaMac.h:2195
MlmeConfirm_t::Status
LoRaMacEventInfoStatus_t Status
Definition: LoRaMac.h:1238
MLME_JOIN
Definition: LoRaMac.h:1029
LoRaMacPrimitives_t::MacMcpsConfirm
void(* MacMcpsConfirm)(McpsConfirm_t *McpsConfirm)
MCPS-Confirm primitive.
Definition: LoRaMac.h:2350
LoRaMacCallback_t::GetTemperatureLevel
float(* GetTemperatureLevel)(void)
Measures the temperature level.
Definition: LoRaMac.h:2390
MlmeConfirm_t
Definition: LoRaMac.h:1229
ACTIVATION_TYPE_ABP
Definition: LoRaMac.h:169
LoRaMacCallback_t
Definition: LoRaMac.h:2374
MibParam_t::DevAddr
uint32_t DevAddr
Definition: LoRaMac.h:1822
MLME_LINK_CHECK
Definition: LoRaMac.h:1047
DR_0
#define DR_0
Definition: LoRaMacTypes.h:77
McpsConfirm_t
Definition: LoRaMac.h:883
LoRaMacMlmeRequest
LoRaMacStatus_t LoRaMacMlmeRequest(MlmeReq_t *mlmeRequest)
LoRaMAC MLME-Request.
LORAMAC_STATUS_OK
Definition: LoRaMac.h:2232
MibParam_t::NetID
uint32_t NetID
Definition: LoRaMac.h:1816
MIB_NET_ID
Definition: LoRaMac.h:1412
McpsIndication_t
Definition: LoRaMac.h:926
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.