ChannelPlan.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_STRATEGY_H__
00017 #define __CHANNEL_STRATEGY_H__
00018 
00019 #include "Lora.h"
00020 #include "SxRadio.h"
00021 #include <vector>
00022 
00023 namespace lora {
00024 
00025     class ChannelPlan {
00026         public:
00027 
00028             enum PlanType {
00029                 DYNAMIC,
00030                 FIXED,
00031             };
00032 
00033             /**
00034              * ChannelPlan constructor
00035              * @param radio SxRadio object used to set Tx/Rx config
00036              * @param settings Settings object
00037              */
00038             ChannelPlan(SxRadio& radio, Settings& settings);
00039 
00040             /**
00041              * ChannelPlan destructor
00042              */
00043             virtual ~ChannelPlan();
00044 
00045             /**
00046              * Initialize channels, datarates and duty cycle bands according to current channel plan in settings
00047              */
00048             virtual void Init();
00049 
00050             /**
00051              * Get the next channel to use to transmit
00052              * @return LORA_OK if channel was found
00053              * @return LORA_NO_CHANS_ENABLED
00054              */
00055             virtual uint8_t GetNextChannel();
00056 
00057             /**
00058              * Set the number of channels in the plan
00059              */
00060             virtual void SetNumberOfChannels(uint8_t channels, bool resize = true);
00061 
00062             /**
00063              * Get the number of channels in the plan
00064              */
00065             virtual uint8_t GetNumberOfChannels();
00066 
00067             /**
00068              * Check if channel is enabled
00069              * @return true if enabled
00070              */
00071             virtual bool IsChannelEnabled(uint8_t channel);
00072 
00073             /**
00074              * Set a 16 bit channel mask with offset
00075              * @param index of mask to set 0:0-15, 1:16-31 ...
00076              * @param mask 16 bit mask of enabled channels
00077              * @return true
00078              */
00079             virtual bool SetChannelMask(uint8_t index, uint16_t mask);
00080 
00081             /**
00082              * Get the channel mask of currently enabled channels
00083              * @return vector containing channel bit masks
00084              */
00085             virtual std::vector<uint16_t> GetChannelMask();
00086 
00087             /**
00088              * Add a channel to the ChannelPlan
00089              * @param index of channel, use -1 to add to end
00090              * @param channel settings to add
00091              */
00092             virtual uint8_t AddChannel(int8_t index, Channel channel);
00093 
00094             /**
00095              * Get channel at index
00096              * @return Channel
00097              */
00098             virtual Channel GetChannel(uint8_t index);
00099 
00100             /**
00101              * Add a downlink channel to the ChannelPlan
00102              * Set to 0 to use the default uplink channel frequency
00103              * @param index of channel, use -1 to add to end
00104              * @param channel settings to add
00105              */
00106             virtual uint8_t AddDownlinkChannel(int8_t index, Channel channel);
00107 
00108             /**
00109              * Get channel at index
00110              * @return Channel
00111              */
00112             virtual Channel GetDownlinkChannel(uint8_t index);
00113 
00114             /**
00115              * Set number of datarates in ChannelPlan
00116              * @param datarates
00117              */
00118             virtual void SetNumberOfDatarates(uint8_t datarates);
00119 
00120             /**
00121              * Add a datarate to the ChannelPlan
00122              * @param index of datarate, use -1 to add to end
00123              * @param datarate settings to add
00124              */
00125             virtual uint8_t AddDatarate(int8_t index, Datarate datarate);
00126 
00127             /**
00128              * Get datarate at index
00129              * @return Datarate
00130              */
00131             virtual Datarate GetDatarate(int8_t index);
00132 
00133             /**
00134              * Get max payload size for current datarate
00135              * @return size in bytes
00136              */
00137             virtual uint8_t GetMaxPayloadSize();
00138 
00139             /**
00140              * Get rx window settings for requested window
00141              * RX_1, RX_2, RX_BEACON, RX_SLOT
00142              * @param window
00143              * @return RxWindow
00144              */
00145             virtual RxWindow GetRxWindow(uint8_t window);
00146 
00147             /**
00148              * Get current channel to use for transmitting
00149              * @param channel index of channel
00150              * @return LORA_OK
00151              */
00152             virtual uint8_t SetTxChannel(uint8_t channel);
00153 
00154             /**
00155              * Get datarate to use on the join request
00156              * @return datarate index
00157              */
00158             virtual uint8_t GetJoinDatarate();
00159 
00160 
00161             /**
00162              * Calculate the next time a join request is possible
00163              * @param size of join frame
00164              * @returns LORA_OK
00165              */
00166             virtual uint8_t CalculateJoinBackoff(uint8_t size);
00167 
00168             /**
00169              * Get the current datarate
00170              * @return Datarate
00171              */
00172             virtual Datarate GetTxDatarate();
00173 
00174             /**
00175              * Set the current datarate
00176              * @param index of datarate
00177              * @return LORA_OK
00178              */
00179             virtual uint8_t SetTxDatarate(uint8_t index);
00180 
00181             /**
00182              * Set the datarate offset used for first receive window
00183              * @param offset
00184              * @return LORA_OK
00185              */
00186             virtual uint8_t SetRx1Offset(uint8_t offset);
00187 
00188             /**
00189              * Set the frequency for second receive window
00190              * @param freq
00191              * @return LORA_OK
00192              */
00193             virtual uint8_t SetRx2Frequency(uint32_t freq);
00194 
00195             /**
00196              * Set the datarate index used for second receive window
00197              * @param index
00198              * @return LORA_OK
00199              */
00200             virtual uint8_t SetRx2DatarateIndex(uint8_t index);
00201 
00202             /**
00203              * Get next channel and set the SxRadio tx config with current settings
00204              * @return LORA_OK
00205              */
00206             virtual uint8_t SetTxConfig();
00207 
00208             /**
00209              * Set the SxRadio rx config provided window
00210              * @param window to be opened
00211              * @param continuous keep window open
00212              * @return LORA_OK
00213              */
00214             virtual uint8_t SetRxConfig(uint8_t window, bool continuous);
00215 
00216             /**
00217              * Set channel group if supported by plan
00218              * @param group
00219              * @return LORA_OK
00220              */
00221             virtual uint8_t SetChannelGroup(uint8_t group);
00222 
00223             /**
00224              * Get channel group if supported by plan
00225              * @param group 0-8 or 0 if not supported
00226              * @return LORA_OK
00227              */
00228             virtual uint8_t GetChannelGroup();
00229 
00230             /**
00231              * Reset the ack counter used to lower datarate if ACK's are missed
00232              */
00233             virtual void ResetAckCounter();
00234 
00235             /**
00236              * Callback for radio to request channel change when frequency hopping
00237              * @param currentChannel
00238              */
00239             virtual void FhssChangeChannel(uint8_t currentChannel);
00240 
00241             /**
00242              * Callback for ACK timeout event
00243              * @return LORA_OK
00244              */
00245             virtual uint8_t HandleAckTimeout();
00246 
00247             /**
00248              * Callback for Join Accept packet to load optional channels
00249              * @return LORA_OK
00250              */
00251             virtual uint8_t HandleJoinAccept(const uint8_t* buffer, uint8_t size);
00252 
00253             /**
00254              * Callback to for rx parameter setup ServerCommand
00255              * @param payload packet data
00256              * @param index of start of command buffer
00257              * @param size number of bytes in command buffer
00258              * @param[out] status to be returned in MoteCommand answer
00259              * @return LORA_OK
00260              */
00261             virtual uint8_t HandleRxParamSetup(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00262 
00263             /**
00264              * Callback to for new channel ServerCommand
00265              * @param payload packet data
00266              * @param index of start of command buffer
00267              * @param size number of bytes in command buffer
00268              * @param[out] status to be returned in MoteCommand answer
00269              * @return LORA_OK
00270              */
00271             virtual uint8_t HandleNewChannel(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00272 
00273             /**
00274              * Callback to for ping slot channel request ServerCommand
00275              * @param payload packet data
00276              * @param index of start of command buffer
00277              * @param size number of bytes in command buffer
00278              * @param[out] status to be returned in MoteCommand answer
00279              * @return LORA_OK
00280              */
00281             virtual uint8_t HandlePingSlotChannelReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00282 
00283             /**
00284              * Callback to for beacon frequency request ServerCommand
00285              * @param payload packet data
00286              * @param index of start of command buffer
00287              * @param size number of bytes in command buffer
00288              * @param[out] status to be returned in MoteCommand answer
00289              * @return LORA_OK
00290              */
00291             virtual uint8_t HandleBeaconFrequencyReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00292 
00293             /**
00294              * Callback to for adaptive datarate ServerCommand
00295              * @param payload packet data
00296              * @param index of start of command buffer
00297              * @param size number of bytes in command buffer
00298              * @param[out] status to be returned in MoteCommand answer
00299              * @return LORA_OK
00300              */
00301             virtual uint8_t HandleAdrCommand(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
00302 
00303             /**
00304              * Check that Rf Frequency is within channel plan range
00305              * @param freq frequency in Hz
00306              * @return true if valid frequency
00307              */
00308             virtual bool CheckRfFrequency(uint32_t freq);
00309 
00310             /**
00311              * Flag for ADR
00312              * @return true if ADR is enable in settings
00313              */
00314             virtual bool IsAdrEnabled();
00315 
00316             /**
00317              * Flag if ADR ACK should be sent in next packet
00318              * @return true when flag should be set
00319              */
00320             virtual bool AdrAckReq();
00321 
00322             /**
00323              * Increment the ADR counter to track when ADR ACK request should be sent
00324              * @return current value
00325              */
00326             virtual uint8_t IncAdrCounter();
00327 
00328             /**
00329              * Reset the ADR counter when valid downlink is received from network server
00330              */
00331             virtual void ResetAdrCounter();
00332 
00333             /**
00334              * Get the time the radio must be off air to comply with regulations
00335              * Time to wait may be dependent on duty-cycle restrictions per channel
00336              * Or duty-cycle of join requests if OTAA is being attempted
00337              * @return ms of time to wait for next tx opportunity
00338              */
00339             virtual uint32_t GetTimeOffAir();
00340 
00341             /**
00342              * Get the channels in use by current channel plan
00343              * @return channel frequencies
00344              */
00345             virtual std::vector<uint32_t> GetChannels();
00346 
00347             /**
00348              * Get the downlink channels in use by current channel plan
00349              * @return channel frequencies
00350              */
00351             virtual std::vector<uint32_t> GetDownlinkChannels();
00352 
00353             /**
00354              * Get the channel datarate ranges in use by current channel plan
00355              * @return channel datarate ranges
00356              */
00357             virtual std::vector<uint8_t> GetChannelRanges();
00358 
00359             /**
00360              * Set the time off air for the given duty band
00361              * @param band index
00362              * @param time off air in ms
00363              */
00364             virtual void SetDutyBandTimeOff(uint8_t band, uint32_t timeoff);
00365 
00366             /**
00367              * Get the time off air for the given duty band
00368              * @param band index
00369              * @return time off air in ms
00370              */
00371             virtual uint32_t GetDutyBandTimeOff(uint8_t band);
00372 
00373             /**
00374              * Get the number of duty bands in the current channel plan
00375              * @return number of bands
00376              */
00377             virtual uint8_t GetNumDutyBands();
00378 
00379             /**
00380              * Get the duty band index for the given frequency
00381              * @param freq frequency in Hz
00382              * @return index of duty band
00383              */
00384             virtual int8_t GetDutyBand(uint32_t freq);
00385 
00386             /**
00387              * Add duty band
00388              * @param index of duty band or -1 to append
00389              * @param band DutyBand definition
00390              * @return LORA_OK
00391              */
00392             virtual uint8_t AddDutyBand(int8_t index, DutyBand band);
00393 
00394             /**
00395              * Update duty cycle with current settings
00396              */
00397             virtual void UpdateDutyCycle(uint8_t bytes);
00398 
00399             /**
00400              * Update duty cycle with at given frequency and time on air
00401              * @param freq frequency
00402              * @param time_on_air_ms tx time on air
00403              */
00404             virtual void UpdateDutyCycle(uint32_t freq, uint32_t time_on_air_ms);
00405 
00406             /**
00407              * Get time on air with current settings
00408              * @param bytes number of bytes to be sent
00409              */
00410             virtual uint32_t GetTimeOnAir(uint8_t bytes);
00411 
00412             /**
00413              * Reset the duty timers with the current time off air
00414              */
00415             virtual void ResetDutyCycleTimer();
00416 
00417             /**
00418              * Print log message for given rx window
00419              * @param wnd 1 or 2
00420              */
00421             virtual void LogRxWindow(uint8_t wnd);
00422 
00423             /**
00424              * Indicator of P2P mode
00425              * @return true if enabled
00426              */
00427             virtual bool P2PEnabled();
00428 
00429             /**
00430              * Ack timeout for P2P mode
00431              * @return timeout in ms
00432              */
00433             virtual uint16_t P2PTimeout();
00434 
00435             /**
00436              * Ack backoff for P2P mode
00437              * @return backoff in ms
00438              */
00439             virtual uint16_t P2PBackoff();
00440 
00441             /**
00442              * Enable the default channels of the channel plan
00443              */
00444             virtual void EnableDefaultChannels();
00445 
00446             /**
00447              *  Callback for radio thread to signal
00448              */
00449             virtual void MacEvent();
00450 
00451             /**
00452              * Called before Mac layer handles command buffer.
00453              * Use to add custom or new mac command handling
00454              * @return LORA_OK
00455              */
00456             virtual uint8_t HandleMacCommands(uint8_t* payload, uint8_t index, uint8_t end_index);
00457 
00458             virtual void DecrementDatarate();
00459             virtual void IncrementDatarate();
00460 
00461             virtual std::string GetPlanName();
00462             virtual uint8_t GetPlanType();
00463             virtual uint32_t GetMinFrequency();
00464             virtual uint32_t GetMaxFrequency();
00465 
00466             virtual uint8_t GetMinDatarate();
00467             virtual uint8_t GetMaxDatarate();
00468             virtual uint8_t GetMinDatarateOffset();
00469             virtual uint8_t GetMaxDatarateOffset();
00470 
00471             virtual uint8_t GetMinRx2Datarate();
00472             virtual uint8_t GetMaxRx2Datarate();
00473             virtual uint8_t GetMaxTxPower();
00474 
00475             virtual uint32_t GetLBT_TimeMs();
00476             virtual void SetLBT_TimeMs(uint32_t ms);
00477 
00478             virtual int32_t GetLBT_Threshold();
00479             virtual void SetLBT_Threshold(int32_t rssi);
00480 
00481             bool ListenBeforeTalk();
00482 
00483         protected:
00484 
00485             SxRadio& _radio;                    //!< Injected SxRadio dependency
00486             Settings& _settings;                //!< Current settings
00487 
00488             uint8_t _txChannel;                 //!< Current channel for transmit
00489             uint8_t _txChannelGroup;            //!< Current channel group for hybrid operation
00490 
00491             std::vector<Datarate> _datarates;   //!< List of datarates
00492 
00493             std::vector<Channel> _channels;     //!< List of channels for transmit
00494             std::vector<Channel> _dlChannels;   //!< List of channels for receive if changed from default
00495 
00496             std::vector<DutyBand> _dutyBands;   //!< List of duty bands to limit radio time on air
00497 
00498             uint8_t _maxTxPower;                //!< Max Tx power for channel Plan
00499             uint8_t _minTxPower;
00500 
00501             uint32_t _minFrequency;             //!< Minimum Frequency
00502             uint32_t _maxFrequency;             //!< Maximum Frequency
00503 
00504             Channel _beaconChannel;             //!< Beacon window settings
00505             Channel _beaconRxChannel;           //!< Beacon slot rx window settings
00506 
00507             uint8_t _minDatarate;               //!< Minimum datarate to accept in ADR request
00508             uint8_t _maxDatarate;               //!< Maximum datarate to accept in ADR request
00509 
00510             uint8_t _minRx2Datarate;            //!< Minimum datarate to accept in for Rx2
00511             uint8_t _maxRx2Datarate;            //!< Maximum datarate to accept in for Rx2
00512             uint8_t _minDatarateOffset;         //!< Minimum datarate offset to accept
00513             uint8_t _maxDatarateOffset;         //!< Maximum datarate offset to accept
00514 
00515             uint32_t _freqUBase125k;            //!< Start of 125K uplink channels
00516             uint32_t _freqUStep125k;            //!< Step between 125K uplink channels
00517             uint32_t _freqUBase500k;            //!< Start of 500K uplink channels
00518             uint32_t _freqUStep500k;            //!< Step between 500K uplink channels
00519             uint32_t _freqDBase500k;            //!< Start of 500K downlink channels
00520             uint32_t _freqDStep500k;            //!< Step between 500K downlink channels
00521 
00522             uint8_t _numChans;                  //!< Number of total channels in plan
00523             uint8_t _numChans125k;              //!< Number of 125K  channels in plan
00524             uint8_t _numChans500k;              //!< Number of 500K channels in plan
00525 
00526             uint32_t _LBT_TimeMs;               //!<
00527             int32_t _LBT_Threshold;             //!<
00528 
00529             std::vector<uint16_t> _channelMask; //!< Bit mask for currently enabled channels
00530 
00531             Timer _dutyCycleTimer;              //!< Timer for tracking time-off-air
00532             RtosTimer _txDutyTimer;             //!< Event timer for expiration of time-off-air
00533 
00534             bool _txDutyCyclePending;           //!< Flag for pending duty cycle event
00535 
00536             static void OnTxDutyCycleEvent(const void* arg);    //!< Rtos callback for duty cycle event
00537             void OnTxDutyCycleEventBottom();                    //!< Callback for duty cycle event
00538 
00539             static const uint8_t* TX_POWERS;                    //!< List of available tx powers
00540             static const uint8_t* RADIO_POWERS;                    //!< List of available tx powers
00541             static const uint8_t* MAX_PAYLOAD_SIZE;             //!< List of max payload sizes for each datarate
00542             static const uint8_t* MAX_PAYLOAD_SIZE_REPEATER;    //!< List of repeater compatible max payload sizes for each datarate
00543 
00544             static const uint8_t EU868_TX_POWERS[6];                    //!< List of available tx powers
00545             static const uint8_t EU868_RADIO_POWERS[21];                 //!< List of calibrated tx powers
00546             static const uint8_t EU868_MAX_PAYLOAD_SIZE[];              //!< List of max payload sizes for each datarate
00547             static const uint8_t EU868_MAX_PAYLOAD_SIZE_REPEATER[];     //!< List of repeater compatible max payload sizes for each datarate
00548 
00549             static const uint8_t US915_TX_POWERS[11];                   //!< List of available tx powers
00550             static const uint8_t US915_RADIO_POWERS[21];                //!< List of calibrated tx powers
00551             static const uint8_t US915_MAX_PAYLOAD_SIZE[];              //!< List of max payload sizes for each datarate
00552             static const uint8_t US915_MAX_PAYLOAD_SIZE_REPEATER[];     //!< List of repeater compatible max payload sizes for each datarate
00553 
00554             static const uint8_t AU915_TX_POWERS[11];                   //!< List of available tx powers
00555             static const uint8_t AU915_RADIO_POWERS[21];                //!< List of calibrated tx powers
00556             static const uint8_t AU915_MAX_PAYLOAD_SIZE[];              //!< List of max payload sizes for each datarate
00557             static const uint8_t AU915_MAX_PAYLOAD_SIZE_REPEATER[];     //!< List of repeater compatible max payload sizes for each datarate
00558 
00559             PlanType _type;
00560             std::string _planName;
00561     };
00562 }
00563 
00564 #endif
00565