SX126x-Arduino  2.0.1
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
LoRa MAC layer implementation

This module specifies the API implementation of the LoRaMAC layer. This is a placeholder for a detailed description of the LoRaMac layer and the supported features. More...

Data Structures

union  uDrRange
 
struct  sBand
 
struct  sChannelParams
 
struct  sRx2ChannelParams
 
struct  sLoRaMacParams
 
struct  sMulticastParams
 
union  uLoRaMacHeader
 
union  uLoRaMacFrameCtrl
 
union  eLoRaMacFlags_t
 
struct  sMcpsReqUnconfirmed
 
struct  sMcpsReqConfirmed
 
struct  sMcpsReqProprietary
 
struct  sMcpsReq
 
struct  sMcpsConfirm
 
struct  sMcpsIndication
 
struct  sMlmeReqJoin
 
struct  sMlmeReqTxCw
 
struct  sMlmeReq
 
struct  sMlmeConfirm
 
union  uMibParam
 
struct  eMibRequestConfirm
 
struct  sLoRaMacTxInfo
 
struct  sLoRaMacPrimitives
 
struct  sLoRaMacCallback
 

Macros

#define MAC_STATE_CHECK_TIMEOUT   250
 
#define MAX_ACK_RETRIES   8
 
#define UP_LINK   0
 
#define DOWN_LINK   1
 
#define LORAMAC_MFR_LEN   4
 
#define LORA_MAC_FRMPAYLOAD_OVERHEAD   13
 

Typedefs

typedef enum eDeviceClass DeviceClass_t
 
typedef union uDrRange DrRange_t
 
typedef struct sBand Band_t
 
typedef struct sChannelParams ChannelParams_t
 
typedef struct sRx2ChannelParams Rx2ChannelParams_t
 
typedef struct sLoRaMacParams LoRaMacParams_t
 
typedef struct sMulticastParams MulticastParams_t
 
typedef enum eLoRaMacFrameType LoRaMacFrameType_t
 
typedef enum eLoRaMacMoteCmd LoRaMacMoteCmd_t
 
typedef enum eLoRaMacSrvCmd LoRaMacSrvCmd_t
 
typedef enum eLoRaMacBatteryLevel LoRaMacBatteryLevel_t
 
typedef union uLoRaMacHeader LoRaMacHeader_t
 
typedef union uLoRaMacFrameCtrl LoRaMacFrameCtrl_t
 
typedef enum eLoRaMacEventInfoStatus LoRaMacEventInfoStatus_t
 
typedef union eLoRaMacFlags_t LoRaMacFlags_t
 
typedef enum eMcps Mcps_t
 LoRaMAC data services. More...
 
typedef struct sMcpsReqUnconfirmed McpsReqUnconfirmed_t
 
typedef struct sMcpsReqConfirmed McpsReqConfirmed_t
 
typedef struct sMcpsReqProprietary McpsReqProprietary_t
 
typedef struct sMcpsReq McpsReq_t
 
typedef struct sMcpsConfirm McpsConfirm_t
 
typedef struct sMcpsIndication McpsIndication_t
 
typedef enum eMlme Mlme_t
 LoRaMAC management services. More...
 
typedef struct sMlmeReqJoin MlmeReqJoin_t
 
typedef struct sMlmeReqTxCw MlmeReqTxCw_t
 
typedef struct sMlmeReq MlmeReq_t
 
typedef struct sMlmeConfirm MlmeConfirm_t
 
typedef enum eMib Mib_t
 
typedef enum eJoinStatus eJoinStatus_t
 
typedef union uMibParam MibParam_t
 
typedef struct eMibRequestConfirm MibRequestConfirm_t
 
typedef struct sLoRaMacTxInfo LoRaMacTxInfo_t
 
typedef enum eLoRaMacStatus LoRaMacStatus_t
 
typedef enum eLoRaMacRegion_t LoRaMacRegion_t
 
typedef struct sLoRaMacPrimitives LoRaMacPrimitives_t
 
typedef struct sLoRaMacCallback LoRaMacCallback_t
 

Enumerations

enum  eDeviceClass { CLASS_A, CLASS_B, CLASS_C }
 
enum  eLoRaMacFrameType {
  FRAME_TYPE_JOIN_REQ = 0x00, FRAME_TYPE_JOIN_ACCEPT = 0x01, FRAME_TYPE_DATA_UNCONFIRMED_UP = 0x02, FRAME_TYPE_DATA_UNCONFIRMED_DOWN = 0x03,
  FRAME_TYPE_DATA_CONFIRMED_UP = 0x04, FRAME_TYPE_DATA_CONFIRMED_DOWN = 0x05, FRAME_TYPE_RFU = 0x06, FRAME_TYPE_PROPRIETARY = 0x07
}
 
enum  eLoRaMacMoteCmd {
  MOTE_MAC_LINK_CHECK_REQ = 0x02, MOTE_MAC_LINK_ADR_ANS = 0x03, MOTE_MAC_DUTY_CYCLE_ANS = 0x04, MOTE_MAC_RX_PARAM_SETUP_ANS = 0x05,
  MOTE_MAC_DEV_STATUS_ANS = 0x06, MOTE_MAC_NEW_CHANNEL_ANS = 0x07, MOTE_MAC_RX_TIMING_SETUP_ANS = 0x08, MOTE_MAC_TX_PARAM_SETUP_ANS = 0x09,
  MOTE_MAC_DL_CHANNEL_ANS = 0x0A
}
 
