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     const uint8_t US915_125K_NUM_CHANS = 64;                    //!< Number of 125k channels in US915 channel plan
00027     const uint8_t US915_500K_NUM_CHANS = 8;                     //!< Number of 500k channels in US915 channel plan
00028 
00029     const uint32_t US915_125K_FREQ_BASE = 902300000;            //!< Frequency base for 125k US915 uplink channels
00030     const uint32_t US915_125K_FREQ_STEP = 200000;               //!< Frequency step for 125k US915 uplink channels
00031 
00032     const uint32_t US915_500K_FREQ_BASE = 903000000;            //!< Frequency base for 500k US915 uplink channels
00033     const uint32_t US915_500K_FREQ_STEP = 1600000;              //!< Frequency step for 500k US915 uplink channels
00034 
00035     const uint32_t US915_500K_DBASE = 923300000;                //!< Frequency base for 500k US915 downlink channels
00036     const uint32_t US915_500K_DSTEP = 600000;                   //!< Frequency step for 500k US915 downlink channels
00037 
00038     const uint32_t US915_FREQ_MIN = 902000000;
00039     const uint32_t US915_FREQ_MAX = 928000000;
00040 
00041     const uint8_t US915_MIN_DATARATE = (uint8_t) DR_0;          //!< Minimum transmit datarate for US915
00042     const uint8_t US915_MAX_DATARATE = (uint8_t) DR_4;          //!< Maximum transmit datarate for US915
00043 
00044     const uint8_t US915_MIN_DATARATE_OFFSET = (uint8_t) 0;      //!< Minimum transmit datarate for US915
00045     const uint8_t US915_MAX_DATARATE_OFFSET = (uint8_t) 3;      //!< Maximum transmit datarate for US915
00046 
00047     const uint8_t  US915_BEACON_DR = DR_8;                      //!< Default beacon datarate
00048     const uint32_t US915_BEACON_FREQ_BASE = 923300000U;         //!< Base beacon broadcast frequency
00049     const uint32_t US915_BEACON_FREQ_STEP = 600000U;            //!< Step size for beacon frequencies
00050     const uint8_t  US915_BEACON_CHANNELS = 8U;                  //!< Number of beacon channels
00051 
00052     class ChannelPlan_US915 : public lora::ChannelPlan {
00053         public:
00054 
00055             /**
00056              * ChannelPlan constructor
00057              * @param radio SxRadio object used to set Tx/Rx config
00058              * @param settings Settings object
00059              */
00060             ChannelPlan_US915();
00061             ChannelPlan_US915(Settings* settings);
00062             ChannelPlan_US915(SxRadio* radio, Settings* settings);
00063 
00064             /**
00065              * ChannelPlan destructor
00066              */
00067             virtual ~ChannelPlan_US915();
00068 
00069             /**
00070              * Initialize channels, datarates and duty cycle bands according to current channel plan in settings
00071              */
00072             virtual void Init();
00073 
00074             /**
00075              * Get the next channel to use to transmit
00076              * @return LORA_OK if channel was found
00077              * @return LORA_NO_CHANS_ENABLED
00078              */
00079             virtual uint8_t GetNextChannel();
00080 
00081             /**
00082              * Set the number of channels in the plan
00083              */
00084             virtual void SetNumberOfChannels(uint8_t channels, bool resize = true);
00085 
00086             /**
00087              * Check if channel is enabled
00088              * @return true if enabled
00089              */
00090             virtual bool IsChannelEnabled(uint8_t channel);
00091 
00092 
00093             /**
00094              * Add a channel to the ChannelPlan
00095              * @param index of channel, use -1 to add to end
00096              * @param channel settings to add
00097              */
00098             virtual uint8_t AddChannel(int8_t index, Channel channel);
00099 
00100             /**
00101              * Get channel at index
00102              * @return Channel
00103              */
00104             virtual Channel GetChannel(int8_t index);
00105 
00106             /**
00107              * Get rx window settings for requested window
00108              * RX_1, RX_2, RX_BEACON, RX_SLOT
00109              * @param window
00110              * @return RxWindow
00111              */
00112             virtual RxWindow GetRxWindow(uint8_t window);
00113 
00114             /**
00115              * Get datarate to use on the join request
00116              * @return datarate index
00117              */
00118             virtual uint8_t GetJoinDatarate();
00119 
00120             /**
00121              * Calculate the next time a join request is possible
00122              * @param size of join frame
00123              * @returns LORA_OK
00124              */
00125             virtual uint8_t CalculateJoinBackoff(uint8_t size);
00126 
00127             /**
00128              * Set the datarate offset used for first receive window
00129              * @param offset
00130              * @return LORA_OK
00131              */
00132             virtual uint8_t SetRx1Offset(uint8_t offset);
00133 
00134             /**
00135              * Set the frequency for second receive window
00136              * @param freq
00137              * @return LORA_OK
00138              */
00139             virtual uint8_t SetRx2Frequency(uint32_t freq);
00140 
00141             /**
00142              * Set the datarate index used for second receive window
00143              * @param index
00144              * @return LORA_OK
00145              */
00146             virtual uint8_t SetRx2DatarateIndex(uint8_t index);
00147 
00148             /**
00149              * Get next channel and set the SxRadio tx config with current settings
00150              * @return LORA_OK
00151              */
00152             virtual uint8_t SetTxConfig();
00153 
00154             /**
00155              * Set the SxRadio rx config provided window
00156              * @param window to be opened
00157              * @param continuous keep window open
00158              * @param wnd_growth factor to increase the rx window by
00159              * @param pad_ms time in milliseconds to add to computed window size
00160              * @return LORA_OK
00161              */
00162             virtual uint8_t SetRxConfig(uint8_t window,
00163                                         bool continuous,
00164                                         uint16_t wnd_growth,
00165                                         uint16_t pad_ms);
00166 
00167             /**
00168              * Set frequency sub band if supported by plan
00169              * @param sub_band
00170              * @return LORA_OK
00171              */
00172             virtual uint8_t SetFrequencySubBand(uint8_t sub_band);
00173 
00174             /**
00175              * Callback for Join Accept packet to load optional channels
00176              * @return LORA_OK
00177              */
00178             virtual uint8_t HandleJoinAccept(const uint8_t* buffer, uint8_t size);
00179 
00180             /**
00181              * Callback to for rx parameter setup ServerCommand
00182              * @param payload packet data
00183              * @param index of start of command buffer
00184              * @param size number of bytes in command buffer
00185              * @param[out] status to be returned in MoteCommand answer
00186              * @return LORA_OK
00187              */
00188             virtual uint8_t HandleRxParamSetup(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00189 
00190             /**
00191              * Callback to for new channel ServerCommand
00192              * @param payload packet data
00193              * @param index of start of command buffer
00194              * @param size number of bytes in command buffer
00195              * @param[out] status to be returned in MoteCommand answer
00196              * @return LORA_OK
00197              */
00198             virtual uint8_t HandleNewChannel(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00199 
00200             /**
00201              * Callback to for downlink channel request ServerCommand
00202              * @param payload packet data
00203              * @param index of start of command buffer
00204              * @param size number of bytes in command buffer
00205              * @param[out] status to be returned in MoteCommand answer
00206              * @return LORA_OK
00207              */
00208             virtual uint8_t HandleDownlinkChannelReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00209 
00210             /**
00211              * Callback to for ping slot channel request ServerCommand
00212              * @param payload packet data
00213              * @param index of start of command buffer
00214              * @param size number of bytes in command buffer
00215              * @param[out] status to be returned in MoteCommand answer
00216              * @return LORA_OK
00217              */
00218             virtual uint8_t HandlePingSlotChannelReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00219 
00220             /**
00221              * Callback to for beacon frequency request ServerCommand
00222              * @param payload packet data
00223              * @param index of start of command buffer
00224              * @param size number of bytes in command buffer
00225              * @param[out] status to be returned in MoteCommand answer
00226              * @return LORA_OK
00227              */
00228             virtual uint8_t HandleBeaconFrequencyReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00229 
00230             /**
00231              * Callback to for adaptive datarate ServerCommand
00232              * @param payload packet data
00233              * @param index of start of command buffer
00234              * @param size number of bytes in command buffer
00235              * @param[out] status to be returned in MoteCommand answer
00236              * @return LORA_OK
00237              */
00238             virtual uint8_t HandleAdrCommand(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00239 
00240             /**
00241              * Validate the configuration after multiple ADR commands have been applied
00242              * @return status to be returned in MoteCommand answer
00243              */
00244             virtual uint8_t ValidateAdrConfiguration();
00245 
00246             /**
00247              * Get the time the radio must be off air to comply with regulations
00248              * Time to wait may be dependent on duty-cycle restrictions per channel
00249              * Or duty-cycle of join requests if OTAA is being attempted
00250              * @return ms of time to wait for next tx opportunity
00251              */
00252             virtual uint32_t GetTimeOffAir();
00253 
00254             /**
00255              * Get the channels in use by current channel plan
00256              * @return channel frequencies
00257              */
00258             virtual std::vector<uint32_t> GetChannels();
00259 
00260             /**
00261              * Get the channel datarate ranges in use by current channel plan
00262              * @return channel datarate ranges
00263              */
00264             virtual std::vector<uint8_t> GetChannelRanges();
00265 
00266 
00267             /**
00268              * Print log message for given rx window
00269              * @param wnd 1 or 2
00270              */
00271             virtual void LogRxWindow(uint8_t wnd);
00272 
00273             /**
00274              * Enable the default channels of the channel plan
00275              */
00276             virtual void EnableDefaultChannels();
00277 
00278             virtual uint8_t GetMinDatarate();
00279 
00280             virtual uint8_t GetMaxDatarate();
00281 
00282             /**
00283              * Check if this packet is a beacon and if so extract parameters needed
00284              * @param payload of potential beacon
00285              * @param size of the packet
00286              * @param [out] data extracted from the beacon if this packet was indeed a beacon
00287              * @return true if this packet is beacon, false if not
00288              */
00289             virtual bool DecodeBeacon(const uint8_t* payload,
00290                                       size_t size,
00291                                       BeaconData_t& data);
00292             /**
00293              * Update class B beacon and ping slot settings if frequency hopping enabled
00294              * @param time received in the last beacon
00295              * @param period of the beacon
00296              * @param devAddr of this end device
00297              */
00298             virtual void FrequencyHop(uint32_t time, uint32_t period, uint32_t devAddr);
00299 
00300         protected:
00301 
00302             static const uint8_t US915_TX_POWERS[11];                   //!< List of available tx powers
00303             static const uint8_t US915_RADIO_POWERS[21];                //!< List of calibrated tx powers
00304             static const uint8_t US915_MAX_PAYLOAD_SIZE[];              //!< List of max payload sizes for each datarate
00305             static const uint8_t US915_MAX_PAYLOAD_SIZE_REPEATER[];     //!< List of repeater compatible max payload sizes for each datarate
00306 
00307             typedef struct __attribute__((packed)) {
00308                 uint8_t RFU1[5];
00309                 uint8_t Time[4];
00310                 uint8_t CRC1[2];
00311                 uint8_t GwSpecific[7];
00312                 uint8_t RFU2[3];
00313                 uint8_t CRC2[2];
00314             } BCNPayload;
00315     };
00316 }
00317 
00318 #endif // __CHANNEL_PLAN_US915_H__