Semtech
LoRaWAN MAC layer implementation
Dependents: LoRaWAN-demo-72_tjm LoRaWAN-demo-72_jlc LoRaWAN-demo-elmo frdm_LoRa_Connect_Woodstream_Demo_tjm ... more
LoRa MAC layer implementation
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.
Typedef Documentation
| typedef struct sChannelParams ChannelParams_t |
LoRaMAC channel definition
| typedef enum eDeviceClass DeviceClass_t |
LoRaMac internal state
LoRaWAN devices classes definition
| typedef enum eLoRaMacBatteryLevel LoRaMacBatteryLevel_t |
LoRaMAC Battery level indicator
| typedef enum eLoRaMacEventInfoStatus LoRaMacEventInfoStatus_t |
Enumeration containing the status of the operation of a MAC service
| typedef union eLoRaMacFlags_t LoRaMacFlags_t |
LoRaMac tx/rx operation state
| typedef union uLoRaMacFrameCtrl LoRaMacFrameCtrl_t |
LoRaMAC frame control field definition (FCtrl)
LoRaWAN Specification V1.0, chapter 4.3.1
| typedef enum eLoRaMacFrameType LoRaMacFrameType_t |
LoRaMAC frame types
LoRaWAN Specification V1.0, chapter 4.2.1, table 1
| typedef union uLoRaMacHeader LoRaMacHeader_t |
LoRaMAC header field definition (MHDR field)
LoRaWAN Specification V1.0, chapter 4.2
| typedef enum eLoRaMacMoteCmd LoRaMacMoteCmd_t |
LoRaMAC mote MAC commands
LoRaWAN Specification V1.0, chapter 5, table 4
| typedef struct sLoRaMacPrimitives LoRaMacPrimitives_t |
LoRaMAC events structure Used to notify upper layers of MAC events
| typedef enum eLoRaMacSrvCmd LoRaMacSrvCmd_t |
LoRaMAC server MAC commands
LoRaWAN Specification V1.0, chapter 5, table 4
| typedef enum eLoRaMacStatus LoRaMacStatus_t |
LoRaMAC Status
| typedef struct sLoRaMacTxInfo LoRaMacTxInfo_t |
LoRaMAC tx information
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
| typedef struct sMcpsConfirm McpsConfirm_t |
LoRaMAC MCPS-Confirm
| typedef struct sMcpsIndication McpsIndication_t |
LoRaMAC MCPS-Indication primitive
| typedef struct sMcpsReqConfirmed McpsReqConfirmed_t |
LoRaMAC MCPS-Request for a confirmed frame
| typedef struct sMcpsReqProprietary McpsReqProprietary_t |
LoRaMAC MCPS-Request for a proprietary frame
| typedef struct sMcpsReqUnconfirmed McpsReqUnconfirmed_t |
LoRaMAC MCPS-Request for an unconfirmed frame
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_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_UPLINK_COUNTER | YES | YES MIB_DOWNLINK_COUNTER | YES | YES MIB_MULTICAST_CHANNEL | YES | NO
The following table provides links to the function implementations of the related MIB primitives:
Primitive | Function ---------------- | :---------------------: MIB-Set | LoRaMacMibSetRequestConfirm MIB-Get | LoRaMacMibGetRequestConfirm
| typedef union uMibParam MibParam_t |
LoRaMAC MIB parameters
| typedef struct eMibRequestConfirm MibRequestConfirm_t |
LoRaMAC MIB-RequestConfirm structure
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
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
| typedef struct sMlmeConfirm MlmeConfirm_t |
LoRaMAC MLME-Confirm primitive
| typedef struct sMlmeReqJoin MlmeReqJoin_t |
LoRaMAC MLME-Request for the join service
| typedef struct sMulticastParams MulticastParams_t |
LoRaMAC multicast channel parameter
| typedef struct sRx2ChannelParams Rx2ChannelParams_t |
LoRaMAC receive window 2 channel parameters
Enumeration Type Documentation
| enum eDeviceClass |
| enum eLoRaMacBatteryLevel |
Enumeration containing the status of the operation of a MAC service
- Enumerator:
| enum eLoRaMacFrameType |
LoRaMAC frame types
LoRaWAN Specification V1.0, chapter 4.2.1, table 1
- Enumerator:
| enum eLoRaMacMoteCmd |
LoRaMAC mote MAC commands
LoRaWAN Specification V1.0, chapter 5, table 4
| enum eLoRaMacSrvCmd |
LoRaMAC server MAC commands
LoRaWAN Specification V1.0, chapter 5, table 4
| enum eLoRaMacStatus |
LoRaMAC Status
- Enumerator:
| 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
| 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_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_UPLINK_COUNTER | YES | YES MIB_DOWNLINK_COUNTER | YES | YES MIB_MULTICAST_CHANNEL | YES | NO
The following table provides links to the function implementations of the related MIB primitives:
Primitive | Function ---------------- | :---------------------: MIB-Set | LoRaMacMibSetRequestConfirm MIB-Get | LoRaMacMibGetRequestConfirm
- Enumerator:
| 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
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
Function Documentation
| 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. For the US915 band, all channels are enabled by default. It is not possible to activate less than 6 125 kHz channels.
- Parameters:
-
[IN] id - Id of the channel. Possible values are:
0-15 for EU868 0-72 for US915
- Parameters:
-
[IN] params - Channel parameters to set.
- Return values:
-
LoRaMacStatus_t Status of the operation. Possible returns are: LORAMAC_STATUS_OK, LORAMAC_STATUS_BUSY, LORAMAC_STATUS_PARAMETER_INVALID.
Definition at line 3381 of file LoRaMac.cpp.
| LoRaMacStatus_t LoRaMacChannelRemove | ( | uint8_t | id ) |
LoRaMAC channel remove service.
Deactivates the id in the channel mask.
- Parameters:
-
[IN] id - Id of the channel.
- Return values:
-
LoRaMacStatus_t Status of the operation. Possible returns are: LORAMAC_STATUS_OK, LORAMAC_STATUS_BUSY, LORAMAC_STATUS_PARAMETER_INVALID.
Definition at line 3489 of file LoRaMac.cpp.
| LoRaMacStatus_t LoRaMacInitialization | ( | LoRaMacPrimitives_t * | primitives, |
| LoRaMacCallback_t * | callbacks | ||
| ) |
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:
-
[IN] events - Pointer to a structure defining the LoRaMAC event functions. Refer to LoRaMacPrimitives_t. [IN] events - Pointer to a structure defining the LoRaMAC callback functions. Refer to LoRaMacCallback_t.
- Return values:
-
LoRaMacStatus_t Status of the operation. Possible returns are: returns are: LORAMAC_STATUS_OK, LORAMAC_STATUS_PARAMETER_INVALID.
Definition at line 2829 of file LoRaMac.cpp.
| 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.Type = MCPS_UNCONFIRMED ;
mcpsReq.Req.Unconfirmed .fPort = 1;
mcpsReq.Req.Unconfirmed .fBuffer = myBuffer;
mcpsReq.Req.Unconfirmed .fBufferSize = sizeof( myBuffer );
if( LoRaMacMcpsRequest( &mcpsReq ) == LORAMAC_STATUS_OK )
{
// Service started successfully. Waiting for the MCPS-Confirm event
}
- Parameters:
-
[IN] mcpsRequest - MCPS-Request to perform. Refer to McpsReq_t.
- Return values:
-
LoRaMacStatus_t Status 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.
Definition at line 3688 of file LoRaMac.cpp.
| 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.
MibRequestConfirm_t mibReq; mibReq.Type = MIB_ADR ; if( LoRaMacMibGetRequestConfirm( &mibReq ) == LORAMAC_STATUS_OK ) { // LoRaMAC updated the parameter mibParam.AdrEnable }
- Parameters:
-
[IN] mibRequest - MIB-GET-Request to perform. Refer to MibRequestConfirm_t.
- Return values:
-
LoRaMacStatus_t Status of the operation. Possible returns are: LORAMAC_STATUS_OK, LORAMAC_STATUS_SERVICE_UNKNOWN, LORAMAC_STATUS_PARAMETER_INVALID.
Definition at line 3003 of file LoRaMac.cpp.
| 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.
MibRequestConfirm_t mibReq; mibReq.Type = MIB_ADR ; mibReq.Param .AdrEnable = true; if( LoRaMacMibGetRequestConfirm( &mibReq ) == LORAMAC_STATUS_OK ) { // LoRaMAC updated the parameter }
- Parameters:
-
[IN] mibRequest - MIB-SET-Request to perform. Refer to MibRequestConfirm_t.
- Return values:
-
LoRaMacStatus_t Status of the operation. Possible returns are: LORAMAC_STATUS_OK, LORAMAC_STATUS_BUSY, LORAMAC_STATUS_SERVICE_UNKNOWN, LORAMAC_STATUS_PARAMETER_INVALID.
Definition at line 3142 of file LoRaMac.cpp.
| 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; if( LoRaMacMlmeRequest( &mlmeReq ) == LORAMAC_STATUS_OK ) { // Service started successfully. Waiting for the Mlme-Confirm event }
- Parameters:
-
[IN] mlmeRequest - MLME-Request to perform. Refer to MlmeReq_t.
- Return values:
-
LoRaMacStatus_t Status 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.
Definition at line 3595 of file LoRaMac.cpp.
| LoRaMacStatus_t LoRaMacMulticastChannelLink | ( | MulticastParams_t * | channelParam ) |
LoRaMAC multicast channel link service.
Links a multicast channel into the linked list.
- Parameters:
-
[IN] channelParam - Multicast channel parameters to link.
- Return values:
-
LoRaMacStatus_t Status of the operation. Possible returns are: LORAMAC_STATUS_OK, LORAMAC_STATUS_BUSY, LORAMAC_STATUS_PARAMETER_INVALID.
Definition at line 3521 of file LoRaMac.cpp.
| LoRaMacStatus_t LoRaMacMulticastChannelUnlink | ( | MulticastParams_t * | channelParam ) |
LoRaMAC multicast channel unlink service.
Unlinks a multicast channel from the linked list.
- Parameters:
-
[IN] channelParam - Multicast channel parameters to unlink.
- Return values:
-
LoRaMacStatus_t Status of the operation. Possible returns are: LORAMAC_STATUS_OK, LORAMAC_STATUS_BUSY, LORAMAC_STATUS_PARAMETER_INVALID.
Definition at line 3556 of file LoRaMac.cpp.
| 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:
-
[IN] size - Size of applicative payload to be send next [OUT] 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_t Status 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 size, the function returns LORAMAC_STATUS_LENGTH_ERROR. In case of a length error due to additional MAC commands in the queue, the function returns LORAMAC_STATUS_MAC_CMD_LENGTH_ERROR. In case the query is valid, and the LoRaMAC is able to send the frame, the function returns LORAMAC_STATUS_OK. *
Definition at line 2961 of file LoRaMac.cpp.
Generated on Tue Jul 12 2022 14:27:12 by
1.7.2