enum  eLoRaMacSrvCmd {
  SRV_MAC_LINK_CHECK_ANS = 0x02, SRV_MAC_LINK_ADR_REQ = 0x03, SRV_MAC_DUTY_CYCLE_REQ = 0x04, SRV_MAC_RX_PARAM_SETUP_REQ = 0x05,
  SRV_MAC_DEV_STATUS_REQ = 0x06, SRV_MAC_NEW_CHANNEL_REQ = 0x07, SRV_MAC_RX_TIMING_SETUP_REQ = 0x08, SRV_MAC_TX_PARAM_SETUP_REQ = 0x09,
  SRV_MAC_DL_CHANNEL_REQ = 0x0A
}
 
enum  eLoRaMacBatteryLevel { BAT_LEVEL_EXT_SRC = 0x00, BAT_LEVEL_EMPTY = 0x01, BAT_LEVEL_FULL = 0xFE, BAT_LEVEL_NO_MEASURE = 0xFF }
 
enum  eLoRaMacEventInfoStatus {
  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
}
 
enum  eMcps { MCPS_UNCONFIRMED, MCPS_CONFIRMED, MCPS_MULTICAST, MCPS_PROPRIETARY }
 LoRaMAC data services. More...
 
enum  eMlme { MLME_JOIN, MLME_LINK_CHECK, MLME_TXCW, MLME_TXCW_1 }
 LoRaMAC management services. More...
 
enum  eMib {
  MIB_DEVICE_CLASS, MIB_NETWORK_JOINED, MIB_ADR, MIB_NET_ID,
  MIB_DEV_ADDR, MIB_NWK_SKEY, MIB_APP_SKEY, MIB_PUBLIC_NETWORK,
  MIB_REPEATER_SUPPORT, MIB_CHANNELS, MIB_RX2_CHANNEL, MIB_RX2_DEFAULT_CHANNEL,
  MIB_CHANNELS_MASK, MIB_CHANNELS_DEFAULT_MASK, MIB_CHANNELS_NB_REP, 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_UPLINK_COUNTER, MIB_DOWNLINK_COUNTER, MIB_MULTICAST_CHANNEL, MIB_SYSTEM_MAX_RX_ERROR,
  MIB_MIN_RX_SYMBOLS, MIB_ANTENNA_GAIN
}
 
enum  eJoinStatus { JOIN_NOT_START, JOIN_OK, JOIN_ONGOING, JOIN_FAILED }
 
enum  eLoRaMacStatus {
  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_DEVICE_OFF, LORAMAC_STATUS_REGION_NOT_SUPPORTED
}
 
enum  eLoRaMacRegion_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_AS923_2, LORAMAC_REGION_AS923_3, LORAMAC_REGION_AS923_4,
  LORAMAC_REGION_RU864
}
 

Functions

LoRaMacStatus_t LoRaMacInitialization (LoRaMacPrimitives_t *primitives, LoRaMacCallback_t *callbacks, LoRaMacRegion_t region, eDeviceClass nodeClass=CLASS_A)
 LoRaMAC layer initialization. More...
 
uint32_t LoRaMacGetOTAADevId (void)
 Returns the Device Address set by the LoRaWan server after OTAA join was successful. More...
 
LoRaMacStatus_t LoRaMacQueryTxPossible (uint8_t size, LoRaMacTxInfo_t *txInfo)
 Queries the LoRaMAC if it is possible to send the next frame with a given 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 LoRaMacMulticastChannelLink (MulticastParams_t *channelParam)
 LoRaMAC multicast channel link service. More...
 
LoRaMacStatus_t LoRaMacMulticastChannelUnlink (MulticastParams_t *channelParam)
 LoRaMAC multicast channel unlink 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...
 

Variables

LoRaMacRegion_t LoRaMacRegion
 
static const uint8_t LoRaMacMaxEirpTable [] = {8, 10, 12, 13, 14, 16, 18, 20, 21, 24, 26, 27, 29, 30, 33, 36}
 

Detailed Description

This module specifies the API implementation of the LoRaMAC layer. This is a placeholder for a detailed description of the LoRaMac layer and the supported features.

Macro Definition Documentation

◆ MAC_STATE_CHECK_TIMEOUT

#define MAC_STATE_CHECK_TIMEOUT   250

Check the Mac layer state every MAC_STATE_CHECK_TIMEOUT in ms

◆ MAX_ACK_RETRIES

#define MAX_ACK_RETRIES   8

Maximum number of times the MAC layer tries to get an acknowledge.

◆ UP_LINK

#define UP_LINK   0

Frame direction definition for up-link communications

◆ DOWN_LINK

#define DOWN_LINK   1

Frame direction definition for down-link communications

◆ LORAMAC_MFR_LEN

#define LORAMAC_MFR_LEN   4

Sets the length of the LoRaMAC footer field. Mainly indicates the MIC field length

◆ LORA_MAC_FRMPAYLOAD_OVERHEAD

#define LORA_MAC_FRMPAYLOAD_OVERHEAD   13

FRMPayload overhead to be used when setting the Radio.SetMaxPayloadLength in RxWindowSetup function. Maximum PHYPayload = MaxPayloadOfDatarate/MaxPayloadOfDatarateRepeater + LORA_MAC_FRMPAYLOAD_OVERHEAD

Typedef Documentation

◆ DeviceClass_t

LoRaWAN devices classes definition

LoRaWAN Specification V1.0.2, chapter 2.1

◆ DrRange_t

typedef union uDrRange DrRange_t

LoRaMAC channels parameters definition

◆ Band_t

typedef struct sBand Band_t

LoRaMAC band parameters definition

◆ ChannelParams_t

LoRaMAC channel definition

◆ Rx2ChannelParams_t

LoRaMAC receive window 2 channel parameters

◆ LoRaMacParams_t

Global MAC layer parameters

◆ MulticastParams_t

LoRaMAC multicast channel parameter

◆ LoRaMacFrameType_t

LoRaMAC frame types

LoRaWAN Specification V1.0.2, chapter 4.2.1, table 1

◆ LoRaMacMoteCmd_t

LoRaMAC mote MAC commands

