LoRaMac.h

Go to the documentation of this file.

 
#ifndef __LORAMAC_H__
#define __LORAMAC_H__
 
#ifdef __cplusplus
extern "C"
{
#endif
 
#include <stdint.h>
#include <stdbool.h>
 
#include "timer.h"
#include "systime.h"
#include "LoRaMacTypes.h"
 
#include "RegionNvm.h"
#include "LoRaMacCryptoNvm.h"
#include "secure-element-nvm.h"
#include "LoRaMacClassBNvm.h"
 
#define MAX_ACK_RETRIES                             8
 
#define UP_LINK                                     0
 
#define DOWN_LINK                                   1
 
#define LORA_MAC_MLME_CONFIRM_QUEUE_LEN             5
 
#define LORAMAC_CRYPTO_MULTICAST_KEYS               127
 
#define LORA_MAC_COMMAND_MAX_LENGTH                 128
 
 
#define LORAMAC_NVM_NOTIFY_FLAG_NONE                0x00
 
#define LORAMAC_NVM_NOTIFY_FLAG_CRYPTO              0x01
 
#define LORAMAC_NVM_NOTIFY_FLAG_MAC_GROUP1          0x02
 
#define LORAMAC_NVM_NOTIFY_FLAG_MAC_GROUP2          0x04
 
#define LORAMAC_NVM_NOTIFY_FLAG_SECURE_ELEMENT      0x08
 
#define LORAMAC_NVM_NOTIFY_FLAG_REGION_GROUP1       0x10
 
#define LORAMAC_NVM_NOTIFY_FLAG_REGION_GROUP2       0x20
 
#define LORAMAC_NVM_NOTIFY_FLAG_CLASS_B             0x40
 
typedef enum eActivationType
{
    ACTIVATION_TYPE_NONE = 0,
    ACTIVATION_TYPE_ABP = 1,
    ACTIVATION_TYPE_OTAA = 2,
}ActivationType_t;
 
typedef struct sRxChannelParams
{
    uint32_t Frequency;
    uint8_t  Datarate;
}RxChannelParams_t;
 
typedef enum eLoRaMacRxSlot
{
    RX_SLOT_WIN_1,
    RX_SLOT_WIN_2,
    RX_SLOT_WIN_CLASS_C,
    RX_SLOT_WIN_CLASS_C_MULTICAST,
    RX_SLOT_WIN_CLASS_B_PING_SLOT,
    RX_SLOT_WIN_CLASS_B_MULTICAST_SLOT,
    RX_SLOT_NONE,
}LoRaMacRxSlot_t;
 
typedef struct sLoRaMacParams
{
    uint32_t SystemMaxRxError;
    uint8_t MinRxSymbols;
    uint32_t MaxRxWindow;
    uint32_t ReceiveDelay1;
    uint32_t ReceiveDelay2;
    uint32_t JoinAcceptDelay1;
    uint32_t JoinAcceptDelay2;
    uint8_t ChannelsNbTrans;
    uint8_t Rx1DrOffset;
    RxChannelParams_t Rx2Channel;
    RxChannelParams_t RxCChannel;
    uint8_t UplinkDwellTime;
    uint8_t DownlinkDwellTime;
    float MaxEirp;
    float AntennaGain;
}LoRaMacParams_t;
 
typedef union uPingSlotInfo
{
    uint8_t Value;
    struct sInfoFields
    {
        uint8_t Periodicity     : 3;
        uint8_t RFU             : 5;
    }Fields;
}PingSlotInfo_t;
 
typedef struct sBeaconInfo
{
    SysTime_t Time;
    uint32_t Frequency;
    uint8_t Datarate;
    int16_t Rssi;
    int8_t Snr;
    struct sGwSpecific
    {
        uint8_t InfoDesc;
        uint8_t Info[6];
    }GwSpecific;
}BeaconInfo_t;
 
typedef 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,
    LORAMAC_EVENT_INFO_STATUS_MULTICAST_FAIL,
    LORAMAC_EVENT_INFO_STATUS_BEACON_LOCKED,
    LORAMAC_EVENT_INFO_STATUS_BEACON_LOST,
    LORAMAC_EVENT_INFO_STATUS_BEACON_NOT_FOUND,
}LoRaMacEventInfoStatus_t;
 
