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