LoRaWAN Specification V1.0.2, chapter 5, table 4

◆ LoRaMacSrvCmd_t

LoRaMAC server MAC commands

LoRaWAN Specification V1.0.2 chapter 5, table 4

◆ LoRaMacBatteryLevel_t

LoRaMAC Battery level indicator

◆ LoRaMacHeader_t

LoRaMAC header field definition (MHDR field)

LoRaWAN Specification V1.0.2, chapter 4.2

◆ LoRaMacFrameCtrl_t

LoRaMAC frame control field definition (FCtrl)

LoRaWAN Specification V1.0.2, chapter 4.3.1

◆ LoRaMacEventInfoStatus_t

Enumeration containing the status of the operation of a MAC service

◆ LoRaMacFlags_t

LoRaMac tx/rx operation state

◆ Mcps_t

typedef enum eMcps Mcps_t

LoRaMAC data services.

The following table list the primitives which are supported by the specific MAC data service:

Name Request Indication Response Confirm
MCPS_UNCONFIRMED YES YES NO YES
MCPS_CONFIRMED YES YES NO YES
MCPS_MULTICAST NO YES NO NO
MCPS_PROPRIETARY YES YES NO YES

The following table provides links to the function implementations of the related MCPS primitives:

Primitive Function
MCPS-Request LoRaMacMlmeRequest
MCPS-Confirm MacMcpsConfirm in LoRaMacPrimitives_t
MCPS-Indication MacMcpsIndication in LoRaMacPrimitives_t

◆ McpsReqUnconfirmed_t

LoRaMAC MCPS-Request for an unconfirmed frame

◆ McpsReqConfirmed_t

LoRaMAC MCPS-Request for a confirmed frame

◆ McpsReqProprietary_t

LoRaMAC MCPS-Request for a proprietary frame

◆ McpsReq_t

typedef struct sMcpsReq McpsReq_t

LoRaMAC MCPS-Request structure

◆ McpsConfirm_t

typedef struct sMcpsConfirm McpsConfirm_t

LoRaMAC MCPS-Confirm

◆ McpsIndication_t

LoRaMAC MCPS-Indication primitive

◆ Mlme_t

typedef enum eMlme Mlme_t

LoRaMAC management services.

The following table list the primitives which are supported by the specific MAC management service:

Name Request Indication Response Confirm
MLME_JOIN YES NO NO YES
MLME_LINK_CHECK YES NO NO YES
MLME_TXCW YES NO NO YES

The following table provides links to the function implementations of the related MLME primitives.

Primitive Function
MLME-Request LoRaMacMlmeRequest
MLME-Confirm MacMlmeConfirm in LoRaMacPrimitives_t

◆ MlmeReqJoin_t

typedef struct sMlmeReqJoin MlmeReqJoin_t

LoRaMAC MLME-Request for the join service

◆ MlmeReqTxCw_t

typedef struct sMlmeReqTxCw MlmeReqTxCw_t

LoRaMAC MLME-Request for Tx continuous wave mode

◆ MlmeReq_t

typedef struct sMlmeReq MlmeReq_t

LoRaMAC MLME-Request structure

◆ MlmeConfirm_t

typedef struct sMlmeConfirm MlmeConfirm_t

LoRaMAC MLME-Confirm primitive

◆ Mib_t

typedef enum eMib Mib_t

LoRa Mac Information Base (MIB)

The following table lists the MIB parameters and the related attributes:

Attribute Get Set
MIB_DEVICE_CLASS YES YES
MIB_NETWORK_JOINED YES YES
MIB_ADR YES YES
MIB_NET_ID YES YES
MIB_DEV_ADDR YES YES
MIB_NWK_SKEY YES YES
MIB_APP_SKEY YES YES
MIB_PUBLIC_NETWORK YES YES
MIB_REPEATER_SUPPORT YES YES
MIB_CHANNELS YES NO
MIB_RX2_CHANNEL YES YES
MIB_CHANNELS_MASK YES YES
MIB_CHANNELS_DEFAULT_MASK YES YES
MIB_CHANNELS_NB_REP YES YES
MIB_MAX_RX_WINDOW_DURATION YES YES
MIB_RECEIVE_DELAY_1 YES YES
MIB_RECEIVE_DELAY_2 YES YES
MIB_JOIN_ACCEPT_DELAY_1 YES YES
MIB_JOIN_ACCEPT_DELAY_2 YES YES
MIB_CHANNELS_DATARATE YES YES
MIB_CHANNELS_DEFAULT_DATARATE YES YES
MIB_CHANNELS_TX_POWER YES YES
MIB_CHANNELS_DEFAULT_TX_POWER YES YES
MIB_UPLINK_COUNTER YES YES
MIB_DOWNLINK_COUNTER YES YES
MIB_MULTICAST_CHANNEL YES NO
MIB_SYSTEM_MAX_RX_ERROR YES YES
MIB_MIN_RX_SYMBOLS YES YES
MIB_ANTENNA_GAIN YES YES

The following table provides links to the function implementations of the related MIB primitives:

Primitive Function
MIB-Set LoRaMacMibSetRequestConfirm
MIB-Get LoRaMacMibGetRequestConfirm

◆ eJoinStatus_t

typedef enum eJoinStatus eJoinStatus_t

Network Joined status

◆ MibParam_t

typedef union uMibParam MibParam_t

LoRaMAC MIB parameters

◆ MibRequestConfirm_t

LoRaMAC MIB-RequestConfirm structure

◆ LoRaMacTxInfo_t

LoRaMAC tx information

◆ LoRaMacStatus_t

LoRaMAC Status

◆ LoRaMacRegion_t

LoRaMAC region enumeration

◆ LoRaMacPrimitives_t

LoRaMAC events structure Used to notify upper layers of MAC events

◆ LoRaMacCallback_t

LoRaMAC callback structure