typedef union eLoRaMacFlags_t
{
    uint8_t Value;
    struct sMacFlagBits
    {
        uint8_t McpsReq                 : 1;
        uint8_t McpsInd                 : 1;
        uint8_t MlmeReq                 : 1;
        uint8_t MlmeInd                 : 1;
        uint8_t MlmeSchedUplinkInd      : 1;
        uint8_t MacDone                 : 1;
    }Bits;
}LoRaMacFlags_t;
 
typedef enum eLoRaMacRegion
{
    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_RU864,
}LoRaMacRegion_t;
 
typedef struct sLoRaMacNvmDataGroup1
{
    uint32_t AdrAckCounter;
    TimerTime_t LastTxDoneTime;
    TimerTime_t AggregatedTimeOff;
    uint32_t LastRxMic;
    int8_t ChannelsTxPower;
    int8_t ChannelsDatarate;
    bool SrvAckRequested;
    uint32_t Crc32;
}LoRaMacNvmDataGroup1_t;
 
typedef struct sLoRaMacNvmDataGroup2
{
    LoRaMacRegion_t Region;
    LoRaMacParams_t MacParams;
    LoRaMacParams_t MacParamsDefaults;
    int8_t ChannelsTxPowerDefault;
    int8_t ChannelsDatarateDefault;
    uint32_t NetID;
    uint32_t DevAddr;
    MulticastCtx_t MulticastChannelList[LORAMAC_MAX_MC_CTX];
    DeviceClass_t DeviceClass;
    bool PublicNetwork;
    /*
     * LoRaMac ADR control status
     */
    bool AdrCtrlOn;
    uint8_t MaxDCycle;
    bool DutyCycleOn;
    uint16_t AggregatedDCycle;
    SysTime_t InitializationTime;
    Version_t Version;
    ActivationType_t NetworkActivation;
    uint32_t Crc32;
}LoRaMacNvmDataGroup2_t;
 
typedef struct sLoRaMacNvmData
{
    LoRaMacCryptoNvmData_t Crypto;
    LoRaMacNvmDataGroup1_t MacGroup1;
    LoRaMacNvmDataGroup2_t MacGroup2;
    SecureElementNvmData_t SecureElement;
    RegionNvmDataGroup1_t RegionGroup1;
    RegionNvmDataGroup2_t RegionGroup2;
    LoRaMacClassBNvmData_t ClassB;
}LoRaMacNvmData_t;
 
typedef enum eMcps
{
    MCPS_UNCONFIRMED,
    MCPS_CONFIRMED,
    MCPS_MULTICAST,
    MCPS_PROPRIETARY,
}Mcps_t;
 
typedef struct sRequestReturnParam
{
    TimerTime_t DutyCycleWaitTime;
}RequestReturnParam_t;
 
typedef struct sMcpsReqUnconfirmed
{
    uint8_t fPort;
    void* fBuffer;
    uint16_t fBufferSize;
    int8_t Datarate;
}McpsReqUnconfirmed_t;
 
typedef struct sMcpsReqConfirmed
{
    uint8_t fPort;
    void* fBuffer;
    uint16_t fBufferSize;
    int8_t Datarate;
    uint8_t NbTrials;
}McpsReqConfirmed_t;
 
typedef struct sMcpsReqProprietary
{
    void* fBuffer;
    uint16_t fBufferSize;
    int8_t Datarate;
}McpsReqProprietary_t;
 
typedef struct sMcpsReq
{
    Mcps_t Type;
 
    union uMcpsParam
    {
        McpsReqUnconfirmed_t Unconfirmed;
        McpsReqConfirmed_t Confirmed;
        McpsReqProprietary_t Proprietary;
    }Req;
 
    RequestReturnParam_t ReqReturn;
}McpsReq_t;
 
typedef struct sMcpsConfirm
{
    Mcps_t McpsRequest;
    LoRaMacEventInfoStatus_t Status;
    uint8_t Datarate;
    int8_t TxPower;
    bool AckReceived;
    uint8_t NbRetries;
    TimerTime_t TxTimeOnAir;
    uint32_t UpLinkCounter;
    uint32_t Channel;
}McpsConfirm_t;
 
typedef struct sMcpsIndication
{
    Mcps_t McpsIndication;
    LoRaMacEventInfoStatus_t Status;
    uint8_t Multicast;
    uint8_t Port;
    uint8_t RxDatarate;
    uint8_t FramePending;
    uint8_t* Buffer;
    uint8_t BufferSize;
    bool RxData;
    int16_t Rssi;
    int8_t Snr;
    LoRaMacRxSlot_t RxSlot;
    bool AckReceived;
    uint32_t DownLinkCounter;
    uint32_t DevAddress;
    bool DeviceTimeAnsReceived;
}McpsIndication_t;
 
