Mote.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::Mote provides a user level class that abstracts the complexity of the Mac layer
00011  *
00012  * @details
00013  *
00014  */
00015 
00016 #ifndef __LORA_MOTE_H__
00017 #define __LORA_MOTE_H__
00018 
00019 #include "rtos.h"
00020 #include "MacEvents.h"
00021 #include <vector>
00022 
00023 class SxRadio;
00024 class SxRadio1272 ;
00025 
00026 namespace lora {
00027 
00028     class Mac;
00029     class ChannelPlan;
00030 
00031     class MoteEvents: public MacEvents {
00032 
00033             /**
00034              * Fired at start of TX
00035              */
00036             virtual void TxStart(void);
00037 
00038             /**
00039              * Fired at end of TX
00040              * @param dr datarate used for TX
00041              */
00042             virtual void TxDone(uint8_t dr);
00043 
00044             /**
00045              * Fired if TX timed out
00046              */
00047             virtual void TxTimeout(void);
00048 
00049             /**
00050              * Fired when JoinAccept message is received and MIC is validated
00051              * @param payload received bytes
00052              * @param size number of received bytes
00053              * @param rssi of received packet
00054              * @param snr of received packet
00055              */
00056             virtual void JoinAccept(uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr);
00057 
00058             /**
00059              * Fired when JoinAccept message is received and MIC is not valid
00060              * @param payload received bytes
00061              * @param size number of received bytes
00062              * @param rssi of received packet
00063              * @param snr of received packet
00064              */
00065             virtual void JoinFailed(uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr);
00066 
00067             /**
00068              * Fired when packet is received and MIC is valid
00069              * @param port of packet
00070              * @param payload received bytes
00071              * @param size number of received bytes
00072              * @param rssi of received packet
00073              * @param snr of received packet
00074              * @param ctrl Downlink control field of packet
00075              * @param slot rx window packet was received
00076              * @param retries number of attempts before ack was received
00077              * @param address of the end device
00078              * @param dupRx set if this packet has already been received
00079              */
00080             virtual void PacketRx(uint8_t port, uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr, lora::DownlinkControl ctrl, uint8_t slot, uint8_t retries = 0, uint32_t address = 0, bool dupRx=false);
00081 
00082             /**
00083              * Fired when radio has received a packet, packet is not validated
00084              * @param payload received bytes
00085              * @param size number of received bytes
00086              * @param rssi of received packet
00087              * @param snr of received packet
00088              * @param ctrl Downlink control field of packet
00089              * @param slot rx window packet was received
00090              */
00091             virtual void RxDone(uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr, lora::DownlinkControl ctrl, uint8_t slot);
00092 
00093             /**
00094              * Fired if rx window times out
00095              * @param slot rx window that timed out
00096              */
00097             virtual void RxTimeout(uint8_t slot);
00098 
00099             /**
00100              * Fired if rx CRC error
00101              * @param slot rx window that errored
00102              */
00103             virtual void RxError(uint8_t slot);
00104 
00105             /**
00106              * Fired if pong packet is received
00107              * @param m_rssi of received packet at mote
00108              * @param m_snr of received packet at mote
00109              * @param s_rssi of received packet at server
00110              * @param s_snr of received packet at server
00111              */
00112             virtual void Pong(int16_t m_rssi, int8_t m_snr, int16_t s_rssi, int8_t s_snr);
00113 
00114             /**
00115              * Fired if network link check answer is received
00116              * @param m_rssi of received packet at mote
00117              * @param m_snr of received packet at mote
00118              * @param s_snr margin of received packet at server
00119              * @param s_gateways number of gateways reporting the packet
00120              */
00121             virtual void NetworkLinkCheck(int16_t m_rssi, int8_t m_snr, int8_t s_snr, uint8_t s_gateways);
00122 
00123             /**
00124              * Callback to for device to measure the battery level and report to server
00125              * @return battery level 0-255, 0 - external power, 1-254 level min-max, 255 device unable to measure battery
00126              */
00127             virtual uint8_t MeasureBattery();
00128 
00129             /**
00130              * Fired when ack attempts are exhausted and RxTimeout or RxError occur
00131              * @param retries number of attempts to resend the packet
00132              */
00133             virtual void MissedAck(uint8_t retries);
00134     };
00135 
00136     class Mote {
00137         public:
00138             Mote(Settings* settings, ChannelPlan* plan);
00139             virtual ~Mote();
00140 
00141             /**
00142              * MTS LoRa version
00143              * @return string containing version information
00144              */
00145             const char* getId();
00146 
00147             /**
00148              * Indicator for network session join status
00149              * @return true if joined to network
00150              */
00151             bool Joined();
00152 
00153             /**
00154              * Send join request
00155              * @return LORA_OK if request was sent
00156              */
00157             uint8_t Join();
00158 
00159             /**
00160              * Send a packet
00161              * @param port to send packet
00162              * @param payload of packet
00163              * @param size in bytes
00164              * @return LORA_OK if successful
00165              * @return LORA_MAX_PAYLOAD_EXCEEDED if payload size exceeds datarate maximum
00166              * @return LORA_NO_CHANS_ENABLED if there is not an available channel that supports the current datarate
00167              * @return LORA_LINK_BUSY if link was busy
00168              * @return LORA_RADIO_BUSY if radio was busy
00169              * @return LORA_BUFFER_FULL if mac commands filled the packet, client should resend the packet
00170              */
00171             uint8_t Send(uint8_t port, const uint8_t* payload, uint8_t size);
00172 
00173             /**
00174              * Configure the channel plan
00175              * @param plan pointer to ChannelPlan object
00176              * @return LORA_OK
00177              */
00178             uint8_t SetChannelPlan(ChannelPlan* plan);
00179 
00180 
00181             Settings* GetSettings();
00182 
00183             /**
00184              * Get the channel mask of currently enabled channels
00185              * @return vector containing channel bit masks
00186              */
00187             std::vector<uint16_t> GetChannelMask();
00188 
00189             /**
00190              * Set a 16 bit channel mask with index
00191              * @param index of mask to set 0:0-15, 1:16-31 ...
00192              * @param mask 16 bit mask of enabled channels
00193              * @return true
00194              */
00195             virtual uint8_t SetChannelMask(uint8_t index, uint16_t mask);
00196 
00197             /**
00198              * Set the current frequency sub band for hybrid operation 1-8 else 0 for 64 channel operation
00199              * @param sub_band 0-8
00200              */
00201             uint8_t SetFrequencySubBand(uint8_t sub_band);
00202 
00203             /**
00204              * Get the current frequency sub band
00205              * @return sub band 0-8
00206              */
00207             uint8_t GetFrequencySubBand();
00208 
00209             /**
00210              * Add a channel to the channel plan
00211              * EU868, AS923 and KR920 allows additional channels to be added
00212              * Channels 0-2 are fixed default channels
00213              *
00214              * @param index of the channel
00215              * @param frequency of the channel or 0 to remove channel
00216              * @param range of datarates allowed by the channel
00217              * @return LORA_OK if channel was added
00218              */
00219             uint8_t AddChannel(uint8_t index, uint32_t frequency, lora::DatarateRange range);
00220 
00221             /**
00222              * Add a downlink channel to the channel plan
00223              * EU868, AS923 and KR920 allows downlink channels to be added
00224              *
00225              * @param index of the channel
00226              * @param frequency of the channel or 0 to remove channel
00227              * @return LORA_OK if channel was added
00228              */
00229             uint8_t AddDownlinkChannel(uint8_t index, uint32_t frequency);
00230 
00231             /**
00232              * Set network mode
00233              * Choose Public LoRaWAN mode or Private Multitech mode
00234              *
00235              * Public mode uses 0x34 sync word with 5/6 second join windows
00236              * Private mode uses 0x12 sync word with 1/2 second join windows
00237              *  US915/AU915 Rx1 and Rx2 are fixed per frequency sub band setting
00238              *
00239              * @param mode public or private
00240              * @return LORA_OK
00241              */
00242             uint8_t SetNetworkMode(uint8_t mode);
00243 
00244             /**
00245              * Get a pointer to the mac layer
00246              * @return Mac mac
00247              */
00248             Mac* GetMac();
00249 
00250             /**
00251              * Get a pointer to the radio
00252              * Can be used to read radio registers or get a random value based on RSSI
00253              *
00254              * @return SxRadio pointer
00255              */
00256             SxRadio* GetRadio();
00257 
00258             /**
00259              * Get the current statistics for the device
00260              * @return Statistics
00261              */
00262             Statistics& GetStats();
00263 
00264             /**
00265              * Reset the current statistics for the device
00266              */
00267             void ResetStats();
00268 
00269             /**
00270              * Get time on air with current settings for provided payload bytes
00271              * 13 overhead bytes will be added to payload
00272              * @param bytes of payload data
00273              * @return time-on-air in ms
00274              */
00275             uint32_t GetTimeOnAir(uint8_t bytes);
00276 
00277             /**
00278              * Get time off air required to adhere to duty-cycle limitations
00279              * @return time-off-air in ms
00280              */
00281             uint32_t GetTimeOffAir();
00282 
00283             /**
00284              * Call before setting device in sleep mode to place radio in sleep
00285              */
00286             void Sleep();
00287 
00288         protected:
00289             SxRadio1272 * _radio;
00290             Settings* _settings;
00291             Mac* _mac;
00292 
00293         private:
00294             ChannelPlan* _plan;
00295             MoteEvents _events;
00296     };
00297 
00298 }
00299 #endif