Enumeration Type Documentation

◆ eDeviceClass

LoRaWAN devices classes definition

LoRaWAN Specification V1.0.2, chapter 2.1

Enumerator
CLASS_A 

LoRaWAN device class A

LoRaWAN Specification V1.0.2, chapter 3

CLASS_B 

LoRaWAN device class B

LoRaWAN Specification V1.0.2, chapter 8

CLASS_C 

LoRaWAN device class C

LoRaWAN Specification V1.0.2, chapter 17

◆ eLoRaMacFrameType

LoRaMAC frame types

LoRaWAN Specification V1.0.2, chapter 4.2.1, table 1

Enumerator
FRAME_TYPE_JOIN_REQ 

LoRaMAC join request frame

FRAME_TYPE_JOIN_ACCEPT 

LoRaMAC join accept frame

FRAME_TYPE_DATA_UNCONFIRMED_UP 

LoRaMAC unconfirmed up-link frame

FRAME_TYPE_DATA_UNCONFIRMED_DOWN 

LoRaMAC unconfirmed down-link frame

FRAME_TYPE_DATA_CONFIRMED_UP 

LoRaMAC confirmed up-link frame

FRAME_TYPE_DATA_CONFIRMED_DOWN 

LoRaMAC confirmed down-link frame

FRAME_TYPE_RFU 

LoRaMAC RFU frame

FRAME_TYPE_PROPRIETARY 

LoRaMAC proprietary frame

◆ eLoRaMacMoteCmd

LoRaMAC mote MAC commands

LoRaWAN Specification V1.0.2, chapter 5, table 4

Enumerator
MOTE_MAC_LINK_CHECK_REQ 

LinkCheckReq

MOTE_MAC_LINK_ADR_ANS 

LinkADRAns

MOTE_MAC_DUTY_CYCLE_ANS 

DutyCycleAns

MOTE_MAC_RX_PARAM_SETUP_ANS 

RXParamSetupAns

MOTE_MAC_DEV_STATUS_ANS 

DevStatusAns

MOTE_MAC_NEW_CHANNEL_ANS 

NewChannelAns

MOTE_MAC_RX_TIMING_SETUP_ANS 

RXTimingSetupAns

MOTE_MAC_TX_PARAM_SETUP_ANS 

TXParamSetupAns

MOTE_MAC_DL_CHANNEL_ANS 

DlChannelAns

◆ eLoRaMacSrvCmd

LoRaMAC server MAC commands

LoRaWAN Specification V1.0.2 chapter 5, table 4

Enumerator
SRV_MAC_LINK_CHECK_ANS 

LinkCheckAns

SRV_MAC_LINK_ADR_REQ 

LinkADRReq

SRV_MAC_DUTY_CYCLE_REQ 

DutyCycleReq

SRV_MAC_RX_PARAM_SETUP_REQ 

RXParamSetupReq

SRV_MAC_DEV_STATUS_REQ 

DevStatusReq

SRV_MAC_NEW_CHANNEL_REQ 

NewChannelReq

SRV_MAC_RX_TIMING_SETUP_REQ 

RXTimingSetupReq

SRV_MAC_TX_PARAM_SETUP_REQ 

NewChannelReq

SRV_MAC_DL_CHANNEL_REQ 

DlChannelReq

◆ eLoRaMacBatteryLevel

LoRaMAC Battery level indicator

Enumerator
BAT_LEVEL_EXT_SRC 

External power source

BAT_LEVEL_EMPTY 

Battery level empty

BAT_LEVEL_FULL 

Battery level full

BAT_LEVEL_NO_MEASURE 

Battery level - no measurement available

◆ eLoRaMacEventInfoStatus

Enumeration containing the status of the operation of a MAC service

Enumerator
LORAMAC_EVENT_INFO_STATUS_OK 

Service performed successfully

LORAMAC_EVENT_INFO_STATUS_ERROR 

An error occurred during the execution of the service

LORAMAC_EVENT_INFO_STATUS_TX_TIMEOUT 

A Tx timeout occurred

LORAMAC_EVENT_INFO_STATUS_RX1_TIMEOUT 

An Rx timeout occurred on receive window 1

LORAMAC_EVENT_INFO_STATUS_RX2_TIMEOUT 

An Rx timeout occurred on receive window 2

LORAMAC_EVENT_INFO_STATUS_RX1_ERROR 

An Rx error occurred on receive window 1

LORAMAC_EVENT_INFO_STATUS_RX2_ERROR 

An Rx error occurred on receive window 2

LORAMAC_EVENT_INFO_STATUS_JOIN_FAIL 

An error occurred in the join procedure

LORAMAC_EVENT_INFO_STATUS_DOWNLINK_REPEATED 

A frame with an invalid downlink counter was received. The downlink counter of the frame was equal to the local copy of the downlink counter of the node.

LORAMAC_EVENT_INFO_STATUS_TX_DR_PAYLOAD_SIZE_ERROR 

The MAC could not retransmit a frame since the MAC decreased the datarate. The payload size is not applicable for the datarate.

LORAMAC_EVENT_INFO_STATUS_DOWNLINK_TOO_MANY_FRAMES_LOSS 

The node has lost MAX_FCNT_GAP or more frames.

LORAMAC_EVENT_INFO_STATUS_ADDRESS_FAIL 

An address error occurred

LORAMAC_EVENT_INFO_STATUS_MIC_FAIL 

message integrity check failure

◆ eMcps

enum eMcps

LoRaMAC data services.

The following table list the primitives which are supported by the specific MAC data service:

Name Request Indication Response Confirm
MCPS_UNCONFIRMED YES YES NO YES
MCPS_CONFIRMED YES YES NO YES
MCPS_MULTICAST NO YES NO NO
MCPS_PROPRIETARY YES YES NO YES