typedef enum eMlme
{
    MLME_UNKNOWN,
    MLME_JOIN,
    MLME_REJOIN_0,
    MLME_REJOIN_1,
    MLME_LINK_CHECK,
    MLME_TXCW,
    MLME_TXCW_1,
    MLME_SCHEDULE_UPLINK,
    MLME_DERIVE_MC_KE_KEY,
    MLME_DERIVE_MC_KEY_PAIR,
    MLME_DEVICE_TIME,
    MLME_BEACON,
    MLME_BEACON_ACQUISITION,
    MLME_PING_SLOT_INFO,
    MLME_BEACON_TIMING,
    MLME_BEACON_LOST,
}Mlme_t;
 
typedef struct sMlmeReqJoin
{
    uint8_t Datarate;
}MlmeReqJoin_t;
 
typedef struct sMlmeReqTxCw
{
    uint16_t Timeout;
    uint32_t Frequency;
    int8_t Power;
}MlmeReqTxCw_t;
 
typedef struct sMlmeReqPingSlotInfo
{
    PingSlotInfo_t PingSlot;
}MlmeReqPingSlotInfo_t;
 
typedef struct sMlmeReqDeriveMcKEKey
{
    KeyIdentifier_t KeyID;
    uint16_t Nonce;
    uint8_t* DevEUI;
}MlmeReqDeriveMcKEKey_t;
 
typedef struct sMlmeReqDeriveMcSessionKeyPair
{
    AddressIdentifier_t GroupID;
}MlmeReqDeriveMcSessionKeyPair_t;
 
typedef struct sMlmeReq
{
    Mlme_t Type;
 
    union uMlmeParam
    {
        MlmeReqJoin_t Join;
        MlmeReqTxCw_t TxCw;
        MlmeReqPingSlotInfo_t PingSlotInfo;
        MlmeReqDeriveMcKEKey_t DeriveMcKEKey;
        MlmeReqDeriveMcSessionKeyPair_t DeriveMcSessionKeyPair;
    }Req;
 
    RequestReturnParam_t ReqReturn;
}MlmeReq_t;
 
typedef struct sMlmeConfirm
{
    Mlme_t MlmeRequest;
    LoRaMacEventInfoStatus_t Status;
    TimerTime_t TxTimeOnAir;
    uint8_t DemodMargin;
    uint8_t NbGateways;
    uint8_t NbRetries;
    TimerTime_t BeaconTimingDelay;
    uint8_t BeaconTimingChannel;
}MlmeConfirm_t;
 
typedef struct sMlmeIndication
{
    Mlme_t MlmeIndication;
    LoRaMacEventInfoStatus_t Status;
    BeaconInfo_t BeaconInfo;
}MlmeIndication_t;
 
typedef enum eMib
{
    MIB_DEVICE_CLASS,
    MIB_NETWORK_ACTIVATION,
    MIB_DEV_EUI,
    MIB_JOIN_EUI,
    MIB_SE_PIN,
    MIB_ADR,
    MIB_NET_ID,
    MIB_DEV_ADDR,
    MIB_APP_KEY,
    MIB_NWK_KEY,
    MIB_J_S_INT_KEY,
    MIB_J_S_ENC_KEY,
    MIB_F_NWK_S_INT_KEY,
    MIB_S_NWK_S_INT_KEY,
    MIB_NWK_S_ENC_KEY,
    MIB_APP_S_KEY,
    MIB_MC_KE_KEY,
    MIB_MC_KEY_0,
    MIB_MC_APP_S_KEY_0,
    MIB_MC_NWK_S_KEY_0,
    MIB_MC_KEY_1,
    MIB_MC_APP_S_KEY_1,
    MIB_MC_NWK_S_KEY_1,
    MIB_MC_KEY_2,
    MIB_MC_APP_S_KEY_2,
    MIB_MC_NWK_S_KEY_2,
    MIB_MC_KEY_3,
    MIB_MC_APP_S_KEY_3,
    MIB_MC_NWK_S_KEY_3,
    MIB_PUBLIC_NETWORK,
    MIB_CHANNELS,
    MIB_RX2_CHANNEL,
    MIB_RX2_DEFAULT_CHANNEL,
    MIB_RXC_CHANNEL,
    MIB_RXC_DEFAULT_CHANNEL,
    MIB_CHANNELS_MASK,
    MIB_CHANNELS_DEFAULT_MASK,
    MIB_CHANNELS_NB_TRANS,
    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_SYSTEM_MAX_RX_ERROR,
    MIB_MIN_RX_SYMBOLS,
    MIB_ANTENNA_GAIN,
    MIB_DEFAULT_ANTENNA_GAIN,
    MIB_NVM_CTXS,
    MIB_ABP_LORAWAN_VERSION,
    MIB_LORAWAN_VERSION,
    MIB_BEACON_INTERVAL,
    MIB_BEACON_RESERVED,
    MIB_BEACON_GUARD,
    MIB_BEACON_WINDOW,
    MIB_BEACON_WINDOW_SLOTS,
    MIB_PING_SLOT_WINDOW,
    MIB_BEACON_SYMBOL_TO_DEFAULT,
    MIB_BEACON_SYMBOL_TO_EXPANSION_MAX,
    MIB_PING_SLOT_SYMBOL_TO_EXPANSION_MAX,
    MIB_BEACON_SYMBOL_TO_EXPANSION_FACTOR,
    MIB_PING_SLOT_SYMBOL_TO_EXPANSION_FACTOR,
    MIB_MAX_BEACON_LESS_PERIOD,
     MIB_PING_SLOT_DATARATE,
}Mib_t;
 
