ChannelPlan_KR920.h

00001 /**   __  ___     ____  _    ______        __     ____         __                  ____
00002  *   /  |/  /_ __/ / /_(_)__/_  __/__ ____/ /    / __/_ _____ / /____ __ _  ___   /  _/__  ____
00003  *  / /|_/ / // / / __/ /___// / / -_) __/ _ \  _\ \/ // (_-</ __/ -_)  ' \(_-<  _/ // _ \/ __/ __
00004  * /_/  /_/\_,_/_/\__/_/    /_/  \__/\__/_//_/ /___/\_, /___/\__/\__/_/_/_/___/ /___/_//_/\__/ /_/
00005  * Copyright (C) 2015 by Multi-Tech Systems        /___/
00006  *
00007  *
00008  * @author Jason Reiss
00009  * @date   10-31-2015
00010  * @brief  lora::ChannelPlan provides an interface for LoRaWAN channel schemes
00011  *
00012  * @details
00013  *
00014  */
00015 
00016 #ifndef __CHANNEL_PLAN_KR920_H__
00017 #define __CHANNEL_PLAN_KR920_H__
00018 
00019 #include "Lora.h"
00020 #include "SxRadio.h"
00021 #include <vector>
00022 #include "ChannelPlan.h"
00023 
00024 namespace lora {
00025 
00026     const uint8_t  KR920_125K_NUM_CHANS = 16;        //!< Number of 125k channels in KR920 channel plan
00027     const uint8_t  KR920_DEFAULT_NUM_CHANS = 3;      //!< Number of default channels in KR920 channel plan
00028     const uint32_t KR920_125K_FREQ_BASE = 922100000; //!< Frequency base for 125k KR920 uplink channels
00029     const uint32_t KR920_125K_FREQ_STEP = 200000;    //!< Frequency step for 125k KR920 uplink channels
00030     const uint32_t KR920_RX2_FREQ = 921900000;       //!< Frequency default for second rx window in KR920
00031     const uint8_t  KR920_TX_POWER_MAX = 14;          //!< Max power for KR920 channel plan
00032     const uint8_t  KR920_BEACON_DR = DR_3;           //!< Default beacon datarate
00033     const uint32_t KR920_BEACON_FREQ = 923100000U;   //!< Default beacon broadcast frequency
00034 
00035     class ChannelPlan_KR920 : public lora::ChannelPlan {
00036         public:
00037             /**
00038              * ChannelPlan constructor
00039              * @param radio SxRadio object used to set Tx/Rx config
00040              * @param settings Settings object
00041              */
00042             ChannelPlan_KR920();
00043             ChannelPlan_KR920(Settings* settings);
00044             ChannelPlan_KR920(SxRadio* radio, Settings* settings);
00045 
00046             /**
00047              * ChannelPlan destructor
00048              */
00049             virtual ~ChannelPlan_KR920();
00050 
00051             /**
00052              * Initialize channels, datarates and duty cycle bands according to current channel plan in settings
00053              */
00054             virtual void Init();
00055 
00056             /**
00057              * Get the next channel to use to transmit
00058              * @return LORA_OK if channel was found
00059              * @return LORA_NO_CHANS_ENABLED
00060              */
00061             virtual uint8_t GetNextChannel();
00062 
00063             /**
00064              * Add a channel to the ChannelPlan
00065              * @param index of channel, use -1 to add to end
00066              * @param channel settings to add
00067              */
00068             virtual uint8_t AddChannel(int8_t index, Channel channel);
00069 
00070             /**
00071              * Get channel at index
00072              * @return Channel
00073              */
00074             virtual Channel GetChannel(int8_t index);
00075 
00076             /**
00077              * Get rx window settings for requested window
00078              * RX_1, RX_2, RX_BEACON, RX_SLOT
00079              * @param window
00080              * @return RxWindow
00081              */
00082             virtual RxWindow GetRxWindow(uint8_t window);
00083 
00084             /**
00085              * Get datarate to use on the join request
00086              * @return datarate index
00087              */
00088             virtual uint8_t GetJoinDatarate();
00089 
00090             /**
00091              * Calculate the next time a join request is possible
00092              * @param size of join frame
00093              * @returns LORA_OK
00094              */
00095             virtual uint8_t CalculateJoinBackoff(uint8_t size);
00096 
00097             /**
00098              * Get next channel and set the SxRadio tx config with current settings
00099              * @return LORA_OK
00100              */
00101             virtual uint8_t SetTxConfig();
00102 
00103             /**
00104              * Set the SxRadio rx config provided window
00105              * @param window to be opened
00106              * @param continuous keep window open
00107              * @param wnd_growth factor to increase the rx window by
00108              * @param pad_ms time in milliseconds to add to computed window size
00109              * @return LORA_OK
00110              */
00111             virtual uint8_t SetRxConfig(uint8_t window,
00112                                         bool continuous,
00113                                         uint16_t wnd_growth,
00114                                         uint16_t pad_ms);
00115 
00116             /**
00117              * Set frequency sub band if supported by plan
00118              * @param sub_band
00119              * @return LORA_OK
00120              */
00121             virtual uint8_t SetFrequencySubBand(uint8_t sub_band);
00122 
00123             /**
00124              * Callback for ACK timeout event
00125              * @return LORA_OK
00126              */
00127             virtual uint8_t HandleAckTimeout();
00128 
00129             /**
00130              * Callback for Join Accept packet to load optional channels
00131              * @return LORA_OK
00132              */
00133             virtual uint8_t HandleJoinAccept(const uint8_t* buffer, uint8_t size);
00134 
00135             /**
00136              * Callback to for rx parameter setup ServerCommand
00137              * @param payload packet data
00138              * @param index of start of command buffer
00139              * @param size number of bytes in command buffer
00140              * @param[out] status to be returned in MoteCommand answer
00141              * @return LORA_OK
00142              */
00143             virtual uint8_t HandleRxParamSetup(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00144 
00145             /**
00146              * Callback to for new channel ServerCommand
00147              * @param payload packet data
00148              * @param index of start of command buffer
00149              * @param size number of bytes in command buffer
00150              * @param[out] status to be returned in MoteCommand answer
00151              * @return LORA_OK
00152              */
00153             virtual uint8_t HandleNewChannel(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00154 
00155             /**
00156              * Callback to for ping slot channel request ServerCommand
00157              * @param payload packet data
00158              * @param index of start of command buffer
00159              * @param size number of bytes in command buffer
00160              * @param[out] status to be returned in MoteCommand answer
00161              * @return LORA_OK
00162              */
00163             virtual uint8_t HandlePingSlotChannelReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00164 
00165             /**
00166              * Callback to for beacon frequency request ServerCommand
00167              * @param payload packet data
00168              * @param index of start of command buffer
00169              * @param size number of bytes in command buffer
00170              * @param[out] status to be returned in MoteCommand answer
00171              * @return LORA_OK
00172              */
00173             virtual uint8_t HandleBeaconFrequencyReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00174 
00175             /**
00176              * Callback to for adaptive datarate ServerCommand
00177              * @param payload packet data
00178              * @param index of start of command buffer
00179              * @param size number of bytes in command buffer
00180              * @param[out] status to be returned in MoteCommand answer
00181              * @return LORA_OK
00182              */
00183             virtual uint8_t HandleAdrCommand(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00184 
00185             /**
00186              * Validate the configuration after multiple ADR commands have been applied
00187              * @return status to be returned in MoteCommand answer
00188              */
00189             virtual uint8_t ValidateAdrConfiguration();
00190 
00191             /**
00192              * Update duty cycle with at given frequency and time on air
00193              * @param freq frequency
00194              * @param time_on_air_ms tx time on air
00195              */
00196             virtual void UpdateDutyCycle(uint32_t freq, uint32_t time_on_air_ms);
00197 
00198             /**
00199              * Get the time the radio must be off air to comply with regulations
00200              * Time to wait may be dependent on duty-cycle restrictions per channel
00201              * Or duty-cycle of join requests if OTAA is being attempted
00202              * @return ms of time to wait for next tx opportunity
00203              */
00204             virtual uint32_t GetTimeOffAir();
00205 
00206             /**
00207              * Get the channels in use by current channel plan
00208              * @return channel frequencies
00209              */
00210             virtual std::vector<uint32_t> GetChannels();
00211 
00212             /**
00213              * Get the channel datarate ranges in use by current channel plan
00214              * @return channel datarate ranges
00215              */
00216             virtual std::vector<uint8_t> GetChannelRanges();
00217 
00218             /**
00219              * Print log message for given rx window
00220              * @param wnd 1 or 2
00221              */
00222             virtual void LogRxWindow(uint8_t wnd);
00223 
00224             /**
00225              * Enable the default channels of the channel plan
00226              */
00227             virtual void EnableDefaultChannels();
00228 
00229             /**
00230              * Called when MAC layer doesn't know about a command.
00231              * Use to add custom or new mac command handling
00232              * @return LORA_OK
00233              */
00234             virtual uint8_t HandleMacCommand(uint8_t* payload, uint8_t& index);
00235 
00236             /**
00237              * Set LBT time and threshold to defaults
00238              */
00239             virtual void DefaultLBT();
00240 
00241             /**
00242              * Check if this packet is a beacon and if so extract parameters needed
00243              * @param payload of potential beacon
00244              * @param size of the packet
00245              * @param [out] data extracted from the beacon if this packet was indeed a beacon
00246              * @return true if this packet is beacon, false if not
00247              */
00248             virtual bool DecodeBeacon(const uint8_t* payload,
00249                                       size_t size,
00250                                       BeaconData_t& data);
00251 
00252         protected:
00253 
00254             static const uint8_t KR920_TX_POWERS[8];                    //!< List of available tx powers
00255             static const uint8_t KR920_RADIO_POWERS[21];                 //!< List of calibrated tx powers
00256             static const uint8_t KR920_MAX_PAYLOAD_SIZE[];              //!< List of max payload sizes for each datarate
00257             static const uint8_t KR920_MAX_PAYLOAD_SIZE_REPEATER[];     //!< List of repeater compatible max payload sizes for each datarate
00258 
00259             typedef struct __attribute__((packed)) {
00260                 uint8_t RFU[2];
00261                 uint8_t Time[4];
00262                 uint8_t CRC1[2];
00263                 uint8_t GwSpecific[7];
00264                 uint8_t CRC2[2];
00265             } BCNPayload;
00266     };
00267 }
00268 
00269 #endif //__CHANNEL_PLAN_KR920_H__