hello 2
Diff: ChannelPlan.h
- Revision:
- 61:58ed1e136af5
- Child:
- 64:64982192a2af
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/ChannelPlan.h Thu Jul 27 10:43:57 2017 -0500 @@ -0,0 +1,611 @@ +/** __ ___ ____ _ ______ __ ____ __ ____ + * / |/ /_ __/ / /_(_)__/_ __/__ ____/ / / __/_ _____ / /____ __ _ ___ / _/__ ____ + * / /|_/ / // / / __/ /___// / / -_) __/ _ \ _\ \/ // (_-</ __/ -_) ' \(_-< _/ // _ \/ __/ __ + * /_/ /_/\_,_/_/\__/_/ /_/ \__/\__/_//_/ /___/\_, /___/\__/\__/_/_/_/___/ /___/_//_/\__/ /_/ + * Copyright (C) 2015 by Multi-Tech Systems /___/ + * + * + * @author Jason Reiss + * @date 10-31-2015 + * @brief lora::ChannelPlan provides an interface for LoRaWAN channel schemes + * + * @details + * + */ + +#ifndef __CHANNEL_STRATEGY_H__ +#define __CHANNEL_STRATEGY_H__ + +#include "Lora.h" +#include "SxRadio.h" +#include <vector> + +namespace lora { + + class ChannelPlan { + public: + + /** + * Descriptions for channel plans & region information. + * Bits 0-2 represent the plan type (fixed or dynamic) + * 0b000 cannot be used as plans may line up with old definitions and cause much badness + * 0b001 fixed channel plans + * 0b010 dynamic channel plans + * 0b011 - 0b111 RFU + * Bits 3-7 represent the specific channel plan/region within the plan type + */ + enum PlanType { + FIXED = 0x20, + DYNAMIC = 0x40, + }; + + enum Plan { + EU868_OLD = 0x00, + US915_OLD = 0x01, + AU915_OLD = 0x02, + + FB_EU868 = 0x00, + FB_US915 = 0x01, + FB_AU915 = 0x02, + + FB_868 = 0x00, + FB_915 = 0x01, + + US915 = FIXED | 0x00, + AU915 = FIXED | 0x01, + + EU868 = DYNAMIC | 0x00, + IN865 = DYNAMIC | 0x01, + AS923 = DYNAMIC | 0x02, + KR920 = DYNAMIC | 0x03, + AS923_JAPAN = DYNAMIC | 0x04, + + NONE = 0xFF, + }; + + /** + * ChannelPlan constructor + * @param radio SxRadio object used to set Tx/Rx config + * @param settings Settings object + */ + ChannelPlan(SxRadio* radio, Settings* settings); + + /** + * ChannelPlan destructor + */ + virtual ~ChannelPlan(); + + /** + * Initialize channels, datarates and duty cycle bands according to current channel plan in settings + */ + virtual void Init() = 0; + + /** + * Set SxRadio object to be used to set Tx/Rx config + */ + virtual void SetRadio(SxRadio* radio); + + /** + * Set Settings object + */ + virtual void SetSettings(Settings* settings); + + /** + * Get the next channel to use to transmit + * @return LORA_OK if channel was found + * @return LORA_NO_CHANS_ENABLED + */ + virtual uint8_t GetNextChannel() = 0; + + /** + * Set the number of channels in the plan + */ + virtual void SetNumberOfChannels(uint8_t channels, bool resize = true); + + /** + * Get the number of channels in the plan + */ + virtual uint8_t GetNumberOfChannels(); + + /** + * Check if channel is enabled + * @return true if enabled + */ + virtual bool IsChannelEnabled(uint8_t channel); + + /** + * Set a 16 bit channel mask with offset + * @param index of mask to set 0:0-15, 1:16-31 ... + * @param mask 16 bit mask of enabled channels + * @return true + */ + virtual bool SetChannelMask(uint8_t index, uint16_t mask); + + /** + * Get the channel mask of currently enabled channels + * @return vector containing channel bit masks + */ + virtual std::vector<uint16_t> GetChannelMask(); + + /** + * Add a channel to the ChannelPlan + * @param index of channel, use -1 to add to end + * @param channel settings to add + */ + virtual uint8_t AddChannel(int8_t index, Channel channel) = 0; + + /** + * Get channel at index + * @return Channel + */ + virtual Channel GetChannel(int8_t index) = 0; + + /** + * Add a downlink channel to the ChannelPlan + * Set to 0 to use the default uplink channel frequency + * @param index of channel, use -1 to add to end + * @param channel settings to add + */ + virtual uint8_t AddDownlinkChannel(int8_t index, Channel channel); + + /** + * Get channel at index + * @return Channel + */ + virtual Channel GetDownlinkChannel(uint8_t index); + + /** + * Set number of datarates in ChannelPlan + * @param datarates + */ + virtual void SetNumberOfDatarates(uint8_t datarates); + + /** + * Add a datarate to the ChannelPlan + * @param index of datarate, use -1 to add to end + * @param datarate settings to add + */ + virtual uint8_t AddDatarate(int8_t index, Datarate datarate); + + /** + * Get datarate at index + * @return Datarate + */ + virtual Datarate GetDatarate(int8_t index); + + /** + * Get max payload size for current datarate + * @return size in bytes + */ + virtual uint8_t GetMaxPayloadSize(); + + /** + * Get rx window settings for requested window + * RX_1, RX_2, RX_BEACON, RX_SLOT + * @param window + * @return RxWindow + */ + virtual RxWindow GetRxWindow(uint8_t window) = 0; + + /** + * Get current channel to use for transmitting + * @param channel index of channel + * @return LORA_OK + */ + virtual uint8_t SetTxChannel(uint8_t channel); + + /** + * Get datarate to use on the join request + * @return datarate index + */ + virtual uint8_t GetJoinDatarate() = 0; + + /** + * Calculate the next time a join request is possible + * @param size of join frame + * @returns LORA_OK + */ + virtual uint8_t CalculateJoinBackoff(uint8_t size) = 0; + + /** + * Get the current datarate + * @return Datarate + */ + virtual Datarate GetTxDatarate(); + + /** + * Set the current datarate + * @param index of datarate + * @return LORA_OK + */ + virtual uint8_t SetTxDatarate(uint8_t index); + + /** + * Set the datarate offset used for first receive window + * @param offset + * @return LORA_OK + */ + virtual uint8_t SetRx1Offset(uint8_t offset); + + /** + * Set the frequency for second receive window + * @param freq + * @return LORA_OK + */ + virtual uint8_t SetRx2Frequency(uint32_t freq); + + /** + * Set the datarate index used for second receive window + * @param index + * @return LORA_OK + */ + virtual uint8_t SetRx2DatarateIndex(uint8_t index); + + /** + * Get next channel and set the SxRadio tx config with current settings + * @return LORA_OK + */ + virtual uint8_t SetTxConfig() = 0; + + /** + * Set the SxRadio rx config provided window + * @param window to be opened + * @param continuous keep window open + * @return LORA_OK + */ + virtual uint8_t SetRxConfig(uint8_t window, bool continuous) = 0; + + /** + * Set frequency sub band if supported by plan + * @param sub_band + * @return LORA_OK + */ + virtual uint8_t SetFrequencySubBand(uint8_t group) = 0; + + /** + * Get frequency sub band if supported by plan + * @return sub band 0-8 or 0 if not supported + */ + virtual uint8_t GetFrequencySubBand(); + + /** + * Reset the ack counter used to lower datarate if ACK's are missed + */ + virtual void ResetAckCounter(); + + /** + * Callback for radio to request channel change when frequency hopping + * @param currentChannel + */ + virtual void FhssChangeChannel(uint8_t currentChannel); + + /** + * Callback for ACK timeout event + * @return LORA_OK + */ + virtual uint8_t HandleAckTimeout(); + + /** + * Callback for Join Accept packet to load optional channels + * @return LORA_OK + */ + virtual uint8_t HandleJoinAccept(const uint8_t* buffer, uint8_t size) = 0; + + /** + * Callback to for rx parameter setup ServerCommand + * @param payload packet data + * @param index of start of command buffer + * @param size number of bytes in command buffer + * @param[out] status to be returned in MoteCommand answer + * @return LORA_OK + */ + virtual uint8_t HandleRxParamSetup(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status) = 0; + + /** + * Callback to for new channel ServerCommand + * @param payload packet data + * @param index of start of command buffer + * @param size number of bytes in command buffer + * @param[out] status to be returned in MoteCommand answer + * @return LORA_OK + */ + virtual uint8_t HandleNewChannel(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status) = 0; + + /** + * Callback to for ping slot channel request ServerCommand + * @param payload packet data + * @param index of start of command buffer + * @param size number of bytes in command buffer + * @param[out] status to be returned in MoteCommand answer + * @return LORA_OK + */ + virtual uint8_t HandlePingSlotChannelReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status) = 0; + + /** + * Callback to for beacon frequency request ServerCommand + * @param payload packet data + * @param index of start of command buffer + * @param size number of bytes in command buffer + * @param[out] status to be returned in MoteCommand answer + * @return LORA_OK + */ + virtual uint8_t HandleBeaconFrequencyReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status) = 0; + + /** + * Callback to for adaptive datarate ServerCommand + * @param payload packet data + * @param index of start of command buffer + * @param size number of bytes in command buffer + * @param[out] status to be returned in MoteCommand answer + * @return LORA_OK + */ + virtual uint8_t HandleAdrCommand(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status) = 0; + + /** + * Validate the configuration after multiple ADR commands have been applied + * @return status to be returned in MoteCommand answer + */ + virtual uint8_t ValidateAdrConfiguration() = 0; + + /** + * Check that Rf Frequency is within channel plan range + * @param freq frequency in Hz + * @return true if valid frequency + */ + virtual bool CheckRfFrequency(uint32_t freq); + + /** + * Flag for ADR + * @return true if ADR is enable in settings + */ + virtual bool IsAdrEnabled(); + + /** + * Flag if ADR ACK should be sent in next packet + * @return true when flag should be set + */ + virtual bool AdrAckReq(); + + /** + * Increment the ADR counter to track when ADR ACK request should be sent + * @return current value + */ + virtual uint8_t IncAdrCounter(); + + /** + * Reset the ADR counter when valid downlink is received from network server + */ + virtual void ResetAdrCounter(); + + /** + * Get the time the radio must be off air to comply with regulations + * Time to wait may be dependent on duty-cycle restrictions per channel + * Or duty-cycle of join requests if OTAA is being attempted + * @return ms of time to wait for next tx opportunity + */ + virtual uint32_t GetTimeOffAir() = 0; + + /** + * Get the channels in use by current channel plan + * @return channel frequencies + */ + virtual std::vector<uint32_t> GetChannels() = 0; + + /** + * Get the downlink channels in use by current channel plan + * @return channel frequencies + */ + virtual std::vector<uint32_t> GetDownlinkChannels(); + + /** + * Get the channel datarate ranges in use by current channel plan + * @return channel datarate ranges + */ + virtual std::vector<uint8_t> GetChannelRanges() = 0; + + /** + * Set the time off air for the given duty band + * @param band index + * @param time off air in ms + */ + virtual void SetDutyBandTimeOff(uint8_t band, uint32_t timeoff); + + /** + * Get the time off air for the given duty band + * @param band index + * @return time off air in ms + */ + virtual uint32_t GetDutyBandTimeOff(uint8_t band); + + /** + * Get the number of duty bands in the current channel plan + * @return number of bands + */ + virtual uint8_t GetNumDutyBands(); + + /** + * Get the duty band index for the given frequency + * @param freq frequency in Hz + * @return index of duty band + */ + virtual int8_t GetDutyBand(uint32_t freq); + + /** + * Add duty band + * @param index of duty band or -1 to append + * @param band DutyBand definition + * @return LORA_OK + */ + virtual uint8_t AddDutyBand(int8_t index, DutyBand band); + + /** + * Update duty cycle with current settings + */ + virtual void UpdateDutyCycle(uint8_t bytes); + + /** + * Update duty cycle with at given frequency and time on air + * @param freq frequency + * @param time_on_air_ms tx time on air + */ + virtual void UpdateDutyCycle(uint32_t freq, uint32_t time_on_air_ms); + + /** + * Get time on air with current settings + * @param bytes number of bytes to be sent + */ + virtual uint32_t GetTimeOnAir(uint8_t bytes); + + /** + * Reset the duty timers with the current time off air + */ + virtual void ResetDutyCycleTimer(); + + /** + * Print log message for given rx window + * @param wnd 1 or 2 + */ + virtual void LogRxWindow(uint8_t wnd) = 0; + + /** + * Indicator of P2P mode + * @return true if enabled + */ + virtual bool P2PEnabled(); + + /** + * Ack timeout for P2P mode + * @return timeout in ms + */ + virtual uint16_t P2PTimeout(); + + /** + * Ack backoff for P2P mode + * @return backoff in ms + */ + virtual uint16_t P2PBackoff(); + + /** + * Enable the default channels of the channel plan + */ + virtual void EnableDefaultChannels() = 0; + + /** + * Callback for radio thread to signal + */ + virtual void MacEvent(); + + /** + * Called when MAC layer doesn't know about a command. + * Use to add custom or new mac command handling + * @return LORA_OK + */ + virtual uint8_t HandleMacCommand(uint8_t* payload, uint8_t& index); + + virtual void DecrementDatarate(); + virtual void IncrementDatarate(); + + virtual std::string GetPlanName(); + virtual uint8_t GetPlan(); + virtual bool IsPlanFixed(); + virtual bool IsPlanDynamic(); + static bool IsPlanFixed(uint8_t plan); + static bool IsPlanDynamic(uint8_t plan); + virtual uint32_t GetMinFrequency(); + virtual uint32_t GetMaxFrequency(); + + virtual uint8_t GetMinDatarate(); + virtual uint8_t GetMaxDatarate(); + virtual uint8_t GetMinDatarateOffset(); + virtual uint8_t GetMaxDatarateOffset(); + + virtual uint8_t GetMinRx2Datarate(); + virtual uint8_t GetMaxRx2Datarate(); + virtual uint8_t GetMaxTxPower(); + virtual uint8_t GetMinTxPower(); + + virtual uint16_t GetLBT_TimeUs(); + virtual void SetLBT_TimeUs(uint16_t us); + + virtual int8_t GetLBT_Threshold(); + virtual void SetLBT_Threshold(int8_t rssi); + + /** + * Set LBT time and threshold to defaults + */ + virtual void DefaultLBT(); + + virtual bool ListenBeforeTalk(); + + protected: + + SxRadio* GetRadio(); //!< Get pointer to the SxRadio object or assert if it is null + Settings* GetSettings(); //!< Get pointer to the settings object or assert if it is null + + uint8_t _txChannel; //!< Current channel for transmit + uint8_t _txFrequencySubBand; //!< Current frequency sub band for hybrid operation + + std::vector<Datarate> _datarates; //!< List of datarates + + std::vector<Channel> _channels; //!< List of channels for transmit + std::vector<Channel> _dlChannels; //!< List of channels for receive if changed from default + + std::vector<DutyBand> _dutyBands; //!< List of duty bands to limit radio time on air + + uint8_t _maxTxPower; //!< Max Tx power for channel Plan + uint8_t _minTxPower; + + uint32_t _minFrequency; //!< Minimum Frequency + uint32_t _maxFrequency; //!< Maximum Frequency + + Channel _beaconChannel; //!< Beacon window settings + Channel _beaconRxChannel; //!< Beacon slot rx window settings + + uint8_t _minDatarate; //!< Minimum datarate to accept in ADR request + uint8_t _maxDatarate; //!< Maximum datarate to accept in ADR request + + uint8_t _minRx2Datarate; //!< Minimum datarate to accept in for Rx2 + uint8_t _maxRx2Datarate; //!< Maximum datarate to accept in for Rx2 + uint8_t _minDatarateOffset; //!< Minimum datarate offset to accept + uint8_t _maxDatarateOffset; //!< Maximum datarate offset to accept + + uint32_t _freqUBase125k; //!< Start of 125K uplink channels + uint32_t _freqUStep125k; //!< Step between 125K uplink channels + uint32_t _freqUBase500k; //!< Start of 500K uplink channels + uint32_t _freqUStep500k; //!< Step between 500K uplink channels + uint32_t _freqDBase500k; //!< Start of 500K downlink channels + uint32_t _freqDStep500k; //!< Step between 500K downlink channels + + uint8_t _numChans; //!< Number of total channels in plan + uint8_t _numChans125k; //!< Number of 125K channels in plan + uint8_t _numChans500k; //!< Number of 500K channels in plan + + uint16_t _LBT_TimeUs; //!< Sample time in us for LBT + int8_t _LBT_Threshold; //!< Threshold in dBm for LBT + + std::vector<uint16_t> _channelMask; //!< Bit mask for currently enabled channels + + Timer _dutyCycleTimer; //!< Timer for tracking time-off-air + RtosTimer _txDutyTimer; //!< Event timer for expiration of time-off-air + + bool _txDutyCyclePending; //!< Flag for pending duty cycle event + + static void OnTxDutyCycleEvent(const void* arg); //!< Rtos callback for duty cycle event + void OnTxDutyCycleEventBottom(); //!< Callback for duty cycle event + + static const uint8_t* TX_POWERS; //!< List of available tx powers + static const uint8_t* RADIO_POWERS; //!< List of available tx powers + static const uint8_t* MAX_PAYLOAD_SIZE; //!< List of max payload sizes for each datarate + static const uint8_t* MAX_PAYLOAD_SIZE_REPEATER; //!< List of repeater compatible max payload sizes for each datarate + + uint8_t _plan; + std::string _planName; + + private: + + SxRadio* _radio; //!< Injected SxRadio dependency + Settings* _settings; //!< Current settings + }; +} + +#endif