The following table provides links to the function implementations of the related MCPS primitives:

Primitive Function
MCPS-Request LoRaMacMlmeRequest
MCPS-Confirm MacMcpsConfirm in LoRaMacPrimitives_t
MCPS-Indication MacMcpsIndication in LoRaMacPrimitives_t
Enumerator
MCPS_UNCONFIRMED 

Unconfirmed LoRaMAC frame

MCPS_CONFIRMED 

Confirmed LoRaMAC frame

MCPS_MULTICAST 

Multicast LoRaMAC frame

MCPS_PROPRIETARY 

Proprietary frame

◆ eMlme

enum eMlme

LoRaMAC management services.

The following table list the primitives which are supported by the specific MAC management service:

Name Request Indication Response Confirm
MLME_JOIN YES NO NO YES
MLME_LINK_CHECK YES NO NO YES
MLME_TXCW YES NO NO YES

The following table provides links to the function implementations of the related MLME primitives.

Primitive Function
MLME-Request LoRaMacMlmeRequest
MLME-Confirm MacMlmeConfirm in LoRaMacPrimitives_t
Enumerator
MLME_JOIN 

Initiates the Over-the-Air activation

LoRaWAN Specification V1.0.2, chapter 6.2

MLME_LINK_CHECK 

LinkCheckReq - Connectivity validation

LoRaWAN Specification V1.0.2, chapter 5, table 4

MLME_TXCW 

Sets Tx continuous wave mode

LoRaWAN end-device certification

MLME_TXCW_1 

Sets Tx continuous wave mode (new LoRa-Alliance CC definition)

LoRaWAN end-device certification

◆ eMib

enum eMib

LoRa Mac Information Base (MIB)

The following table lists the MIB parameters and the related attributes:

Attribute Get Set
MIB_DEVICE_CLASS YES YES
MIB_NETWORK_JOINED YES YES
MIB_ADR YES YES
MIB_NET_ID YES YES
MIB_DEV_ADDR YES YES
MIB_NWK_SKEY YES YES
MIB_APP_SKEY YES YES
MIB_PUBLIC_NETWORK YES YES
MIB_REPEATER_SUPPORT YES YES
MIB_CHANNELS YES NO
MIB_RX2_CHANNEL YES YES
MIB_CHANNELS_MASK YES YES
MIB_CHANNELS_DEFAULT_MASK YES YES
MIB_CHANNELS_NB_REP YES YES
MIB_MAX_RX_WINDOW_DURATION YES YES
MIB_RECEIVE_DELAY_1 YES YES
MIB_RECEIVE_DELAY_2 YES YES
MIB_JOIN_ACCEPT_DELAY_1 YES YES
MIB_JOIN_ACCEPT_DELAY_2 YES YES
MIB_CHANNELS_DATARATE YES YES
MIB_CHANNELS_DEFAULT_DATARATE YES YES
MIB_CHANNELS_TX_POWER YES YES
MIB_CHANNELS_DEFAULT_TX_POWER YES YES
MIB_UPLINK_COUNTER YES YES
MIB_DOWNLINK_COUNTER YES YES
MIB_MULTICAST_CHANNEL YES NO
MIB_SYSTEM_MAX_RX_ERROR YES YES
MIB_MIN_RX_SYMBOLS YES YES
MIB_ANTENNA_GAIN YES YES

The following table provides links to the function implementations of the related MIB primitives:

Primitive Function
MIB-Set LoRaMacMibSetRequestConfirm
MIB-Get LoRaMacMibGetRequestConfirm
Enumerator
MIB_DEVICE_CLASS 

LoRaWAN device class

LoRaWAN Specification V1.0.2

MIB_NETWORK_JOINED 

LoRaWAN Network joined attribute

LoRaWAN Specification V1.0.2

MIB_ADR 

Adaptive data rate

LoRaWAN Specification V1.0.2, chapter 4.3.1.1

[true: ADR enabled, false: ADR disabled]

MIB_NET_ID 

Network identifier

LoRaWAN Specification V1.0.2, chapter 6.1.1

MIB_DEV_ADDR 

End-device address

LoRaWAN Specification V1.0.2, chapter 6.1.1

MIB_NWK_SKEY 

Network session key

LoRaWAN Specification V1.0.2, chapter 6.1.3

MIB_APP_SKEY 

Application session key

LoRaWAN Specification V1.0.2, chapter 6.1.4

MIB_PUBLIC_NETWORK 

Set the network type to public or private

LoRaWAN Regional Parameters V1.0.2rB

[true: public network, false: private network]

MIB_REPEATER_SUPPORT 

Support the operation with repeaters

LoRaWAN Regional Parameters V1.0.2rB

[true: repeater support enabled, false: repeater support disabled]

MIB_CHANNELS 

Communication channels. A get request will return a pointer which references the first entry of the channel list. The list is of size LORA_MAX_NB_CHANNELS

LoRaWAN Regional Parameters V1.0.2rB

MIB_RX2_CHANNEL 

Set receive window 2 channel

LoRaWAN Specification V1.0.2, chapter 3.3.1

MIB_RX2_DEFAULT_CHANNEL 

Set receive window 2 channel

LoRaWAN Specification V1.0.2, chapter 3.3.2

MIB_CHANNELS_MASK 

LoRaWAN channels mask

LoRaWAN Regional Parameters V1.0.2rB

MIB_CHANNELS_DEFAULT_MASK 

LoRaWAN default channels mask

LoRaWAN Regional Parameters V1.0.2rB

MIB_CHANNELS_NB_REP 

Set the number of repetitions on a channel

LoRaWAN Specification V1.0.2, chapter 5.2

MIB_MAX_RX_WINDOW_DURATION 

Maximum receive window duration in [ms]

LoRaWAN Specification V1.0.2, chapter 3.3.3

MIB_RECEIVE_DELAY_1 

