Region.h

Go to the documentation of this file.

 
#ifndef __REGION_H__
#define __REGION_H__
 
#ifdef __cplusplus
extern "C"
{
#endif
 
#include <stdint.h>
#include <stdbool.h>
#include "utilities.h"
#include "LoRaMac.h"
#include "timer.h"
#include "RegionCommon.h"
 
#define LC( channelIndex )                          ( uint16_t )( 1 << ( channelIndex - 1 ) )
 
#ifndef REGION_VERSION
 
#define REGION_VERSION                              0x00010003
#endif
 
 
 
#define DR_0                                        0
 
#define DR_1                                        1
 
#define DR_2                                        2
 
#define DR_3                                        3
 
#define DR_4                                        4
 
#define DR_5                                        5
 
#define DR_6                                        6
 
#define DR_7                                        7
 
#define DR_8                                        8
 
#define DR_9                                        9
 
#define DR_10                                       10
 
#define DR_11                                       11
 
#define DR_12                                       12
 
#define DR_13                                       13
 
#define DR_14                                       14
 
#define DR_15                                       15
 
 
 
#define TX_POWER_0                                  0
 
#define TX_POWER_1                                  1
 
#define TX_POWER_2                                  2
 
#define TX_POWER_3                                  3
 
#define TX_POWER_4                                  4
 
#define TX_POWER_5                                  5
 
#define TX_POWER_6                                  6
 
#define TX_POWER_7                                  7
 
#define TX_POWER_8                                  8
 
#define TX_POWER_9                                  9
 
#define TX_POWER_10                                 10
 
#define TX_POWER_11                                 11
 
#define TX_POWER_12                                 12
 
#define TX_POWER_13                                 13
 
#define TX_POWER_14                                 14
 
#define TX_POWER_15                                 15
 
 
 
typedef enum ePhyAttribute
{
    PHY_FREQUENCY,
    PHY_MIN_RX_DR,
    PHY_MIN_TX_DR,
    PHY_MAX_RX_DR,
    PHY_MAX_TX_DR,
    PHY_TX_DR,
    PHY_DEF_TX_DR,
    PHY_RX_DR,
    PHY_MAX_TX_POWER,
    PHY_TX_POWER,
    PHY_DEF_TX_POWER,
    PHY_DEF_ADR_ACK_LIMIT,
    PHY_DEF_ADR_ACK_DELAY,
    PHY_MAX_PAYLOAD,
    PHY_DUTY_CYCLE,
    PHY_MAX_RX_WINDOW,
    PHY_RECEIVE_DELAY1,
    PHY_RECEIVE_DELAY2,
    PHY_JOIN_ACCEPT_DELAY1,
    PHY_JOIN_ACCEPT_DELAY2,
    PHY_MAX_FCNT_GAP,
    PHY_ACK_TIMEOUT,
    PHY_DEF_DR1_OFFSET,
    PHY_DEF_RX2_FREQUENCY,
    PHY_DEF_RX2_DR,
    PHY_CHANNELS_MASK,
    PHY_CHANNELS_DEFAULT_MASK,
    PHY_MAX_NB_CHANNELS,
    PHY_CHANNELS,
    PHY_DEF_UPLINK_DWELL_TIME,
    PHY_DEF_DOWNLINK_DWELL_TIME,
    PHY_DEF_MAX_EIRP,
    PHY_DEF_ANTENNA_GAIN,
    PHY_NEXT_LOWER_TX_DR,
    PHY_BEACON_INTERVAL,
    PHY_BEACON_RESERVED,
    PHY_BEACON_GUARD,
    PHY_BEACON_WINDOW,
    PHY_BEACON_WINDOW_SLOTS,
    PHY_PING_SLOT_WINDOW,
    PHY_BEACON_SYMBOL_TO_DEFAULT,
    PHY_BEACON_SYMBOL_TO_EXPANSION_MAX,
    PHY_PING_SLOT_SYMBOL_TO_EXPANSION_MAX,
    PHY_BEACON_SYMBOL_TO_EXPANSION_FACTOR,
    PHY_PING_SLOT_SYMBOL_TO_EXPANSION_FACTOR,
    PHY_MAX_BEACON_LESS_PERIOD,
    PHY_BEACON_DELAY_BEACON_TIMING_ANS,
    PHY_BEACON_CHANNEL_FREQ,
    PHY_BEACON_FORMAT,
    PHY_BEACON_CHANNEL_DR,
    PHY_BEACON_NB_CHANNELS,
    PHY_BEACON_CHANNEL_OFFSET,
    PHY_PING_SLOT_CHANNEL_FREQ,
    PHY_PING_SLOT_CHANNEL_DR,
    PHY_PING_SLOT_NB_CHANNELS,
    PHY_SF_FROM_DR,
    PHY_BW_FROM_DR,
}PhyAttribute_t;
 
typedef enum eInitType
{
    INIT_TYPE_DEFAULTS,
    INIT_TYPE_RESET_TO_DEFAULT_CHANNELS,
    INIT_TYPE_ACTIVATE_DEFAULT_CHANNELS,
    INIT_TYPE_RESTORE_CTX
}InitType_t;
 
typedef enum eChannelsMask
{
    CHANNELS_MASK,
    CHANNELS_DEFAULT_MASK
}ChannelsMask_t;
 
typedef struct sBeaconFormat
{
    uint8_t BeaconSize;
    uint8_t Rfu1Size;
    uint8_t Rfu2Size;
}BeaconFormat_t;
 
typedef union uPhyParam
{
    uint32_t Value;
    float fValue;
    uint16_t* ChannelsMask;
    ChannelParams_t* Channels;
    BeaconFormat_t BeaconFormat;
    TimerTime_t DutyCycleTimePeriod;
}PhyParam_t;
 
typedef struct sGetPhyParams
{
    PhyAttribute_t Attribute;
    int8_t Datarate;
    uint8_t UplinkDwellTime;
    uint8_t DownlinkDwellTime;
    uint8_t Channel;
}GetPhyParams_t;
 
typedef struct sSetBandTxDoneParams
{
    uint8_t Channel;
    bool Joined;
    TimerTime_t LastTxDoneTime;
    TimerTime_t LastTxAirTime;
    SysTime_t ElapsedTimeSinceStartUp;
}SetBandTxDoneParams_t;
 
typedef struct sInitDefaultsParams
{
    void* NvmCtx;
     InitType_t Type;
}InitDefaultsParams_t;
 
typedef struct sGetNvmCtxParams
{
     size_t nvmCtxSize;
}GetNvmCtxParams_t;
 
 
typedef union uVerifyParams
{
    uint32_t Frequency;
    int8_t TxPower;
    bool DutyCycle;
    struct sDatarateParams
    {
        int8_t Datarate;
        uint8_t DownlinkDwellTime;
        uint8_t UplinkDwellTime;
    }DatarateParams;
}VerifyParams_t;
 
typedef struct sApplyCFListParams
{
    uint8_t* Payload;
    uint8_t Size;
}ApplyCFListParams_t;
 
typedef struct sChanMaskSetParams
{
    uint16_t* ChannelsMaskIn;
    ChannelsMask_t ChannelsMaskType;
}ChanMaskSetParams_t;
 
typedef struct sRxConfigParams
{
    uint8_t Channel;
    int8_t Datarate;
    uint8_t Bandwidth;
    int8_t DrOffset;
    uint32_t Frequency;
     uint32_t WindowTimeout;
    int32_t WindowOffset;
    uint8_t DownlinkDwellTime;
    bool RxContinuous;
    LoRaMacRxSlot_t RxSlot;
}RxConfigParams_t;
 
typedef struct sTxConfigParams
{
    uint8_t Channel;
    int8_t Datarate;
    int8_t TxPower;
    float MaxEirp;
    float AntennaGain;
    uint16_t PktLen;
}TxConfigParams_t;
 
typedef struct sLinkAdrReqParams
{
    Version_t Version;
    uint8_t* Payload;
    uint8_t PayloadSize;
    uint8_t UplinkDwellTime;
    bool AdrEnabled;
    int8_t CurrentDatarate;
    int8_t CurrentTxPower;
    uint8_t CurrentNbRep;
}LinkAdrReqParams_t;
 
typedef struct sRxParamSetupReqParams
{
    int8_t Datarate;
    int8_t DrOffset;
    uint32_t Frequency;
}RxParamSetupReqParams_t;
 
typedef struct sNewChannelReqParams
{
    ChannelParams_t* NewChannel;
    int8_t ChannelId;
}NewChannelReqParams_t;
 
typedef struct sTxParamSetupReqParams
{
    uint8_t UplinkDwellTime;
    uint8_t DownlinkDwellTime;
    uint8_t MaxEirp;
}TxParamSetupReqParams_t;
 
typedef struct sDlChannelReqParams
{
    uint8_t ChannelId;
    uint32_t Rx1Frequency;
}DlChannelReqParams_t;
 
typedef enum eAlternateDrType
{
    ALTERNATE_DR,
    ALTERNATE_DR_RESTORE
}AlternateDrType_t;
 
typedef struct sNextChanParams
{
    TimerTime_t AggrTimeOff;
    TimerTime_t LastAggrTx;
    int8_t Datarate;
    bool Joined;
    bool DutyCycleEnabled;
    SysTime_t ElapsedTimeSinceStartUp;
    bool LastTxIsJoinRequest;
    uint16_t PktLen;
}NextChanParams_t;
 
typedef struct sChannelAddParams
{
    ChannelParams_t* NewChannel;
    uint8_t ChannelId;
}ChannelAddParams_t;
 
typedef struct sChannelRemoveParams
{
    uint8_t ChannelId;
}ChannelRemoveParams_t;
 
typedef struct sContinuousWaveParams
{
    uint8_t Channel;
    int8_t Datarate;
    int8_t TxPower;
    float MaxEirp;
    float AntennaGain;
    uint16_t Timeout;
}ContinuousWaveParams_t;
 
typedef struct sRxBeaconSetupParams
{
    uint16_t SymbolTimeout;
    uint32_t RxTime;
    uint32_t Frequency;
}RxBeaconSetup_t;
 
 
 
bool RegionIsActive( LoRaMacRegion_t region );
 
PhyParam_t RegionGetPhyParam( LoRaMacRegion_t region, GetPhyParams_t* getPhy );
 
void RegionSetBandTxDone( LoRaMacRegion_t region, SetBandTxDoneParams_t* txDone );
 
void RegionInitDefaults( LoRaMacRegion_t region, InitDefaultsParams_t* params );
 
void* RegionGetNvmCtx( LoRaMacRegion_t region, GetNvmCtxParams_t* params );
 
bool RegionVerify( LoRaMacRegion_t region, VerifyParams_t* verify, PhyAttribute_t phyAttribute );
 
void RegionApplyCFList( LoRaMacRegion_t region, ApplyCFListParams_t* applyCFList );
 
bool RegionChanMaskSet( LoRaMacRegion_t region, ChanMaskSetParams_t* chanMaskSet );
 
bool RegionRxConfig( LoRaMacRegion_t region, RxConfigParams_t* rxConfig, int8_t* datarate );
 
/*
 * Rx window precise timing
 *
 * For more details please consult the following document, chapter 3.1.2.
 * https://www.semtech.com/uploads/documents/SX1272_settings_for_LoRaWAN_v2.0.pdf
 * or
 * https://www.semtech.com/uploads/documents/SX1276_settings_for_LoRaWAN_v2.0.pdf
 *
 *                 Downlink start: T = Tx + 1s (+/- 20 us)
 *                            |
 *             TRxEarly       |        TRxLate
 *                |           |           |
 *                |           |           +---+---+---+---+---+---+---+---+
 *                |           |           |       Latest Rx window        |
 *                |           |           +---+---+---+---+---+---+---+---+
 *                |           |           |
 *                +---+---+---+---+---+---+---+---+
 *                |       Earliest Rx window      |
 *                +---+---+---+---+---+---+---+---+
 *                            |
 *                            +---+---+---+---+---+---+---+---+
 *Downlink preamble 8 symbols |   |   |   |   |   |   |   |   |
 *                            +---+---+---+---+---+---+---+---+
 *
 *                     Worst case Rx window timings
 *
 * TRxLate  = DEFAULT_MIN_RX_SYMBOLS * tSymbol - RADIO_WAKEUP_TIME
 * TRxEarly = 8 - DEFAULT_MIN_RX_SYMBOLS * tSymbol - RxWindowTimeout - RADIO_WAKEUP_TIME
 *
 * TRxLate - TRxEarly = 2 * DEFAULT_SYSTEM_MAX_RX_ERROR
 *
 * RxOffset = ( TRxLate + TRxEarly ) / 2
 *
 * RxWindowTimeout = ( 2 * DEFAULT_MIN_RX_SYMBOLS - 8 ) * tSymbol + 2 * DEFAULT_SYSTEM_MAX_RX_ERROR
 * RxOffset = 4 * tSymbol - RxWindowTimeout / 2 - RADIO_WAKE_UP_TIME
 *
 * Minimal value of RxWindowTimeout must be 5 symbols which implies that the system always tolerates at least an error of 1.5 * tSymbol
 */
void RegionComputeRxWindowParameters( LoRaMacRegion_t region, int8_t datarate, uint8_t minRxSymbols, uint32_t rxError, RxConfigParams_t *rxConfigParams );
 
bool RegionTxConfig( LoRaMacRegion_t region, TxConfigParams_t* txConfig, int8_t* txPower, TimerTime_t* txTimeOnAir );
 
uint8_t RegionLinkAdrReq( LoRaMacRegion_t region, LinkAdrReqParams_t* linkAdrReq, int8_t* drOut, int8_t* txPowOut, uint8_t* nbRepOut, uint8_t* nbBytesParsed );
 
uint8_t RegionRxParamSetupReq( LoRaMacRegion_t region, RxParamSetupReqParams_t* rxParamSetupReq );
 
uint8_t RegionNewChannelReq( LoRaMacRegion_t region, NewChannelReqParams_t* newChannelReq );
 
int8_t RegionTxParamSetupReq( LoRaMacRegion_t region, TxParamSetupReqParams_t* txParamSetupReq );
 
uint8_t RegionDlChannelReq( LoRaMacRegion_t region, DlChannelReqParams_t* dlChannelReq );
 
int8_t RegionAlternateDr( LoRaMacRegion_t region, int8_t currentDr, AlternateDrType_t type );
 
LoRaMacStatus_t RegionNextChannel( LoRaMacRegion_t region, NextChanParams_t* nextChanParams, uint8_t* channel, TimerTime_t* time, TimerTime_t* aggregatedTimeOff );
 
LoRaMacStatus_t RegionChannelAdd( LoRaMacRegion_t region, ChannelAddParams_t* channelAdd );
 
bool RegionChannelsRemove( LoRaMacRegion_t region, ChannelRemoveParams_t* channelRemove );
 
void RegionSetContinuousWave( LoRaMacRegion_t region, ContinuousWaveParams_t* continuousWave );
 
uint8_t RegionApplyDrOffset( LoRaMacRegion_t region, uint8_t downlinkDwellTime, int8_t dr, int8_t drOffset );
 
void RegionRxBeaconSetup( LoRaMacRegion_t region, RxBeaconSetup_t* rxBeaconSetup, uint8_t* outDr );
 
Version_t RegionGetVersion( void );
 
#ifdef __cplusplus
}
#endif
 
#endif // __REGION_H__