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