Receive delay 1 in [ms]

LoRaWAN Regional Parameters V1.0.2rB

MIB_RECEIVE_DELAY_2 

Receive delay 2 in [ms]

LoRaWAN Regional Parameters V1.0.2rB

MIB_JOIN_ACCEPT_DELAY_1 

Join accept delay 1 in [ms]

LoRaWAN Regional Parameters V1.0.2rB

MIB_JOIN_ACCEPT_DELAY_2 

Join accept delay 2 in [ms]

LoRaWAN Regional Parameters V1.0.2rB

MIB_CHANNELS_DEFAULT_DATARATE 

Default Data rate of a channel

LoRaWAN Regional Parameters V1.0.2rB

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

MIB_CHANNELS_DATARATE 

Data rate of a channel

LoRaWAN Regional Parameters V1.0.2rB

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

MIB_CHANNELS_TX_POWER 

Transmission power of a channel

LoRaWAN Regional Parameters V1.0.2rB

The allowed ranges are region specific. Please refer to TX_POWER_0 to TX_POWER_15 for details.

MIB_CHANNELS_DEFAULT_TX_POWER 

Transmission power of a channel

LoRaWAN Regional Parameters V1.0.2rB

The allowed ranges are region specific. Please refer to TX_POWER_0 to TX_POWER_15 for details.

MIB_UPLINK_COUNTER 

LoRaWAN Up-link counter

LoRaWAN Specification V1.0.2, chapter 4.3.1.5

MIB_DOWNLINK_COUNTER 

LoRaWAN Down-link counter

LoRaWAN Specification V1.0.2, chapter 4.3.1.5

MIB_MULTICAST_CHANNEL 

Multicast channels. A get request will return a pointer to the first entry of the multicast channel linked list. If the pointer is equal to NULL, the list is empty.

MIB_SYSTEM_MAX_RX_ERROR 

System overall timing error in milliseconds. [-SystemMaxRxError : +SystemMaxRxError] Default: +/-10 ms

MIB_MIN_RX_SYMBOLS 

Minimum required number of symbols to detect an Rx frame Default: 6 symbols

MIB_ANTENNA_GAIN 

Antenna gain of the node. Default value is region specific. The antenna gain is used to calculate the TX power of the node. The formula is: radioTxPower = ( int8_t )floor( maxEirp - antennaGain )

◆ eJoinStatus

Network Joined status

Enumerator
JOIN_NOT_START 
JOIN_OK 
JOIN_ONGOING 
JOIN_FAILED 

◆ eLoRaMacStatus

LoRaMAC Status

Enumerator
LORAMAC_STATUS_OK 

Service started successfully

LORAMAC_STATUS_BUSY 

Service not started - LoRaMAC is busy

LORAMAC_STATUS_SERVICE_UNKNOWN 

Service unknown

LORAMAC_STATUS_PARAMETER_INVALID 

Service not started - invalid parameter

LORAMAC_STATUS_FREQUENCY_INVALID 

Service not started - invalid frequency

LORAMAC_STATUS_DATARATE_INVALID 

Service not started - invalid datarate

LORAMAC_STATUS_FREQ_AND_DR_INVALID 

Service not started - invalid frequency and datarate

LORAMAC_STATUS_NO_NETWORK_JOINED 

Service not started - the device is not in a LoRaWAN

LORAMAC_STATUS_LENGTH_ERROR 

Service not started - payload length error

LORAMAC_STATUS_DEVICE_OFF 

Service not started - the device is switched off

LORAMAC_STATUS_REGION_NOT_SUPPORTED 

Service not started - the specified region is not supported or not activated with preprocessor definitions.

◆ eLoRaMacRegion_t

LoRaMAC region enumeration

Enumerator
LORAMAC_REGION_AS923 

AS band on 923MHz

LORAMAC_REGION_AU915 

Australian band on 915MHz

LORAMAC_REGION_CN470 

Chinese band on 470MHz

LORAMAC_REGION_CN779 

Chinese band on 779MHz

LORAMAC_REGION_EU433 

European band on 433MHz

LORAMAC_REGION_EU868 

European band on 868MHz

LORAMAC_REGION_KR920 

South korean band on 920MHz

LORAMAC_REGION_IN865 

India band on 865MHz

LORAMAC_REGION_US915 

North american band on 915MHz

LORAMAC_REGION_AS923_2 

AS band on 923MHz -1.8MHz

LORAMAC_REGION_AS923_3 

AS band on 923MHz -6.6MHz

LORAMAC_REGION_AS923_4 

AS band on 923MHz -5.9MHz

LORAMAC_REGION_RU864 

Russia band on 864MHz

Function Documentation

◆ LoRaMacInitialization()

LoRaMacStatus_t LoRaMacInitialization ( LoRaMacPrimitives_t primitives,
LoRaMacCallback_t callbacks,
LoRaMacRegion_t  region,
eDeviceClass  nodeClass = CLASS_A 
)

LoRaMAC layer initialization.

In addition to the initialization of the LoRaMAC layer, this function initializes the callback primitives of the MCPS and MLME services. Every data field of LoRaMacPrimitives_t must be set to a valid callback function.

Parameters
primitives- Pointer to a structure defining the LoRaMAC event functions. Refer to LoRaMacPrimitives_t.
callbacks- Pointer to a structure defining the LoRaMAC callback functions. Refer to LoRaMacCallback_t.
region- The region to start.
nodeClass- Choose node class CLASS_A, CLASS_B or CLASS_C, default to CLASS_A
Return values
LoRaMacStatus_tStatus of the operation. Possible returns are: returns are: LORAMAC_STATUS_OK, LORAMAC_STATUS_PARAMETER_INVALID, LORAMAC_STATUS_REGION_NOT_SUPPORTED.
Todo:
Putting the RegionTxConfig here makes the OTAA join more stable

