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