Creating new channel plans

File content as of revision 18:aa39c917aa3f:

/**   __  ___     ____  _    ______        __     ____         __                  ____
 *   /  |/  /_ __/ / /_(_)__/_  __/__ ____/ /    / __/_ _____ / /____ __ _  ___   /  _/__  ____
 *  / /|_/ / // / / __/ /___// / / -_) __/ _ \  _\ \/ // (_-</ __/ -_)  ' \(_-<  _/ // _ \/ __/ __
 * /_/  /_/\_,_/_/\__/_/    /_/  \__/\__/_//_/ /___/\_, /___/\__/\__/_/_/_/___/ /___/_//_/\__/ /_/
 * 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:

            enum PlanType {
                DYNAMIC,
                FIXED,
            };

            /**
             * 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();

            /**
             * Get the next channel to use to transmit
             * @return LORA_OK if channel was found
             * @return LORA_NO_CHANS_ENABLED
             */
            virtual uint8_t GetNextChannel();

            /**
             * 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);

            /**
             * Get channel at index
             * @return Channel
             */
            virtual Channel GetChannel(int8_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);

            /**
             * 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();


            /**
             * Calculate the next time a join request is possible
             * @param size of join frame
             * @returns LORA_OK
             */
            virtual uint8_t CalculateJoinBackoff(uint8_t size);

            /**
             * 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();

            /**
             * 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);

            /**
             * Set channel group if supported by plan
             * @param group
             * @return LORA_OK
             */
            virtual uint8_t SetChannelGroup(uint8_t group);

            /**
             * Get channel group if supported by plan
             * @param group 0-8 or 0 if not supported
             * @return LORA_OK
             */
            virtual uint8_t GetChannelGroup();

            /**
             * 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);

            /**
             * 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);

            /**
             * 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);

            /**
             * 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);

            /**
             * 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);

            /**
             * 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);

            /**
             * 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();

            /**
             * Get the channels in use by current channel plan
             * @return channel frequencies
             */
            virtual std::vector<uint32_t> GetChannels();

            /**
             * Get the channel datarate ranges in use by current channel plan
             * @return channel datarate ranges
             */
            virtual std::vector<uint8_t> GetChannelRanges();

            /**
             * 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);

            /**
             * 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();

            /**
             *  Callback for radio thread to signal
             */
            virtual void MacEvent();

            virtual void DecrementDatarate();
            virtual void IncrementDatarate();

            virtual uint8_t HandleMacCommands(uint8_t* payload, uint8_t index, uint8_t end_index);

            virtual uint8_t GetPlanType();
            virtual uint32_t GetMinimumFrequency();
            virtual uint32_t GetMaximumFrequency();

        protected:

            SxRadio& _radio;                    //!< Injected SxRadio dependency
            Settings& _settings;                //!< Current settings

            uint8_t _txChannel;                 //!< Current channel for transmit
            uint8_t _txChannelGroup;            //!< Current channel group for hybrid operation

            std::vector<Datarate> _datarates;   //!< List of datarates

            std::vector<Channel> _channels;     //!< List of channels for transmit

            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

            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

            static const uint8_t EU868_TX_POWERS[6];                    //!< List of available tx powers
            static const uint8_t EU868_RADIO_POWERS[21];                 //!< List of calibrated tx powers
            static const uint8_t EU868_MAX_PAYLOAD_SIZE[];              //!< List of max payload sizes for each datarate
            static const uint8_t EU868_MAX_PAYLOAD_SIZE_REPEATER[];     //!< List of repeater compatible max payload sizes for each datarate

            static const uint8_t US915_TX_POWERS[11];                   //!< List of available tx powers
            static const uint8_t US915_RADIO_POWERS[21];                //!< List of calibrated tx powers
            static const uint8_t US915_MAX_PAYLOAD_SIZE[];              //!< List of max payload sizes for each datarate
            static const uint8_t US915_MAX_PAYLOAD_SIZE_REPEATER[];     //!< List of repeater compatible max payload sizes for each datarate

            static const uint8_t AU915_TX_POWERS[11];                   //!< List of available tx powers
            static const uint8_t AU915_RADIO_POWERS[21];                //!< List of calibrated tx powers
            static const uint8_t AU915_MAX_PAYLOAD_SIZE[];              //!< List of max payload sizes for each datarate
            static const uint8_t AU915_MAX_PAYLOAD_SIZE_REPEATER[];     //!< List of repeater compatible max payload sizes for each datarate

            PlanType _type;
    };
}

#endif