◆ LoRaMacGetOTAADevId()

uint32_t LoRaMacGetOTAADevId ( void  )

Returns the Device Address set by the LoRaWan server after OTAA join was successful.

Return values
DeviceAddress given by the LoRaWan server

◆ LoRaMacQueryTxPossible()

LoRaMacStatus_t LoRaMacQueryTxPossible ( uint8_t  size,
LoRaMacTxInfo_t txInfo 
)

Queries the LoRaMAC if it is possible to send the next frame with a given payload size. The LoRaMAC takes scheduled MAC commands into account and reports, when the frame can be send or not.

Parameters
size- Size of applicative payload to be send next
txInfo- The structure LoRaMacTxInfo_t contains information about the actual maximum payload possible ( according to the configured datarate or the next datarate according to ADR ), and the maximum frame size, taking the scheduled MAC commands into account.
Return values
LoRaMacStatus_tStatus of the operation. When the parameters are not valid, the function returns LORAMAC_STATUS_PARAMETER_INVALID. In case of a length error caused by the applicative payload in combination with the MAC commands, the function returns LORAMAC_STATUS_LENGTH_ERROR. Please note that if the size of the MAC commands which are in the queue do not fit into the payload size on the related datarate, the LoRaMAC will omit the MAC commands. In case the query is valid, and the LoRaMAC is able to send the frame, the function returns LORAMAC_STATUS_OK.

◆ LoRaMacChannelAdd()

LoRaMacStatus_t LoRaMacChannelAdd ( uint8_t  id,
ChannelParams_t  params 
)

LoRaMAC channel add service.

Adds a new channel to the channel list and activates the id in the channel mask. Please note that this functionality is not available on all regions. Information about allowed ranges are available at the LoRaWAN Regional Parameters V1.0.2rB

Parameters
id- Id of the channel.
params- Channel parameters to set.
Return values
LoRaMacStatus_tStatus of the operation. Possible returns are: LORAMAC_STATUS_OK, LORAMAC_STATUS_BUSY, LORAMAC_STATUS_PARAMETER_INVALID.

◆ LoRaMacChannelRemove()

LoRaMacStatus_t LoRaMacChannelRemove ( uint8_t  id)

LoRaMAC channel remove service.

Deactivates the id in the channel mask.

Parameters
id- Id of the channel.
Return values
LoRaMacStatus_tStatus of the operation. Possible returns are: LORAMAC_STATUS_OK, LORAMAC_STATUS_BUSY, LORAMAC_STATUS_PARAMETER_INVALID.

◆ LoRaMacMulticastChannelLink()

LoRaMacStatus_t LoRaMacMulticastChannelLink ( MulticastParams_t channelParam)

LoRaMAC multicast channel link service.

Links a multicast channel into the linked list.

Parameters
channelParam- Multicast channel parameters to link.
Return values
LoRaMacStatus_tStatus of the operation. Possible returns are: LORAMAC_STATUS_OK, LORAMAC_STATUS_BUSY, LORAMAC_STATUS_PARAMETER_INVALID.

◆ LoRaMacMulticastChannelUnlink()

LoRaMacStatus_t LoRaMacMulticastChannelUnlink ( MulticastParams_t channelParam)

LoRaMAC multicast channel unlink service.

Unlinks a multicast channel from the linked list.

Parameters
channelParam- Multicast channel parameters to unlink.
Return values
LoRaMacStatus_tStatus of the operation. Possible returns are: LORAMAC_STATUS_OK, LORAMAC_STATUS_BUSY, LORAMAC_STATUS_PARAMETER_INVALID.

◆ LoRaMacMibGetRequestConfirm()

LoRaMacStatus_t LoRaMacMibGetRequestConfirm ( MibRequestConfirm_t mibGet)

LoRaMAC MIB-Get.

The mac information base service to get attributes of the LoRaMac layer.

The following code-snippet shows how to use the API to get the parameter AdrEnable, defined by the enumeration type MIB_ADR.

{
// LoRaMAC updated the parameter mibParam.AdrEnable
}
Parameters
mibGet- MIB-GET-Request to perform. Refer to MibRequestConfirm_t.
Return values
LoRaMacStatus_tStatus of the operation. Possible returns are: LORAMAC_STATUS_OK, LORAMAC_STATUS_SERVICE_UNKNOWN, LORAMAC_STATUS_PARAMETER_INVALID.

◆ LoRaMacMibSetRequestConfirm()

LoRaMacStatus_t LoRaMacMibSetRequestConfirm ( MibRequestConfirm_t mibSet)

LoRaMAC MIB-Set.

The mac information base service to set attributes of the LoRaMac layer.

The following code-snippet shows how to use the API to set the parameter AdrEnable, defined by the enumeration type MIB_ADR.

Parameters
mibSet- MIB-SET-Request to perform. Refer to MibRequestConfirm_t.
Return values
LoRaMacStatus_tStatus of the operation. Possible returns are: LORAMAC_STATUS_OK, LORAMAC_STATUS_BUSY, LORAMAC_STATUS_SERVICE_UNKNOWN, LORAMAC_STATUS_PARAMETER_INVALID.

◆ LoRaMacMlmeRequest()

LoRaMacStatus_t LoRaMacMlmeRequest ( MlmeReq_t mlmeRequest)

LoRaMAC MLME-Request.

The Mac layer management entity handles management services. The following code-snippet shows how to use the API to perform a network join request.

