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, ChannelPlan* plan);
00132             virtual ~Mote();
00133 
00134             /**
00135              * MTS LoRa version
00136              * @return string containing version information
00137              */
00138             const char* getId();
00139 
00140             /**
00141              * Indicator for network session join status
00142              * @return true if joined to network
00143              */
00144             bool Joined();
00145 
00146             /**
00147              * Send join request
00148              * @return LORA_OK if request was sent
00149              */
00150             uint8_t Join();
00151 
00152             /**
00153              * Send a packet
00154              * @param port to send packet
00155              * @param payload of packet
00156              * @param size in bytes
00157              * @return LORA_OK if successful
00158              * @return LORA_MAX_PAYLOAD_EXCEEDED if payload size exceeds datarate maximum
00159              * @return LORA_NO_CHANS_ENABLED if there is not an available channel that supports the current datarate
00160              * @return LORA_LINK_BUSY if link was busy
00161              * @return LORA_RADIO_BUSY if radio was busy
00162              * @return LORA_BUFFER_FULL if mac commands filled the packet, client should resend the packet
00163              */
00164             uint8_t Send(uint8_t port, const uint8_t* payload, uint8_t size);
00165 
00166             /**
00167              * Configure the channel plan
00168              * @param plan pointer to ChannelPlan object
00169              * @return LORA_OK
00170              */
00171             uint8_t SetChannelPlan(ChannelPlan* plan);
00172 
00173             Settings* GetSettings();
00174 
00175             /**
00176              * Get the channel mask of currently enabled channels
00177              * @return vector containing channel bit masks
00178              */
00179             std::vector<uint16_t> GetChannelMask();
00180 
00181             /**
00182              * Set a 16 bit channel mask with index
00183              * @param index of mask to set 0:0-15, 1:16-31 ...
00184              * @param mask 16 bit mask of enabled channels
00185              * @return true
00186              */
00187             virtual uint8_t SetChannelMask(uint8_t index, uint16_t mask);
00188 
00189             /**
00190              * Set the current frequency sub band for hybrid operation 1-8 else 0 for 64 channel operation
00191              * @param sub_band 0-8
00192              */
00193             uint8_t SetFrequencySubBand(uint8_t sub_band);
00194 
00195             /**
00196              * Get the current frequency sub band
00197              * @return sub band 0-8
00198              */
00199             uint8_t GetFrequencySubBand();
00200 
00201             /**
00202              * Add a channel to the channel plan
00203              * EU868, AS923 and KR920 allows additional channels to be added
00204              * Channels 0-2 are fixed default channels
00205              *
00206              * @param index of the channel
00207              * @param frequency of the channel or 0 to remove channel
00208              * @param range of datarates allowed by the channel
00209              * @return LORA_OK if channel was added
00210              */
00211             uint8_t AddChannel(uint8_t index, uint32_t frequency, lora::DatarateRange range);
00212 
00213             /**
00214              * Add a downlink channel to the channel plan
00215              * EU868, AS923 and KR920 allows downlink channels to be added
00216              *
00217              * @param index of the channel
00218              * @param frequency of the channel or 0 to remove channel
00219              * @return LORA_OK if channel was added
00220              */
00221             uint8_t AddDownlinkChannel(uint8_t index, uint32_t frequency);
00222 
00223             /**
00224              * Set network mode
00225              * Choose Public LoRaWAN mode or Private Multitech mode
00226              *
00227              * Public mode uses 0x34 sync word with 5/6 second join windows
00228              * Private mode uses 0x12 sync word with 1/2 second join windows
00229              *  US915/AU915 Rx1 and Rx2 are fixed per frequency sub band setting
00230              *
00231              * @param mode public or private
00232              * @return LORA_OK
00233              */
00234             uint8_t SetNetworkMode(uint8_t mode);
00235 
00236             /**
00237              * Get a pointer to the mac layer
00238              * @return Mac mac
00239              */
00240             Mac* GetMac();
00241 
00242             /**
00243              * Get a pointer to the radio
00244              * Can be used to read radio registers or get a random value based on RSSI
00245              *
00246              * @return SxRadio pointer
00247              */
00248             SxRadio* GetRadio();
00249 
00250             /**
00251              * Get the current statistics for the device
00252              * @return Statistics
00253              */
00254             Statistics& GetStats();
00255 
00256             /**
00257              * Reset the current statistics for the device
00258              */
00259             void ResetStats();
00260 
00261             /**
00262              * Get time on air with current settings for provided payload bytes
00263              * 13 overhead bytes will be added to payload
00264              * @param bytes of payload data
00265              * @return time-on-air in ms
00266              */
00267             uint32_t GetTimeOnAir(uint8_t bytes);
00268 
00269             /**
00270              * Get time off air required to adhere to duty-cycle limitations
00271              * @return time-off-air in ms
00272              */
00273             uint32_t GetTimeOffAir();
00274 
00275             /**
00276              * Call before setting device in sleep mode to place radio in sleep
00277              */
00278             void Sleep();
00279 
00280         protected:
00281             SxRadio1272* _radio;
00282             Settings* _settings;
00283             Mac* _mac;
00284 
00285         private:
00286             ChannelPlan* _plan;
00287             MoteEvents _events;
00288     };
00289 
00290 }
00291 #endif