ChannelPlan_AS923.h

00001 /**********************************************************************
00002 * COPYRIGHT 2015 MULTI-TECH SYSTEMS, INC.
00003 *
00004 * Redistribution and use in source and binary forms, with or without modification,
00005 * are permitted provided that the following conditions are met:
00006 *   1. Redistributions of source code must retain the above copyright notice,
00007 *      this list of conditions and the following disclaimer.
00008 *   2. Redistributions in binary form must reproduce the above copyright notice,
00009 *      this list of conditions and the following disclaimer in the documentation
00010 *      and/or other materials provided with the distribution.
00011 *   3. Neither the name of MULTI-TECH SYSTEMS, INC. nor the names of its contributors
00012 *      may be used to endorse or promote products derived from this software
00013 *      without specific prior written permission.
00014 *
00015 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00016 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00017 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00018 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
00019 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00020 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
00021 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00022 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
00023 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
00024 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00025 *
00026 ******************************************************************************
00027  *
00028  * @author Jason Reiss
00029  * @date   10-31-2015
00030  * @brief  lora::ChannelPlan provides an interface for LoRaWAN channel schemes
00031  *
00032  * @details
00033  *
00034  */
00035 
00036 #ifndef __CHANNEL_PLAN_AS923_H__
00037 #define __CHANNEL_PLAN_AS923_H__
00038 
00039 #include "Lora.h"
00040 #include "SxRadio.h"
00041 #include <vector>
00042 #include "ChannelPlan.h"
00043 
00044 namespace lora {
00045 
00046     const uint8_t  AS923_125K_NUM_CHANS = 16;        //!< Number of 125k channels in AS923 channel plan
00047     const uint8_t  AS923_DEFAULT_NUM_CHANS = 2;      //!< Number of default channels in AS923 channel plan
00048     const uint32_t AS923_125K_FREQ_BASE = 923200000; //!< Frequency base for 125k AS923 uplink channels
00049     const uint32_t AS923_125K_FREQ_STEP = 200000;    //!< Frequency step for 125k AS923 uplink channels
00050     const uint32_t AS923_RX2_FREQ = 923200000;       //!< Frequency default for second rx window in AS923
00051     const uint8_t  AS923_BEACON_DR = DR_3;           //!< Default beacon datarate
00052     const uint32_t AS923_BEACON_FREQ = 923400000U;   //!< Default beacon broadcast frequency
00053 
00054     class ChannelPlan_AS923: public lora::ChannelPlan {
00055         public:
00056             /**
00057              * ChannelPlan constructor
00058              * @param radio SxRadio object used to set Tx/Rx config
00059              * @param settings Settings object
00060              */
00061             ChannelPlan_AS923();
00062             ChannelPlan_AS923(Settings* settings);
00063             ChannelPlan_AS923(SxRadio* radio, Settings* settings);
00064 
00065             /**
00066              * ChannelPlan destructor
00067              */
00068             virtual ~ChannelPlan_AS923();
00069 
00070             /**
00071              * Initialize channels, datarates and duty cycle bands according to current channel plan in settings
00072              */
00073             virtual void Init();
00074 
00075             /**
00076              * Get the next channel to use to transmit
00077              * @return LORA_OK if channel was found
00078              * @return LORA_NO_CHANS_ENABLED
00079              */
00080             virtual uint8_t GetNextChannel();
00081 
00082             /**
00083              * Add a channel to the ChannelPlan
00084              * @param index of channel, use -1 to add to end
00085              * @param channel settings to add
00086              */
00087             virtual uint8_t AddChannel(int8_t index, Channel channel);
00088 
00089             /**
00090              * Get channel at index
00091              * @return Channel
00092              */
00093             virtual Channel GetChannel(int8_t index);
00094 
00095             /**
00096              * Get rx window settings for requested window
00097              * RX_1, RX_2, RX_BEACON, RX_SLOT
00098              * @param window
00099              * @return RxWindow
00100              */
00101             virtual RxWindow GetRxWindow(uint8_t window);
00102 
00103             /**
00104              * Get datarate to use on the join request
00105              * @return datarate index
00106              */
00107             virtual uint8_t GetJoinDatarate();
00108 
00109             /**
00110              * Calculate the next time a join request is possible
00111              * @param size of join frame
00112              * @returns LORA_OK
00113              */
00114             virtual uint8_t CalculateJoinBackoff(uint8_t size);
00115 
00116             /**
00117              * Get next channel and set the SxRadio tx config with current settings
00118              * @return LORA_OK
00119              */
00120             virtual uint8_t SetTxConfig();
00121 
00122             /**
00123              * Set the SxRadio rx config provided window
00124              * @param window to be opened
00125              * @param continuous keep window open
00126              * @param wnd_growth factor to increase the rx window by
00127              * @param pad_ms time in milliseconds to add to computed window size
00128              * @return LORA_OK
00129              */
00130             virtual uint8_t SetRxConfig(uint8_t window,
00131                                         bool continuous,
00132                                         uint16_t wnd_growth,
00133                                         uint16_t pad_ms);
00134 
00135             /**
00136              * Set frequency sub band if supported by plan
00137              * @param sub_band
00138              * @return LORA_OK
00139              */
00140             virtual uint8_t SetFrequencySubBand(uint8_t sub_band);
00141 
00142             /**
00143              * Callback for ACK timeout event
00144              * @return LORA_OK
00145              */
00146             virtual uint8_t HandleAckTimeout();
00147 
00148             /**
00149              * Callback for Join Accept packet to load optional channels
00150              * @return LORA_OK
00151              */
00152             virtual uint8_t HandleJoinAccept(const uint8_t* buffer, uint8_t size);
00153 
00154             /**
00155              * Callback to for rx parameter setup ServerCommand
00156              * @param payload packet data
00157              * @param index of start of command buffer
00158              * @param size number of bytes in command buffer
00159              * @param[out] status to be returned in MoteCommand answer
00160              * @return LORA_OK
00161              */
00162             virtual uint8_t HandleRxParamSetup(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00163 
00164             /**
00165              * Callback to for new channel ServerCommand
00166              * @param payload packet data
00167              * @param index of start of command buffer
00168              * @param size number of bytes in command buffer
00169              * @param[out] status to be returned in MoteCommand answer
00170              * @return LORA_OK
00171              */
00172             virtual uint8_t HandleNewChannel(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00173 
00174             /**
00175              * Callback to for ping slot channel request ServerCommand
00176              * @param payload packet data
00177              * @param index of start of command buffer
00178              * @param size number of bytes in command buffer
00179              * @param[out] status to be returned in MoteCommand answer
00180              * @return LORA_OK
00181              */
00182             virtual uint8_t HandlePingSlotChannelReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00183 
00184             /**
00185              * Callback to for beacon frequency request ServerCommand
00186              * @param payload packet data
00187              * @param index of start of command buffer
00188              * @param size number of bytes in command buffer
00189              * @param[out] status to be returned in MoteCommand answer
00190              * @return LORA_OK
00191              */
00192             virtual uint8_t HandleBeaconFrequencyReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00193 
00194             /**
00195              * Callback to for adaptive datarate ServerCommand
00196              * @param payload packet data
00197              * @param index of start of command buffer
00198              * @param size number of bytes in command buffer
00199              * @param[out] status to be returned in MoteCommand answer
00200              * @return LORA_OK
00201              */
00202             virtual uint8_t HandleAdrCommand(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00203 
00204             /**
00205              * Validate the configuration after multiple ADR commands have been applied
00206              * @return status to be returned in MoteCommand answer
00207              */
00208             virtual uint8_t ValidateAdrConfiguration();
00209 
00210             /**
00211              * Update duty cycle with at given frequency and time on air
00212              * @param freq frequency
00213              * @param time_on_air_ms tx time on air
00214              */
00215             virtual void UpdateDutyCycle(uint32_t freq, uint32_t time_on_air_ms);
00216 
00217             /**
00218              * Get the time the radio must be off air to comply with regulations
00219              * Time to wait may be dependent on duty-cycle restrictions per channel
00220              * Or duty-cycle of join requests if OTAA is being attempted
00221              * @return ms of time to wait for next tx opportunity
00222              */
00223             virtual uint32_t GetTimeOffAir();
00224 
00225             /**
00226              * Get the channels in use by current channel plan
00227              * @return channel frequencies
00228              */
00229             virtual std::vector<uint32_t> GetChannels();
00230 
00231             /**
00232              * Get the channel datarate ranges in use by current channel plan
00233              * @return channel datarate ranges
00234              */
00235             virtual std::vector<uint8_t> GetChannelRanges();
00236 
00237             /**
00238              * Print log message for given rx window
00239              * @param wnd 1 or 2
00240              */
00241             virtual void LogRxWindow(uint8_t wnd);
00242 
00243             /**
00244              * Enable the default channels of the channel plan
00245              */
00246             virtual void EnableDefaultChannels();
00247 
00248             /**
00249              * Called when MAC layer doesn't know about a command.
00250              * Use to add custom or new mac command handling
00251              * @return LORA_OK
00252              */
00253             virtual uint8_t HandleMacCommand(uint8_t* payload, uint8_t& index);
00254 
00255             /**
00256              * Get max payload size for current datarate
00257              * @return size in bytes
00258              */
00259             virtual uint8_t GetMaxPayloadSize();
00260 
00261             /**
00262              * Decrements the datarate based on TxDwellTime
00263              */
00264             virtual void DecrementDatarate();
00265 
00266             /**
00267              * Check if this packet is a beacon and if so extract parameters needed
00268              * @param payload of potential beacon
00269              * @param size of the packet
00270              * @param [out] data extracted from the beacon if this packet was indeed a beacon
00271              * @return true if this packet is beacon, false if not
00272              */
00273             virtual bool DecodeBeacon(const uint8_t* payload,
00274                                       size_t size,
00275                                       BeaconData_t& data);
00276 
00277 
00278             virtual uint8_t GetMinDatarate();
00279 
00280         protected:
00281 
00282             static const uint8_t AS923_TX_POWERS[8];                    //!< List of available tx powers
00283             static const uint8_t AS923_RADIO_POWERS[21];                //!< List of calibrated tx powers
00284             static const uint8_t AS923_MAX_PAYLOAD_SIZE[];              //!< List of max payload sizes for each datarate
00285             static const uint8_t AS923_MAX_PAYLOAD_SIZE_400[];          //!< List of max payload sizes for each datarate
00286             static const uint8_t AS923_MAX_PAYLOAD_SIZE_REPEATER[];     //!< List of repeater compatible max payload sizes for each datarate
00287             static const uint8_t AS923_MAX_PAYLOAD_SIZE_REPEATER_400[]; //!< List of repeater compatible max payload sizes for each datarate
00288             static const uint8_t MAX_ERP_VALUES[];                      //!< Lookup table for Max EIRP (dBm) codes
00289             typedef struct __attribute__((packed)) {
00290                 uint8_t RFU[2];
00291                 uint8_t Time[4];
00292                 uint8_t CRC1[2];
00293                 uint8_t GwSpecific[7];
00294                 uint8_t CRC2[2];
00295             } BCNPayload;
00296     };
00297 }
00298 
00299 #endif //__CHANNEL_PLAN_AS923_H__