Eliott Fersko / libmDot-mbed5

libmDot0mbed5

Fork of libmDot-mbed5 by MultiTech

Mote.h@60:d58af0eae613, 2017-07-13 (annotated)

Committer:
efersko
Date:
Thu Jul 13 19:03:33 2017 +0000
Revision:
60:d58af0eae613
Parent:
26:17479e0039f6 
No change

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:
Mike Fiore 16:b630e18103e5 131 Mote(Settings* settings);
Mike Fiore 16:b630e18103e5 132 virtual ~Mote();
Mike Fiore 16:b630e18103e5 133
Mike Fiore 16:b630e18103e5 134 /**
Mike Fiore 16:b630e18103e5 135 * Indicator for network session join status
Mike Fiore 16:b630e18103e5 136 * @return true if joined to network
Mike Fiore 16:b630e18103e5 137 */
Mike Fiore 16:b630e18103e5 138 bool Joined();
Mike Fiore 16:b630e18103e5 139
Mike Fiore 16:b630e18103e5 140 /**
Mike Fiore 16:b630e18103e5 141 * Send join request
Mike Fiore 16:b630e18103e5 142 * @return LORA_OK if request was sent
Mike Fiore 16:b630e18103e5 143 */
Mike Fiore 16:b630e18103e5 144 uint8_t Join();
Mike Fiore 16:b630e18103e5 145
Mike Fiore 16:b630e18103e5 146 /**
Mike Fiore 16:b630e18103e5 147 * Send a packet
Mike Fiore 16:b630e18103e5 148 * @param port to send packet
Mike Fiore 16:b630e18103e5 149 * @param payload of packet
Mike Fiore 16:b630e18103e5 150 * @param size in bytes
Mike Fiore 16:b630e18103e5 151 * @return LORA_OK if successful
Mike Fiore 16:b630e18103e5 152 * @return LORA_MAX_PAYLOAD_EXCEEDED if payload size exceeds datarate maximum
Mike Fiore 16:b630e18103e5 153 * @return LORA_NO_CHANS_ENABLED if there is not an available channel that supports the current datarate
Mike Fiore 16:b630e18103e5 154 * @return LORA_LINK_BUSY if link was busy
Mike Fiore 16:b630e18103e5 155 * @return LORA_RADIO_BUSY if radio was busy
Mike Fiore 16:b630e18103e5 156 * @return LORA_BUFFER_FULL if mac commands filled the packet, client should resend the packet
Mike Fiore 16:b630e18103e5 157 */
Mike Fiore 16:b630e18103e5 158 uint8_t Send(uint8_t port, const uint8_t* payload, uint8_t size);
Mike Fiore 16:b630e18103e5 159
Mike Fiore 16:b630e18103e5 160 /**
Mike Fiore 16:b630e18103e5 161 * Configure the channel plan
Mike Fiore 16:b630e18103e5 162 * @param freqBand EU868, US915, AU915
Mike Fiore 16:b630e18103e5 163 * @return LORA_OK
Mike Fiore 16:b630e18103e5 164 */
Mike Fiore 16:b630e18103e5 165 uint8_t SetChannelPlan(uint8_t freqBand);
Mike Fiore 16:b630e18103e5 166
Mike Fiore 16:b630e18103e5 167 /**
Mike Fiore 16:b630e18103e5 168 * Get the channel mask of currently enabled channels
Mike Fiore 16:b630e18103e5 169 * @return vector containing channel bit masks
Mike Fiore 16:b630e18103e5 170 */
Mike Fiore 16:b630e18103e5 171 std::vector<uint16_t> GetChannelMask();
Mike Fiore 16:b630e18103e5 172
Mike Fiore 16:b630e18103e5 173 /**
Mike Fiore 16:b630e18103e5 174 * Set a 16 bit channel mask with index
Mike Fiore 16:b630e18103e5 175 * @param index of mask to set 0:0-15, 1:16-31 ...
Mike Fiore 16:b630e18103e5 176 * @param mask 16 bit mask of enabled channels
Mike Fiore 16:b630e18103e5 177 * @return true
Mike Fiore 16:b630e18103e5 178 */
Mike Fiore 16:b630e18103e5 179 virtual uint8_t SetChannelMask(uint8_t index, uint16_t mask);
Mike Fiore 16:b630e18103e5 180
Mike Fiore 16:b630e18103e5 181 /**
Mike Fiore 16:b630e18103e5 182 * Set the current channel group for hybrid operation 1-8 else 0 for 64 channel operation
Mike Fiore 16:b630e18103e5 183 * @param group 0-8
Mike Fiore 16:b630e18103e5 184 */
Mike Fiore 16:b630e18103e5 185 uint8_t SetChannelGroup(uint8_t group);
Mike Fiore 16:b630e18103e5 186
Mike Fiore 16:b630e18103e5 187 /**
Mike Fiore 16:b630e18103e5 188 * Get the current channel group
Mike Fiore 16:b630e18103e5 189 * @return group 0-8
Mike Fiore 16:b630e18103e5 190 */
Mike Fiore 16:b630e18103e5 191 uint8_t GetChannelGroup();
Mike Fiore 16:b630e18103e5 192
Mike Fiore 16:b630e18103e5 193 /**
Mike Fiore 16:b630e18103e5 194 * Add a channel to the channel plan
Mike Fiore 16:b630e18103e5 195 * EU868 allows additional channels to be added
Mike Fiore 16:b630e18103e5 196 * Channels 0-2 are fixed default channels
Mike Fiore 16:b630e18103e5 197 *
Mike Fiore 16:b630e18103e5 198 * @param index of the channel
Mike Fiore 16:b630e18103e5 199 * @param frequency of the channel or 0 to remove channel
Mike Fiore 16:b630e18103e5 200 * @param range of datarates allowed by the channel
Mike Fiore 16:b630e18103e5 201 * @return LORA_OK if channel was added
Mike Fiore 16:b630e18103e5 202 */
Mike Fiore 16:b630e18103e5 203 uint8_t AddChannel(uint8_t index, uint32_t frequency, lora::DatarateRange range);
Mike Fiore 16:b630e18103e5 204
Mike Fiore 16:b630e18103e5 205 /**
Mike Fiore 16:b630e18103e5 206 * Set network mode
Mike Fiore 16:b630e18103e5 207 * Choose Public LoRaWAN mode or Private Multitech mode
Mike Fiore 16:b630e18103e5 208 *
Mike Fiore 16:b630e18103e5 209 * Public mode uses 0x34 sync word with 5/6 second join windows
Mike Fiore 16:b630e18103e5 210 * Private mode uses 0x12 sync word with 1/2 second join windows
Mike Fiore 16:b630e18103e5 211 * US915/AU915 Rx1 and Rx2 are fixed per Channel Group setting
Mike Fiore 16:b630e18103e5 212 *
Mike Fiore 16:b630e18103e5 213 * @param mode public or private
Mike Fiore 16:b630e18103e5 214 * @return LORA_OK
Mike Fiore 16:b630e18103e5 215 */
Mike Fiore 16:b630e18103e5 216 uint8_t SetNetworkMode(uint8_t mode);
Mike Fiore 16:b630e18103e5 217
Mike Fiore 16:b630e18103e5 218 /**
Mike Fiore 16:b630e18103e5 219 * Get a pointer to the mac layer
Mike Fiore 16:b630e18103e5 220 * @return Mac mac
Mike Fiore 16:b630e18103e5 221 */
Mike Fiore 16:b630e18103e5 222 Mac* GetMac();
Mike Fiore 16:b630e18103e5 223
Mike Fiore 16:b630e18103e5 224 /**
Mike Fiore 16:b630e18103e5 225 * Get a pointer to the radio
Mike Fiore 16:b630e18103e5 226 * Can be used to read radio registers or get a random value based on RSSI
Mike Fiore 16:b630e18103e5 227 *
Mike Fiore 16:b630e18103e5 228 * @return SxRadio pointer
Mike Fiore 16:b630e18103e5 229 */
Mike Fiore 16:b630e18103e5 230 SxRadio* GetRadio();
Mike Fiore 16:b630e18103e5 231
Mike Fiore 16:b630e18103e5 232 /**
Mike Fiore 16:b630e18103e5 233 * Get the current statistics for the device
Mike Fiore 16:b630e18103e5 234 * @return Statistics
Mike Fiore 16:b630e18103e5 235 */
Mike Fiore 16:b630e18103e5 236 Statistics& GetStats();
Mike Fiore 16:b630e18103e5 237
Mike Fiore 16:b630e18103e5 238 /**
Mike Fiore 16:b630e18103e5 239 * Get time on air with current settings for provided payload bytes
Mike Fiore 16:b630e18103e5 240 * 13 overhead bytes will be added to payload
Mike Fiore 16:b630e18103e5 241 * @param bytes of payload data
Mike Fiore 16:b630e18103e5 242 * @return time-on-air in ms
Mike Fiore 16:b630e18103e5 243 */
Mike Fiore 16:b630e18103e5 244 uint32_t GetTimeOnAir(uint8_t bytes);
Mike Fiore 16:b630e18103e5 245
Mike Fiore 16:b630e18103e5 246 /**
Mike Fiore 16:b630e18103e5 247 * Call before setting device in sleep mode to place radio in sleep
Mike Fiore 16:b630e18103e5 248 */
Mike Fiore 16:b630e18103e5 249 void Sleep();
Mike Fiore 16:b630e18103e5 250
Mike Fiore 16:b630e18103e5 251 protected:
Mike Fiore 16:b630e18103e5 252 SxRadio1272* _radio;
Mike Fiore 16:b630e18103e5 253 Settings* _settings;
Mike Fiore 16:b630e18103e5 254 Mac* _mac;
Mike Fiore 16:b630e18103e5 255
Mike Fiore 16:b630e18103e5 256 private:
Mike Fiore 16:b630e18103e5 257 ChannelPlan* _plan;
Mike Fiore 16:b630e18103e5 258 MoteEvents _events;
Mike Fiore 16:b630e18103e5 259 };
Mike Fiore 16:b630e18103e5 260
Mike Fiore 16:b630e18103e5 261 }
Mike Fiore 16:b630e18103e5 262 #endif