typedef union uMibParam
{
    DeviceClass_t Class;
    ActivationType_t NetworkActivation;
    uint8_t* DevEui;
    uint8_t* JoinEui;
    uint8_t* SePin;
    bool AdrEnable;
    uint32_t NetID;
    uint32_t DevAddr;
    uint8_t* AppKey;
    uint8_t* NwkKey;
    uint8_t* JSIntKey;
    uint8_t* JSEncKey;
    uint8_t* FNwkSIntKey;
    uint8_t* SNwkSIntKey;
    uint8_t* NwkSEncKey;
    uint8_t* AppSKey;
    uint8_t* McKEKey;
    uint8_t* McKey0;
    uint8_t* McAppSKey0;
    uint8_t* McNwkSKey0;
    uint8_t* McKey1;
    uint8_t* McAppSKey1;
    uint8_t* McNwkSKey1;
    uint8_t* McKey2;
    uint8_t* McAppSKey2;
    uint8_t* McNwkSKey2;
    uint8_t* McKey3;
    uint8_t* McAppSKey3;
    uint8_t* McNwkSKey3;
    bool EnablePublicNetwork;
    ChannelParams_t* ChannelList;
    RxChannelParams_t Rx2Channel;
    RxChannelParams_t Rx2DefaultChannel;
    RxChannelParams_t RxCChannel;
    RxChannelParams_t RxCDefaultChannel;
    uint16_t* ChannelsMask;
    uint16_t* ChannelsDefaultMask;
    uint8_t ChannelsNbTrans;
    uint32_t MaxRxWindow;
    uint32_t ReceiveDelay1;
    uint32_t ReceiveDelay2;
    uint32_t JoinAcceptDelay1;
    uint32_t JoinAcceptDelay2;
    int8_t ChannelsDefaultDatarate;
    int8_t ChannelsDatarate;
    int8_t ChannelsDefaultTxPower;
    int8_t ChannelsTxPower;
    McChannelParams_t MulticastChannel;
    uint32_t SystemMaxRxError;
    uint8_t MinRxSymbols;
    float AntennaGain;
    float DefaultAntennaGain;
    LoRaMacNvmData_t* Contexts;
    /*
     * LoRaWAN MAC layer operating version when activated by ABP.
     *
     * Related MIB type: \ref MIB_ABP_LORAWAN_VERSION
     */
    Version_t AbpLrWanVersion;
    /*
     * LoRaWAN MAC regional parameter version.
     *
     * Related MIB type: \ref MIB_LORAWAN_VERSION
     */
    struct sLrWanVersion
    {
        Version_t LoRaWan;
        Version_t LoRaWanRegion;
    }LrWanVersion;
    uint32_t BeaconInterval;
    uint32_t BeaconReserved;
    uint32_t BeaconGuard;
    uint32_t BeaconWindow;
    uint32_t BeaconWindowSlots;
    uint32_t PingSlotWindow;
    uint32_t BeaconSymbolToDefault;
    uint32_t BeaconSymbolToExpansionMax;
    uint32_t PingSlotSymbolToExpansionMax;
    uint32_t BeaconSymbolToExpansionFactor;
    uint32_t PingSlotSymbolToExpansionFactor;
    uint32_t MaxBeaconLessPeriod;
    int8_t PingSlotDatarate;
}MibParam_t;
 
