ChannelPlan_US915.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_US915_H__
00017 #define __CHANNEL_PLAN_US915_H__
00018 
00019 #include "Lora.h"
00020 #include "SxRadio.h"
00021 #include "ChannelPlan.h"
00022 #include <vector>
00023 
00024 namespace lora {
00025 
00026     class ChannelPlan_US915 : public lora::ChannelPlan {
00027         public:
00028 
00029             /**
00030              * ChannelPlan constructor
00031              * @param radio SxRadio object used to set Tx/Rx config
00032              * @param settings Settings object
00033              */
00034             ChannelPlan_US915();
00035             ChannelPlan_US915(Settings* settings);
00036             ChannelPlan_US915(SxRadio* radio, Settings* settings);
00037 
00038             /**
00039              * ChannelPlan destructor
00040              */
00041             virtual ~ChannelPlan_US915();
00042 
00043             /**
00044              * Initialize channels, datarates and duty cycle bands according to current channel plan in settings
00045              */
00046             virtual void Init();
00047 
00048             /**
00049              * Get the next channel to use to transmit
00050              * @return LORA_OK if channel was found
00051              * @return LORA_NO_CHANS_ENABLED
00052              */
00053             virtual uint8_t GetNextChannel();
00054 
00055             /**
00056              * Set the number of channels in the plan
00057              */
00058             virtual void SetNumberOfChannels(uint8_t channels, bool resize = true);
00059 
00060             /**
00061              * Check if channel is enabled
00062              * @return true if enabled
00063              */
00064             virtual bool IsChannelEnabled(uint8_t channel);
00065 
00066 
00067             /**
00068              * Add a channel to the ChannelPlan
00069              * @param index of channel, use -1 to add to end
00070              * @param channel settings to add
00071              */
00072             virtual uint8_t AddChannel(int8_t index, Channel channel);
00073 
00074             /**
00075              * Get channel at index
00076              * @return Channel
00077              */
00078             virtual Channel GetChannel(int8_t index);
00079 
00080             /**
00081              * Get rx window settings for requested window
00082              * RX_1, RX_2, RX_BEACON, RX_SLOT
00083              * @param window
00084              * @return RxWindow
00085              */
00086             virtual RxWindow GetRxWindow(uint8_t window);
00087 
00088             /**
00089              * Get datarate to use on the join request
00090              * @return datarate index
00091              */
00092             virtual uint8_t GetJoinDatarate();
00093 
00094             /**
00095              * Calculate the next time a join request is possible
00096              * @param size of join frame
00097              * @returns LORA_OK
00098              */
00099             virtual uint8_t CalculateJoinBackoff(uint8_t size);
00100 
00101             /**
00102              * Set the datarate offset used for first receive window
00103              * @param offset
00104              * @return LORA_OK
00105              */
00106             virtual uint8_t SetRx1Offset(uint8_t offset);
00107 
00108             /**
00109              * Set the frequency for second receive window
00110              * @param freq
00111              * @return LORA_OK
00112              */
00113             virtual uint8_t SetRx2Frequency(uint32_t freq);
00114 
00115             /**
00116              * Set the datarate index used for second receive window
00117              * @param index
00118              * @return LORA_OK
00119              */
00120             virtual uint8_t SetRx2DatarateIndex(uint8_t index);
00121 
00122             /**
00123              * Get next channel and set the SxRadio tx config with current settings
00124              * @return LORA_OK
00125              */
00126             virtual uint8_t SetTxConfig();
00127 
00128             /**
00129              * Set the SxRadio rx config provided window
00130              * @param window to be opened
00131              * @param continuous keep window open
00132              * @return LORA_OK
00133              */
00134             virtual uint8_t SetRxConfig(uint8_t window, bool continuous);
00135 
00136             /**
00137              * Set frequency sub band if supported by plan
00138              * @param sub_band
00139              * @return LORA_OK
00140              */
00141             virtual uint8_t SetFrequencySubBand(uint8_t sub_band);
00142 
00143             /**
00144              * Callback for Join Accept packet to load optional channels
00145              * @return LORA_OK
00146              */
00147             virtual uint8_t HandleJoinAccept(const uint8_t* buffer, uint8_t size);
00148 
00149             /**
00150              * Callback to for rx parameter setup ServerCommand
00151              * @param payload packet data
00152              * @param index of start of command buffer
00153              * @param size number of bytes in command buffer
00154              * @param[out] status to be returned in MoteCommand answer
00155              * @return LORA_OK
00156              */
00157             virtual uint8_t HandleRxParamSetup(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00158 
00159             /**
00160              * Callback to for new channel ServerCommand
00161              * @param payload packet data
00162              * @param index of start of command buffer
00163              * @param size number of bytes in command buffer
00164              * @param[out] status to be returned in MoteCommand answer
00165              * @return LORA_OK
00166              */
00167             virtual uint8_t HandleNewChannel(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00168 
00169             /**
00170              * Callback to for downlink channel request ServerCommand
00171              * @param payload packet data
00172              * @param index of start of command buffer
00173              * @param size number of bytes in command buffer
00174              * @param[out] status to be returned in MoteCommand answer
00175              * @return LORA_OK
00176              */
00177             virtual uint8_t HandleDownlinkChannelReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00178 
00179             /**
00180              * Callback to for ping slot channel request ServerCommand
00181              * @param payload packet data
00182              * @param index of start of command buffer
00183              * @param size number of bytes in command buffer
00184              * @param[out] status to be returned in MoteCommand answer
00185              * @return LORA_OK
00186              */
00187             virtual uint8_t HandlePingSlotChannelReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00188 
00189             /**
00190              * Callback to for beacon frequency request ServerCommand
00191              * @param payload packet data
00192              * @param index of start of command buffer
00193              * @param size number of bytes in command buffer
00194              * @param[out] status to be returned in MoteCommand answer
00195              * @return LORA_OK
00196              */
00197             virtual uint8_t HandleBeaconFrequencyReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00198 
00199             /**
00200              * Callback to for adaptive datarate ServerCommand
00201              * @param payload packet data
00202              * @param index of start of command buffer
00203              * @param size number of bytes in command buffer
00204              * @param[out] status to be returned in MoteCommand answer
00205              * @return LORA_OK
00206              */
00207             virtual uint8_t HandleAdrCommand(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00208 
00209             /**
00210              * Validate the configuration after multiple ADR commands have been applied
00211              * @return status to be returned in MoteCommand answer
00212              */
00213             virtual uint8_t ValidateAdrConfiguration();
00214 
00215             /**
00216              * Get the time the radio must be off air to comply with regulations
00217              * Time to wait may be dependent on duty-cycle restrictions per channel
00218              * Or duty-cycle of join requests if OTAA is being attempted
00219              * @return ms of time to wait for next tx opportunity
00220              */
00221             virtual uint32_t GetTimeOffAir();
00222 
00223             /**
00224              * Get the channels in use by current channel plan
00225              * @return channel frequencies
00226              */
00227             virtual std::vector<uint32_t> GetChannels();
00228 
00229             /**
00230              * Get the channel datarate ranges in use by current channel plan
00231              * @return channel datarate ranges
00232              */
00233             virtual std::vector<uint8_t> GetChannelRanges();
00234 
00235 
00236             /**
00237              * Print log message for given rx window
00238              * @param wnd 1 or 2
00239              */
00240             virtual void LogRxWindow(uint8_t wnd);
00241 
00242             /**
00243              * Enable the default channels of the channel plan
00244              */
00245             virtual void EnableDefaultChannels();
00246 
00247             virtual uint8_t GetMinDatarate();
00248 
00249             virtual uint8_t GetMaxDatarate();
00250 
00251         protected:
00252 
00253             static const uint8_t US915_TX_POWERS[11];                   //!< List of available tx powers
00254             static const uint8_t US915_RADIO_POWERS[21];                //!< List of calibrated tx powers
00255             static const uint8_t US915_MAX_PAYLOAD_SIZE[];              //!< List of max payload sizes for each datarate
00256             static const uint8_t US915_MAX_PAYLOAD_SIZE_REPEATER[];     //!< List of repeater compatible max payload sizes for each datarate
00257 
00258     };
00259 }
00260 
00261 #endif // __CHANNEL_PLAN_US915_H__