Brendan Kelly / libmDot-mbed5

libMDot form for loop/dht22 project

Dependents:   mDot_LoRa_Connect_ABPA_DHT22_sleep mDot_LoRa_Connect_ABPA FrostyBoySensor mDot_LoRa_Connect_ABPA_Lux ... more

Fork of libmDot-mbed5 by MultiTech

Mote.h@63:af2fa55cbace, 2017-08-21 (annotated)

Committer:
kellybs1
Date:
Mon Aug 21 05:00:54 2017 +0000
Revision:
63:af2fa55cbace
Parent:
60:7985b4783af9 
Working version

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Mike Fiore 16:b630e18103e5 1 /** __ ___ ____ _ ______ __ ____ __ ____
Mike Fiore 16:b630e18103e5 2 * / |/ /_ __/ / /_(_)__/_ __/__ ____/ / / __/_ _____ / /____ __ _ ___ / _/__ ____
Mike Fiore 16:b630e18103e5 3 * / /|_/ / // / / __/ /___// / / -_) __/ _ \ _\ \/ // (_-</ __/ -_) ' \(_-< _/ // _ \/ __/ __
Mike Fiore 16:b630e18103e5 4 * /_/ /_/\_,_/_/\__/_/ /_/ \__/\__/_//_/ /___/\_, /___/\__/\__/_/_/_/___/ /___/_//_/\__/ /_/
Mike Fiore 16:b630e18103e5 5 * Copyright (C) 2015 by Multi-Tech Systems /___/
Mike Fiore 16:b630e18103e5 6 *
Mike Fiore 16:b630e18103e5 7 *
Mike Fiore 16:b630e18103e5 8 * @author Jason Reiss
Mike Fiore 16:b630e18103e5 9 * @date 10-31-2015
Mike Fiore 16:b630e18103e5 10 * @brief lora::Mote provides a user level class that abstracts the complexity of the Mac layer
Mike Fiore 16:b630e18103e5 11 *
Mike Fiore 16:b630e18103e5 12 * @details
Mike Fiore 16:b630e18103e5 13 *
Mike Fiore 16:b630e18103e5 14 */
Mike Fiore 16:b630e18103e5 15
Mike Fiore 16:b630e18103e5 16 #ifndef __LORA_MOTE_H__
Mike Fiore 16:b630e18103e5 17 #define __LORA_MOTE_H__
Mike Fiore 16:b630e18103e5 18
Mike Fiore 16:b630e18103e5 19 #include "rtos.h"
Mike Fiore 16:b630e18103e5 20 #include "MacEvents.h"
Mike Fiore 16:b630e18103e5 21 #include <vector>
Mike Fiore 16:b630e18103e5 22
Mike Fiore 16:b630e18103e5 23 class SxRadio;
Mike Fiore 16:b630e18103e5 24 class SxRadio1272;
Mike Fiore 16:b630e18103e5 25
Mike Fiore 16:b630e18103e5 26 namespace lora {
Mike Fiore 16:b630e18103e5 27
Mike Fiore 16:b630e18103e5 28 class Mac;
Mike Fiore 16:b630e18103e5 29 class ChannelPlan;
Mike Fiore 16:b630e18103e5 30
Mike Fiore 16:b630e18103e5 31 class MoteEvents: public MacEvents {
Mike Fiore 16:b630e18103e5 32
Mike Fiore 16:b630e18103e5 33 /**
Mike Fiore 16:b630e18103e5 34 * Fired at end of TX
Mike Fiore 16:b630e18103e5 35 * @param dr datarate used for TX
Mike Fiore 16:b630e18103e5 36 */
Mike Fiore 16:b630e18103e5 37 virtual void TxDone(uint8_t dr);
Mike Fiore 16:b630e18103e5 38
Mike Fiore 16:b630e18103e5 39 /**
Mike Fiore 16:b630e18103e5 40 * Fired if TX timed out
Mike Fiore 16:b630e18103e5 41 */
Mike Fiore 16:b630e18103e5 42 virtual void TxTimeout(void);
Mike Fiore 16:b630e18103e5 43
Mike Fiore 16:b630e18103e5 44 /**
Mike Fiore 16:b630e18103e5 45 * Fired when JoinAccept message is received and MIC is validated
Mike Fiore 16:b630e18103e5 46 * @param payload received bytes
Mike Fiore 16:b630e18103e5 47 * @param size number of received bytes
Mike Fiore 16:b630e18103e5 48 * @param rssi of received packet
Mike Fiore 16:b630e18103e5 49 * @param snr of received packet
Mike Fiore 16:b630e18103e5 50 */
Mike Fiore 16:b630e18103e5 51 virtual void JoinAccept(uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr);
Mike Fiore 16:b630e18103e5 52
Mike Fiore 16:b630e18103e5 53 /**
Mike Fiore 16:b630e18103e5 54 * Fired when JoinAccept message is received and MIC is not valid
Mike Fiore 16:b630e18103e5 55 * @param payload received bytes
Mike Fiore 16:b630e18103e5 56 * @param size number of received bytes
Mike Fiore 16:b630e18103e5 57 * @param rssi of received packet
Mike Fiore 16:b630e18103e5 58 * @param snr of received packet
Mike Fiore 16:b630e18103e5 59 */
Mike Fiore 16:b630e18103e5 60 virtual void JoinFailed(uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr);
Mike Fiore 16:b630e18103e5 61
Mike Fiore 16:b630e18103e5 62 /**
Mike Fiore 16:b630e18103e5 63 * Fired when non duplicate packet is received and MIC is valid
Mike Fiore 16:b630e18103e5 64 * @param port of packet
Mike Fiore 16:b630e18103e5 65 * @param payload received bytes
Mike Fiore 16:b630e18103e5 66 * @param size number of received bytes
Mike Fiore 16:b630e18103e5 67 * @param rssi of received packet
Mike Fiore 16:b630e18103e5 68 * @param snr of received packet
Mike Fiore 16:b630e18103e5 69 * @param ctrl Downlink control field of packet
Mike Fiore 16:b630e18103e5 70 * @param slot rx window packet was received
Mike Fiore 16:b630e18103e5 71 * @param retries number of attempts before ack was received
Mike Fiore 16:b630e18103e5 72 */
Mike Fiore 16:b630e18103e5 73 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);
Mike Fiore 16:b630e18103e5 74
Mike Fiore 16:b630e18103e5 75 /**
Mike Fiore 16:b630e18103e5 76 * Fired when radio has received a packet, packet is not validated
Mike Fiore 16:b630e18103e5 77 * @param payload received bytes
Mike Fiore 16:b630e18103e5 78 * @param size number of received bytes
Mike Fiore 16:b630e18103e5 79 * @param rssi of received packet
Mike Fiore 16:b630e18103e5 80 * @param snr of received packet
Mike Fiore 16:b630e18103e5 81 * @param ctrl Downlink control field of packet
Mike Fiore 16:b630e18103e5 82 * @param slot rx window packet was received
Mike Fiore 16:b630e18103e5 83 */
Mike Fiore 16:b630e18103e5 84 virtual void RxDone(uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr, lora::DownlinkControl ctrl, uint8_t slot);
Mike Fiore 16:b630e18103e5 85
Mike Fiore 16:b630e18103e5 86 /**
Mike Fiore 16:b630e18103e5 87 * Fired if rx window times out
Mike Fiore 16:b630e18103e5 88 * @param slot rx window that timed out
Mike Fiore 16:b630e18103e5 89 */
Mike Fiore 16:b630e18103e5 90 virtual void RxTimeout(uint8_t slot);
Mike Fiore 16:b630e18103e5 91
Mike Fiore 16:b630e18103e5 92 /**
Mike Fiore 16:b630e18103e5 93 * Fired if rx CRC error
Mike Fiore 16:b630e18103e5 94 * @param slot rx window that errored
Mike Fiore 16:b630e18103e5 95 */
Mike Fiore 16:b630e18103e5 96 virtual void RxError(uint8_t slot);
Mike Fiore 16:b630e18103e5 97
Mike Fiore 16:b630e18103e5 98 /**
Mike Fiore 16:b630e18103e5 99 * Fired if pong packet is received
Mike Fiore 16:b630e18103e5 100 * @param m_rssi of received packet at mote
Mike Fiore 16:b630e18103e5 101 * @param m_snr of received packet at mote
Mike Fiore 16:b630e18103e5 102 * @param s_rssi of received packet at server
Mike Fiore 16:b630e18103e5 103 * @param s_snr of received packet at server
Mike Fiore 16:b630e18103e5 104 */
Mike Fiore 16:b630e18103e5 105 virtual void Pong(int16_t m_rssi, int8_t m_snr, int16_t s_rssi, int8_t s_snr);
Mike Fiore 16:b630e18103e5 106
Mike Fiore 16:b630e18103e5 107 /**
Mike Fiore 16:b630e18103e5 108 * Fired if network link check answer is received
Mike Fiore 16:b630e18103e5 109 * @param m_rssi of received packet at mote
Mike Fiore 16:b630e18103e5 110 * @param m_snr of received packet at mote
Mike Fiore 16:b630e18103e5 111 * @param s_snr margin of received packet at server
Mike Fiore 16:b630e18103e5 112 * @param s_gateways number of gateways reporting the packet
Mike Fiore 16:b630e18103e5 113 */
Mike Fiore 16:b630e18103e5 114 virtual void NetworkLinkCheck(int16_t m_rssi, int8_t m_snr, int8_t s_snr, uint8_t s_gateways);
Mike Fiore 16:b630e18103e5 115
Mike Fiore 16:b630e18103e5 116 /**
Mike Fiore 16:b630e18103e5 117 * Callback to for device to measure the battery level and report to server
Mike Fiore 16:b630e18103e5 118 * @return battery level 0-255, 0 - external power, 1-254 level min-max, 255 device unable to measure battery
Mike Fiore 16:b630e18103e5 119 */
Mike Fiore 16:b630e18103e5 120 virtual uint8_t MeasureBattery();
Jenkins@KEILDM1.dc.multitech.prv 26:17479e0039f6 121
Jenkins@KEILDM1.dc.multitech.prv 26:17479e0039f6 122 /**
Jenkins@KEILDM1.dc.multitech.prv 26:17479e0039f6 123 * Fired when ack attempts are exhausted and RxTimeout or RxError occur
Jenkins@KEILDM1.dc.multitech.prv 26:17479e0039f6 124 * @param retries number of attempts to resend the packet
Jenkins@KEILDM1.dc.multitech.prv 26:17479e0039f6 125 */
Jenkins@KEILDM1.dc.multitech.prv 26:17479e0039f6 126 virtual void MissedAck(uint8_t retries);
Mike Fiore 16:b630e18103e5 127 };
Mike Fiore 16:b630e18103e5 128
Mike Fiore 16:b630e18103e5 129 class Mote {
Mike Fiore 16:b630e18103e5 130 public:
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 131 Mote(Settings* settings, ChannelPlan* plan);
Mike Fiore 16:b630e18103e5 132 virtual ~Mote();
Mike Fiore 16:b630e18103e5 133
Mike Fiore 16:b630e18103e5 134 /**
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 135 * MTS LoRa version
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 136 * @return string containing version information
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 137 */
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 138 const char* getId();
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 139
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 140 /**
Mike Fiore 16:b630e18103e5 141 * Indicator for network session join status
Mike Fiore 16:b630e18103e5 142 * @return true if joined to network
Mike Fiore 16:b630e18103e5 143 */
Mike Fiore 16:b630e18103e5 144 bool Joined();
Mike Fiore 16:b630e18103e5 145
Mike Fiore 16:b630e18103e5 146 /**
Mike Fiore 16:b630e18103e5 147 * Send join request
Mike Fiore 16:b630e18103e5 148 * @return LORA_OK if request was sent
Mike Fiore 16:b630e18103e5 149 */
Mike Fiore 16:b630e18103e5 150 uint8_t Join();
Mike Fiore 16:b630e18103e5 151
Mike Fiore 16:b630e18103e5 152 /**
Mike Fiore 16:b630e18103e5 153 * Send a packet
Mike Fiore 16:b630e18103e5 154 * @param port to send packet
Mike Fiore 16:b630e18103e5 155 * @param payload of packet
Mike Fiore 16:b630e18103e5 156 * @param size in bytes
Mike Fiore 16:b630e18103e5 157 * @return LORA_OK if successful
Mike Fiore 16:b630e18103e5 158 * @return LORA_MAX_PAYLOAD_EXCEEDED if payload size exceeds datarate maximum
Mike Fiore 16:b630e18103e5 159 * @return LORA_NO_CHANS_ENABLED if there is not an available channel that supports the current datarate
Mike Fiore 16:b630e18103e5 160 * @return LORA_LINK_BUSY if link was busy
Mike Fiore 16:b630e18103e5 161 * @return LORA_RADIO_BUSY if radio was busy
Mike Fiore 16:b630e18103e5 162 * @return LORA_BUFFER_FULL if mac commands filled the packet, client should resend the packet
Mike Fiore 16:b630e18103e5 163 */
Mike Fiore 16:b630e18103e5 164 uint8_t Send(uint8_t port, const uint8_t* payload, uint8_t size);
Mike Fiore 16:b630e18103e5 165
Mike Fiore 16:b630e18103e5 166 /**
Mike Fiore 16:b630e18103e5 167 * Configure the channel plan
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 168 * @param plan pointer to ChannelPlan object
Mike Fiore 16:b630e18103e5 169 * @return LORA_OK
Mike Fiore 16:b630e18103e5 170 */
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 171 uint8_t SetChannelPlan(ChannelPlan* plan);
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 172
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 173 Settings* GetSettings();
Mike Fiore 16:b630e18103e5 174
Mike Fiore 16:b630e18103e5 175 /**
Mike Fiore 16:b630e18103e5 176 * Get the channel mask of currently enabled channels
Mike Fiore 16:b630e18103e5 177 * @return vector containing channel bit masks
Mike Fiore 16:b630e18103e5 178 */
Mike Fiore 16:b630e18103e5 179 std::vector<uint16_t> GetChannelMask();
Mike Fiore 16:b630e18103e5 180
Mike Fiore 16:b630e18103e5 181 /**
Mike Fiore 16:b630e18103e5 182 * Set a 16 bit channel mask with index
Mike Fiore 16:b630e18103e5 183 * @param index of mask to set 0:0-15, 1:16-31 ...
Mike Fiore 16:b630e18103e5 184 * @param mask 16 bit mask of enabled channels
Mike Fiore 16:b630e18103e5 185 * @return true
Mike Fiore 16:b630e18103e5 186 */
Mike Fiore 16:b630e18103e5 187 virtual uint8_t SetChannelMask(uint8_t index, uint16_t mask);
Mike Fiore 16:b630e18103e5 188
Mike Fiore 16:b630e18103e5 189 /**
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 190 * Set the current frequency sub band for hybrid operation 1-8 else 0 for 64 channel operation
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 191 * @param sub_band 0-8
Mike Fiore 16:b630e18103e5 192 */
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 193 uint8_t SetFrequencySubBand(uint8_t sub_band);
Mike Fiore 16:b630e18103e5 194
Mike Fiore 16:b630e18103e5 195 /**
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 196 * Get the current frequency sub band
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 197 * @return sub band 0-8
Mike Fiore 16:b630e18103e5 198 */
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 199 uint8_t GetFrequencySubBand();
Mike Fiore 16:b630e18103e5 200
Mike Fiore 16:b630e18103e5 201 /**
Mike Fiore 16:b630e18103e5 202 * Add a channel to the channel plan
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 203 * EU868, AS923 and KR920 allows additional channels to be added
Mike Fiore 16:b630e18103e5 204 * Channels 0-2 are fixed default channels
Mike Fiore 16:b630e18103e5 205 *
Mike Fiore 16:b630e18103e5 206 * @param index of the channel
Mike Fiore 16:b630e18103e5 207 * @param frequency of the channel or 0 to remove channel
Mike Fiore 16:b630e18103e5 208 * @param range of datarates allowed by the channel
Mike Fiore 16:b630e18103e5 209 * @return LORA_OK if channel was added
Mike Fiore 16:b630e18103e5 210 */
Mike Fiore 16:b630e18103e5 211 uint8_t AddChannel(uint8_t index, uint32_t frequency, lora::DatarateRange range);
Mike Fiore 16:b630e18103e5 212
Mike Fiore 16:b630e18103e5 213 /**
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 214 * Add a downlink channel to the channel plan
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 215 * EU868, AS923 and KR920 allows downlink channels to be added
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 216 *
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 217 * @param index of the channel
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 218 * @param frequency of the channel or 0 to remove channel
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 219 * @return LORA_OK if channel was added
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 220 */
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 221 uint8_t AddDownlinkChannel(uint8_t index, uint32_t frequency);
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 222
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 223 /**
Mike Fiore 16:b630e18103e5 224 * Set network mode
Mike Fiore 16:b630e18103e5 225 * Choose Public LoRaWAN mode or Private Multitech mode
Mike Fiore 16:b630e18103e5 226 *
Mike Fiore 16:b630e18103e5 227 * Public mode uses 0x34 sync word with 5/6 second join windows
Mike Fiore 16:b630e18103e5 228 * Private mode uses 0x12 sync word with 1/2 second join windows
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 229 * US915/AU915 Rx1 and Rx2 are fixed per frequency sub band setting
Mike Fiore 16:b630e18103e5 230 *
Mike Fiore 16:b630e18103e5 231 * @param mode public or private
Mike Fiore 16:b630e18103e5 232 * @return LORA_OK
Mike Fiore 16:b630e18103e5 233 */
Mike Fiore 16:b630e18103e5 234 uint8_t SetNetworkMode(uint8_t mode);
Mike Fiore 16:b630e18103e5 235
Mike Fiore 16:b630e18103e5 236 /**
Mike Fiore 16:b630e18103e5 237 * Get a pointer to the mac layer
Mike Fiore 16:b630e18103e5 238 * @return Mac mac
Mike Fiore 16:b630e18103e5 239 */
Mike Fiore 16:b630e18103e5 240 Mac* GetMac();
Mike Fiore 16:b630e18103e5 241
Mike Fiore 16:b630e18103e5 242 /**
Mike Fiore 16:b630e18103e5 243 * Get a pointer to the radio
Mike Fiore 16:b630e18103e5 244 * Can be used to read radio registers or get a random value based on RSSI
Mike Fiore 16:b630e18103e5 245 *
Mike Fiore 16:b630e18103e5 246 * @return SxRadio pointer
Mike Fiore 16:b630e18103e5 247 */
Mike Fiore 16:b630e18103e5 248 SxRadio* GetRadio();
Mike Fiore 16:b630e18103e5 249
Mike Fiore 16:b630e18103e5 250 /**
Mike Fiore 16:b630e18103e5 251 * Get the current statistics for the device
Mike Fiore 16:b630e18103e5 252 * @return Statistics
Mike Fiore 16:b630e18103e5 253 */
Mike Fiore 16:b630e18103e5 254 Statistics& GetStats();
Mike Fiore 16:b630e18103e5 255
Mike Fiore 16:b630e18103e5 256 /**
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 257 * Reset the current statistics for the device
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 258 */
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 259 void ResetStats();
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 260
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 261 /**
Mike Fiore 16:b630e18103e5 262 * Get time on air with current settings for provided payload bytes
Mike Fiore 16:b630e18103e5 263 * 13 overhead bytes will be added to payload
Mike Fiore 16:b630e18103e5 264 * @param bytes of payload data
Mike Fiore 16:b630e18103e5 265 * @return time-on-air in ms
Mike Fiore 16:b630e18103e5 266 */
Mike Fiore 16:b630e18103e5 267 uint32_t GetTimeOnAir(uint8_t bytes);
Mike Fiore 16:b630e18103e5 268
Mike Fiore 16:b630e18103e5 269 /**
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 270 * Get time off air required to adhere to duty-cycle limitations
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 271 * @return time-off-air in ms
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 272 */
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 273 uint32_t GetTimeOffAir();
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 274
Jenkins@KEILDM1.dc.multitech.prv 60:7985b4783af9 275 /**
Mike Fiore 16:b630e18103e5 276 * Call before setting device in sleep mode to place radio in sleep
Mike Fiore 16:b630e18103e5 277 */
Mike Fiore 16:b630e18103e5 278 void Sleep();
Mike Fiore 16:b630e18103e5 279
Mike Fiore 16:b630e18103e5 280 protected:
Mike Fiore 16:b630e18103e5 281 SxRadio1272* _radio;
Mike Fiore 16:b630e18103e5 282 Settings* _settings;
Mike Fiore 16:b630e18103e5 283 Mac* _mac;
Mike Fiore 16:b630e18103e5 284
Mike Fiore 16:b630e18103e5 285 private:
Mike Fiore 16:b630e18103e5 286 ChannelPlan* _plan;
Mike Fiore 16:b630e18103e5 287 MoteEvents _events;
Mike Fiore 16:b630e18103e5 288 };
Mike Fiore 16:b630e18103e5 289
Mike Fiore 16:b630e18103e5 290 }
Mike Fiore 16:b630e18103e5 291 #endif