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