Eliott Fersko / libmDot-mbed5

libmDot0mbed5

Fork of libmDot-mbed5 by MultiTech

mDot.h@6:390fc83d588d, 2015-07-16 (annotated)

Committer:
Mike Fiore
Date:
Thu Jul 16 16:41:08 2015 -0500
Revision:
6:390fc83d588d
Parent:
5:0bfe6a650513
Child:
7:683dba5d576f
update from rev 0310fa23bc9c37c0575342961eac26e61d0966f4. NOTE: this version breaks compatibility with older MTS network server versions - use setJoinByteOrder(mDot::MSB) if operating with a network server version earlier than 0.0.5 or AEP 1.0.30

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Mike Fiore 6:390fc83d588d 1 // TODO: add license header
mfiore 0:c62615f15125 2
mfiore 0:c62615f15125 3 #ifndef MDOT_H
mfiore 0:c62615f15125 4 #define MDOT_H
mfiore 0:c62615f15125 5
mfiore 0:c62615f15125 6 #include "mbed.h"
mfiore 0:c62615f15125 7 #include "rtos.h"
mfiore 0:c62615f15125 8 #include <vector>
mfiore 0:c62615f15125 9 #include <map>
mfiore 0:c62615f15125 10 #include <string>
mfiore 0:c62615f15125 11
mfiore 0:c62615f15125 12 class LoRaMacEvent;
mfiore 0:c62615f15125 13 class LoRaConfig;
mfiore 0:c62615f15125 14 class LoRaMac;
mfiore 0:c62615f15125 15 class MdotRadio;
mfiore 0:c62615f15125 16
mfiore 0:c62615f15125 17
mfiore 0:c62615f15125 18 class mDot {
mfiore 0:c62615f15125 19
mfiore 0:c62615f15125 20 private:
mfiore 0:c62615f15125 21
mfiore 0:c62615f15125 22 mDot();
mfiore 0:c62615f15125 23 ~mDot();
mfiore 0:c62615f15125 24
mfiore 0:c62615f15125 25 static void idle(void const* args) {
mfiore 0:c62615f15125 26 while (1)
mfiore 0:c62615f15125 27 __WFI();
mfiore 0:c62615f15125 28 }
mfiore 0:c62615f15125 29
mfiore 0:c62615f15125 30 void setLastError(const std::string& str);
mfiore 0:c62615f15125 31
mfiore 0:c62615f15125 32 static bool validateBaudRate(const uint32_t& baud);
mfiore 0:c62615f15125 33 static bool validateFrequencySubBand(const uint8_t& band);
mfiore 0:c62615f15125 34 bool validateDataRate(const uint8_t& dr);
mfiore 0:c62615f15125 35
mfiore 0:c62615f15125 36 int32_t joinBase(const uint32_t& retries);
mfiore 0:c62615f15125 37 int32_t sendBase(const std::vector<uint8_t>& data, const bool& confirmed = false, const bool& blocking = true, const bool& highBw = false);
mfiore 0:c62615f15125 38 void waitForPacket();
mfiore 0:c62615f15125 39 void waitForLinkCheck();
mfiore 0:c62615f15125 40
mfiore 0:c62615f15125 41 void setActivityLedState(const uint8_t& state);
mfiore 0:c62615f15125 42 uint8_t getActivityLedState();
mfiore 0:c62615f15125 43
mfiore 0:c62615f15125 44 void blinkActivityLed(void) {
Mike Fiore 6:390fc83d588d 45 if (_activity_led) {
Mike Fiore 6:390fc83d588d 46 int val = _activity_led->read();
Mike Fiore 6:390fc83d588d 47 _activity_led->write(!val);
Mike Fiore 6:390fc83d588d 48 }
mfiore 0:c62615f15125 49 }
mfiore 0:c62615f15125 50
mfiore 0:c62615f15125 51 mDot(const mDot&);
mfiore 0:c62615f15125 52 mDot& operator=(const mDot&);
mfiore 0:c62615f15125 53
mfiore 0:c62615f15125 54 static mDot* _instance;
mfiore 0:c62615f15125 55
mfiore 0:c62615f15125 56 LoRaMac* _mac;
mfiore 0:c62615f15125 57 MdotRadio* _radio;
mfiore 0:c62615f15125 58 LoRaMacEvent* _events;
mfiore 0:c62615f15125 59 LoRaConfig* _config;
mfiore 0:c62615f15125 60 Thread _idle_thread;
mfiore 0:c62615f15125 61 std::string _last_error;
mfiore 0:c62615f15125 62 static const uint32_t _baud_rates[];
mfiore 0:c62615f15125 63 uint8_t _activity_led_state;
mfiore 0:c62615f15125 64 Ticker _tick;
Mike Fiore 6:390fc83d588d 65 DigitalOut* _activity_led;
Mike Fiore 6:390fc83d588d 66 bool _activity_led_enable;
Mike Fiore 6:390fc83d588d 67 PinName _activity_led_pin;
Mike Fiore 5:0bfe6a650513 68 bool _activity_led_external;
mfiore 0:c62615f15125 69 uint16_t _linkFailCount;
mfiore 0:c62615f15125 70
mfiore 0:c62615f15125 71 typedef enum {
mfiore 0:c62615f15125 72 OFF, ON, BLINK,
mfiore 0:c62615f15125 73 } state;
mfiore 0:c62615f15125 74
mfiore 0:c62615f15125 75 public:
mfiore 0:c62615f15125 76
mfiore 0:c62615f15125 77 typedef enum {
mfiore 0:c62615f15125 78 MDOT_OK = 0,
mfiore 0:c62615f15125 79 MDOT_INVALID_PARAM = -1,
mfiore 0:c62615f15125 80 MDOT_TX_ERROR = -2,
mfiore 0:c62615f15125 81 MDOT_RX_ERROR = -3,
mfiore 0:c62615f15125 82 MDOT_JOIN_ERROR = -4,
mfiore 0:c62615f15125 83 MDOT_TIMEOUT = -5,
mfiore 0:c62615f15125 84 MDOT_NOT_JOINED = -6,
mfiore 0:c62615f15125 85 MDOT_ENCRYPTION_DISABLED = -7,
mfiore 0:c62615f15125 86 MDOT_NO_FREE_CHAN = -8,
mfiore 0:c62615f15125 87 MDOT_ERROR = -1024,
mfiore 0:c62615f15125 88 } mdot_ret_code;
mfiore 0:c62615f15125 89
mfiore 0:c62615f15125 90 enum JoinMode {
mfiore 0:c62615f15125 91 MANUAL, OTA, AUTO_OTA
mfiore 0:c62615f15125 92 };
mfiore 0:c62615f15125 93
mfiore 0:c62615f15125 94 enum Mode {
mfiore 0:c62615f15125 95 COMMAND_MODE, SERIAL_MODE
mfiore 0:c62615f15125 96 };
mfiore 0:c62615f15125 97
mfiore 0:c62615f15125 98 enum RX_Output {
mfiore 0:c62615f15125 99 HEXADECIMAL, BINARY
mfiore 0:c62615f15125 100 };
mfiore 0:c62615f15125 101
mfiore 0:c62615f15125 102 enum DataRates {
mfiore 0:c62615f15125 103 SF_12, SF_11, SF_10, SF_9, SF_8, SF_7, SF_7H, SF_50
mfiore 0:c62615f15125 104 };
mfiore 0:c62615f15125 105
mfiore 0:c62615f15125 106 enum FrequencyBands {
mfiore 0:c62615f15125 107 FB_868, FB_915
mfiore 0:c62615f15125 108 };
mfiore 0:c62615f15125 109
mfiore 0:c62615f15125 110 enum FrequencySubBands {
mfiore 0:c62615f15125 111 FSB_ALL, FSB_1, FSB_2, FSB_3, FSB_4, FSB_5, FSB_6, FSB_7, FSB_8
mfiore 0:c62615f15125 112 };
mfiore 0:c62615f15125 113
Mike Fiore 6:390fc83d588d 114 enum JoinByteOrder {
Mike Fiore 6:390fc83d588d 115 LSB, MSB
Mike Fiore 6:390fc83d588d 116 };
Mike Fiore 6:390fc83d588d 117
mfiore 0:c62615f15125 118 typedef struct {
mfiore 0:c62615f15125 119 uint32_t Up;
mfiore 0:c62615f15125 120 uint32_t Down;
mfiore 0:c62615f15125 121 uint32_t Joins;
mfiore 0:c62615f15125 122 uint32_t JoinFails;
mfiore 0:c62615f15125 123 uint32_t MissedAcks;
mfiore 0:c62615f15125 124 } mdot_stats;
mfiore 0:c62615f15125 125
mfiore 0:c62615f15125 126 typedef struct {
mfiore 0:c62615f15125 127 int16_t last;
mfiore 0:c62615f15125 128 int16_t min;
mfiore 0:c62615f15125 129 int16_t max;
mfiore 0:c62615f15125 130 int16_t avg;
mfiore 0:c62615f15125 131 } rssi_stats;
mfiore 0:c62615f15125 132
mfiore 0:c62615f15125 133 typedef struct {
mfiore 0:c62615f15125 134 int8_t last;
mfiore 0:c62615f15125 135 int8_t min;
mfiore 0:c62615f15125 136 int8_t max;
mfiore 0:c62615f15125 137 int8_t avg;
mfiore 0:c62615f15125 138 } snr_stats;
mfiore 0:c62615f15125 139
mfiore 0:c62615f15125 140 typedef struct {
mfiore 0:c62615f15125 141 bool status;
mfiore 0:c62615f15125 142 int32_t dBm;
mfiore 0:c62615f15125 143 uint32_t gateways;
mfiore 0:c62615f15125 144 std::vector<uint8_t> payload;
mfiore 0:c62615f15125 145 } link_check;
mfiore 0:c62615f15125 146
mfiore 0:c62615f15125 147 typedef struct {
mfiore 0:c62615f15125 148 int32_t status;
mfiore 0:c62615f15125 149 int16_t rssi;
mfiore 0:c62615f15125 150 int16_t snr;
mfiore 0:c62615f15125 151 } ping_response;
mfiore 0:c62615f15125 152
mfiore 0:c62615f15125 153 static const uint8_t MaxLengths_915[];
mfiore 0:c62615f15125 154 static const uint8_t MaxLengths_868[];
mfiore 0:c62615f15125 155
mfiore 0:c62615f15125 156 static std::string JoinModeStr(uint8_t mode);
mfiore 0:c62615f15125 157 static std::string ModeStr(uint8_t mode);
mfiore 0:c62615f15125 158 static std::string RxOutputStr(uint8_t format);
mfiore 0:c62615f15125 159 static std::string DataRateStr(uint8_t rate);
mfiore 0:c62615f15125 160 static std::string FrequencyBandStr(uint8_t band);
mfiore 0:c62615f15125 161 static std::string FrequencySubBandStr(uint8_t band);
mfiore 0:c62615f15125 162
mfiore 0:c62615f15125 163 /** Get a handle to the singleton object
mfiore 0:c62615f15125 164 * @returns pointer to mDot object
mfiore 0:c62615f15125 165 */
mfiore 0:c62615f15125 166 static mDot* getInstance();
mfiore 0:c62615f15125 167
mfiore 0:c62615f15125 168 /** Get library version information
mfiore 0:c62615f15125 169 * @returns string containing library version information
mfiore 0:c62615f15125 170 */
mfiore 0:c62615f15125 171 std::string getId();
mfiore 0:c62615f15125 172
mfiore 0:c62615f15125 173 /** Perform a soft reset of the system
mfiore 0:c62615f15125 174 */
mfiore 0:c62615f15125 175 void resetCpu();
mfiore 0:c62615f15125 176
mfiore 0:c62615f15125 177 /** Reset config to factory default
mfiore 0:c62615f15125 178 */
mfiore 0:c62615f15125 179 void resetConfig();
mfiore 0:c62615f15125 180
mfiore 0:c62615f15125 181 /** Save config data to non volatile memory
mfiore 0:c62615f15125 182 * @returns true if success, false if failure
mfiore 0:c62615f15125 183 */
mfiore 0:c62615f15125 184 bool saveConfig();
mfiore 0:c62615f15125 185
mfiore 0:c62615f15125 186 /** Set the log level for the library
mfiore 0:c62615f15125 187 * options are:
mfiore 0:c62615f15125 188 * NONE_LEVEL - logging is off at this level
mfiore 0:c62615f15125 189 * FATAL_LEVEL - only critical errors will be reported
mfiore 0:c62615f15125 190 * ERROR_LEVEL
mfiore 0:c62615f15125 191 * WARNING_LEVEL
mfiore 0:c62615f15125 192 * INFO_LEVEL
mfiore 0:c62615f15125 193 * DEBUG_LEVEL
mfiore 0:c62615f15125 194 * TRACE_LEVEL - every detail will be reported
mfiore 0:c62615f15125 195 * @param level the level to log at
mfiore 0:c62615f15125 196 * @returns MDOT_OK if success
mfiore 0:c62615f15125 197 */
mfiore 0:c62615f15125 198 int32_t setLogLevel(const uint8_t& level);
mfiore 0:c62615f15125 199
mfiore 0:c62615f15125 200 /** Get the current log level for the library
mfiore 0:c62615f15125 201 * @returns current log level
mfiore 0:c62615f15125 202 */
Mike Fiore 6:390fc83d588d 203 uint8_t getLogLevel();
Mike Fiore 6:390fc83d588d 204
Mike Fiore 6:390fc83d588d 205 /** Enable or disable the activity LED.
Mike Fiore 6:390fc83d588d 206 * @param enable true to enable the LED, false to disable
Mike Fiore 6:390fc83d588d 207 */
Mike Fiore 6:390fc83d588d 208 void setActivityLedEnable(const bool& enable);
Mike Fiore 4:94969e981dcc 209
Mike Fiore 6:390fc83d588d 210 /** Find out if the activity LED is enabled
Mike Fiore 6:390fc83d588d 211 * @returns true if activity LED is enabled, false if disabled
Mike Fiore 6:390fc83d588d 212 */
Mike Fiore 6:390fc83d588d 213 bool getActivityLedEnable();
Mike Fiore 6:390fc83d588d 214
Mike Fiore 6:390fc83d588d 215 /** Use a different pin for the activity LED.
Mike Fiore 6:390fc83d588d 216 * The default is XBEE_RSSI.
Mike Fiore 6:390fc83d588d 217 * @param pin the new pin to use
Mike Fiore 6:390fc83d588d 218 */
Mike Fiore 6:390fc83d588d 219 void setActivityLedPin(const PinName& pin);
Mike Fiore 6:390fc83d588d 220
Mike Fiore 5:0bfe6a650513 221 /** Use an external DigitalOut object for the activity LED.
Mike Fiore 5:0bfe6a650513 222 * The pointer must stay valid!
Mike Fiore 5:0bfe6a650513 223 * @param pin the DigitalOut object to use
Mike Fiore 5:0bfe6a650513 224 */
Mike Fiore 5:0bfe6a650513 225 void setActivityLedPin(DigitalOut* pin);
Mike Fiore 6:390fc83d588d 226
Mike Fiore 6:390fc83d588d 227 /** Find out what pin the activity LED is on
Mike Fiore 6:390fc83d588d 228 * @returns the pin the activity LED is using
Mike Fiore 6:390fc83d588d 229 */
Mike Fiore 6:390fc83d588d 230 PinName getActivityLedPin();
mfiore 0:c62615f15125 231
mfiore 0:c62615f15125 232 /** Get list of channel frequencies currently in use
mfiore 0:c62615f15125 233 * @returns vector of channels currently in use
mfiore 0:c62615f15125 234 */
mfiore 0:c62615f15125 235 std::vector<uint32_t> getChannels();
mfiore 0:c62615f15125 236
mfiore 0:c62615f15125 237 /** Get frequency band
mfiore 0:c62615f15125 238 * @returns FB_915 if configured for United States, FB_868 if configured for Europe
mfiore 0:c62615f15125 239 */
mfiore 0:c62615f15125 240 uint8_t getFrequencyBand();
mfiore 0:c62615f15125 241
mfiore 0:c62615f15125 242 /** Set frequency sub band
mfiore 0:c62615f15125 243 * only applicable if frequency band is set for United States (FB_915)
mfiore 0:c62615f15125 244 * sub band 0 will allow the radio to use all 64 channels
mfiore 0:c62615f15125 245 * sub band 1 - 8 will allow the radio to use the 8 channels in that sub band
mfiore 0:c62615f15125 246 * for use with Conduit gateway and MTAC_LORA, use sub bands 1 - 8, not sub band 0
mfiore 0:c62615f15125 247 * @param band the sub band to use (0 - 8)
mfiore 0:c62615f15125 248 * @returns MDOT_OK if success
mfiore 0:c62615f15125 249 */
mfiore 0:c62615f15125 250 int32_t setFrequencySubBand(const uint8_t& band);
mfiore 0:c62615f15125 251
mfiore 0:c62615f15125 252 /** Get frequency sub band
mfiore 0:c62615f15125 253 * @returns frequency sub band currently in use
mfiore 0:c62615f15125 254 */
mfiore 0:c62615f15125 255 uint8_t getFrequencySubBand();
mfiore 0:c62615f15125 256
mfiore 0:c62615f15125 257 /** Enable/disable public network mode
mfiore 0:c62615f15125 258 * for use with Conduit gateway and MTAC_LORA, disable public network mode
mfiore 0:c62615f15125 259 * @param on should be true to enable public network mode
mfiore 0:c62615f15125 260 * @returns MDOT_OK if success
mfiore 0:c62615f15125 261 */
mfiore 0:c62615f15125 262 int32_t setPublicNetwork(const bool& on);
mfiore 0:c62615f15125 263
mfiore 0:c62615f15125 264 /** Get public network mode
mfiore 0:c62615f15125 265 * @returns true if public network mode is enabled
mfiore 0:c62615f15125 266 */
mfiore 0:c62615f15125 267 bool getPublicNetwork();
mfiore 0:c62615f15125 268
mfiore 0:c62615f15125 269 /** Get the device ID
mfiore 0:c62615f15125 270 * @returns vector containing the device ID (size 8)
mfiore 0:c62615f15125 271 */
mfiore 0:c62615f15125 272 std::vector<uint8_t> getDeviceId();
mfiore 0:c62615f15125 273
mfiore 0:c62615f15125 274 /** Set network address
mfiore 0:c62615f15125 275 * for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes
mfiore 0:c62615f15125 276 * @param addr a vector of 4 bytes
mfiore 0:c62615f15125 277 * @returns MDOT_OK if success
mfiore 0:c62615f15125 278 */
mfiore 0:c62615f15125 279 int32_t setNetworkAddress(const std::vector<uint8_t>& addr);
mfiore 0:c62615f15125 280
mfiore 0:c62615f15125 281 /** Get network address
mfiore 0:c62615f15125 282 * @returns vector containing network address (size 4)
mfiore 0:c62615f15125 283 */
mfiore 0:c62615f15125 284 std::vector<uint8_t> getNetworkAddress();
mfiore 0:c62615f15125 285
mfiore 0:c62615f15125 286 /** Set network session key
mfiore 0:c62615f15125 287 * for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes
mfiore 0:c62615f15125 288 * @param key a vector of 16 bytes
mfiore 0:c62615f15125 289 * @returns MDOT_OK if success
mfiore 0:c62615f15125 290 */
mfiore 0:c62615f15125 291 int32_t setNetworkSessionKey(const std::vector<uint8_t>& key);
mfiore 0:c62615f15125 292
mfiore 0:c62615f15125 293 /** Get network session key
mfiore 0:c62615f15125 294 * @returns vector containing network session key (size 16)
mfiore 0:c62615f15125 295 */
mfiore 0:c62615f15125 296 std::vector<uint8_t> getNetworkSessionKey();
mfiore 0:c62615f15125 297
mfiore 0:c62615f15125 298 /** Set data session key
mfiore 0:c62615f15125 299 * for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes
mfiore 0:c62615f15125 300 * @param key a vector of 16 bytes
mfiore 0:c62615f15125 301 * @returns MDOT_OK if success
mfiore 0:c62615f15125 302 */
mfiore 0:c62615f15125 303 int32_t setDataSessionKey(const std::vector<uint8_t>& key);
mfiore 0:c62615f15125 304
mfiore 0:c62615f15125 305 /** Get data session key
mfiore 0:c62615f15125 306 * @returns vector containing data session key (size 16)
mfiore 0:c62615f15125 307 */
mfiore 0:c62615f15125 308 std::vector<uint8_t> getDataSessionKey();
mfiore 0:c62615f15125 309
mfiore 0:c62615f15125 310 /** Set network name
mfiore 0:c62615f15125 311 * for use with OTA & AUTO_OTA network join modes
mfiore 0:c62615f15125 312 * generates network ID (crc64 of name) automatically
mfiore 0:c62615f15125 313 * @param name a string of of at least 8 bytes and no more than 128 bytes
mfiore 0:c62615f15125 314 * @return MDOT_OK if success
mfiore 0:c62615f15125 315 */
mfiore 0:c62615f15125 316 int32_t setNetworkName(const std::string& name);
mfiore 0:c62615f15125 317
mfiore 0:c62615f15125 318 /** Get network name
mfiore 0:c62615f15125 319 * @return string containing network name (size 8 to 128)
mfiore 0:c62615f15125 320 */
mfiore 0:c62615f15125 321 std::string getNetworkName();
mfiore 0:c62615f15125 322
mfiore 0:c62615f15125 323 /** Set network ID
mfiore 0:c62615f15125 324 * for use with OTA & AUTO_OTA network join modes
mfiore 0:c62615f15125 325 * setting network ID via this function sets network name to empty
mfiore 0:c62615f15125 326 * @param id a vector of 8 bytes
mfiore 0:c62615f15125 327 * @returns MDOT_OK if success
mfiore 0:c62615f15125 328 */
mfiore 0:c62615f15125 329 int32_t setNetworkId(const std::vector<uint8_t>& id);
mfiore 0:c62615f15125 330
mfiore 0:c62615f15125 331 /** Get network ID
mfiore 0:c62615f15125 332 * @returns vector containing network ID (size 8)
mfiore 0:c62615f15125 333 */
mfiore 0:c62615f15125 334 std::vector<uint8_t> getNetworkId();
mfiore 0:c62615f15125 335
mfiore 0:c62615f15125 336 /** Set network passphrase
mfiore 0:c62615f15125 337 * for use with OTA & AUTO_OTA network join modes
mfiore 0:c62615f15125 338 * generates network key (cmac of passphrase) automatically
mfiore 0:c62615f15125 339 * @param name a string of of at least 8 bytes and no more than 128 bytes
mfiore 0:c62615f15125 340 * @return MDOT_OK if success
mfiore 0:c62615f15125 341 */
mfiore 0:c62615f15125 342 int32_t setNetworkPassphrase(const std::string& passphrase);
mfiore 0:c62615f15125 343
mfiore 0:c62615f15125 344 /** Get network passphrase
mfiore 0:c62615f15125 345 * @return string containing network passphrase (size 8 to 128)
mfiore 0:c62615f15125 346 */
mfiore 0:c62615f15125 347 std::string getNetworkPassphrase();
mfiore 0:c62615f15125 348
mfiore 0:c62615f15125 349 /** Set network key
mfiore 0:c62615f15125 350 * for use with OTA & AUTO_OTA network join modes
mfiore 0:c62615f15125 351 * setting network key via this function sets network passphrase to empty
mfiore 0:c62615f15125 352 * @param id a vector of 16 bytes
mfiore 0:c62615f15125 353 * @returns MDOT_OK if success
mfiore 0:c62615f15125 354 */
mfiore 0:c62615f15125 355 int32_t setNetworkKey(const std::vector<uint8_t>& id);
mfiore 0:c62615f15125 356
mfiore 0:c62615f15125 357 /** Get network key
mfiore 0:c62615f15125 358 * @returns a vector containing network key (size 16)
mfiore 0:c62615f15125 359 */
mfiore 0:c62615f15125 360 std::vector<uint8_t> getNetworkKey();
mfiore 0:c62615f15125 361
Mike Fiore 6:390fc83d588d 362 /** Set join byte order
Mike Fiore 6:390fc83d588d 363 * @param order 0:LSB 1:MSB
Mike Fiore 6:390fc83d588d 364 */
Mike Fiore 6:390fc83d588d 365 uint32_t setJoinByteOrder(uint8_t order);
Mike Fiore 6:390fc83d588d 366
Mike Fiore 6:390fc83d588d 367 /** Get join byte order
Mike Fiore 6:390fc83d588d 368 * @returns byte order to use in joins 0:LSB 1:MSB
Mike Fiore 6:390fc83d588d 369 */
Mike Fiore 6:390fc83d588d 370 uint8_t getJoinByteOrder();
Mike Fiore 6:390fc83d588d 371
mfiore 0:c62615f15125 372 /** Attempt to join network
mfiore 0:c62615f15125 373 * retries according to configuration set by setJoinRetries()
mfiore 0:c62615f15125 374 * @returns MDOT_OK if success
mfiore 0:c62615f15125 375 */
mfiore 0:c62615f15125 376 int32_t joinNetwork();
mfiore 0:c62615f15125 377
mfiore 0:c62615f15125 378 /** Attempts to join network once
mfiore 0:c62615f15125 379 * @returns MDOT_OK if success
mfiore 0:c62615f15125 380 */
mfiore 0:c62615f15125 381 int32_t joinNetworkOnce();
mfiore 0:c62615f15125 382
mfiore 0:c62615f15125 383 /** Resets current network session, essentially disconnecting from the network
mfiore 0:c62615f15125 384 * has no effect for MANUAL network join mode
mfiore 0:c62615f15125 385 */
mfiore 0:c62615f15125 386 void resetNetworkSession();
mfiore 0:c62615f15125 387
mfiore 0:c62615f15125 388 /** Set number of times joining will retry before giving up
mfiore 0:c62615f15125 389 * @param retries must be between 0 - 255
mfiore 0:c62615f15125 390 * @returns MDOT_OK if success
mfiore 0:c62615f15125 391 */
mfiore 0:c62615f15125 392 int32_t setJoinRetries(const uint8_t& retries);
mfiore 0:c62615f15125 393
mfiore 0:c62615f15125 394 /** Set number of times joining will retry before giving up
mfiore 0:c62615f15125 395 * @returns join retries (0 - 255)
mfiore 0:c62615f15125 396 */
mfiore 0:c62615f15125 397 uint8_t getJoinRetries();
mfiore 0:c62615f15125 398
mfiore 0:c62615f15125 399 /** Set network join mode
mfiore 0:c62615f15125 400 * MANUAL: set network address and session keys manually
mfiore 0:c62615f15125 401 * OTA: User sets network name and passphrase, then attempts to join
mfiore 0:c62615f15125 402 * AUTO_OTA: same as OTA, but network sessions can be saved and restored
mfiore 0:c62615f15125 403 * @param mode MANUAL, OTA, or AUTO_OTA
mfiore 0:c62615f15125 404 * @returns MDOT_OK if success
mfiore 0:c62615f15125 405 */
mfiore 0:c62615f15125 406 int32_t setJoinMode(const uint8_t& mode);
mfiore 0:c62615f15125 407
mfiore 0:c62615f15125 408 /** Get network join mode
mfiore 0:c62615f15125 409 * @returns MANUAL, OTA, or AUTO_OTA
mfiore 0:c62615f15125 410 */
mfiore 0:c62615f15125 411 uint8_t getJoinMode();
mfiore 0:c62615f15125 412
mfiore 0:c62615f15125 413 /** Get network join status
mfiore 0:c62615f15125 414 * @returns true if currently joined to network
mfiore 0:c62615f15125 415 */
mfiore 0:c62615f15125 416 bool getNetworkJoinStatus();
mfiore 0:c62615f15125 417
mfiore 0:c62615f15125 418 /** Do a network link check
mfiore 0:c62615f15125 419 * application data may be returned in response to a network link check command
mfiore 0:c62615f15125 420 * @returns link_check structure containing success, dBm above noise floor, gateways in range, and packet payload
mfiore 0:c62615f15125 421 */
mfiore 0:c62615f15125 422 link_check networkLinkCheck();
mfiore 0:c62615f15125 423
mfiore 0:c62615f15125 424 /** Set network link check count to perform automatic link checks every count packets
mfiore 0:c62615f15125 425 * only applicable if ACKs are disabled
mfiore 0:c62615f15125 426 * @param count must be between 0 - 255
mfiore 0:c62615f15125 427 * @returns MDOT_OK if success
mfiore 0:c62615f15125 428 */
mfiore 0:c62615f15125 429 int32_t setLinkCheckCount(const uint8_t& count);
mfiore 0:c62615f15125 430
mfiore 0:c62615f15125 431 /** Get network link check count
mfiore 0:c62615f15125 432 * @returns count (0 - 255)
mfiore 0:c62615f15125 433 */
mfiore 0:c62615f15125 434 uint8_t getLinkCheckCount();
mfiore 0:c62615f15125 435
mfiore 0:c62615f15125 436 /** Set network link check threshold, number of link check failures or missed acks to tolerate
mfiore 0:c62615f15125 437 * before considering network connection lost
mfiore 0:c62615f15125 438 * @pararm count must be between 0 - 255
mfiore 0:c62615f15125 439 * @returns MDOT_OK if success
mfiore 0:c62615f15125 440 */
mfiore 0:c62615f15125 441 int32_t setLinkCheckThreshold(const uint8_t& count);
mfiore 0:c62615f15125 442
mfiore 0:c62615f15125 443 /** Get network link check threshold
mfiore 0:c62615f15125 444 * @returns threshold (0 - 255)
mfiore 0:c62615f15125 445 */
mfiore 0:c62615f15125 446 uint8_t getLinkCheckThreshold();
mfiore 0:c62615f15125 447
mfiore 0:c62615f15125 448 /** Get UpLinkCounter
mfiore 0:c62615f15125 449 * @returns number of packets sent to the gateway during this network session (sequence number)
mfiore 0:c62615f15125 450 */
mfiore 0:c62615f15125 451 uint32_t getUpLinkCounter();
mfiore 0:c62615f15125 452
mfiore 0:c62615f15125 453 /** Enable/disable AES encryption
mfiore 0:c62615f15125 454 * AES encryption must be enabled for use with Conduit gateway and MTAC_LORA card
mfiore 0:c62615f15125 455 * @param on true for AES encryption to be enabled
mfiore 0:c62615f15125 456 * @returns MDOT_OK if success
mfiore 0:c62615f15125 457 */
mfiore 0:c62615f15125 458 int32_t setAesEncryption(const bool& on);
mfiore 0:c62615f15125 459
mfiore 0:c62615f15125 460 /** Get AES encryption
mfiore 0:c62615f15125 461 * @returns true if AES encryption is enabled
mfiore 0:c62615f15125 462 */
mfiore 0:c62615f15125 463 bool getAesEncryption();
mfiore 0:c62615f15125 464
mfiore 0:c62615f15125 465 /** Get RSSI stats
mfiore 0:c62615f15125 466 * @returns rssi_stats struct containing last, min, max, and avg RSSI
mfiore 0:c62615f15125 467 */
mfiore 0:c62615f15125 468 rssi_stats getRssiStats();
mfiore 0:c62615f15125 469
mfiore 0:c62615f15125 470 /** Get SNR stats
mfiore 0:c62615f15125 471 * @returns snr_stats struct containing last, min, max, and avg SNR
mfiore 0:c62615f15125 472 */
mfiore 0:c62615f15125 473 snr_stats getSnrStats();
mfiore 0:c62615f15125 474
mfiore 0:c62615f15125 475 /** Get ms until next free channel
mfiore 0:c62615f15125 476 * only applicable for European models, US models return 0
mfiore 0:c62615f15125 477 * @returns time (ms) until a channel is free to use for transmitting
mfiore 0:c62615f15125 478 */
mfiore 0:c62615f15125 479 uint32_t getNextTxMs();
mfiore 0:c62615f15125 480
mfiore 0:c62615f15125 481 /** Get data pending
mfiore 0:c62615f15125 482 * only valid after sending data to the gateway
mfiore 0:c62615f15125 483 * @returns true if server has available packet(s)
mfiore 0:c62615f15125 484 */
mfiore 0:c62615f15125 485 bool getDataPending();
mfiore 0:c62615f15125 486
mfiore 0:c62615f15125 487 /** Get transmitting
mfiore 0:c62615f15125 488 * @returns true if currently transmitting
mfiore 0:c62615f15125 489 */
mfiore 0:c62615f15125 490 bool getIsTransmitting();
mfiore 0:c62615f15125 491
mfiore 0:c62615f15125 492 /** Set TX data rate
mfiore 0:c62615f15125 493 * data rates affect maximum payload size
mfiore 0:c62615f15125 494 * @param dr SF_7 - SF_12 for Europe, SF_7 - SF_10 for United States
mfiore 0:c62615f15125 495 * @returns MDOT_OK if success
mfiore 0:c62615f15125 496 */
mfiore 0:c62615f15125 497 int32_t setTxDataRate(const uint8_t& dr);
mfiore 0:c62615f15125 498
mfiore 0:c62615f15125 499 /** Get TX data rate
mfiore 0:c62615f15125 500 * @returns current TX data rate (SF_7 - SF_12)
mfiore 0:c62615f15125 501 */
mfiore 0:c62615f15125 502 uint8_t getTxDataRate();
mfiore 0:c62615f15125 503
mfiore 0:c62615f15125 504 /** Set TX power
mfiore 0:c62615f15125 505 * power affects maximum range
mfiore 0:c62615f15125 506 * @param power 2 dBm - 20 dBm
mfiore 0:c62615f15125 507 * @returns MDOT_OK if success
mfiore 0:c62615f15125 508 */
mfiore 0:c62615f15125 509 int32_t setTxPower(const uint32_t& power);
mfiore 0:c62615f15125 510
mfiore 0:c62615f15125 511 /** Get TX power
mfiore 0:c62615f15125 512 * @returns TX power (2 dBm - 20 dBm)
mfiore 0:c62615f15125 513 */
mfiore 0:c62615f15125 514 uint32_t getTxPower();
mfiore 0:c62615f15125 515
mfiore 0:c62615f15125 516 /** Enable/disable TX waiting for rx windows
mfiore 0:c62615f15125 517 * when enabled, send calls will block until a packet is received or RX timeout
mfiore 0:c62615f15125 518 * @param enable set to true if expecting responses to transmitted packets
mfiore 0:c62615f15125 519 * @returns MDOT_OK if success
mfiore 0:c62615f15125 520 */
mfiore 0:c62615f15125 521 int32_t setTxWait(const bool& enable);
mfiore 0:c62615f15125 522
mfiore 0:c62615f15125 523 /** Get TX wait
mfiore 0:c62615f15125 524 * @returns true if TX wait is enabled
mfiore 0:c62615f15125 525 */
mfiore 0:c62615f15125 526 bool getTxWait();
mfiore 0:c62615f15125 527
mfiore 0:c62615f15125 528 /** Get time on air
mfiore 0:c62615f15125 529 * @returns the amount of time (in ms) it would take to send bytes bytes based on current configuration
mfiore 0:c62615f15125 530 */
mfiore 0:c62615f15125 531 uint32_t getTimeOnAir(uint8_t bytes);
mfiore 0:c62615f15125 532
mfiore 0:c62615f15125 533 /** Get min frequency
mfiore 0:c62615f15125 534 * @returns minimum frequency based on current configuration
mfiore 0:c62615f15125 535 */
mfiore 0:c62615f15125 536 uint32_t getMinFrequency();
mfiore 0:c62615f15125 537
mfiore 0:c62615f15125 538 /** Get max frequency
mfiore 0:c62615f15125 539 * @returns maximum frequency based on current configuration
mfiore 0:c62615f15125 540 */
mfiore 0:c62615f15125 541 uint32_t getMaxFrequency();
mfiore 0:c62615f15125 542
mfiore 0:c62615f15125 543 /** Set forward error correction bytes
mfiore 0:c62615f15125 544 * @param bytes 1 - 4 bytes
mfiore 0:c62615f15125 545 * @returns MDOT_OK if success
mfiore 0:c62615f15125 546 */
mfiore 0:c62615f15125 547 int32_t setFec(const uint8_t& bytes);
mfiore 0:c62615f15125 548
mfiore 0:c62615f15125 549 /** Get forward error correction bytes
mfiore 0:c62615f15125 550 * @returns bytes (1 - 4)
mfiore 0:c62615f15125 551 */
mfiore 0:c62615f15125 552 uint8_t getFec();
mfiore 0:c62615f15125 553
mfiore 0:c62615f15125 554 /** Enable/disable CRC checking of packets
mfiore 0:c62615f15125 555 * CRC checking must be enabled for use with Conduit gateway and MTAC_LORA card
mfiore 0:c62615f15125 556 * @param on set to true to enable CRC checking
mfiore 0:c62615f15125 557 * @returns MDOT_OK if success
mfiore 0:c62615f15125 558 */
mfiore 0:c62615f15125 559 int32_t setCrc(const bool& on);
mfiore 0:c62615f15125 560
mfiore 0:c62615f15125 561 /** Get CRC checking
mfiore 0:c62615f15125 562 * @returns true if CRC checking is enabled
mfiore 0:c62615f15125 563 */
mfiore 0:c62615f15125 564 bool getCrc();
mfiore 0:c62615f15125 565
mfiore 0:c62615f15125 566 /** Set ack
mfiore 0:c62615f15125 567 * @param retries 0 to disable acks, otherwise 1 - 8
mfiore 0:c62615f15125 568 * @returns MDOT_OK if success
mfiore 0:c62615f15125 569 */
mfiore 0:c62615f15125 570 int32_t setAck(const uint8_t& retries);
mfiore 0:c62615f15125 571
mfiore 0:c62615f15125 572 /** Get ack
mfiore 0:c62615f15125 573 * @returns 0 if acks are disabled, otherwise retries (1 - 8)
mfiore 0:c62615f15125 574 */
mfiore 0:c62615f15125 575 uint8_t getAck();
mfiore 0:c62615f15125 576
mfiore 0:c62615f15125 577 /** Send data to the gateway
mfiore 0:c62615f15125 578 * validates data size (based on spreading factor)
mfiore 0:c62615f15125 579 * @param data a vector of up to 242 bytes (may be less based on spreading factor)
mfiore 0:c62615f15125 580 * @returns MDOT_OK if packet was sent successfully (ACKs disabled), or if an ACK was received (ACKs enabled)
mfiore 0:c62615f15125 581 */
mfiore 0:c62615f15125 582 int32_t send(const std::vector<uint8_t>& data, const bool& blocking = true, const bool& highBw = false);
mfiore 0:c62615f15125 583
mfiore 0:c62615f15125 584 /** Fetch data received from the gateway
mfiore 0:c62615f15125 585 * this function only checks to see if a packet has been received - it does not open a receive window
mfiore 0:c62615f15125 586 * send() must be called before recv()
mfiore 0:c62615f15125 587 * @param data a vector to put the received data into
mfiore 0:c62615f15125 588 * @returns MDOT_OK if packet was successfully received
mfiore 0:c62615f15125 589 */
mfiore 0:c62615f15125 590 int32_t recv(std::vector<uint8_t>& data);
mfiore 0:c62615f15125 591
Mike Fiore 6:390fc83d588d 592 void openRxWindow(uint32_t timeout);
Mike Fiore 6:390fc83d588d 593
mfiore 0:c62615f15125 594 /** Ping
mfiore 0:c62615f15125 595 * status will be MDOT_OK if ping succeeded
mfiore 0:c62615f15125 596 * @returns ping_response struct containing status, RSSI, and SNR
mfiore 0:c62615f15125 597 */
mfiore 0:c62615f15125 598 ping_response ping();
mfiore 0:c62615f15125 599
mfiore 0:c62615f15125 600 /** Get return code string
mfiore 0:c62615f15125 601 * @returns string containing a description of the given error code
mfiore 0:c62615f15125 602 */
mfiore 0:c62615f15125 603 static std::string getReturnCodeString(const int32_t& code);
mfiore 0:c62615f15125 604
mfiore 0:c62615f15125 605 /** Get last error
mfiore 0:c62615f15125 606 * @returns string explaining the last error that occured
mfiore 0:c62615f15125 607 */
mfiore 0:c62615f15125 608 std::string getLastError();
mfiore 0:c62615f15125 609
mfiore 0:c62615f15125 610 /******************************************
mfiore 0:c62615f15125 611 * THESE FEATURES ARE NOT FULLY IMPLEMENTED
mfiore 0:c62615f15125 612 *****************************************/
mfiore 0:c62615f15125 613 void sleep();
mfiore 0:c62615f15125 614 void wakeup();
mfiore 0:c62615f15125 615
mfiore 0:c62615f15125 616 // get/set adaptive data rate
mfiore 0:c62615f15125 617 // configure data rates and power levels based on signal to noise information from gateway
mfiore 0:c62615f15125 618 // true == adaptive data rate is on
mfiore 0:c62615f15125 619 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 620 int32_t setAdr(const bool& on);
mfiore 0:c62615f15125 621 bool getAdr();
mfiore 0:c62615f15125 622
mfiore 0:c62615f15125 623 /*************************************************************************
mfiore 0:c62615f15125 624 * The following functions are only used by the AT command application and
mfiore 0:c62615f15125 625 * should not be used by standard applications consuming the mDot library
mfiore 0:c62615f15125 626 ************************************************************************/
mfiore 0:c62615f15125 627
mfiore 0:c62615f15125 628 // set/get configured baud rate for command port
mfiore 0:c62615f15125 629 // only for use in conjunction with AT interface
mfiore 0:c62615f15125 630 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 631 int32_t setBaud(const uint32_t& baud);
mfiore 0:c62615f15125 632 uint32_t getBaud();
mfiore 0:c62615f15125 633
mfiore 0:c62615f15125 634 // set/get baud rate for debug port
mfiore 0:c62615f15125 635 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 636 int32_t setDebugBaud(const uint32_t& baud);
mfiore 0:c62615f15125 637 uint32_t getDebugBaud();
mfiore 0:c62615f15125 638
mfiore 0:c62615f15125 639 // set/get command terminal echo
mfiore 0:c62615f15125 640 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 641 int32_t setEcho(const bool& on);
mfiore 0:c62615f15125 642 bool getEcho();
mfiore 0:c62615f15125 643
mfiore 0:c62615f15125 644 // set/get command terminal verbose mode
mfiore 0:c62615f15125 645 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 646 int32_t setVerbose(const bool& on);
mfiore 0:c62615f15125 647 bool getVerbose();
mfiore 0:c62615f15125 648
mfiore 0:c62615f15125 649 // set/get startup mode
mfiore 0:c62615f15125 650 // COMMAND_MODE (default), starts up ready to accept AT commands
mfiore 0:c62615f15125 651 // SERIAL_MODE, read serial data and send it as LoRa packets
mfiore 0:c62615f15125 652 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 653 int32_t setStartUpMode(const uint8_t& mode);
mfiore 0:c62615f15125 654 uint8_t getStartUpMode();
mfiore 0:c62615f15125 655
mfiore 0:c62615f15125 656 int32_t setRxDataRate(const uint8_t& dr);
mfiore 0:c62615f15125 657 uint8_t getRxDataRate();
mfiore 0:c62615f15125 658
mfiore 0:c62615f15125 659 // get/set TX/RX frequency
mfiore 0:c62615f15125 660 // if frequency band == FB_868 (Europe), must be between 863000000 - 870000000
mfiore 0:c62615f15125 661 // if frequency band == FB_915 (United States), must be between 902000000-928000000
mfiore 0:c62615f15125 662 // if set to 0, device will hop frequencies
mfiore 0:c62615f15125 663 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 664 int32_t setTxFrequency(const uint32_t& freq);
mfiore 0:c62615f15125 665 uint32_t getTxFrequency();
mfiore 0:c62615f15125 666 int32_t setRxFrequency(const uint32_t& freq);
mfiore 0:c62615f15125 667 uint32_t getRxFrequency();
mfiore 0:c62615f15125 668
mfiore 0:c62615f15125 669 // get/set TX/RX inverted
mfiore 0:c62615f15125 670 // true == signal is inverted
mfiore 0:c62615f15125 671 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 672 int32_t setTxInverted(const bool& on);
mfiore 0:c62615f15125 673 bool getTxInverted();
mfiore 0:c62615f15125 674 int32_t setRxInverted(const bool& on);
mfiore 0:c62615f15125 675 bool getRxInverted();
mfiore 0:c62615f15125 676
mfiore 0:c62615f15125 677 // get/set RX output mode
mfiore 0:c62615f15125 678 // valid options are HEXADECIMAL and BINARY
mfiore 0:c62615f15125 679 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 680 int32_t setRxOutput(const uint8_t& mode);
mfiore 0:c62615f15125 681 uint8_t getRxOutput();
mfiore 0:c62615f15125 682
mfiore 0:c62615f15125 683 // get/set serial wake interval
mfiore 0:c62615f15125 684 // valid values are 2 s - INT_MAX (2147483647) s
mfiore 0:c62615f15125 685 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 686 int32_t setSerialWakeInterval(const uint32_t& interval);
mfiore 0:c62615f15125 687 uint32_t getSerialWakeInterval();
mfiore 0:c62615f15125 688
mfiore 0:c62615f15125 689 // get/set serial wake delay
mfiore 0:c62615f15125 690 // valid values are 2 ms - INT_MAX (2147483647) ms
mfiore 0:c62615f15125 691 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 692 int32_t setSerialWakeDelay(const uint32_t& delay);
mfiore 0:c62615f15125 693 uint32_t getSerialWakeDelay();
mfiore 0:c62615f15125 694
mfiore 0:c62615f15125 695 // get/set serial receive timeout
mfiore 0:c62615f15125 696 // valid values are 0 ms - 65000 ms
mfiore 0:c62615f15125 697 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 698 int32_t setSerialReceiveTimeout(const uint16_t& timeout);
mfiore 0:c62615f15125 699 uint16_t getSerialReceiveTimeout();
mfiore 0:c62615f15125 700
mfiore 0:c62615f15125 701 uint64_t crc64(uint64_t crc, const unsigned char *s, uint64_t l);
mfiore 0:c62615f15125 702
mfiore 0:c62615f15125 703 // MTS_RADIO_DEBUG_COMMANDS
Mike Fiore 6:390fc83d588d 704 void sendContinuous();
mfiore 0:c62615f15125 705 int32_t setDeviceId(const std::vector<uint8_t>& id);
mfiore 0:c62615f15125 706 int32_t setFrequencyBand(const uint8_t& band);
mfiore 0:c62615f15125 707 bool saveProtectedConfig();
mfiore 0:c62615f15125 708 void resetRadio();
mfiore 0:c62615f15125 709 int32_t setRadioMode(const uint8_t& mode);
mfiore 0:c62615f15125 710 std::map<uint8_t, uint8_t> dumpRegisters();
mfiore 0:c62615f15125 711 void eraseFlash();
mfiore 0:c62615f15125 712
mfiore 0:c62615f15125 713 mdot_stats getStats();
Mike Fiore 6:390fc83d588d 714 void resetStats();
Mike Fiore 6:390fc83d588d 715
mfiore 0:c62615f15125 716
mfiore 0:c62615f15125 717 private:
mfiore 0:c62615f15125 718 mdot_stats _stats;
mfiore 0:c62615f15125 719
mfiore 0:c62615f15125 720 };
mfiore 0:c62615f15125 721
mfiore 0:c62615f15125 722 #endif