MultiTech / libmDot

Library for LoRa communication using MultiTech MDOT.

Dependents:   mDot_test_rx adc_sensor_lora mDotEVBM2X mDot_AT_firmware ... more

Function documentation is in mDot.h

Warning

Using libmDot 2.0.3 and above with an existing application may require a change in the MacEvent handler!
Compile applications with mbed v121 and mbed-rtos v116 libraries.

In AT Command Firmware remove line 803.

CommandTerminal/CommandTerminal.cpp

        delete[] info->RxBuffer;

Likewise, if your application is handling events from the library asynchronously.

Mote.h@15:b50f92f1c6ff, 2016-08-18 (annotated)

Committer:
jreiss
Date:
Thu Aug 18 16:07:10 2016 +0000
Revision:
15:b50f92f1c6ff
update libmDot to 2.0.3

Who changed what in which revision?

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