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