Akshay Mishra
to be used with the DSPLoRa module (minor changes wrt transmit power)
Fork of
LoRaWAN-lib
by 
S P
Diff: LoRaMac.h
- Revision:
- 2:14a5d6ad92d5
- Parent:
- 1:91e4e6c60d1e
- Child:
- 3:b9d87593a8ae
--- a/LoRaMac.h Mon Nov 23 10:09:43 2015 +0000
+++ b/LoRaMac.h Tue Jan 05 16:41:54 2016 +0000
@@ -1,17 +1,48 @@
-/*
- / _____) _ | |
-( (____ _____ ____ _| |_ _____ ____| |__
- \____ \| ___ | (_ _) ___ |/ ___) _ \
- _____) ) ____| | | || |_| ____( (___| | | |
-(______/|_____)_|_|_| \__)_____)\____)_| |_|
- (C)2013 Semtech
-
-Description: LoRa MAC layer implementation
-
-License: Revised BSD License, see LICENSE.TXT file include in the project
-
-Maintainer: Miguel Luis and Gregory Cristian
-*/
+/*!
+ * \file LoRaMac.h
+ *
+ * \brief LoRa MAC layer implementation
+ *
+ * \copyright Revised BSD License, see section \ref LICENSE.
+ *
+ * \code
+ * ______ _
+ * / _____) _ | |
+ * ( (____ _____ ____ _| |_ _____ ____| |__
+ * \____ \| ___ | (_ _) ___ |/ ___) _ \
+ * _____) ) ____| | | || |_| ____( (___| | | |
+ * (______/|_____)_|_|_| \__)_____)\____)_| |_|
+ * (C)2013 Semtech
+ *
+ * ___ _____ _ ___ _ _____ ___ ___ ___ ___
+ * / __|_ _/_\ / __| |/ / __/ _ \| _ \/ __| __|
+ * \__ \ | |/ _ \ (__| ' <| _| (_) | / (__| _|
+ * |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___|
+ * embedded.connectivity.solutions===============
+ *
+ * \endcode
+ *
+ * \author Miguel Luis ( Semtech )
+ *
+ * \author Gregory Cristian ( Semtech )
+ *
+ * \author Daniel Jäckle ( STACKFORCE )
+ *
+ * \defgroup LORAMAC 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.
+ * \{
+ *
+ * \example classA/LoRaMote/main.c
+ * LoRaWAN class A application example for the LoRaMote.
+ *
+ * \example classB/LoRaMote/main.c
+ * LoRaWAN class B application example for the LoRaMote.
+ *
+ * \example classC/LoRaMote/main.c
+ * LoRaWAN class C application example for the LoRaMote.
+ */
#ifndef __LORAMAC_H__
#define __LORAMAC_H__
@@ -24,15 +55,23 @@
#define BEACON_INTERVAL 128000000
/*!
- * Class A&B receive delay in us
+ * Class A&B receive delay 1 in us
*/
#define RECEIVE_DELAY1 1000000
+
+/*!
+ * Class A&B receive delay 2 in us
+ */
#define RECEIVE_DELAY2 2000000
/*!
- * Join accept receive delay in us
+ * Join accept receive delay 1 in us
*/
#define JOIN_ACCEPT_DELAY1 5000000
+
+/*!
+ * Join accept receive delay 2 in us
+ */
#define JOIN_ACCEPT_DELAY2 6000000
/*!
@@ -58,19 +97,19 @@
/*!
* Number of seconds after the start of the second reception window without
* receiving an acknowledge.
- * AckTimeout = ACK_TIMEOUT + Random( -ACK_TIMEOUT_RND, ACK_TIMEOUT_RND )
+ * AckTimeout = \ref ACK_TIMEOUT + Random( -\ref ACK_TIMEOUT_RND, \ref ACK_TIMEOUT_RND )
*/
#define ACK_TIMEOUT 2000000
/*!
* Random number of seconds after the start of the second reception window without
* receiving an acknowledge
- * AckTimeout = ACK_TIMEOUT + Random( -ACK_TIMEOUT_RND, ACK_TIMEOUT_RND )
+ * AckTimeout = \ref ACK_TIMEOUT + Random( -\ref ACK_TIMEOUT_RND, \ref ACK_TIMEOUT_RND )
*/
#define ACK_TIMEOUT_RND 1000000
/*!
- * Check the Mac layer state every MAC_STATE_CHECK_TIMEOUT
+ * Check the Mac layer state every MAC_STATE_CHECK_TIMEOUT in us
*/
#define MAC_STATE_CHECK_TIMEOUT 1000000
@@ -80,14 +119,18 @@
#define MAX_ACK_RETRIES 8
/*!
- * RSSI free threshold
+ * RSSI free threshold [dBm]
*/
-#define RSSI_FREE_TH ( int8_t )( -90 ) // [dBm]
+#define RSSI_FREE_TH ( int8_t )( -90 )
-/*!
- * Frame direction definition
+/*!
+ * Frame direction definition for up-link communications
*/
#define UP_LINK 0
+
+/*!
+ * Frame direction definition for down-link communications
+ */
#define DOWN_LINK 1
/*!
@@ -106,480 +149,1503 @@
*/
#define LORA_MAC_PUBLIC_SYNCWORD 0x34
+ /*!
+ * LoRaMac internal state
+ */
+//uint32_t LoRaMacState;
+
/*!
* LoRaWAN devices classes definition
*/
-typedef enum
+typedef enum eDeviceClass
{
+ /*!
+ * LoRaWAN device class A
+ *
+ * LoRaWAN Specification V1.0, chapter 3ff
+ */
CLASS_A,
+ /*!
+ * LoRaWAN device class B
+ *
+ * LoRaWAN Specification V1.0, chapter 8ff
+ */
CLASS_B,
+ /*!
+ * LoRaWAN device class C
+ *
+ * LoRaWAN Specification V1.0, chapter 17ff
+ */
CLASS_C,
}DeviceClass_t;
/*!
* LoRaMAC channels parameters definition
*/
-typedef union
+typedef union uDrRange
{
+ /*!
+ * Byte-access to the bits
+ */
int8_t Value;
- struct
+ /*!
+ * Structure to store the minimum and the maximum datarate
+ */
+ struct sFields
{
+ /*!
+ * Minimum data rate
+ *
+ * EU868 - [DR_0, DR_1, DR_2, DR_3, DR_4, DR_5, DR_6, DR_7]
+ *
+ * US915 - [DR_0, DR_1, DR_2, DR_3, DR_4]
+ */
int8_t Min : 4;
+ /*!
+ * Maximum data rate
+ *
+ * EU868 - [DR_0, DR_1, DR_2, DR_3, DR_4, DR_5, DR_6, DR_7]
+ *
+ * US915 - [DR_0, DR_1, DR_2, DR_3, DR_4]
+ */
int8_t Max : 4;
}Fields;
}DrRange_t;
-typedef struct
+/*!
+ * LoRaMAC band parameters definition
+ */
+typedef struct sBand
{
+ /*!
+ * Duty cycle
+ */
uint16_t DCycle;
+ /*!
+ * Maximum Tx power
+ */
int8_t TxMaxPower;
- uint64_t LastTxDoneTime;
- uint64_t TimeOff;
+ /*!
+ * Time stamp of the last Tx frame
+ */
+ TimerTime_t LastTxDoneTime;
+ /*!
+ * Holds the time where the device is off
+ */
+ TimerTime_t TimeOff;
}Band_t;
-typedef struct
+/*!
+ * LoRaMAC channel definition
+ */
+typedef struct sChannelParams
{
- uint32_t Frequency; // Hz
- DrRange_t DrRange; // Max datarate [0: SF12, 1: SF11, 2: SF10, 3: SF9, 4: SF8, 5: SF7, 6: SF7, 7: FSK]
- // Min datarate [0: SF12, 1: SF11, 2: SF10, 3: SF9, 4: SF8, 5: SF7, 6: SF7, 7: FSK]
- uint8_t Band; // Band index
+ /*!
+ * Frequency in Hz
+ */
+ uint32_t Frequency;
+ /*!
+ * Data rate definition
+ */
+ DrRange_t DrRange;
+ /*!
+ * Band index
+ */
+ uint8_t Band;
}ChannelParams_t;
-typedef struct
+/*!
+ * LoRaMAC receive window 2 channel parameters
+ */
+typedef struct sRx2ChannelParams
{
- uint32_t Frequency; // Hz
- uint8_t Datarate; // [0: SF12, 1: SF11, 2: SF10, 3: SF9, 4: SF8, 5: SF7, 6: SF7, 7: FSK]
+ /*!
+ * Frequency in Hz
+ */
+ uint32_t Frequency;
+ /*!
+ * Data rate
+ *
+ * EU868 - [DR_0, DR_1, DR_2, DR_3, DR_4, DR_5, DR_6, DR_7]
+ *
+ * US915 - [DR_8, DR_9, DR_10, DR_11, DR_12, DR_13]
+ */
+ uint8_t Datarate;
}Rx2ChannelParams_t;
-typedef struct MulticastParams_s
+/*!
+ * LoRaMAC multicast channel parameter
+ */
+typedef struct sMulticastParams
{
+ /*!
+ * Address
+ */
uint32_t Address;
+ /*!
+ * Network session key
+ */
uint8_t NwkSKey[16];
+ /*!
+ * Application session key
+ */
uint8_t AppSKey[16];
+ /*!
+ * Downlink counter
+ */
uint32_t DownLinkCounter;
- struct MulticastParams_s *Next;
+ /*!
+ * Reference pointer to the next multicast channel parameters in the list
+ */
+ struct sMulticastParams *Next;
}MulticastParams_t;
/*!
* LoRaMAC frame types
+ *
+ * LoRaWAN Specification V1.0, chapter 4.2.1, table 1
*/
-typedef enum
+typedef enum eLoRaMacFrameType
{
+ /*!
+ * LoRaMAC join request frame
+ */
FRAME_TYPE_JOIN_REQ = 0x00,
+ /*!
+ * LoRaMAC join accept frame
+ */
FRAME_TYPE_JOIN_ACCEPT = 0x01,
+ /*!
+ * LoRaMAC unconfirmed up-link frame
+ */
FRAME_TYPE_DATA_UNCONFIRMED_UP = 0x02,
+ /*!
+ * LoRaMAC unconfirmed down-link frame
+ */
FRAME_TYPE_DATA_UNCONFIRMED_DOWN = 0x03,
+ /*!
+ * LoRaMAC confirmed up-link frame
+ */
FRAME_TYPE_DATA_CONFIRMED_UP = 0x04,
+ /*!
+ * LoRaMAC confirmed down-link frame
+ */
FRAME_TYPE_DATA_CONFIRMED_DOWN = 0x05,
+ /*!
+ * LoRaMAC RFU frame
+ */
FRAME_TYPE_RFU = 0x06,
+ /*!
+ * LoRaMAC proprietary frame
+ */
FRAME_TYPE_PROPRIETARY = 0x07,
}LoRaMacFrameType_t;
/*!
* LoRaMAC mote MAC commands
+ *
+ * LoRaWAN Specification V1.0, chapter 5, table 4
*/
-typedef enum
+typedef enum eLoRaMacMoteCmd
{
+ /*!
+ * LinkCheckReq
+ */
MOTE_MAC_LINK_CHECK_REQ = 0x02,
+ /*!
+ * LinkADRAns
+ */
MOTE_MAC_LINK_ADR_ANS = 0x03,
+ /*!
+ * DutyCycleAns
+ */
MOTE_MAC_DUTY_CYCLE_ANS = 0x04,
+ /*!
+ * RXParamSetupAns
+ */
MOTE_MAC_RX_PARAM_SETUP_ANS = 0x05,
+ /*!
+ * DevStatusAns
+ */
MOTE_MAC_DEV_STATUS_ANS = 0x06,
+ /*!
+ * NewChannelAns
+ */
MOTE_MAC_NEW_CHANNEL_ANS = 0x07,
+ /*!
+ * RXTimingSetupAns
+ */
MOTE_MAC_RX_TIMING_SETUP_ANS = 0x08,
}LoRaMacMoteCmd_t;
/*!
* LoRaMAC server MAC commands
+ *
+ * LoRaWAN Specification V1.0, chapter 5, table 4
*/
-typedef enum
+typedef enum eLoRaMacSrvCmd
{
+ /*!
+ * LinkCheckAns
+ */
SRV_MAC_LINK_CHECK_ANS = 0x02,
+ /*!
+ * LinkADRReq
+ */
SRV_MAC_LINK_ADR_REQ = 0x03,
+ /*!
+ * DutyCycleReq
+ */
SRV_MAC_DUTY_CYCLE_REQ = 0x04,
+ /*!
+ * RXParamSetupReq
+ */
SRV_MAC_RX_PARAM_SETUP_REQ = 0x05,
+ /*!
+ * DevStatusReq
+ */
SRV_MAC_DEV_STATUS_REQ = 0x06,
+ /*!
+ * NewChannelReq
+ */
SRV_MAC_NEW_CHANNEL_REQ = 0x07,
+ /*!
+ * RXTimingSetupReq
+ */
SRV_MAC_RX_TIMING_SETUP_REQ = 0x08,
}LoRaMacSrvCmd_t;
/*!
* LoRaMAC Battery level indicator
*/
-typedef enum
+typedef enum eLoRaMacBatteryLevel
{
+ /*!
+ * External power source
+ */
BAT_LEVEL_EXT_SRC = 0x00,
+ /*!
+ * Battery level empty
+ */
BAT_LEVEL_EMPTY = 0x01,
+ /*!
+ * Battery level full
+ */
BAT_LEVEL_FULL = 0xFE,
+ /*!
+ * Battery level - no measurement available
+ */
BAT_LEVEL_NO_MEASURE = 0xFF,
}LoRaMacBatteryLevel_t;
/*!
- * LoRaMAC header field definition
+ * LoRaMAC header field definition (MHDR field)
+ *
+ * LoRaWAN Specification V1.0, chapter 4.2
*/
-typedef union
+typedef union uLoRaMacHeader
{
+ /*!
+ * Byte-access to the bits
+ */
uint8_t Value;
- struct
+ /*!
+ * Structure containing single access to header bits
+ */
+ struct sHdrBits
{
+ /*!
+ * Major version
+ */
uint8_t Major : 2;
+ /*!
+ * RFU
+ */
uint8_t RFU : 3;
+ /*!
+ * Message type
+ */
uint8_t MType : 3;
}Bits;
}LoRaMacHeader_t;
/*!
- * LoRaMAC frame header field definition
+ * LoRaMAC frame control field definition (FCtrl)
+ *
+ * LoRaWAN Specification V1.0, chapter 4.3.1
*/
-typedef union
+typedef union uLoRaMacFrameCtrl
{
+ /*!
+ * Byte-access to the bits
+ */
uint8_t Value;
- struct
+ struct sCtrlBits
{
+ /*!
+ * Frame options length
+ */
uint8_t FOptsLen : 4;
+ /*!
+ * Frame pending bit
+ */
uint8_t FPending : 1;
+ /*!
+ * Message acknowledge bit
+ */
uint8_t Ack : 1;
+ /*!
+ * ADR acknowledgment request bit
+ */
uint8_t AdrAckReq : 1;
+ /*!
+ * ADR control in frame header
+ */
uint8_t Adr : 1;
}Bits;
}LoRaMacFrameCtrl_t;
/*!
- * LoRaMAC event flags
+ * Enumeration containing the status of the operation of a MAC service
*/
-typedef union
+typedef enum eLoRaMacEventInfoStatus
{
- uint8_t Value;
- struct
- {
- uint8_t Tx : 1;
- uint8_t Rx : 1;
- uint8_t RxData : 1;
- uint8_t Multicast : 1;
- uint8_t RxSlot : 2;
- uint8_t LinkCheck : 1;
- uint8_t JoinAccept : 1;
- }Bits;
-}LoRaMacEventFlags_t;
-
-typedef enum
-{
+ /*!
+ * Service performed successfully
+ */
LORAMAC_EVENT_INFO_STATUS_OK = 0,
+ /*!
+ * An error occured during the execution of the service
+ */
LORAMAC_EVENT_INFO_STATUS_ERROR,
+ /*!
+ * A Tx timeouit occured
+ */
LORAMAC_EVENT_INFO_STATUS_TX_TIMEOUT,
+ /*!
+ * An Rx timeout occured on receive window 2
+ */
LORAMAC_EVENT_INFO_STATUS_RX2_TIMEOUT,
+ /*!
+ * An Rx error occured on receive window 2
+ */
LORAMAC_EVENT_INFO_STATUS_RX2_ERROR,
+ /*!
+ * An error occured in the join procedure
+ */
LORAMAC_EVENT_INFO_STATUS_JOIN_FAIL,
- LORAMAC_EVENT_INFO_STATUS_DOWNLINK_FAIL,
+ /*!
+ * 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_DOWNLINK_REPEATED,
+ /*!
+ * An address error occured
+ */
LORAMAC_EVENT_INFO_STATUS_ADDRESS_FAIL,
+ /*!
+ * message integrity check failure
+ */
LORAMAC_EVENT_INFO_STATUS_MIC_FAIL,
}LoRaMacEventInfoStatus_t;
/*!
- * LoRaMAC event information
+ * LoRaMac tx/rx operation state
+ */
+typedef union eLoRaMacFlags_t
+{
+ /*!
+ * Byte-access to the bits
+ */
+ uint8_t Value;
+ struct sMacFlagBits
+ {
+ /*!
+ * MCPS-Req pending
+ */
+ uint8_t McpsReq : 1;
+ /*!
+ * MCPS-Ind pending
+ */
+ uint8_t McpsInd : 1;
+ /*!
+ * MLME-Req pending
+ */
+ uint8_t MlmeReq : 1;
+ /*!
+ * MAC cycle done
+ */
+ uint8_t MacDone : 1;
+ }Bits;
+}LoRaMacFlags_t;
+
+/*!
+ *
+ * \brief LoRaMAC data services
+ *
+ * \details The following table list the primitives which are supported by the
+ * specific MAC data service:
+ *
+ * Name | Request | Indication | Response | Confirm
+ * --------------------- | :-----: | :--------: | :------: | :-----:
+ * \ref MCPS_UNCONFIRMED | YES | YES | NO | YES
+ * \ref MCPS_CONFIRMED | YES | YES | NO | YES
+ * \ref MCPS_MULTICAST | NO | YES | NO | NO
+ * \ref MCPS_PROPRIETARY | YES | YES | NO | YES
+ *
+ * The following table provides links to the function implementations of the
+ * related MCPS primitives:
+ *
+ * Primitive | Function
+ * ---------------- | :---------------------:
+ * MCPS-Request | \ref LoRaMacMlmeRequest
+ * MCPS-Confirm | MacMcpsConfirm in \ref LoRaMacPrimitives_t
+ * MCPS-Indication | MacMcpsIndication in \ref LoRaMacPrimitives_t
+ */
+typedef enum eMcps
+{
+ /*!
+ * Unconfirmed LoRaMAC frame
+ */
+ MCPS_UNCONFIRMED,
+ /*!
+ * Confirmed LoRaMAC frame
+ */
+ MCPS_CONFIRMED,
+ /*!
+ * Multicast LoRaMAC frame
+ */
+ MCPS_MULTICAST,
+ /*!
+ * Proprietary frame
+ */
+ MCPS_PROPRIETARY,
+}Mcps_t;
+
+/*!
+ * LoRaMAC MCPS-Request for an unconfirmed frame
+ */
+typedef struct sMcpsReqUnconfirmed
+{
+ /*!
+ * Frame port field. Must be set if the payload is not empty. Use the
+ * application specific frame port values: [1...223]
+ *
+ * LoRaWAN Specification V1.0, chapter 4.3.2
+ */
+ uint8_t fPort;
+ /*!
+ * Pointer to the buffer of the frame payload
+ */
+ void *fBuffer;
+ /*!
+ * Size of the frame payload
+ */
+ uint16_t fBufferSize;
+ /*!
+ * Uplink datarate, if ADR is off
+ */
+ int8_t Datarate;
+}McpsReqUnconfirmed_t;
+
+/*!
+ * LoRaMAC MCPS-Request for a confirmed frame
+ */
+typedef struct sMcpsReqConfirmed
+{
+ /*!
+ * Frame port field. Must be set if the payload is not empty. Use the
+ * application specific frame port values: [1...223]
+ *
+ * LoRaWAN Specification V1.0, chapter 4.3.2
+ */
+ uint8_t fPort;
+ /*!
+ * Pointer to the buffer of the frame payload
+ */
+ void *fBuffer;
+ /*!
+ * Size of the frame payload
+ */
+ uint16_t fBufferSize;
+ /*!
+ * Uplink datarate, if ADR is off
+ */
+ int8_t Datarate;
+ /*!
+ * Number of attempts to transmit the frame, if frame could not be send, or
+ * if the LoRaMAC layer did not receive an acknowledgment
+ */
+ uint8_t nbRetries;
+}McpsReqConfirmed_t;
+
+/*!
+ * LoRaMAC MCPS-Request for a proprietary frame
+ */
+typedef struct sMcpsReqProprietary
+{
+ /*!
+ * Pointer to the buffer of the frame payload
+ */
+ void *fBuffer;
+ /*!
+ * Size of the frame payload
+ */
+ uint16_t fBufferSize;
+ /*!
+ * Uplink datarate, if ADR is off
+ */
+ int8_t Datarate;
+}McpsReqProprietary_t;
+
+/*!
+ * LoRaMAC MCPS-Request structure
+ */
+typedef struct sMcpsReq
+{
+ /*!
+ * MCPS-Request type
+ */
+ Mcps_t Type;
+
+ /*!
+ * MCPS-Request parameters
+ */
+ union uMcpsParam
+ {
+ /*!
+ * MCPS-Request parameters for an unconfirmed frame
+ */
+ McpsReqUnconfirmed_t Unconfirmed;
+ /*!
+ * MCPS-Request parameters for a confirmed frame
+ */
+ McpsReqConfirmed_t Confirmed;
+ /*!
+ * MCPS-Request parameters for a proprietary frame
+ */
+ McpsReqProprietary_t Proprietary;
+ }Req;
+}McpsReq_t;
+
+/*!
+ * LoRaMAC MCPS-Confirm
*/
-typedef struct
+typedef struct sMcpsConfirm
+{
+ /*!
+ * Holds the previously performed MCPS-Request
+ */
+ Mcps_t McpsRequest;
+ /*!
+ * Status of the operation
+ */
+ LoRaMacEventInfoStatus_t Status;
+ /*!
+ * Uplink datarate
+ */
+ uint8_t Datarate;
+ /*!
+ * Transmission power
+ */
+ int8_t TxPower;
+ /*!
+ * Set if an acknowledgement was received
+ */
+ bool AckReceived;
+ /*!
+ * Provides the number of retransmissions
+ */
+ uint8_t NbRetries;
+ /*!
+ * The transmission time on air of the frame
+ */
+ TimerTime_t TxTimeOnAir;
+ /*!
+ * The uplink counter value related to the frame
+ */
+ uint32_t UpLinkCounter;
+}McpsConfirm_t;
+
+/*!
+ * LoRaMAC MCPS-Indication primitive
+ */
+typedef struct sMcpsIndication
{
+ /*!
+ * MCPS-Indication type
+ */
+ Mcps_t McpsIndication;
+ /*!
+ * Status of the operation
+ */
+ LoRaMacEventInfoStatus_t Status;
+ /*!
+ * Multicast
+ */
+ uint8_t Multicast;
+ /*!
+ * Application port
+ */
+ uint8_t Port;
+ /*!
+ * Downlink datarate
+ */
+ uint8_t RxDatarate;
+ /*!
+ * Frame pending status
+ */
+ uint8_t FramePending;
+ /*!
+ * Pointer to the received data stream
+ */
+ uint8_t *Buffer;
+ /*!
+ * Size of the received data stream
+ */
+ uint8_t BufferSize;
+ /*!
+ * Indicates, if data is available
+ */
+ bool RxData;
+ /*!
+ * Rssi of the received packet
+ */
+ int16_t Rssi;
+ /*!
+ * Snr of the received packet
+ */
+ uint8_t Snr;
+ /*!
+ * Receive window
+ *
+ * [0: Rx window 1, 1: Rx window 2]
+ */
+ uint8_t RxSlot;
+ /*!
+ * Set if an acknowledgement was received
+ */
+ bool AckReceived;
+ /*!
+ * The downlink counter value for the received frame
+ */
+ uint32_t DownLinkCounter;
+}McpsIndication_t;
+
+/*!
+ * \brief LoRaMAC management services
+ *
+ * \details The following table list the primitives which are supported by the
+ * specific MAC management service:
+ *
+ * Name | Request | Indication | Response | Confirm
+ * --------------------- | :-----: | :--------: | :------: | :-----:
+ * \ref MLME_JOIN | YES | NO | NO | YES
+ * \ref 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 | \ref LoRaMacMlmeRequest
+ * MLME-Confirm | MacMlmeConfirm in \ref LoRaMacPrimitives_t
+ */
+typedef enum eMlme
+{
+ /*!
+ * Initiates the Over-the-Air activation
+ *
+ * LoRaWAN Specification V1.0, chapter 6.2
+ */
+ MLME_JOIN,
+ /*!
+ * LinkCheckReq - Connectivity validation
+ *
+ * LoRaWAN Specification V1.0, chapter 5, table 4
+ */
+ MLME_LINK_CHECK,
+}Mlme_t;
+
+/*!
+ * LoRaMAC MLME-Request for the join service
+ */
+typedef struct sMlmeReqJoin
+{
+ /*!
+ * Globally unique end-device identifier
+ *
+ * LoRaWAN Specification V1.0, chapter 6.2.1
+ */
+ uint8_t *DevEui;
+ /*!
+ * Application identifier
+ *
+ * LoRaWAN Specification V1.0, chapter 6.1.2
+ */
+ uint8_t *AppEui;
+ /*!
+ * AES-128 application key
+ *
+ * LoRaWAN Specification V1.0, chapter 6.2.2
+ */
+ uint8_t *AppKey;
+}MlmeReqJoin_t;
+
+/*!
+ *
+ */
+typedef struct sMlmeReq
+{
+ /*!
+ * MLME-Request type
+ */
+ Mlme_t Type;
+
+ /*!
+ * MLME-Request parameters
+ */
+ union uMlmeParam
+ {
+ /*!
+ * MLME-Request parameters for a join request
+ */
+ MlmeReqJoin_t Join;
+ }Req;
+}MlmeReq_t;
+
+/*!
+ * LoRaMAC MLME-Confirm primitive
+ */
+typedef struct sMlmeConfirm
+{
+ /*!
+ * Holds the previously performed MLME-Request
+ */
+ Mlme_t MlmeRequest;
+ /*!
+ * Status of the operation
+ */
LoRaMacEventInfoStatus_t Status;
- bool TxAckReceived;
- uint8_t TxNbRetries;
- uint8_t TxDatarate;
- uint8_t RxPort;
- uint8_t *RxBuffer;
- uint8_t RxBufferSize;
- int16_t RxRssi;
- uint8_t RxSnr;
- uint16_t Energy;
+ /*!
+ * The transmission time on air of the frame
+ */
+ TimerTime_t TxTimeOnAir;
+ /*!
+ * Demodulation margin. Contains the link margin [dB] of the last
+ * successfully received LinkCheckReq
+ */
uint8_t DemodMargin;
+ /*!
+ * Number of gateways which received the last LinkCheckReq
+ */
uint8_t NbGateways;
-}LoRaMacEventInfo_t;
+}MlmeConfirm_t;
+
+/*!
+ * LoRa Mac Information Base (MIB)
+ *
+ * The following table lists the MIB parameters and the related attributes:
+ *
+ * Attribute | Get | Set
+ * --------------------------------- | :-: | :-:
+ * \ref MIB_DEVICE_CLASS | YES | YES
+ * \ref MIB_NETWORK_JOINED | YES | YES
+ * \ref MIB_ADR | YES | YES
+ * \ref MIB_NET_ID | YES | YES
+ * \ref MIB_DEV_ADDR | YES | YES
+ * \ref MIB_NWK_SKEY | YES | YES
+ * \ref MIB_APP_SKEY | YES | YES
+ * \ref MIB_PUBLIC_NETWORK | YES | YES
+ * \ref MIB_CHANNELS | YES | NO
+ * \ref MIB_RX2_CHANNEL | YES | YES
+ * \ref MIB_CHANNELS_MASK | YES | YES
+ * \ref MIB_CHANNELS_NB_REP | YES | YES
+ * \ref MIB_MAX_RX_WINDOW_DURATION | YES | YES
+ * \ref MIB_RECEIVE_DELAY_1 | YES | YES
+ * \ref MIB_RECEIVE_DELAY_2 | YES | YES
+ * \ref MIB_JOIN_ACCEPT_DELAY_1 | YES | YES
+ * \ref MIB_JOIN_ACCEPT_DELAY_2 | YES | YES
+ * \ref MIB_CHANNELS_DATARATE | YES | YES
+ * \ref MIB_CHANNELS_TX_POWER | YES | YES
+ * \ref MIB_UPLINK_COUNTER | YES | NO
+ * \ref MIB_DOWNLINK_COUNTER | YES | NO
+ * \ref MIB_MULTICAST_CHANNEL | YES | NO
+ *
+ * The following table provides links to the function implementations of the
+ * related MIB primitives:
+ *
+ * Primitive | Function
+ * ---------------- | :---------------------:
+ * MIB-Set | \ref LoRaMacMibSetRequestConfirm
+ * MIB-Get | \ref LoRaMacMibGetRequestConfirm
+ */
+typedef enum eMib
+{
+ /*!
+ * LoRaWAN device class
+ *
+ * LoRaWAN Specification V1.0
+ */
+ MIB_DEVICE_CLASS,
+ /*!
+ * LoRaWAN Network joined attribute
+ *
+ * LoRaWAN Specification V1.0
+ */
+ MIB_NETWORK_JOINED,
+ /*!
+ * Adaptive data rate
+ *
+ * LoRaWAN Specification V1.0, chapter 4.3.1.1
+ *
+ * [true: ADR enabled, false: ADR disabled]
+ */
+ MIB_ADR,
+ /*!
+ * Network identifier
+ *
+ * LoRaWAN Specification V1.0, chapter 6.2.5
+ */
+ MIB_NET_ID,
+ /*!
+ * End-device address
+ *
+ * LoRaWAN Specification V1.0, chapter 6.1.2
+ */
+ MIB_DEV_ADDR,
+ /*!
+ * Network session key
+ *
+ * LoRaWAN Specification V1.0, chapter 6.1.3
+ */
+ MIB_NWK_SKEY,
+ /*!
+ * Application session key
+ *
+ * LoRaWAN Specification V1.0, chapter 6.1.4
+ */
+ MIB_APP_SKEY,
+ /*!
+ * Set the network type to public or private
+ *
+ * LoRaWAN Specification V1.0, chapter 7
+ *
+ * [true: public network, false: private network]
+ */
+ MIB_PUBLIC_NETWORK,
+ /*!
+ * Support the operation with repeaters
+ *
+ * LoRaWAN Specification V1.0, chapter 7
+ *
+ * [true: repeater support enabled, false: repeater support disabled]
+ */
+ MIB_REPEATER_SUPPORT,
+ /*!
+ * 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 Specification V1.0, chapter 7
+ */
+ MIB_CHANNELS,
+ /*!
+ * Set receive window 2 channel
+ *
+ * LoRaWAN Specification V1.0, chapter 3.3.2
+ */
+ MIB_RX2_CHANNEL,
+ /*!
+ * LoRaWAN channels mask
+ *
+ * LoRaWAN Specification V1.0, chapter 5.2
+ */
+ MIB_CHANNELS_MASK,
+ /*!
+ * Set the number of repetitions on a channel
+ *
+ * LoRaWAN Specification V1.0, chapter 5.2
+ */
+ MIB_CHANNELS_NB_REP,
+ /*!
+ * Maximum receive window duration in [us]
+ *
+ * LoRaWAN Specification V1.0, chapter 3.3.3
+ */
+ MIB_MAX_RX_WINDOW_DURATION,
+ /*!
+ * Receive delay 1 in [us]
+ *
+ * LoRaWAN Specification V1.0, chapter 6
+ */
+ MIB_RECEIVE_DELAY_1,
+ /*!
+ * Receive delay 2 in [us]
+ *
+ * LoRaWAN Specification V1.0, chapter 6
+ */
+ MIB_RECEIVE_DELAY_2,
+ /*!
+ * Join accept delay 1 in [us]
+ *
+ * LoRaWAN Specification V1.0, chapter 6
+ */
+ MIB_JOIN_ACCEPT_DELAY_1,
+ /*!
+ * Join accept delay 2 in [us]
+ *
+ * LoRaWAN Specification V1.0, chapter 6
+ */
+ MIB_JOIN_ACCEPT_DELAY_2,
+ /*!
+ * Data rate of a channel
+ *
+ * LoRaWAN Specification V1.0, chapter 7
+ *
+ * EU868 - [DR_0, DR_1, DR_2, DR_3, DR_4, DR_5, DR_6, DR_7]
+ *
+ * US915 - [DR_0, DR_1, DR_2, DR_3, DR_4, DR_8, DR_9, DR_10, DR_11, DR_12, DR_13]
+ */
+ MIB_CHANNELS_DATARATE,
+ /*!
+ * Transmission power of a channel
+ *
+ * LoRaWAN Specification V1.0, chapter 7
+ *
+ * EU868 - [TX_POWER_20_DBM, TX_POWER_14_DBM, TX_POWER_11_DBM,
+ * TX_POWER_08_DBM, TX_POWER_05_DBM, TX_POWER_02_DBM]
+ *
+ * US915 - [TX_POWER_30_DBM, TX_POWER_28_DBM, TX_POWER_26_DBM,
+ * TX_POWER_24_DBM, TX_POWER_22_DBM, TX_POWER_20_DBM,
+ * TX_POWER_18_DBM, TX_POWER_14_DBM, TX_POWER_12_DBM,
+ * TX_POWER_10_DBM]
+ */
+ MIB_CHANNELS_TX_POWER,
+ /*!
+ * LoRaWAN Up-link counter
+ *
+ * LoRaWAN Specification V1.0, chapter 4.3.1.5
+ */
+ MIB_UPLINK_COUNTER,
+ /*!
+ * LoRaWAN Down-link counter
+ *
+ * LoRaWAN Specification V1.0, chapter 4.3.1.5
+ */
+ MIB_DOWNLINK_COUNTER,
+ /*!
+ * 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_MULTICAST_CHANNEL,
+}Mib_t;
+
+/*!
+ * LoRaMAC MIB parameters
+ */
+typedef union uMibParam
+{
+ /*!
+ * LoRaWAN device class
+ *
+ * Related MIB type: \ref MIB_DEVICE_CLASS
+ */
+ DeviceClass_t Class;
+ /*!
+ * LoRaWAN network joined attribute
+ *
+ * Related MIB type: \ref MIB_NETWORK_JOINED
+ */
+ bool IsNetworkJoined;
+ /*!
+ * Activation state of ADR
+ *
+ * Related MIB type: \ref MIB_ADR
+ */
+ bool AdrEnable;
+ /*!
+ * Network identifier
+ *
+ * Related MIB type: \ref MIB_NET_ID
+ */
+ uint32_t NetID;
+ /*!
+ * End-device address
+ *
+ * Related MIB type: \ref MIB_DEV_ADDR
+ */
+ uint32_t DevAddr;
+ /*!
+ * Network session key
+ *
+ * Related MIB type: \ref MIB_NWK_SKEY
+ */
+ uint8_t *NwkSKey;
+ /*!
+ * Application session key
+ *
+ * Related MIB type: \ref MIB_APP_SKEY
+ */
+ uint8_t *AppSKey;
+ /*!
+ * Enable or disable a public network
+ *
+ * Related MIB type: \ref MIB_PUBLIC_NETWORK
+ */
+ bool EnablePublicNetwork;
+ /*!
+ * Enable or disable repeater support
+ *
+ * Related MIB type: \ref MIB_REPEATER_SUPPORT
+ */
+ bool EnableRepeaterSupport;
+ /*!
+ * LoRaWAN Channel
+ *
+ * Related MIB type: \ref MIB_CHANNELS
+ */
+ ChannelParams_t* ChannelList;
+ /*!
+ * Channel for the receive window 2
+ *
+ * Related MIB type: \ref MIB_RX2_CHANNEL
+ */
+ Rx2ChannelParams_t Rx2Channel;
+ /*!
+ * Channel mask
+ *
+ * Related MIB type: \ref MIB_CHANNELS_MASK
+ */
+ uint16_t* ChannelsMask;
+ /*!
+ * Number of frame repetitions
+ *
+ * Related MIB type: \ref MIB_CHANNELS_NB_REP
+ */
+ uint8_t ChannelNbRep;
+ /*!
+ * Maximum receive window duration
+ *
+ * Related MIB type: \ref MIB_MAX_RX_WINDOW_DURATION
+ */
+ uint32_t MaxRxWindow;
+ /*!
+ * Receive delay 1
+ *
+ * Related MIB type: \ref MIB_RECEIVE_DELAY_1
+ */
+ uint32_t ReceiveDelay1;
+ /*!
+ * Receive delay 2
+ *
+ * Related MIB type: \ref MIB_RECEIVE_DELAY_2
+ */
+ uint32_t ReceiveDelay2;
+ /*!
+ * Join accept delay 1
+ *
+ * Related MIB type: \ref MIB_JOIN_ACCEPT_DELAY_1
+ */
+ uint32_t JoinAcceptDelay1;
+ /*!
+ * Join accept delay 2
+ *
+ * Related MIB type: \ref MIB_JOIN_ACCEPT_DELAY_2
+ */
+ uint32_t JoinAcceptDelay2;
+ /*!
+ * Channels data rate
+ *
+ * Related MIB type: \ref MIB_CHANNELS_DATARATE
+ */
+ int8_t ChannelsDatarate;
+ /*!
+ * Channels TX power
+ *
+ * Related MIB type: \ref MIB_CHANNELS_TX_POWER
+ */
+ int8_t ChannelsTxPower;
+ /*!
+ * LoRaWAN Up-link counter
+ *
+ * Related MIB type: \ref MIB_UPLINK_COUNTER
+ */
+ uint32_t UpLinkCounter;
+ /*!
+ * LoRaWAN Down-link counter
+ *
+ * Related MIB type: \ref MIB_DOWNLINK_COUNTER
+ */
+ uint32_t DownLinkCounter;
+ /*!
+ * Multicast channel
+ *
+ * Related MIB type: \ref MIB_MULTICAST_CHANNEL
+ */
+ MulticastParams_t* MulticastList;
+}MibParam_t;
+
+/*!
+ * LoRaMAC MIB-RequestConfirm structure
+ */
+typedef struct eMibRequestConfirm
+{
+ /*!
+ * MIB-Request type
+ */
+ Mib_t Type;
+
+ /*!
+ * MLME-RequestConfirm parameters
+ */
+ MibParam_t Param;
+}MibRequestConfirm_t;
+
+/*!
+ * LoRaMAC tx information
+ */
+typedef struct sLoRaMacTxInfo
+{
+ /*!
+ * Defines the size of the applicative payload which can be processed
+ */
+ uint8_t MaxPossiblePayload;
+ /*!
+ * The current payload size, dependent on the current datarate
+ */
+ uint8_t CurrentPayloadSize;
+}LoRaMacTxInfo_t;
+
+/*!
+ * LoRaMAC Status
+ */
+typedef enum eLoRaMacStatus
+{
+ /*!
+ * Service started successfully
+ */
+ LORAMAC_STATUS_OK,
+ /*!
+ * Service not started - LoRaMAC is busy
+ */
+ LORAMAC_STATUS_BUSY,
+ /*!
+ * Service unknown
+ */
+ LORAMAC_STATUS_SERVICE_UNKNOWN,
+ /*!
+ * Service not started - invalid parameter
+ */
+ LORAMAC_STATUS_PARAMETER_INVALID,
+ /*!
+ * Service not started - the device is not in a LoRaWAN
+ */
+ LORAMAC_STATUS_NO_NETWORK_JOINED,
+ /*!
+ * Service not started - playload lenght error
+ */
+ LORAMAC_STATUS_LENGTH_ERROR,
+ /*!
+ * Service not started - playload lenght error
+ */
+ LORAMAC_STATUS_MAC_CMD_LENGTH_ERROR,
+ /*!
+ * Service not started - the device is switched off
+ */
+ LORAMAC_STATUS_DEVICE_OFF,
+}LoRaMacStatus_t;
/*!
* LoRaMAC events structure
* Used to notify upper layers of MAC events
*/
-typedef struct sLoRaMacCallbacks
+typedef struct sLoRaMacPrimitives
{
/*!
- * MAC layer event callback prototype.
+ * \brief MCPS-Confirm primitive
*
- * \param [IN] flags Bit field indicating the MAC events occurred
- * \param [IN] info Details about MAC events occurred
+ * \param [OUT] MCPS-Confirm parameters
+ */
+ void ( *MacMcpsConfirm )( McpsConfirm_t *McpsConfirm );
+ /*!
+ * \brief MCPS-Indication primitive
+ *
+ * \param [OUT] MCPS-Indication parameters
*/
- void ( *MacEvent )( LoRaMacEventFlags_t *flags, LoRaMacEventInfo_t *info );
+ void ( *MacMcpsIndication )( McpsIndication_t *McpsIndication );
/*!
- * Function callback to get the current battery level
+ * \brief MLME-Confirm primitive
*
- * \retval batteryLevel Current battery level
+ * \param [OUT] MLME-Confirm parameters
+ */
+ void ( *MacMlmeConfirm )( MlmeConfirm_t *MlmeConfirm );
+}LoRaMacPrimitives_t;
+
+typedef struct sLoRaMacCallback
+{
+ /*!
+ * \brief Measures the battery level
+ *
+ * \retval Battery level [0: node is connected to an external
+ * power source, 1..254: battery level, where 1 is the minimum
+ * and 254 is the maximum value, 255: the node was not able
+ * to measure the battery level]
*/
uint8_t ( *GetBatteryLevel )( void );
-}LoRaMacCallbacks_t;
-
-/*!
- * LoRaMAC layer initialization
- *
- * \param [IN] callabcks Pointer to a structure defining the LoRaMAC
- * callback functions.
- */
-void LoRaMacInit( LoRaMacCallbacks_t *callabcks );
+}LoRaMacCallback_t;
/*!
- * Enables/Disables the ADR (Adaptive Data Rate)
- *
- * \param [IN] enable [true: ADR ON, false: ADR OFF]
- */
-void LoRaMacSetAdrOn( bool enable );
-
-/*!
- * Initializes the network IDs. Device address,
- * network session AES128 key and application session AES128 key.
+ * \brief LoRaMAC layer initialization
*
- * \remark To be only used when Over-the-Air activation isn't used.
+ * \details 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 \ref LoRaMacPrimitives_t must be
+ * set to a valid callback function.
+ *
+ * \param [IN] events - Pointer to a structure defining the LoRaMAC
+ * event functions. Refer to \ref LoRaMacPrimitives_t.
*
- * \param [IN] netID 24 bits network identifier
- * ( provided by network operator )
- * \param [IN] devAddr 32 bits device address on the network
- * (must be unique to the network)
- * \param [IN] nwkSKey Pointer to the network session AES128 key array
- * ( 16 bytes )
- * \param [IN] appSKey Pointer to the application session AES128 key array
- * ( 16 bytes )
+ * \param [IN] events - Pointer to a structure defining the LoRaMAC
+ * callback functions. Refer to \ref LoRaMacCallback_t.
+ *
+ * \retval LoRaMacStatus_t Status of the operation. Possible returns are:
+ * returns are:
+ * \ref LORAMAC_STATUS_OK,
+ * \ref LORAMAC_STATUS_PARAMETER_INVALID.
*/
-void LoRaMacInitNwkIds( uint32_t netID, uint32_t devAddr, uint8_t *nwkSKey, uint8_t *appSKey );
-
-/*
- * TODO: Add documentation
- */
-void LoRaMacMulticastChannelAdd( MulticastParams_t *channelParam );
-
-/*
- * TODO: Add documentation
- */
-void LoRaMacMulticastChannelRemove( MulticastParams_t *channelParam );
+LoRaMacStatus_t LoRaMacInitialization( LoRaMacPrimitives_t *primitives, LoRaMacCallback_t *callbacks );
/*!
- * Initiates the Over-the-Air activation
- *
- * \param [IN] devEui Pointer to the device EUI array ( 8 bytes )
- * \param [IN] appEui Pointer to the application EUI array ( 8 bytes )
- * \param [IN] appKey Pointer to the application AES128 key array ( 16 bytes )
+ * \brief 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.
+ *
+ * \param [IN] size - Size of applicative payload to be send next
*
- * \retval status [0: OK, 1: Tx error, 2: Already joined a network]
- */
-uint8_t LoRaMacJoinReq( uint8_t *devEui, uint8_t *appEui, uint8_t *appKey );
-
-/*!
- * Sends a LinkCheckReq MAC command on the next uplink frame
+ * \param [OUT] txInfo - The structure \ref 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.
*
- * \retval status Function status [0: OK, 1: Busy]
+ * \retval LoRaMacStatus_t Status of the operation. When the parameters are
+ * not valid, the function returns \ref 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. *
*/
-uint8_t LoRaMacLinkCheckReq( void );
-
-/*!
- * LoRaMAC layer send frame
- *
- * \param [IN] fPort MAC payload port (must be > 0)
- * \param [IN] fBuffer MAC data buffer to be sent
- * \param [IN] fBufferSize MAC data buffer size
- *
- * \retval status [0: OK, 1: Busy, 2: No network joined,
- * 3: Length or port error, 4: Unknown MAC command
- * 5: Unable to find a free channel
- * 6: Device switched off]
- */
-uint8_t LoRaMacSendFrame( uint8_t fPort, void *fBuffer, uint16_t fBufferSize );
+LoRaMacStatus_t LoRaMacQueryTxPossible( uint8_t size, LoRaMacTxInfo_t* txInfo );
/*!
- * LoRaMAC layer send frame
+ * \brief LoRaMAC channel add service
+ *
+ * \details 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.
+ *
+ * \param [IN] id - Id of the channel. Possible values are:
*
- * \param [IN] fPort MAC payload port (must be > 0)
- * \param [IN] fBuffer MAC data buffer to be sent
- * \param [IN] fBufferSize MAC data buffer size
- * \param [IN] fBufferSize MAC data buffer size
- * \param [IN] nbRetries Number of retries to receive the acknowledgement
+ * 0-15 for EU868
+ * 0-72 for US915
+ *
+ * \param [IN] params - Channel parameters to set.
*
- * \retval status [0: OK, 1: Busy, 2: No network joined,
- * 3: Length or port error, 4: Unknown MAC command
- * 5: Unable to find a free channel
- * 6: Device switched off]
+ * \retval LoRaMacStatus_t Status of the operation. Possible returns are:
+ * \ref LORAMAC_STATUS_OK,
+ * \ref LORAMAC_STATUS_BUSY,
+ * \ref LORAMAC_STATUS_PARAMETER_INVALID.
*/
-uint8_t LoRaMacSendConfirmedFrame( uint8_t fPort, void *fBuffer, uint16_t fBufferSize, uint8_t nbRetries );
+LoRaMacStatus_t LoRaMacChannelAdd( uint8_t id, ChannelParams_t params );
/*!
- * ============================================================================
- * = LoRaMac test functions =
- * ============================================================================
+ * \brief LoRaMAC channel remove service
+ *
+ * \details Deactivates the id in the channel mask.
+ *
+ * \param [IN] id - Id of the channel.
+ *
+ * \retval LoRaMacStatus_t Status of the operation. Possible returns are:
+ * \ref LORAMAC_STATUS_OK,
+ * \ref LORAMAC_STATUS_BUSY,
+ * \ref LORAMAC_STATUS_PARAMETER_INVALID.
*/
+LoRaMacStatus_t LoRaMacChannelRemove( uint8_t id );
/*!
- * LoRaMAC layer generic send frame
+ * \brief LoRaMAC multicast channel link service
+ *
+ * \details Links a multicast channel into the linked list.
+ *
+ * \param [IN] channelParam - Multicast channel parameters to link.
*
- * \param [IN] macHdr MAC header field
- * \param [IN] fOpts MAC commands buffer
- * \param [IN] fPort MAC payload port
- * \param [IN] fBuffer MAC data buffer to be sent
- * \param [IN] fBufferSize MAC data buffer size
- * \retval status [0: OK, 1: Busy, 2: No network joined,
- * 3: Length or port error, 4: Unknown MAC command
- * 5: Unable to find a free channel
- * 6: Device switched off]
+ * \retval LoRaMacStatus_t Status of the operation. Possible returns are:
+ * \ref LORAMAC_STATUS_OK,
+ * \ref LORAMAC_STATUS_BUSY,
+ * \ref LORAMAC_STATUS_PARAMETER_INVALID.
*/
-uint8_t LoRaMacSend( LoRaMacHeader_t *macHdr, uint8_t *fOpts, uint8_t fPort, void *fBuffer, uint16_t fBufferSize );
+LoRaMacStatus_t LoRaMacMulticastChannelLink( MulticastParams_t *channelParam );
+
+/*!
+ * \brief LoRaMAC multicast channel unlink service
+ *
+ * \details Unlinks a multicast channel from the linked list.
+ *
+ * \param [IN] channelParam - Multicast channel parameters to unlink.
+ *
+ * \retval LoRaMacStatus_t Status of the operation. Possible returns are:
+ * \ref LORAMAC_STATUS_OK,
+ * \ref LORAMAC_STATUS_BUSY,
+ * \ref LORAMAC_STATUS_PARAMETER_INVALID.
+ */
+LoRaMacStatus_t LoRaMacMulticastChannelUnlink( MulticastParams_t *channelParam );
/*!
- * LoRaMAC layer frame buffer initialization.
+ * \brief LoRaMAC MIB-Get
+ *
+ * \details 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
+ * \ref MIB_ADR.
+ * \code
+ * MibRequestConfirm_t mibReq;
+ * mibReq.Type = MIB_ADR;
*
- * \param [IN] channel Channel parameters
- * \param [IN] macHdr MAC header field
- * \param [IN] fCtrl MAC frame control field
- * \param [IN] fOpts MAC commands buffer
- * \param [IN] fPort MAC payload port
- * \param [IN] fBuffer MAC data buffer to be sent
- * \param [IN] fBufferSize MAC data buffer size
- * \retval status [0: OK, 1: N/A, 2: No network joined,
- * 3: Length or port error, 4: Unknown MAC command]
+ * if( LoRaMacMibGetRequestConfirm( &mibReq ) == LORAMAC_STATUS_OK )
+ * {
+ * // LoRaMAC updated the parameter mibParam.AdrEnable
+ * }
+ * \endcode
+ *
+ * \param [IN] mibRequest - MIB-GET-Request to perform. Refer to \ref MibRequestConfirm_t.
+ *
+ * \retval LoRaMacStatus_t Status of the operation. Possible returns are:
+ * \ref LORAMAC_STATUS_OK,
+ * \ref LORAMAC_STATUS_SERVICE_UNKNOWN,
+ * \ref LORAMAC_STATUS_PARAMETER_INVALID.
*/
-uint8_t LoRaMacPrepareFrame( ChannelParams_t channel,LoRaMacHeader_t *macHdr, LoRaMacFrameCtrl_t *fCtrl, uint8_t *fOpts, uint8_t fPort, void *fBuffer, uint16_t fBufferSize );
-
-/*!
- * LoRaMAC layer prepared frame buffer transmission with channel specification
- *
- * \remark LoRaMacPrepareFrame must be called at least once before calling this
- * function.
- *
- * \param [IN] channel Channel parameters
- * \retval status [0: OK, 1: Busy]
- */
-uint8_t LoRaMacSendFrameOnChannel( ChannelParams_t channel );
+LoRaMacStatus_t LoRaMacMibGetRequestConfirm( MibRequestConfirm_t *mibGet );
/*!
- * LoRaMAC layer generic send frame with channel specification
+ * \brief LoRaMAC MIB-Set
+ *
+ * \details 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
+ * \ref MIB_ADR.
+ *
+ * \code
+ * MibRequestConfirm_t mibReq;
+ * mibReq.Type = MIB_ADR;
+ * mibReq.Param.AdrEnable = true;
*
- * \param [IN] channel Channel parameters
- * \param [IN] macHdr MAC header field
- * \param [IN] fCtrl MAC frame control field
- * \param [IN] fOpts MAC commands buffer
- * \param [IN] fPort MAC payload port
- * \param [IN] fBuffer MAC data buffer to be sent
- * \param [IN] fBufferSize MAC data buffer size
- * \retval status [0: OK, 1: Busy, 2: No network joined,
- * 3: Length or port error, 4: Unknown MAC command]
- */
-uint8_t LoRaMacSendOnChannel( ChannelParams_t channel, LoRaMacHeader_t *macHdr, LoRaMacFrameCtrl_t *fCtrl, uint8_t *fOpts, uint8_t fPort, void *fBuffer, uint16_t fBufferSize );
-
-/*!
- * ============================================================================
- * = LoRaMac setup functions =
- * ============================================================================
- */
-
-/*
- * TODO: Add documentation
+ * if( LoRaMacMibGetRequestConfirm( &mibReq ) == LORAMAC_STATUS_OK )
+ * {
+ * // LoRaMAC updated the parameter
+ * }
+ * \endcode
+ *
+ * \param [IN] mibRequest - MIB-SET-Request to perform. Refer to \ref MibRequestConfirm_t.
+ *
+ * \retval LoRaMacStatus_t Status of the operation. Possible returns are:
+ * \ref LORAMAC_STATUS_OK,
+ * \ref LORAMAC_STATUS_BUSY,
+ * \ref LORAMAC_STATUS_SERVICE_UNKNOWN,
+ * \ref LORAMAC_STATUS_PARAMETER_INVALID.
*/
-void LoRaMacSetDeviceClass( DeviceClass_t deviceClass );
-
-/*
- * TODO: Add documentation
- */
-void LoRaMacSetPublicNetwork( bool enable );
-
-/*
- * TODO: Add documentation
- */
-void LoRaMacSetChannel( uint8_t id, ChannelParams_t params );
-
-/*
- * TODO: Add documentation
- */
-void LoRaMacSetRx2Channel( Rx2ChannelParams_t param );
-
-/*!
- * Sets channels tx output power
- *
- * \param [IN] txPower [TX_POWER_20_DBM, TX_POWER_14_DBM,
- TX_POWER_11_DBM, TX_POWER_08_DBM,
- TX_POWER_05_DBM, TX_POWER_02_DBM]
- */
-void LoRaMacSetChannelsTxPower( int8_t txPower );
+LoRaMacStatus_t LoRaMacMibSetRequestConfirm( MibRequestConfirm_t *mibSet );
/*!
- * Sets channels datarate
+ * \brief LoRaMAC MLME-Request
+ *
+ * \details The Mac layer management entity handles management services. The
+ * following code-snippet shows how to use the API to perform a
+ * network join request.
+ *
+ * \code
+ * 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
+ * };
*
- * \param [IN] datarate eu868 - [DR_0, DR_1, DR_2, DR_3, DR_4, DR_5, DR_6, DR_7]
- * us915 - [DR_0, DR_1, DR_2, DR_3, DR_4]
- */
-void LoRaMacSetChannelsDatarate( int8_t datarate );
-
-/*
- * TODO: Add documentation
- */
-void LoRaMacSetChannelsMask( uint16_t *mask );
-
-/*
- * TODO: Add documentation
- */
-void LoRaMacSetChannelsNbRep( uint8_t nbRep );
-
-/*
- * TODO: Add documentation
- */
-void LoRaMacSetMaxRxWindow( uint32_t delay );
-
-/*
- * TODO: Add documentation
+ * 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
+ * }
+ * \endcode
+ *
+ * \param [IN] mlmeRequest - MLME-Request to perform. Refer to \ref MlmeReq_t.
+ *
+ * \retval LoRaMacStatus_t Status of the operation. Possible returns are:
+ * \ref LORAMAC_STATUS_OK,
+ * \ref LORAMAC_STATUS_BUSY,
+ * \ref LORAMAC_STATUS_SERVICE_UNKNOWN,
+ * \ref LORAMAC_STATUS_PARAMETER_INVALID,
+ * \ref LORAMAC_STATUS_NO_NETWORK_JOINED,
+ * \ref LORAMAC_STATUS_LENGTH_ERROR,
+ * \ref LORAMAC_STATUS_DEVICE_OFF.
*/
-void LoRaMacSetReceiveDelay1( uint32_t delay );
-
-/*
- * TODO: Add documentation
- */
-void LoRaMacSetReceiveDelay2( uint32_t delay );
-
-/*
- * TODO: Add documentation
- */
-void LoRaMacSetJoinAcceptDelay1( uint32_t delay );
-
-/*
- * TODO: Add documentation
- */
-void LoRaMacSetJoinAcceptDelay2( uint32_t delay );
-
-/*
- * TODO: Add documentation
- */
-uint32_t LoRaMacGetUpLinkCounter( void );
-
-/*
- * TODO: Add documentation
- */
-uint32_t LoRaMacGetDownLinkCounter( void );
-
-/*
- * ============================================================================
- * = LoRaMac test functions =
- * ============================================================================
- */
+LoRaMacStatus_t LoRaMacMlmeRequest( MlmeReq_t *mlmeRequest );
/*!
- * Disables/Enables the duty cycle enforcement (EU868)
+ * \brief LoRaMAC MCPS-Request
+ *
+ * \details The Mac Common Part Sublayer handles data services. The following
+ * code-snippet shows how to use the API to send an unconfirmed
+ * LoRaMAC frame.
*
- * \param [IN] enable - Enabled or disables the duty cycle
- */
-void LoRaMacTestSetDutyCycleOn( bool enable );
-
-/*!
- * Disables/Enables the reception windows opening
+ * \code
+ * 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 );
*
- * \param [IN] enable [true: enable, false: disable]
+ * if( LoRaMacMcpsRequest( &mcpsReq ) == LORAMAC_STATUS_OK )
+ * {
+ * // Service started successfully. Waiting for the MCPS-Confirm event
+ * }
+ * \endcode
+ *
+ * \param [IN] mcpsRequest - MCPS-Request to perform. Refer to \ref McpsReq_t.
+ *
+ * \retval LoRaMacStatus_t Status of the operation. Possible returns are:
+ * \ref LORAMAC_STATUS_OK,
+ * \ref LORAMAC_STATUS_BUSY,
+ * \ref LORAMAC_STATUS_SERVICE_UNKNOWN,
+ * \ref LORAMAC_STATUS_PARAMETER_INVALID,
+ * \ref LORAMAC_STATUS_NO_NETWORK_JOINED,
+ * \ref LORAMAC_STATUS_LENGTH_ERROR,
+ * \ref LORAMAC_STATUS_DEVICE_OFF.
*/
-void LoRaMacTestRxWindowsOn( bool enable );
+LoRaMacStatus_t LoRaMacMcpsRequest( McpsReq_t *mcpsRequest );
-/*!
- * Enables the MIC field test
- *
- * \param [IN] upLinkCounter Fixed Tx packet counter value
- */
-void LoRaMacTestSetMic( uint16_t upLinkCounter );
+/*! \} defgroup LORAMAC */
#endif // __LORAMAC_H__