static uint8_t DevEui[] =
{
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
};
static uint8_t AppEui[] =
{
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
};
static uint8_t AppKey[] =
{
0x2B, 0x7E, 0x15, 0x16, 0x28, 0xAE, 0xD2, 0xA6,
0xAB, 0xF7, 0x15, 0x88, 0x09, 0xCF, 0x4F, 0x3C
};
MlmeReq_t mlmeReq;
mlmeReq.Type = MLME_JOIN;
mlmeReq.Req.Join.DevEui = DevEui;
mlmeReq.Req.Join.AppEui = AppEui;
mlmeReq.Req.Join.AppKey = AppKey;
{
// Service started successfully. Waiting for the Mlme-Confirm event
}
Parameters
mlmeRequest- MLME-Request to perform. Refer to MlmeReq_t.
Return values
LoRaMacStatus_tStatus of the operation. Possible returns are: LORAMAC_STATUS_OK, LORAMAC_STATUS_BUSY, LORAMAC_STATUS_SERVICE_UNKNOWN, LORAMAC_STATUS_PARAMETER_INVALID, LORAMAC_STATUS_NO_NETWORK_JOINED, LORAMAC_STATUS_LENGTH_ERROR, LORAMAC_STATUS_DEVICE_OFF.

◆ LoRaMacMcpsRequest()

LoRaMacStatus_t LoRaMacMcpsRequest ( McpsReq_t mcpsRequest)

LoRaMAC MCPS-Request.

The Mac Common Part Sublayer handles data services. The following code-snippet shows how to use the API to send an unconfirmed LoRaMAC frame.

uint8_t myBuffer[] = { 1, 2, 3 };
McpsReq_t mcpsReq;
mcpsReq.Req.Unconfirmed.fPort = 1;
mcpsReq.Req.Unconfirmed.fBuffer = myBuffer;
mcpsReq.Req.Unconfirmed.fBufferSize = sizeof( myBuffer );
{
// Service started successfully. Waiting for the MCPS-Confirm event
}
Parameters
mcpsRequest- MCPS-Request to perform. Refer to McpsReq_t.
Return values
LoRaMacStatus_tStatus of the operation. Possible returns are: LORAMAC_STATUS_OK, LORAMAC_STATUS_BUSY, LORAMAC_STATUS_SERVICE_UNKNOWN, LORAMAC_STATUS_PARAMETER_INVALID, LORAMAC_STATUS_NO_NETWORK_JOINED, LORAMAC_STATUS_LENGTH_ERROR, LORAMAC_STATUS_DEVICE_OFF.

Variable Documentation

◆ LoRaMacRegion

LoRaMacRegion_t LoRaMacRegion

LoRaMac region.

◆ LoRaMacMaxEirpTable

const uint8_t LoRaMacMaxEirpTable[] = {8, 10, 12, 13, 14, 16, 18, 20, 21, 24, 26, 27, 29, 30, 33, 36}
static

LoRaMAC Max EIRP (dBm) table

eMibRequestConfirm::Param
MibParam_t Param
Definition: LoRaMac.h:1516
sMlmeReq::Req
union sMlmeReq::uMlmeParam Req
sMlmeReq::uMlmeParam::Join
MlmeReqJoin_t Join
Definition: LoRaMac.h:1020
uMibParam::AdrEnable
bool AdrEnable
Definition: LoRaMac.h:1338
MLME_JOIN
@ MLME_JOIN
Definition: LoRaMac.h:933
LoRaMacMcpsRequest
LoRaMacStatus_t LoRaMacMcpsRequest(McpsReq_t *mcpsRequest)
LoRaMAC MCPS-Request.
Definition: LoRaMac.cpp:3284
AppKey
static uint8_t AppKey[]
Definition: LoRaMacHelper.cpp:84
sMcpsReq::uMcpsParam::Unconfirmed
McpsReqUnconfirmed_t Unconfirmed
Definition: LoRaMac.h:786
sMcpsReq::Req
union sMcpsReq::uMcpsParam Req
eMibRequestConfirm::Type
Mib_t Type
Definition: LoRaMac.h:1511
sMlmeReqJoin::AppEui
uint8_t * AppEui
Definition: LoRaMac.h:970
mibReq
static MibRequestConfirm_t mibReq
Definition: LoRaMacHelper.cpp:98
sMlmeReq::Type
Mlme_t Type
Definition: LoRaMac.h:1010
MCPS_UNCONFIRMED
@ MCPS_UNCONFIRMED
Definition: LoRaMac.h:661
eMibRequestConfirm
Definition: LoRaMac.h:1507
DevEui
static uint8_t DevEui[]
Definition: LoRaMacHelper.cpp:82
sMlmeReqJoin::AppKey
uint8_t * AppKey
Definition: LoRaMac.h:976
LORAMAC_STATUS_OK
@ LORAMAC_STATUS_OK
Definition: LoRaMac.h:1542
sMlmeReqJoin::DevEui
uint8_t * DevEui
Definition: LoRaMac.h:964
sMcpsReqUnconfirmed::fBuffer
void * fBuffer
Definition: LoRaMac.h:691
sMcpsReqUnconfirmed::fPort
uint8_t fPort
Definition: LoRaMac.h:687
LoRaMacMlmeRequest
LoRaMacStatus_t LoRaMacMlmeRequest(MlmeReq_t *mlmeRequest)
LoRaMAC MLME-Request.
Definition: LoRaMac.cpp:3175
AppEui
static uint8_t AppEui[]
Definition: LoRaMacHelper.cpp:83
LoRaMacMibGetRequestConfirm
LoRaMacStatus_t LoRaMacMibGetRequestConfirm(MibRequestConfirm_t *mibGet)
LoRaMAC MIB-Get.
Definition: LoRaMac.cpp:2574
sMcpsReqUnconfirmed::fBufferSize
uint16_t fBufferSize
Definition: LoRaMac.h:695
MIB_ADR
@ MIB_ADR
Definition: LoRaMac.h:1126
sMcpsReq
Definition: LoRaMac.h:772
sMcpsReq::Type
Mcps_t Type
Definition: LoRaMac.h:776
sMlmeReq
Definition: LoRaMac.h:1006