typedef struct eMibRequestConfirm
{
    Mib_t Type;
 
    MibParam_t Param;
}MibRequestConfirm_t;
 
typedef struct sLoRaMacTxInfo
{
    uint8_t MaxPossibleApplicationDataSize;
    uint8_t CurrentPossiblePayloadSize;
}LoRaMacTxInfo_t;
 
typedef 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_REGION_NOT_SUPPORTED,
    LORAMAC_STATUS_SKIPPED_APP_DATA,
    LORAMAC_STATUS_DUTYCYCLE_RESTRICTED,
    LORAMAC_STATUS_NO_CHANNEL_FOUND,
    LORAMAC_STATUS_NO_FREE_CHANNEL_FOUND,
    LORAMAC_STATUS_BUSY_BEACON_RESERVED_TIME,
    LORAMAC_STATUS_BUSY_PING_SLOT_WINDOW_TIME,
    LORAMAC_STATUS_BUSY_UPLINK_COLLISION,
    LORAMAC_STATUS_CRYPTO_ERROR,
    LORAMAC_STATUS_FCNT_HANDLER_ERROR,
    LORAMAC_STATUS_MAC_COMMAD_ERROR,
    LORAMAC_STATUS_CLASS_B_ERROR,
    LORAMAC_STATUS_CONFIRM_QUEUE_ERROR,
    LORAMAC_STATUS_MC_GROUP_UNDEFINED,
    LORAMAC_STATUS_ERROR
}LoRaMacStatus_t;
 
typedef struct sLoRaMacPrimitives
{
    void ( *MacMcpsConfirm )( McpsConfirm_t* McpsConfirm );
    void ( *MacMcpsIndication )( McpsIndication_t* McpsIndication );
    void ( *MacMlmeConfirm )( MlmeConfirm_t* MlmeConfirm );
    void ( *MacMlmeIndication )( MlmeIndication_t* MlmeIndication );
}LoRaMacPrimitives_t;
 
typedef struct sLoRaMacCallback
{
    uint8_t ( *GetBatteryLevel )( void );
    float ( *GetTemperatureLevel )( void );
    void ( *NvmDataChange )( uint16_t notifyFlags );
    void ( *MacProcessNotify )( void );
}LoRaMacCallback_t;
 
 
static const uint8_t LoRaMacMaxEirpTable[] = { 8, 10, 12, 13, 14, 16, 18, 20, 21, 24, 26, 27, 29, 30, 33, 36 };
 
LoRaMacStatus_t LoRaMacInitialization( LoRaMacPrimitives_t* primitives, LoRaMacCallback_t* callbacks, LoRaMacRegion_t region );
 
LoRaMacStatus_t LoRaMacStart( void );
 
LoRaMacStatus_t LoRaMacStop( void );
 
bool LoRaMacIsBusy( void );
 
void LoRaMacProcess( void );
 
LoRaMacStatus_t LoRaMacQueryTxPossible( uint8_t size, LoRaMacTxInfo_t* txInfo );
 
LoRaMacStatus_t LoRaMacChannelAdd( uint8_t id, ChannelParams_t params );
 
LoRaMacStatus_t LoRaMacChannelRemove( uint8_t id );
 
LoRaMacStatus_t LoRaMacMcChannelSetup( McChannelParams_t *channel );
 
LoRaMacStatus_t LoRaMacMcChannelDelete( AddressIdentifier_t groupID );
 
uint8_t LoRaMacMcChannelGetGroupId( uint32_t mcAddress );
 
LoRaMacStatus_t LoRaMacMcChannelSetupRxParams( AddressIdentifier_t groupID, McRxParams_t *rxParams, uint8_t *status );
 
LoRaMacStatus_t LoRaMacMibGetRequestConfirm( MibRequestConfirm_t* mibGet );
 
LoRaMacStatus_t LoRaMacMibSetRequestConfirm( MibRequestConfirm_t* mibSet );
 
LoRaMacStatus_t LoRaMacMlmeRequest( MlmeReq_t* mlmeRequest );
 
LoRaMacStatus_t LoRaMacMcpsRequest( McpsReq_t* mcpsRequest );
 
LoRaMacStatus_t LoRaMacDeInitialization( void );
 
#ifdef __cplusplus
}
#endif
 
#endif // __LORAMAC_H__