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

mDot.h@11:d8464345e1f1, 2016-01-07 (annotated)

Committer:
Mike Fiore
Date:
Thu Jan 07 12:07:28 2016 -0600
Revision:
11:d8464345e1f1
Parent:
10:27dafba9fe19
Child:
12:54f9cac9d690
build library against mbed rev 104 instead of 111 until RTC issue is fixed

Who changed what in which revision?

UserRevisionLine numberNew contents of line
jreiss 9:ec2fffe31793 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 class mDot {
mfiore 0:c62615f15125 18
mfiore 0:c62615f15125 19 private:
mfiore 0:c62615f15125 20
mfiore 0:c62615f15125 21 mDot();
mfiore 0:c62615f15125 22 ~mDot();
mfiore 0:c62615f15125 23
mfiore 0:c62615f15125 24 static void idle(void const* args) {
mfiore 0:c62615f15125 25 while (1)
mfiore 0:c62615f15125 26 __WFI();
mfiore 0:c62615f15125 27 }
mfiore 0:c62615f15125 28
mfiore 0:c62615f15125 29 void setLastError(const std::string& str);
mfiore 0:c62615f15125 30
mfiore 0:c62615f15125 31 static bool validateBaudRate(const uint32_t& baud);
mfiore 0:c62615f15125 32 static bool validateFrequencySubBand(const uint8_t& band);
mfiore 0:c62615f15125 33 bool validateDataRate(const uint8_t& dr);
mfiore 0:c62615f15125 34
mfiore 0:c62615f15125 35 int32_t joinBase(const uint32_t& retries);
mfiore 0:c62615f15125 36 int32_t sendBase(const std::vector<uint8_t>& data, const bool& confirmed = false, const bool& blocking = true, const bool& highBw = false);
mfiore 0:c62615f15125 37 void waitForPacket();
mfiore 0:c62615f15125 38 void waitForLinkCheck();
mfiore 0:c62615f15125 39
mfiore 0:c62615f15125 40 void setActivityLedState(const uint8_t& state);
mfiore 0:c62615f15125 41 uint8_t getActivityLedState();
mfiore 0:c62615f15125 42
mfiore 0:c62615f15125 43 void blinkActivityLed(void) {
Mike Fiore 6:390fc83d588d 44 if (_activity_led) {
Mike Fiore 6:390fc83d588d 45 int val = _activity_led->read();
Mike Fiore 6:390fc83d588d 46 _activity_led->write(!val);
Mike Fiore 6:390fc83d588d 47 }
mfiore 0:c62615f15125 48 }
mfiore 0:c62615f15125 49
mfiore 0:c62615f15125 50 mDot(const mDot&);
mfiore 0:c62615f15125 51 mDot& operator=(const mDot&);
mfiore 0:c62615f15125 52
Mike Fiore 7:683dba5d576f 53 uint32_t RTC_ReadBackupRegister(uint32_t RTC_BKP_DR);
Mike Fiore 7:683dba5d576f 54 void RTC_WriteBackupRegister(uint32_t RTC_BKP_DR, uint32_t Data);
Mike Fiore 7:683dba5d576f 55
Mike Fiore 7:683dba5d576f 56 void wakeup();
Mike Fiore 7:683dba5d576f 57
mfiore 0:c62615f15125 58 static mDot* _instance;
mfiore 0:c62615f15125 59
mfiore 0:c62615f15125 60 LoRaMac* _mac;
mfiore 0:c62615f15125 61 MdotRadio* _radio;
mfiore 0:c62615f15125 62 LoRaMacEvent* _events;
mfiore 0:c62615f15125 63 LoRaConfig* _config;
mfiore 0:c62615f15125 64 Thread _idle_thread;
mfiore 0:c62615f15125 65 std::string _last_error;
mfiore 0:c62615f15125 66 static const uint32_t _baud_rates[];
mfiore 0:c62615f15125 67 uint8_t _activity_led_state;
mfiore 0:c62615f15125 68 Ticker _tick;
Mike Fiore 6:390fc83d588d 69 DigitalOut* _activity_led;
Mike Fiore 6:390fc83d588d 70 bool _activity_led_enable;
Mike Fiore 6:390fc83d588d 71 PinName _activity_led_pin;
Mike Fiore 5:0bfe6a650513 72 bool _activity_led_external;
jreiss 9:ec2fffe31793 73 uint8_t _linkFailCount;
Mike Fiore 7:683dba5d576f 74 uint8_t _class;
Mike Fiore 7:683dba5d576f 75 InterruptIn* _wakeup;
Mike Fiore 7:683dba5d576f 76 PinName _wakeup_pin;
mfiore 0:c62615f15125 77
mfiore 0:c62615f15125 78 typedef enum {
Jason Reiss 10:27dafba9fe19 79 OFF,
Jason Reiss 10:27dafba9fe19 80 ON,
Jason Reiss 10:27dafba9fe19 81 BLINK,
mfiore 0:c62615f15125 82 } state;
mfiore 0:c62615f15125 83
mfiore 0:c62615f15125 84 public:
mfiore 0:c62615f15125 85
mfiore 0:c62615f15125 86 typedef enum {
Mike Fiore 7:683dba5d576f 87 FM_APPEND = (1 << 0),
Mike Fiore 7:683dba5d576f 88 FM_TRUNC = (1 << 1),
Mike Fiore 7:683dba5d576f 89 FM_CREAT = (1 << 2),
Mike Fiore 7:683dba5d576f 90 FM_RDONLY = (1 << 3),
Mike Fiore 7:683dba5d576f 91 FM_WRONLY = (1 << 4),
Mike Fiore 7:683dba5d576f 92 FM_RDWR = (FM_RDONLY | FM_WRONLY),
Mike Fiore 7:683dba5d576f 93 FM_DIRECT = (1 << 5)
Mike Fiore 7:683dba5d576f 94 } FileMode;
Mike Fiore 7:683dba5d576f 95
Mike Fiore 7:683dba5d576f 96 typedef enum {
mfiore 0:c62615f15125 97 MDOT_OK = 0,
mfiore 0:c62615f15125 98 MDOT_INVALID_PARAM = -1,
mfiore 0:c62615f15125 99 MDOT_TX_ERROR = -2,
mfiore 0:c62615f15125 100 MDOT_RX_ERROR = -3,
mfiore 0:c62615f15125 101 MDOT_JOIN_ERROR = -4,
mfiore 0:c62615f15125 102 MDOT_TIMEOUT = -5,
mfiore 0:c62615f15125 103 MDOT_NOT_JOINED = -6,
mfiore 0:c62615f15125 104 MDOT_ENCRYPTION_DISABLED = -7,
mfiore 0:c62615f15125 105 MDOT_NO_FREE_CHAN = -8,
mfiore 0:c62615f15125 106 MDOT_ERROR = -1024,
mfiore 0:c62615f15125 107 } mdot_ret_code;
mfiore 0:c62615f15125 108
mfiore 0:c62615f15125 109 enum JoinMode {
Jason Reiss 10:27dafba9fe19 110 MANUAL,
Jason Reiss 10:27dafba9fe19 111 OTA,
Jason Reiss 10:27dafba9fe19 112 AUTO_OTA
mfiore 0:c62615f15125 113 };
mfiore 0:c62615f15125 114
mfiore 0:c62615f15125 115 enum Mode {
Jason Reiss 10:27dafba9fe19 116 COMMAND_MODE,
Jason Reiss 10:27dafba9fe19 117 SERIAL_MODE
mfiore 0:c62615f15125 118 };
mfiore 0:c62615f15125 119
mfiore 0:c62615f15125 120 enum RX_Output {
Jason Reiss 10:27dafba9fe19 121 HEXADECIMAL,
Jason Reiss 10:27dafba9fe19 122 BINARY
mfiore 0:c62615f15125 123 };
mfiore 0:c62615f15125 124
mfiore 0:c62615f15125 125 enum DataRates {
Jason Reiss 10:27dafba9fe19 126 SF_12,
Jason Reiss 10:27dafba9fe19 127 SF_11,
Jason Reiss 10:27dafba9fe19 128 SF_10,
Jason Reiss 10:27dafba9fe19 129 SF_9,
Jason Reiss 10:27dafba9fe19 130 SF_8,
Jason Reiss 10:27dafba9fe19 131 SF_7,
Jason Reiss 10:27dafba9fe19 132 SF_7H,
Jason Reiss 10:27dafba9fe19 133 SF_50
mfiore 0:c62615f15125 134 };
mfiore 0:c62615f15125 135
mfiore 0:c62615f15125 136 enum FrequencyBands {
Mike Fiore 11:d8464345e1f1 137 FB_868, // EU868
Mike Fiore 11:d8464345e1f1 138 FB_915 // US915
mfiore 0:c62615f15125 139 };
mfiore 0:c62615f15125 140
mfiore 0:c62615f15125 141 enum FrequencySubBands {
Jason Reiss 10:27dafba9fe19 142 FSB_ALL,
Jason Reiss 10:27dafba9fe19 143 FSB_1,
Jason Reiss 10:27dafba9fe19 144 FSB_2,
Jason Reiss 10:27dafba9fe19 145 FSB_3,
Jason Reiss 10:27dafba9fe19 146 FSB_4,
Jason Reiss 10:27dafba9fe19 147 FSB_5,
Jason Reiss 10:27dafba9fe19 148 FSB_6,
Jason Reiss 10:27dafba9fe19 149 FSB_7,
Jason Reiss 10:27dafba9fe19 150 FSB_8
mfiore 0:c62615f15125 151 };
mfiore 0:c62615f15125 152
Mike Fiore 6:390fc83d588d 153 enum JoinByteOrder {
Jason Reiss 10:27dafba9fe19 154 LSB,
Jason Reiss 10:27dafba9fe19 155 MSB
Mike Fiore 6:390fc83d588d 156 };
Mike Fiore 6:390fc83d588d 157
Mike Fiore 7:683dba5d576f 158 enum wakeup_mode {
Jason Reiss 10:27dafba9fe19 159 RTC_ALARM,
Jason Reiss 10:27dafba9fe19 160 INTERRUPT,
Jason Reiss 10:27dafba9fe19 161 RTC_ALARM_OR_INTERRUPT
Mike Fiore 7:683dba5d576f 162 };
Mike Fiore 7:683dba5d576f 163
jreiss 9:ec2fffe31793 164 enum UserBackupRegs {
Jason Reiss 10:27dafba9fe19 165 UBR0,
Jason Reiss 10:27dafba9fe19 166 UBR1,
Jason Reiss 10:27dafba9fe19 167 UBR2,
Jason Reiss 10:27dafba9fe19 168 UBR3,
Jason Reiss 10:27dafba9fe19 169 UBR4,
Jason Reiss 10:27dafba9fe19 170 UBR5,
Jason Reiss 10:27dafba9fe19 171 UBR6,
Jason Reiss 10:27dafba9fe19 172 UBR7,
Jason Reiss 10:27dafba9fe19 173 UBR8,
Jason Reiss 10:27dafba9fe19 174 UBR9
jreiss 9:ec2fffe31793 175 };
jreiss 9:ec2fffe31793 176
Mike Fiore 7:683dba5d576f 177 typedef struct {
Mike Fiore 7:683dba5d576f 178 int16_t fd;
Mike Fiore 7:683dba5d576f 179 char name[30];
Mike Fiore 7:683dba5d576f 180 uint32_t size;
Mike Fiore 7:683dba5d576f 181 } mdot_file;
Mike Fiore 7:683dba5d576f 182
mfiore 0:c62615f15125 183 typedef struct {
mfiore 0:c62615f15125 184 uint32_t Up;
mfiore 0:c62615f15125 185 uint32_t Down;
mfiore 0:c62615f15125 186 uint32_t Joins;
mfiore 0:c62615f15125 187 uint32_t JoinFails;
mfiore 0:c62615f15125 188 uint32_t MissedAcks;
mfiore 0:c62615f15125 189 } mdot_stats;
mfiore 0:c62615f15125 190
mfiore 0:c62615f15125 191 typedef struct {
mfiore 0:c62615f15125 192 int16_t last;
mfiore 0:c62615f15125 193 int16_t min;
mfiore 0:c62615f15125 194 int16_t max;
mfiore 0:c62615f15125 195 int16_t avg;
mfiore 0:c62615f15125 196 } rssi_stats;
mfiore 0:c62615f15125 197
mfiore 0:c62615f15125 198 typedef struct {
Mike Fiore 11:d8464345e1f1 199 int16_t last;
Mike Fiore 11:d8464345e1f1 200 int16_t min;
Mike Fiore 11:d8464345e1f1 201 int16_t max;
Mike Fiore 11:d8464345e1f1 202 int16_t avg;
mfiore 0:c62615f15125 203 } snr_stats;
mfiore 0:c62615f15125 204
mfiore 0:c62615f15125 205 typedef struct {
mfiore 0:c62615f15125 206 bool status;
mfiore 0:c62615f15125 207 int32_t dBm;
mfiore 0:c62615f15125 208 uint32_t gateways;
mfiore 0:c62615f15125 209 std::vector<uint8_t> payload;
mfiore 0:c62615f15125 210 } link_check;
mfiore 0:c62615f15125 211
mfiore 0:c62615f15125 212 typedef struct {
mfiore 0:c62615f15125 213 int32_t status;
mfiore 0:c62615f15125 214 int16_t rssi;
mfiore 0:c62615f15125 215 int16_t snr;
mfiore 0:c62615f15125 216 } ping_response;
mfiore 0:c62615f15125 217
mfiore 0:c62615f15125 218 static const uint8_t MaxLengths_915[];
mfiore 0:c62615f15125 219 static const uint8_t MaxLengths_868[];
mfiore 0:c62615f15125 220
mfiore 0:c62615f15125 221 static std::string JoinModeStr(uint8_t mode);
mfiore 0:c62615f15125 222 static std::string ModeStr(uint8_t mode);
mfiore 0:c62615f15125 223 static std::string RxOutputStr(uint8_t format);
mfiore 0:c62615f15125 224 static std::string DataRateStr(uint8_t rate);
mfiore 0:c62615f15125 225 static std::string FrequencyBandStr(uint8_t band);
mfiore 0:c62615f15125 226 static std::string FrequencySubBandStr(uint8_t band);
mfiore 0:c62615f15125 227
jreiss 9:ec2fffe31793 228 uint32_t UserRegisters[10];
jreiss 9:ec2fffe31793 229
mfiore 0:c62615f15125 230 /** Get a handle to the singleton object
mfiore 0:c62615f15125 231 * @returns pointer to mDot object
mfiore 0:c62615f15125 232 */
mfiore 0:c62615f15125 233 static mDot* getInstance();
mfiore 0:c62615f15125 234
mfiore 0:c62615f15125 235 /** Get library version information
mfiore 0:c62615f15125 236 * @returns string containing library version information
mfiore 0:c62615f15125 237 */
mfiore 0:c62615f15125 238 std::string getId();
mfiore 0:c62615f15125 239
mfiore 0:c62615f15125 240 /** Perform a soft reset of the system
mfiore 0:c62615f15125 241 */
mfiore 0:c62615f15125 242 void resetCpu();
mfiore 0:c62615f15125 243
mfiore 0:c62615f15125 244 /** Reset config to factory default
mfiore 0:c62615f15125 245 */
mfiore 0:c62615f15125 246 void resetConfig();
mfiore 0:c62615f15125 247
mfiore 0:c62615f15125 248 /** Save config data to non volatile memory
mfiore 0:c62615f15125 249 * @returns true if success, false if failure
mfiore 0:c62615f15125 250 */
mfiore 0:c62615f15125 251 bool saveConfig();
mfiore 0:c62615f15125 252
mfiore 0:c62615f15125 253 /** Set the log level for the library
mfiore 0:c62615f15125 254 * options are:
mfiore 0:c62615f15125 255 * NONE_LEVEL - logging is off at this level
mfiore 0:c62615f15125 256 * FATAL_LEVEL - only critical errors will be reported
mfiore 0:c62615f15125 257 * ERROR_LEVEL
mfiore 0:c62615f15125 258 * WARNING_LEVEL
mfiore 0:c62615f15125 259 * INFO_LEVEL
mfiore 0:c62615f15125 260 * DEBUG_LEVEL
mfiore 0:c62615f15125 261 * TRACE_LEVEL - every detail will be reported
mfiore 0:c62615f15125 262 * @param level the level to log at
mfiore 0:c62615f15125 263 * @returns MDOT_OK if success
mfiore 0:c62615f15125 264 */
mfiore 0:c62615f15125 265 int32_t setLogLevel(const uint8_t& level);
mfiore 0:c62615f15125 266
mfiore 0:c62615f15125 267 /** Get the current log level for the library
mfiore 0:c62615f15125 268 * @returns current log level
mfiore 0:c62615f15125 269 */
Mike Fiore 6:390fc83d588d 270 uint8_t getLogLevel();
Mike Fiore 6:390fc83d588d 271
Mike Fiore 6:390fc83d588d 272 /** Enable or disable the activity LED.
Mike Fiore 6:390fc83d588d 273 * @param enable true to enable the LED, false to disable
Mike Fiore 6:390fc83d588d 274 */
Mike Fiore 6:390fc83d588d 275 void setActivityLedEnable(const bool& enable);
Mike Fiore 4:94969e981dcc 276
Mike Fiore 6:390fc83d588d 277 /** Find out if the activity LED is enabled
Mike Fiore 6:390fc83d588d 278 * @returns true if activity LED is enabled, false if disabled
Mike Fiore 6:390fc83d588d 279 */
Mike Fiore 6:390fc83d588d 280 bool getActivityLedEnable();
Mike Fiore 6:390fc83d588d 281
Mike Fiore 6:390fc83d588d 282 /** Use a different pin for the activity LED.
Mike Fiore 6:390fc83d588d 283 * The default is XBEE_RSSI.
Mike Fiore 6:390fc83d588d 284 * @param pin the new pin to use
Mike Fiore 6:390fc83d588d 285 */
Mike Fiore 6:390fc83d588d 286 void setActivityLedPin(const PinName& pin);
Mike Fiore 6:390fc83d588d 287
Mike Fiore 5:0bfe6a650513 288 /** Use an external DigitalOut object for the activity LED.
Mike Fiore 5:0bfe6a650513 289 * The pointer must stay valid!
Mike Fiore 5:0bfe6a650513 290 * @param pin the DigitalOut object to use
Mike Fiore 5:0bfe6a650513 291 */
Mike Fiore 5:0bfe6a650513 292 void setActivityLedPin(DigitalOut* pin);
Mike Fiore 6:390fc83d588d 293
Mike Fiore 6:390fc83d588d 294 /** Find out what pin the activity LED is on
Mike Fiore 6:390fc83d588d 295 * @returns the pin the activity LED is using
Mike Fiore 6:390fc83d588d 296 */
Mike Fiore 6:390fc83d588d 297 PinName getActivityLedPin();
mfiore 0:c62615f15125 298
mfiore 0:c62615f15125 299 /** Get list of channel frequencies currently in use
mfiore 0:c62615f15125 300 * @returns vector of channels currently in use
mfiore 0:c62615f15125 301 */
mfiore 0:c62615f15125 302 std::vector<uint32_t> getChannels();
mfiore 0:c62615f15125 303
mfiore 0:c62615f15125 304 /** Get frequency band
mfiore 0:c62615f15125 305 * @returns FB_915 if configured for United States, FB_868 if configured for Europe
mfiore 0:c62615f15125 306 */
mfiore 0:c62615f15125 307 uint8_t getFrequencyBand();
mfiore 0:c62615f15125 308
mfiore 0:c62615f15125 309 /** Set frequency sub band
mfiore 0:c62615f15125 310 * only applicable if frequency band is set for United States (FB_915)
Jason Reiss 10:27dafba9fe19 311 * sub band 0 will allow the radio to use all 64 channels
mfiore 0:c62615f15125 312 * sub band 1 - 8 will allow the radio to use the 8 channels in that sub band
mfiore 0:c62615f15125 313 * for use with Conduit gateway and MTAC_LORA, use sub bands 1 - 8, not sub band 0
mfiore 0:c62615f15125 314 * @param band the sub band to use (0 - 8)
mfiore 0:c62615f15125 315 * @returns MDOT_OK if success
mfiore 0:c62615f15125 316 */
mfiore 0:c62615f15125 317 int32_t setFrequencySubBand(const uint8_t& band);
mfiore 0:c62615f15125 318
mfiore 0:c62615f15125 319 /** Get frequency sub band
mfiore 0:c62615f15125 320 * @returns frequency sub band currently in use
mfiore 0:c62615f15125 321 */
mfiore 0:c62615f15125 322 uint8_t getFrequencySubBand();
mfiore 0:c62615f15125 323
mfiore 0:c62615f15125 324 /** Enable/disable public network mode
Jason Reiss 10:27dafba9fe19 325 * JoinDelay will be set to (public: 5s, private: 1s) and
Jason Reiss 10:27dafba9fe19 326 * RxDelay will be set to 1s both can be adjusted afterwards
mfiore 0:c62615f15125 327 * @param on should be true to enable public network mode
mfiore 0:c62615f15125 328 * @returns MDOT_OK if success
mfiore 0:c62615f15125 329 */
mfiore 0:c62615f15125 330 int32_t setPublicNetwork(const bool& on);
mfiore 0:c62615f15125 331
mfiore 0:c62615f15125 332 /** Get public network mode
mfiore 0:c62615f15125 333 * @returns true if public network mode is enabled
mfiore 0:c62615f15125 334 */
mfiore 0:c62615f15125 335 bool getPublicNetwork();
mfiore 0:c62615f15125 336
mfiore 0:c62615f15125 337 /** Get the device ID
mfiore 0:c62615f15125 338 * @returns vector containing the device ID (size 8)
mfiore 0:c62615f15125 339 */
mfiore 0:c62615f15125 340 std::vector<uint8_t> getDeviceId();
mfiore 0:c62615f15125 341
Jason Reiss 10:27dafba9fe19 342 /** Get the device port to be used for lora application data (1-223)
Jason Reiss 10:27dafba9fe19 343 * @returns port
Jason Reiss 10:27dafba9fe19 344 */
Jason Reiss 10:27dafba9fe19 345 uint8_t getAppPort();
Jason Reiss 10:27dafba9fe19 346
Jason Reiss 10:27dafba9fe19 347 /** Set the device port to be used for lora application data (1-223)
Jason Reiss 10:27dafba9fe19 348 * @returns MDOT_OK if success
Jason Reiss 10:27dafba9fe19 349 */
Jason Reiss 10:27dafba9fe19 350 int32_t setAppPort(uint8_t port);
Jason Reiss 10:27dafba9fe19 351
Jason Reiss 10:27dafba9fe19 352 /** Set the device class A, B or C
Jason Reiss 10:27dafba9fe19 353 * @returns MDOT_OK if success
Jason Reiss 10:27dafba9fe19 354 */
Jason Reiss 10:27dafba9fe19 355 int32_t setClass(std::string newClass);
Jason Reiss 10:27dafba9fe19 356
Jason Reiss 10:27dafba9fe19 357 /** Get the device class A, B or C
Jason Reiss 10:27dafba9fe19 358 * @returns MDOT_OK if success
Jason Reiss 10:27dafba9fe19 359 */
Jason Reiss 10:27dafba9fe19 360 std::string getClass();
Jason Reiss 10:27dafba9fe19 361
Jason Reiss 10:27dafba9fe19 362 /** Get the max packet length with current settings
Jason Reiss 10:27dafba9fe19 363 * @returns max packet length
Jason Reiss 10:27dafba9fe19 364 */
Jason Reiss 10:27dafba9fe19 365 uint8_t getMaxPacketLength();
Jason Reiss 10:27dafba9fe19 366
mfiore 0:c62615f15125 367 /** Set network address
mfiore 0:c62615f15125 368 * for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes
mfiore 0:c62615f15125 369 * @param addr a vector of 4 bytes
mfiore 0:c62615f15125 370 * @returns MDOT_OK if success
mfiore 0:c62615f15125 371 */
mfiore 0:c62615f15125 372 int32_t setNetworkAddress(const std::vector<uint8_t>& addr);
mfiore 0:c62615f15125 373
mfiore 0:c62615f15125 374 /** Get network address
mfiore 0:c62615f15125 375 * @returns vector containing network address (size 4)
mfiore 0:c62615f15125 376 */
mfiore 0:c62615f15125 377 std::vector<uint8_t> getNetworkAddress();
mfiore 0:c62615f15125 378
mfiore 0:c62615f15125 379 /** Set network session key
mfiore 0:c62615f15125 380 * for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes
mfiore 0:c62615f15125 381 * @param key a vector of 16 bytes
mfiore 0:c62615f15125 382 * @returns MDOT_OK if success
mfiore 0:c62615f15125 383 */
mfiore 0:c62615f15125 384 int32_t setNetworkSessionKey(const std::vector<uint8_t>& key);
mfiore 0:c62615f15125 385
mfiore 0:c62615f15125 386 /** Get network session key
mfiore 0:c62615f15125 387 * @returns vector containing network session key (size 16)
mfiore 0:c62615f15125 388 */
mfiore 0:c62615f15125 389 std::vector<uint8_t> getNetworkSessionKey();
mfiore 0:c62615f15125 390
mfiore 0:c62615f15125 391 /** Set data session key
mfiore 0:c62615f15125 392 * for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes
mfiore 0:c62615f15125 393 * @param key a vector of 16 bytes
mfiore 0:c62615f15125 394 * @returns MDOT_OK if success
mfiore 0:c62615f15125 395 */
mfiore 0:c62615f15125 396 int32_t setDataSessionKey(const std::vector<uint8_t>& key);
mfiore 0:c62615f15125 397
mfiore 0:c62615f15125 398 /** Get data session key
mfiore 0:c62615f15125 399 * @returns vector containing data session key (size 16)
mfiore 0:c62615f15125 400 */
mfiore 0:c62615f15125 401 std::vector<uint8_t> getDataSessionKey();
mfiore 0:c62615f15125 402
mfiore 0:c62615f15125 403 /** Set network name
mfiore 0:c62615f15125 404 * for use with OTA & AUTO_OTA network join modes
mfiore 0:c62615f15125 405 * generates network ID (crc64 of name) automatically
mfiore 0:c62615f15125 406 * @param name a string of of at least 8 bytes and no more than 128 bytes
mfiore 0:c62615f15125 407 * @return MDOT_OK if success
mfiore 0:c62615f15125 408 */
mfiore 0:c62615f15125 409 int32_t setNetworkName(const std::string& name);
mfiore 0:c62615f15125 410
mfiore 0:c62615f15125 411 /** Get network name
mfiore 0:c62615f15125 412 * @return string containing network name (size 8 to 128)
mfiore 0:c62615f15125 413 */
mfiore 0:c62615f15125 414 std::string getNetworkName();
mfiore 0:c62615f15125 415
mfiore 0:c62615f15125 416 /** Set network ID
mfiore 0:c62615f15125 417 * for use with OTA & AUTO_OTA network join modes
mfiore 0:c62615f15125 418 * setting network ID via this function sets network name to empty
mfiore 0:c62615f15125 419 * @param id a vector of 8 bytes
mfiore 0:c62615f15125 420 * @returns MDOT_OK if success
mfiore 0:c62615f15125 421 */
mfiore 0:c62615f15125 422 int32_t setNetworkId(const std::vector<uint8_t>& id);
mfiore 0:c62615f15125 423
mfiore 0:c62615f15125 424 /** Get network ID
mfiore 0:c62615f15125 425 * @returns vector containing network ID (size 8)
mfiore 0:c62615f15125 426 */
mfiore 0:c62615f15125 427 std::vector<uint8_t> getNetworkId();
mfiore 0:c62615f15125 428
mfiore 0:c62615f15125 429 /** Set network passphrase
mfiore 0:c62615f15125 430 * for use with OTA & AUTO_OTA network join modes
mfiore 0:c62615f15125 431 * generates network key (cmac of passphrase) automatically
mfiore 0:c62615f15125 432 * @param name a string of of at least 8 bytes and no more than 128 bytes
mfiore 0:c62615f15125 433 * @return MDOT_OK if success
mfiore 0:c62615f15125 434 */
mfiore 0:c62615f15125 435 int32_t setNetworkPassphrase(const std::string& passphrase);
mfiore 0:c62615f15125 436
mfiore 0:c62615f15125 437 /** Get network passphrase
mfiore 0:c62615f15125 438 * @return string containing network passphrase (size 8 to 128)
mfiore 0:c62615f15125 439 */
mfiore 0:c62615f15125 440 std::string getNetworkPassphrase();
mfiore 0:c62615f15125 441
mfiore 0:c62615f15125 442 /** Set network key
mfiore 0:c62615f15125 443 * for use with OTA & AUTO_OTA network join modes
mfiore 0:c62615f15125 444 * setting network key via this function sets network passphrase to empty
mfiore 0:c62615f15125 445 * @param id a vector of 16 bytes
mfiore 0:c62615f15125 446 * @returns MDOT_OK if success
mfiore 0:c62615f15125 447 */
mfiore 0:c62615f15125 448 int32_t setNetworkKey(const std::vector<uint8_t>& id);
mfiore 0:c62615f15125 449
mfiore 0:c62615f15125 450 /** Get network key
mfiore 0:c62615f15125 451 * @returns a vector containing network key (size 16)
mfiore 0:c62615f15125 452 */
mfiore 0:c62615f15125 453 std::vector<uint8_t> getNetworkKey();
mfiore 0:c62615f15125 454
Mike Fiore 6:390fc83d588d 455 /** Set join byte order
Mike Fiore 6:390fc83d588d 456 * @param order 0:LSB 1:MSB
Mike Fiore 6:390fc83d588d 457 */
Mike Fiore 6:390fc83d588d 458 uint32_t setJoinByteOrder(uint8_t order);
Mike Fiore 6:390fc83d588d 459
Mike Fiore 6:390fc83d588d 460 /** Get join byte order
Mike Fiore 6:390fc83d588d 461 * @returns byte order to use in joins 0:LSB 1:MSB
Mike Fiore 6:390fc83d588d 462 */
Mike Fiore 6:390fc83d588d 463 uint8_t getJoinByteOrder();
Mike Fiore 6:390fc83d588d 464
mfiore 0:c62615f15125 465 /** Attempt to join network
mfiore 0:c62615f15125 466 * retries according to configuration set by setJoinRetries()
mfiore 0:c62615f15125 467 * @returns MDOT_OK if success
mfiore 0:c62615f15125 468 */
mfiore 0:c62615f15125 469 int32_t joinNetwork();
mfiore 0:c62615f15125 470
mfiore 0:c62615f15125 471 /** Attempts to join network once
mfiore 0:c62615f15125 472 * @returns MDOT_OK if success
mfiore 0:c62615f15125 473 */
mfiore 0:c62615f15125 474 int32_t joinNetworkOnce();
mfiore 0:c62615f15125 475
mfiore 0:c62615f15125 476 /** Resets current network session, essentially disconnecting from the network
mfiore 0:c62615f15125 477 * has no effect for MANUAL network join mode
mfiore 0:c62615f15125 478 */
mfiore 0:c62615f15125 479 void resetNetworkSession();
mfiore 0:c62615f15125 480
mfiore 0:c62615f15125 481 /** Set number of times joining will retry before giving up
mfiore 0:c62615f15125 482 * @param retries must be between 0 - 255
mfiore 0:c62615f15125 483 * @returns MDOT_OK if success
mfiore 0:c62615f15125 484 */
mfiore 0:c62615f15125 485 int32_t setJoinRetries(const uint8_t& retries);
mfiore 0:c62615f15125 486
mfiore 0:c62615f15125 487 /** Set number of times joining will retry before giving up
mfiore 0:c62615f15125 488 * @returns join retries (0 - 255)
mfiore 0:c62615f15125 489 */
mfiore 0:c62615f15125 490 uint8_t getJoinRetries();
mfiore 0:c62615f15125 491
mfiore 0:c62615f15125 492 /** Set network join mode
mfiore 0:c62615f15125 493 * MANUAL: set network address and session keys manually
mfiore 0:c62615f15125 494 * OTA: User sets network name and passphrase, then attempts to join
mfiore 0:c62615f15125 495 * AUTO_OTA: same as OTA, but network sessions can be saved and restored
mfiore 0:c62615f15125 496 * @param mode MANUAL, OTA, or AUTO_OTA
mfiore 0:c62615f15125 497 * @returns MDOT_OK if success
mfiore 0:c62615f15125 498 */
mfiore 0:c62615f15125 499 int32_t setJoinMode(const uint8_t& mode);
mfiore 0:c62615f15125 500
mfiore 0:c62615f15125 501 /** Get network join mode
mfiore 0:c62615f15125 502 * @returns MANUAL, OTA, or AUTO_OTA
mfiore 0:c62615f15125 503 */
mfiore 0:c62615f15125 504 uint8_t getJoinMode();
mfiore 0:c62615f15125 505
mfiore 0:c62615f15125 506 /** Get network join status
mfiore 0:c62615f15125 507 * @returns true if currently joined to network
mfiore 0:c62615f15125 508 */
mfiore 0:c62615f15125 509 bool getNetworkJoinStatus();
mfiore 0:c62615f15125 510
mfiore 0:c62615f15125 511 /** Do a network link check
mfiore 0:c62615f15125 512 * application data may be returned in response to a network link check command
mfiore 0:c62615f15125 513 * @returns link_check structure containing success, dBm above noise floor, gateways in range, and packet payload
mfiore 0:c62615f15125 514 */
mfiore 0:c62615f15125 515 link_check networkLinkCheck();
mfiore 0:c62615f15125 516
mfiore 0:c62615f15125 517 /** Set network link check count to perform automatic link checks every count packets
mfiore 0:c62615f15125 518 * only applicable if ACKs are disabled
mfiore 0:c62615f15125 519 * @param count must be between 0 - 255
mfiore 0:c62615f15125 520 * @returns MDOT_OK if success
mfiore 0:c62615f15125 521 */
mfiore 0:c62615f15125 522 int32_t setLinkCheckCount(const uint8_t& count);
mfiore 0:c62615f15125 523
mfiore 0:c62615f15125 524 /** Get network link check count
mfiore 0:c62615f15125 525 * @returns count (0 - 255)
mfiore 0:c62615f15125 526 */
mfiore 0:c62615f15125 527 uint8_t getLinkCheckCount();
mfiore 0:c62615f15125 528
mfiore 0:c62615f15125 529 /** Set network link check threshold, number of link check failures or missed acks to tolerate
mfiore 0:c62615f15125 530 * before considering network connection lost
mfiore 0:c62615f15125 531 * @pararm count must be between 0 - 255
mfiore 0:c62615f15125 532 * @returns MDOT_OK if success
mfiore 0:c62615f15125 533 */
mfiore 0:c62615f15125 534 int32_t setLinkCheckThreshold(const uint8_t& count);
mfiore 0:c62615f15125 535
mfiore 0:c62615f15125 536 /** Get network link check threshold
mfiore 0:c62615f15125 537 * @returns threshold (0 - 255)
mfiore 0:c62615f15125 538 */
mfiore 0:c62615f15125 539 uint8_t getLinkCheckThreshold();
mfiore 0:c62615f15125 540
mfiore 0:c62615f15125 541 /** Get UpLinkCounter
mfiore 0:c62615f15125 542 * @returns number of packets sent to the gateway during this network session (sequence number)
mfiore 0:c62615f15125 543 */
mfiore 0:c62615f15125 544 uint32_t getUpLinkCounter();
mfiore 0:c62615f15125 545
mfiore 0:c62615f15125 546 /** Enable/disable AES encryption
mfiore 0:c62615f15125 547 * AES encryption must be enabled for use with Conduit gateway and MTAC_LORA card
mfiore 0:c62615f15125 548 * @param on true for AES encryption to be enabled
mfiore 0:c62615f15125 549 * @returns MDOT_OK if success
mfiore 0:c62615f15125 550 */
mfiore 0:c62615f15125 551 int32_t setAesEncryption(const bool& on);
mfiore 0:c62615f15125 552
mfiore 0:c62615f15125 553 /** Get AES encryption
mfiore 0:c62615f15125 554 * @returns true if AES encryption is enabled
mfiore 0:c62615f15125 555 */
mfiore 0:c62615f15125 556 bool getAesEncryption();
mfiore 0:c62615f15125 557
mfiore 0:c62615f15125 558 /** Get RSSI stats
Mike Fiore 11:d8464345e1f1 559 * @returns rssi_stats struct containing last, min, max, and avg RSSI in dB
mfiore 0:c62615f15125 560 */
mfiore 0:c62615f15125 561 rssi_stats getRssiStats();
mfiore 0:c62615f15125 562
mfiore 0:c62615f15125 563 /** Get SNR stats
Mike Fiore 11:d8464345e1f1 564 * @returns snr_stats struct containing last, min, max, and avg SNR in cB
mfiore 0:c62615f15125 565 */
mfiore 0:c62615f15125 566 snr_stats getSnrStats();
mfiore 0:c62615f15125 567
mfiore 0:c62615f15125 568 /** Get ms until next free channel
mfiore 0:c62615f15125 569 * only applicable for European models, US models return 0
mfiore 0:c62615f15125 570 * @returns time (ms) until a channel is free to use for transmitting
mfiore 0:c62615f15125 571 */
mfiore 0:c62615f15125 572 uint32_t getNextTxMs();
mfiore 0:c62615f15125 573
Jason Reiss 10:27dafba9fe19 574 /** Get join delay in seconds
Jason Reiss 10:27dafba9fe19 575 * Public network defaults to 5 seconds
Jason Reiss 10:27dafba9fe19 576 * Private network defaults to 1 second
Jason Reiss 10:27dafba9fe19 577 * @returns number of seconds before join accept message is expected
Jason Reiss 10:27dafba9fe19 578 */
Jason Reiss 10:27dafba9fe19 579 uint8_t getJoinDelay();
Jason Reiss 10:27dafba9fe19 580
Jason Reiss 10:27dafba9fe19 581 /** Set join delay in seconds
Jason Reiss 10:27dafba9fe19 582 * Public network defaults to 5 seconds
Jason Reiss 10:27dafba9fe19 583 * Private network defaults to 1 second
Jason Reiss 10:27dafba9fe19 584 * @param delay number of seconds before join accept message is expected
Jason Reiss 10:27dafba9fe19 585 * @return MDOT_OK if success
Jason Reiss 10:27dafba9fe19 586 */
Jason Reiss 10:27dafba9fe19 587 uint32_t setJoinDelay(uint8_t delay);
Jason Reiss 10:27dafba9fe19 588
Jason Reiss 10:27dafba9fe19 589 /** Get rx delay in seconds
Jason Reiss 10:27dafba9fe19 590 * Defaults to 1 second
Jason Reiss 10:27dafba9fe19 591 * @returns number of seconds before response message is expected
Jason Reiss 10:27dafba9fe19 592 */
Jason Reiss 10:27dafba9fe19 593 uint8_t getRxDelay();
Jason Reiss 10:27dafba9fe19 594
Jason Reiss 10:27dafba9fe19 595 /** Set rx delay in seconds
Jason Reiss 10:27dafba9fe19 596 * Defaults to 1 second
Jason Reiss 10:27dafba9fe19 597 * @param delay number of seconds before response message is expected
Jason Reiss 10:27dafba9fe19 598 * @return MDOT_OK if success
Jason Reiss 10:27dafba9fe19 599 */
Jason Reiss 10:27dafba9fe19 600 uint32_t setRxDelay(uint8_t delay);
Jason Reiss 10:27dafba9fe19 601
Jason Reiss 10:27dafba9fe19 602 /** Get preserve session to save network session info through reset or power down in AUTO_OTA mode
Jason Reiss 10:27dafba9fe19 603 * Defaults to off
Jason Reiss 10:27dafba9fe19 604 * @returns true if enabled
Jason Reiss 10:27dafba9fe19 605 */
Jason Reiss 10:27dafba9fe19 606 bool getPreserveSession();
Jason Reiss 10:27dafba9fe19 607
Jason Reiss 10:27dafba9fe19 608 /** Set preserve session to save network session info through reset or power down in AUTO_OTA mode
Jason Reiss 10:27dafba9fe19 609 * Defaults to off
Jason Reiss 10:27dafba9fe19 610 * @param enable
Jason Reiss 10:27dafba9fe19 611 * @return MDOT_OK if success
Jason Reiss 10:27dafba9fe19 612 */
Jason Reiss 10:27dafba9fe19 613 uint32_t setPreserveSession(bool enable);
Jason Reiss 10:27dafba9fe19 614
mfiore 0:c62615f15125 615 /** Get data pending
mfiore 0:c62615f15125 616 * only valid after sending data to the gateway
mfiore 0:c62615f15125 617 * @returns true if server has available packet(s)
mfiore 0:c62615f15125 618 */
mfiore 0:c62615f15125 619 bool getDataPending();
mfiore 0:c62615f15125 620
Jason Reiss 10:27dafba9fe19 621 /** Get transmitting
mfiore 0:c62615f15125 622 * @returns true if currently transmitting
mfiore 0:c62615f15125 623 */
mfiore 0:c62615f15125 624 bool getIsTransmitting();
mfiore 0:c62615f15125 625
mfiore 0:c62615f15125 626 /** Set TX data rate
mfiore 0:c62615f15125 627 * data rates affect maximum payload size
Mike Fiore 11:d8464345e1f1 628 * @param dr SF_7 - SF_12|DR0-DR7 for Europe, SF_7 - SF_10 | DR0-DR4 for United States
mfiore 0:c62615f15125 629 * @returns MDOT_OK if success
mfiore 0:c62615f15125 630 */
mfiore 0:c62615f15125 631 int32_t setTxDataRate(const uint8_t& dr);
mfiore 0:c62615f15125 632
mfiore 0:c62615f15125 633 /** Get TX data rate
Mike Fiore 11:d8464345e1f1 634 * @returns current TX data rate (DR0-DR15)
mfiore 0:c62615f15125 635 */
mfiore 0:c62615f15125 636 uint8_t getTxDataRate();
mfiore 0:c62615f15125 637
Mike Fiore 11:d8464345e1f1 638
Mike Fiore 11:d8464345e1f1 639 /** Get data rate spreading factor and bandwidth
Mike Fiore 11:d8464345e1f1 640 * EU868 Datarates
Mike Fiore 11:d8464345e1f1 641 * ---------------
Mike Fiore 11:d8464345e1f1 642 * DR0 - SF12BW125
Mike Fiore 11:d8464345e1f1 643 * DR1 - SF11BW125
Mike Fiore 11:d8464345e1f1 644 * DR2 - SF10BW125
Mike Fiore 11:d8464345e1f1 645 * DR3 - SF9BW125
Mike Fiore 11:d8464345e1f1 646 * DR4 - SF8BW125
Mike Fiore 11:d8464345e1f1 647 * DR5 - SF7BW125
Mike Fiore 11:d8464345e1f1 648 * DR6 - SF7BW250
Mike Fiore 11:d8464345e1f1 649 * DR7 - FSK
Mike Fiore 11:d8464345e1f1 650 *
Mike Fiore 11:d8464345e1f1 651 * US915 Datarates
Mike Fiore 11:d8464345e1f1 652 * ---------------
Mike Fiore 11:d8464345e1f1 653 * DR0 - SF10BW125
Mike Fiore 11:d8464345e1f1 654 * DR1 - SF9BW125
Mike Fiore 11:d8464345e1f1 655 * DR2 - SF8BW125
Mike Fiore 11:d8464345e1f1 656 * DR3 - SF7BW125
Mike Fiore 11:d8464345e1f1 657 * DR4 - SF8BW500
Mike Fiore 11:d8464345e1f1 658 *
Mike Fiore 11:d8464345e1f1 659 * @returns spreading factor and bandwidth
Mike Fiore 11:d8464345e1f1 660 */
Mike Fiore 11:d8464345e1f1 661 std::string getDateRateDetails(uint8_t rate);
Mike Fiore 11:d8464345e1f1 662
mfiore 0:c62615f15125 663 /** Set TX power
mfiore 0:c62615f15125 664 * power affects maximum range
mfiore 0:c62615f15125 665 * @param power 2 dBm - 20 dBm
mfiore 0:c62615f15125 666 * @returns MDOT_OK if success
mfiore 0:c62615f15125 667 */
mfiore 0:c62615f15125 668 int32_t setTxPower(const uint32_t& power);
mfiore 0:c62615f15125 669
mfiore 0:c62615f15125 670 /** Get TX power
mfiore 0:c62615f15125 671 * @returns TX power (2 dBm - 20 dBm)
mfiore 0:c62615f15125 672 */
mfiore 0:c62615f15125 673 uint32_t getTxPower();
mfiore 0:c62615f15125 674
Mike Fiore 11:d8464345e1f1 675 /** Get configured gain of installed antenna
Mike Fiore 11:d8464345e1f1 676 * @returns gain of antenna in dBi
Mike Fiore 11:d8464345e1f1 677 */
Mike Fiore 11:d8464345e1f1 678 int8_t getAntennaGain();
Mike Fiore 11:d8464345e1f1 679
Mike Fiore 11:d8464345e1f1 680 /** Set configured gain of installed antenna
Mike Fiore 11:d8464345e1f1 681 * @param gain -127 dBi - 128 dBi
Mike Fiore 11:d8464345e1f1 682 * @returns MDOT_OK if success
Mike Fiore 11:d8464345e1f1 683 */
Mike Fiore 11:d8464345e1f1 684 int32_t setAntennaGain(int8_t gain);
Mike Fiore 11:d8464345e1f1 685
mfiore 0:c62615f15125 686 /** Enable/disable TX waiting for rx windows
mfiore 0:c62615f15125 687 * when enabled, send calls will block until a packet is received or RX timeout
mfiore 0:c62615f15125 688 * @param enable set to true if expecting responses to transmitted packets
mfiore 0:c62615f15125 689 * @returns MDOT_OK if success
mfiore 0:c62615f15125 690 */
mfiore 0:c62615f15125 691 int32_t setTxWait(const bool& enable);
mfiore 0:c62615f15125 692
mfiore 0:c62615f15125 693 /** Get TX wait
mfiore 0:c62615f15125 694 * @returns true if TX wait is enabled
mfiore 0:c62615f15125 695 */
mfiore 0:c62615f15125 696 bool getTxWait();
mfiore 0:c62615f15125 697
mfiore 0:c62615f15125 698 /** Get time on air
mfiore 0:c62615f15125 699 * @returns the amount of time (in ms) it would take to send bytes bytes based on current configuration
mfiore 0:c62615f15125 700 */
mfiore 0:c62615f15125 701 uint32_t getTimeOnAir(uint8_t bytes);
mfiore 0:c62615f15125 702
mfiore 0:c62615f15125 703 /** Get min frequency
mfiore 0:c62615f15125 704 * @returns minimum frequency based on current configuration
mfiore 0:c62615f15125 705 */
mfiore 0:c62615f15125 706 uint32_t getMinFrequency();
mfiore 0:c62615f15125 707
mfiore 0:c62615f15125 708 /** Get max frequency
mfiore 0:c62615f15125 709 * @returns maximum frequency based on current configuration
mfiore 0:c62615f15125 710 */
mfiore 0:c62615f15125 711 uint32_t getMaxFrequency();
mfiore 0:c62615f15125 712
mfiore 0:c62615f15125 713 /** Set forward error correction bytes
mfiore 0:c62615f15125 714 * @param bytes 1 - 4 bytes
mfiore 0:c62615f15125 715 * @returns MDOT_OK if success
mfiore 0:c62615f15125 716 */
mfiore 0:c62615f15125 717 int32_t setFec(const uint8_t& bytes);
mfiore 0:c62615f15125 718
mfiore 0:c62615f15125 719 /** Get forward error correction bytes
mfiore 0:c62615f15125 720 * @returns bytes (1 - 4)
mfiore 0:c62615f15125 721 */
mfiore 0:c62615f15125 722 uint8_t getFec();
mfiore 0:c62615f15125 723
mfiore 0:c62615f15125 724 /** Enable/disable CRC checking of packets
mfiore 0:c62615f15125 725 * CRC checking must be enabled for use with Conduit gateway and MTAC_LORA card
mfiore 0:c62615f15125 726 * @param on set to true to enable CRC checking
mfiore 0:c62615f15125 727 * @returns MDOT_OK if success
mfiore 0:c62615f15125 728 */
mfiore 0:c62615f15125 729 int32_t setCrc(const bool& on);
mfiore 0:c62615f15125 730
mfiore 0:c62615f15125 731 /** Get CRC checking
mfiore 0:c62615f15125 732 * @returns true if CRC checking is enabled
mfiore 0:c62615f15125 733 */
mfiore 0:c62615f15125 734 bool getCrc();
mfiore 0:c62615f15125 735
mfiore 0:c62615f15125 736 /** Set ack
mfiore 0:c62615f15125 737 * @param retries 0 to disable acks, otherwise 1 - 8
mfiore 0:c62615f15125 738 * @returns MDOT_OK if success
mfiore 0:c62615f15125 739 */
mfiore 0:c62615f15125 740 int32_t setAck(const uint8_t& retries);
mfiore 0:c62615f15125 741
mfiore 0:c62615f15125 742 /** Get ack
mfiore 0:c62615f15125 743 * @returns 0 if acks are disabled, otherwise retries (1 - 8)
mfiore 0:c62615f15125 744 */
mfiore 0:c62615f15125 745 uint8_t getAck();
mfiore 0:c62615f15125 746
mfiore 0:c62615f15125 747 /** Send data to the gateway
mfiore 0:c62615f15125 748 * validates data size (based on spreading factor)
mfiore 0:c62615f15125 749 * @param data a vector of up to 242 bytes (may be less based on spreading factor)
mfiore 0:c62615f15125 750 * @returns MDOT_OK if packet was sent successfully (ACKs disabled), or if an ACK was received (ACKs enabled)
mfiore 0:c62615f15125 751 */
mfiore 0:c62615f15125 752 int32_t send(const std::vector<uint8_t>& data, const bool& blocking = true, const bool& highBw = false);
mfiore 0:c62615f15125 753
mfiore 0:c62615f15125 754 /** Fetch data received from the gateway
mfiore 0:c62615f15125 755 * this function only checks to see if a packet has been received - it does not open a receive window
mfiore 0:c62615f15125 756 * send() must be called before recv()
mfiore 0:c62615f15125 757 * @param data a vector to put the received data into
mfiore 0:c62615f15125 758 * @returns MDOT_OK if packet was successfully received
mfiore 0:c62615f15125 759 */
mfiore 0:c62615f15125 760 int32_t recv(std::vector<uint8_t>& data);
mfiore 0:c62615f15125 761
mfiore 0:c62615f15125 762 /** Ping
mfiore 0:c62615f15125 763 * status will be MDOT_OK if ping succeeded
mfiore 0:c62615f15125 764 * @returns ping_response struct containing status, RSSI, and SNR
mfiore 0:c62615f15125 765 */
mfiore 0:c62615f15125 766 ping_response ping();
mfiore 0:c62615f15125 767
mfiore 0:c62615f15125 768 /** Get return code string
mfiore 0:c62615f15125 769 * @returns string containing a description of the given error code
mfiore 0:c62615f15125 770 */
mfiore 0:c62615f15125 771 static std::string getReturnCodeString(const int32_t& code);
mfiore 0:c62615f15125 772
mfiore 0:c62615f15125 773 /** Get last error
mfiore 0:c62615f15125 774 * @returns string explaining the last error that occured
mfiore 0:c62615f15125 775 */
mfiore 0:c62615f15125 776 std::string getLastError();
mfiore 0:c62615f15125 777
Mike Fiore 7:683dba5d576f 778 /** Go to sleep
Jason Reiss 10:27dafba9fe19 779 * @param interval the number of seconds to sleep before waking up if wakeup_mode == RTC_ALARM or RTC_ALARM_OR_INTERRUPT, else ignored
Jason Reiss 10:27dafba9fe19 780 * @param wakeup_mode RTC_ALARM, INTERRUPT, RTC_ALARM_OR_INTERRUPT
Mike Fiore 7:683dba5d576f 781 * if RTC_ALARM the real time clock is configured to wake the device up after the specified interval
Mike Fiore 7:683dba5d576f 782 * if INTERRUPT the device will wake up on the rising edge of the interrupt pin
Jason Reiss 10:27dafba9fe19 783 * if RTC_ALARM_OR_INTERRUPT the device will wake on the first event to occur
Mike Fiore 7:683dba5d576f 784 * @param deepsleep if true go into deep sleep mode (lowest power, all memory and registers are lost, peripherals turned off)
Mike Fiore 7:683dba5d576f 785 * else go into sleep mode (low power, memory and registers are maintained, peripherals stay on)
Mike Fiore 7:683dba5d576f 786 *
Mike Fiore 11:d8464345e1f1 787 * in sleep mode, the device can be woken up on an XBEE_DI (2-8) pin or by the RTC alarm
Mike Fiore 7:683dba5d576f 788 * in deepsleep mode, the device can only be woken up using the WKUP pin (PA0, XBEE_DIO7) or by the RTC alarm
Mike Fiore 7:683dba5d576f 789 */
Mike Fiore 7:683dba5d576f 790 void sleep(const uint32_t& interval, const uint8_t& wakeup_mode = RTC_ALARM, const bool& deepsleep = true);
Mike Fiore 7:683dba5d576f 791
Mike Fiore 7:683dba5d576f 792 /** Set wake pin
Mike Fiore 11:d8464345e1f1 793 * @param pin the pin to use to wake the device from sleep mode XBEE_DI (2-8)
Mike Fiore 7:683dba5d576f 794 */
Mike Fiore 7:683dba5d576f 795 void setWakePin(const PinName& pin);
Mike Fiore 7:683dba5d576f 796
Mike Fiore 7:683dba5d576f 797 /** Get wake pin
Mike Fiore 11:d8464345e1f1 798 * @returns the pin to use to wake the device from sleep mode XBEE_DI (2-8)
Mike Fiore 7:683dba5d576f 799 */
Mike Fiore 7:683dba5d576f 800 PinName getWakePin();
Mike Fiore 7:683dba5d576f 801
jreiss 9:ec2fffe31793 802 /** Write data in a user backup register
jreiss 9:ec2fffe31793 803 * @param register one of UBR0 through UBR9
jreiss 9:ec2fffe31793 804 * @param data user data to back up
jreiss 9:ec2fffe31793 805 * @returns true if success
jreiss 9:ec2fffe31793 806 */
jreiss 9:ec2fffe31793 807 bool writeUserBackupRegister(uint32_t reg, uint32_t data);
jreiss 9:ec2fffe31793 808
jreiss 9:ec2fffe31793 809 /** Read data in a user backup register
jreiss 9:ec2fffe31793 810 * @param register one of UBR0 through UBR9
jreiss 9:ec2fffe31793 811 * @param data gets set to content of register
jreiss 9:ec2fffe31793 812 * @returns true if success
jreiss 9:ec2fffe31793 813 */
jreiss 9:ec2fffe31793 814 bool readUserBackupRegister(uint32_t reg, uint32_t& data);
jreiss 9:ec2fffe31793 815
Mike Fiore 11:d8464345e1f1 816 // Save user file data to flash
Mike Fiore 11:d8464345e1f1 817 // file - name of file max 30 chars
Mike Fiore 11:d8464345e1f1 818 // data - data of file
Mike Fiore 11:d8464345e1f1 819 // size - size of file
Mike Fiore 11:d8464345e1f1 820 bool saveUserFile(const char* file, void* data, uint32_t size);
Mike Fiore 11:d8464345e1f1 821
Mike Fiore 11:d8464345e1f1 822 // Append user file data to flash
Mike Fiore 11:d8464345e1f1 823 // file - name of file max 30 chars
Mike Fiore 11:d8464345e1f1 824 // data - data of file
Mike Fiore 11:d8464345e1f1 825 // size - size of file
Mike Fiore 11:d8464345e1f1 826 bool appendUserFile(const char* file, void* data, uint32_t size);
Mike Fiore 11:d8464345e1f1 827
Mike Fiore 11:d8464345e1f1 828 // Read user file data from flash
Mike Fiore 11:d8464345e1f1 829 // file - name of file max 30 chars
Mike Fiore 11:d8464345e1f1 830 // data - data of file
Mike Fiore 11:d8464345e1f1 831 // size - size of file
Mike Fiore 11:d8464345e1f1 832 bool readUserFile(const char* file, void* data, uint32_t size);
Mike Fiore 11:d8464345e1f1 833
Mike Fiore 11:d8464345e1f1 834 // Move a user file in flash
Mike Fiore 11:d8464345e1f1 835 // file - name of file
Mike Fiore 11:d8464345e1f1 836 // new_name - new name of file
Mike Fiore 11:d8464345e1f1 837 bool moveUserFile(const char* file, const char* new_name);
Mike Fiore 11:d8464345e1f1 838
Mike Fiore 11:d8464345e1f1 839 // Delete user file data from flash
Mike Fiore 11:d8464345e1f1 840 // file - name of file max 30 chars
Mike Fiore 11:d8464345e1f1 841 bool deleteUserFile(const char* file);
Mike Fiore 11:d8464345e1f1 842
Mike Fiore 11:d8464345e1f1 843 // Open user file in flash, max of 4 files open concurrently
Mike Fiore 11:d8464345e1f1 844 // file - name of file max 30 chars
Mike Fiore 11:d8464345e1f1 845 // mode - combination of FM_APPEND | FM_TRUNC | FM_CREAT |
Mike Fiore 11:d8464345e1f1 846 // FM_RDONLY | FM_WRONLY | FM_RDWR | FM_DIRECT
Mike Fiore 11:d8464345e1f1 847 // returns - mdot_file struct, fd field will be a negative value if file could not be opened
Mike Fiore 11:d8464345e1f1 848 mDot::mdot_file openUserFile(const char* file, int mode);
Mike Fiore 11:d8464345e1f1 849
Mike Fiore 11:d8464345e1f1 850 // Seek an open file
Mike Fiore 11:d8464345e1f1 851 // file - mdot file struct
Mike Fiore 11:d8464345e1f1 852 // offset - offset in bytes
Mike Fiore 11:d8464345e1f1 853 // whence - where offset is based SEEK_SET, SEEK_CUR, SEEK_END
Mike Fiore 11:d8464345e1f1 854 bool seekUserFile(mDot::mdot_file& file, size_t offset, int whence);
Mike Fiore 11:d8464345e1f1 855
Mike Fiore 11:d8464345e1f1 856 // Read bytes from open file
Mike Fiore 11:d8464345e1f1 857 // file - mdot file struct
Mike Fiore 11:d8464345e1f1 858 // data - mem location to store data
Mike Fiore 11:d8464345e1f1 859 // length - number of bytes to read
Mike Fiore 11:d8464345e1f1 860 // returns - number of bytes written
Mike Fiore 11:d8464345e1f1 861 int readUserFile(mDot::mdot_file& file, void* data, size_t length);
Mike Fiore 11:d8464345e1f1 862
Mike Fiore 11:d8464345e1f1 863 // Write bytes to open file
Mike Fiore 11:d8464345e1f1 864 // file - mdot file struct
Mike Fiore 11:d8464345e1f1 865 // data - data to write
Mike Fiore 11:d8464345e1f1 866 // length - number of bytes to write
Mike Fiore 11:d8464345e1f1 867 // returns - number of bytes written
Mike Fiore 11:d8464345e1f1 868 int writeUserFile(mDot::mdot_file& file, void* data, size_t length);
Mike Fiore 11:d8464345e1f1 869
Mike Fiore 11:d8464345e1f1 870 // Close open file
Mike Fiore 11:d8464345e1f1 871 // file - mdot file struct
Mike Fiore 11:d8464345e1f1 872 bool closeUserFile(mDot::mdot_file& file);
Mike Fiore 11:d8464345e1f1 873
Mike Fiore 11:d8464345e1f1 874 // List user files stored in flash
Mike Fiore 11:d8464345e1f1 875 std::vector<mDot::mdot_file> listUserFiles();
Mike Fiore 11:d8464345e1f1 876
Mike Fiore 11:d8464345e1f1 877 // Move file into the firmware upgrade path to be flashed on next boot
Mike Fiore 11:d8464345e1f1 878 // file - name of file
Mike Fiore 11:d8464345e1f1 879 bool moveUserFileToFirmwareUpgrade(const char* file);
Mike Fiore 11:d8464345e1f1 880
Mike Fiore 11:d8464345e1f1 881 // get current statistics
Mike Fiore 11:d8464345e1f1 882 // Join Attempts, Join Fails, Up Packets, Down Packets, Missed Acks
Mike Fiore 11:d8464345e1f1 883 mdot_stats getStats();
Mike Fiore 11:d8464345e1f1 884
Mike Fiore 11:d8464345e1f1 885 // reset statistics
Mike Fiore 11:d8464345e1f1 886 // Join Attempts, Join Fails, Up Packets, Down Packets, Missed Acks
Mike Fiore 11:d8464345e1f1 887 void resetStats();
Mike Fiore 11:d8464345e1f1 888
Mike Fiore 11:d8464345e1f1 889 // Convert pin number 2-8 to pin name DIO2-DI8
Mike Fiore 11:d8464345e1f1 890 static PinName pinNum2Name(uint8_t num);
Mike Fiore 11:d8464345e1f1 891
Mike Fiore 11:d8464345e1f1 892 // Convert pin name DIO2-DI8 to pin number 2-8
Mike Fiore 11:d8464345e1f1 893 static uint8_t pinName2Num(PinName name);
Mike Fiore 11:d8464345e1f1 894
Mike Fiore 11:d8464345e1f1 895 // Convert pin name DIO2-DI8 to string
Mike Fiore 11:d8464345e1f1 896 static std::string pinName2Str(PinName name);
Mike Fiore 11:d8464345e1f1 897
Mike Fiore 11:d8464345e1f1 898 uint64_t crc64(uint64_t crc, const unsigned char *s, uint64_t l);
mfiore 0:c62615f15125 899
mfiore 0:c62615f15125 900 /*************************************************************************
mfiore 0:c62615f15125 901 * The following functions are only used by the AT command application and
mfiore 0:c62615f15125 902 * should not be used by standard applications consuming the mDot library
mfiore 0:c62615f15125 903 ************************************************************************/
Mike Fiore 7:683dba5d576f 904
mfiore 0:c62615f15125 905 // set/get configured baud rate for command port
mfiore 0:c62615f15125 906 // only for use in conjunction with AT interface
mfiore 0:c62615f15125 907 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 908 int32_t setBaud(const uint32_t& baud);
mfiore 0:c62615f15125 909 uint32_t getBaud();
mfiore 0:c62615f15125 910
mfiore 0:c62615f15125 911 // set/get baud rate for debug port
mfiore 0:c62615f15125 912 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 913 int32_t setDebugBaud(const uint32_t& baud);
mfiore 0:c62615f15125 914 uint32_t getDebugBaud();
mfiore 0:c62615f15125 915
mfiore 0:c62615f15125 916 // set/get command terminal echo
mfiore 0:c62615f15125 917 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 918 int32_t setEcho(const bool& on);
mfiore 0:c62615f15125 919 bool getEcho();
mfiore 0:c62615f15125 920
mfiore 0:c62615f15125 921 // set/get command terminal verbose mode
mfiore 0:c62615f15125 922 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 923 int32_t setVerbose(const bool& on);
mfiore 0:c62615f15125 924 bool getVerbose();
mfiore 0:c62615f15125 925
mfiore 0:c62615f15125 926 // set/get startup mode
mfiore 0:c62615f15125 927 // COMMAND_MODE (default), starts up ready to accept AT commands
mfiore 0:c62615f15125 928 // SERIAL_MODE, read serial data and send it as LoRa packets
mfiore 0:c62615f15125 929 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 930 int32_t setStartUpMode(const uint8_t& mode);
mfiore 0:c62615f15125 931 uint8_t getStartUpMode();
mfiore 0:c62615f15125 932
mfiore 0:c62615f15125 933 int32_t setRxDataRate(const uint8_t& dr);
mfiore 0:c62615f15125 934 uint8_t getRxDataRate();
mfiore 0:c62615f15125 935
mfiore 0:c62615f15125 936 // get/set TX/RX frequency
mfiore 0:c62615f15125 937 // if frequency band == FB_868 (Europe), must be between 863000000 - 870000000
mfiore 0:c62615f15125 938 // if frequency band == FB_915 (United States), must be between 902000000-928000000
mfiore 0:c62615f15125 939 // if set to 0, device will hop frequencies
mfiore 0:c62615f15125 940 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 941 int32_t setTxFrequency(const uint32_t& freq);
mfiore 0:c62615f15125 942 uint32_t getTxFrequency();
mfiore 0:c62615f15125 943 int32_t setRxFrequency(const uint32_t& freq);
mfiore 0:c62615f15125 944 uint32_t getRxFrequency();
mfiore 0:c62615f15125 945
mfiore 0:c62615f15125 946 // get/set TX/RX inverted
mfiore 0:c62615f15125 947 // true == signal is inverted
mfiore 0:c62615f15125 948 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 949 int32_t setTxInverted(const bool& on);
mfiore 0:c62615f15125 950 bool getTxInverted();
mfiore 0:c62615f15125 951 int32_t setRxInverted(const bool& on);
mfiore 0:c62615f15125 952 bool getRxInverted();
mfiore 0:c62615f15125 953
mfiore 0:c62615f15125 954 // get/set RX output mode
mfiore 0:c62615f15125 955 // valid options are HEXADECIMAL and BINARY
mfiore 0:c62615f15125 956 // set function returns MDOT_OK if success
mfiore 0:c62615f15125 957 int32_t setRxOutput(const uint8_t& mode);
mfiore 0:c62615f15125 958 uint8_t getRxOutput();
mfiore 0:c62615f15125 959
mfiore 0:c62615f15125 960 // get/set serial wake interval
mfiore 0:c62615f15125 961 // valid values are 2 s - INT_MAX (2147483647) s
mfiore 0:c62615f15125 962 // set function returns MDOT_OK if success
Mike Fiore 7:683dba5d576f 963 int32_t setWakeInterval(const uint32_t& interval);
Mike Fiore 7:683dba5d576f 964 uint32_t getWakeInterval();
mfiore 0:c62615f15125 965
mfiore 0:c62615f15125 966 // get/set serial wake delay
mfiore 0:c62615f15125 967 // valid values are 2 ms - INT_MAX (2147483647) ms
mfiore 0:c62615f15125 968 // set function returns MDOT_OK if success
Mike Fiore 7:683dba5d576f 969 int32_t setWakeDelay(const uint32_t& delay);
Mike Fiore 7:683dba5d576f 970 uint32_t getWakeDelay();
mfiore 0:c62615f15125 971
mfiore 0:c62615f15125 972 // get/set serial receive timeout
mfiore 0:c62615f15125 973 // valid values are 0 ms - 65000 ms
mfiore 0:c62615f15125 974 // set function returns MDOT_OK if success
Mike Fiore 7:683dba5d576f 975 int32_t setWakeTimeout(const uint16_t& timeout);
Mike Fiore 7:683dba5d576f 976 uint16_t getWakeTimeout();
Mike Fiore 7:683dba5d576f 977
Mike Fiore 7:683dba5d576f 978 // get/set serial wake mode
Mike Fiore 7:683dba5d576f 979 // valid values are INTERRUPT or RTC_ALARM
Mike Fiore 7:683dba5d576f 980 // set function returns MDOT_OK if success
Mike Fiore 7:683dba5d576f 981 int32_t setWakeMode(const uint8_t& delay);
Mike Fiore 7:683dba5d576f 982 uint8_t getWakeMode();
Mike Fiore 7:683dba5d576f 983
Mike Fiore 11:d8464345e1f1 984 /******************************************
Mike Fiore 11:d8464345e1f1 985 * THESE FEATURES ARE NOT FULLY IMPLEMENTED
Mike Fiore 11:d8464345e1f1 986 *****************************************/
Mike Fiore 7:683dba5d576f 987
Mike Fiore 11:d8464345e1f1 988 // get/set adaptive data rate
Mike Fiore 11:d8464345e1f1 989 // configure data rates and power levels based on signal to noise information from gateway
Mike Fiore 11:d8464345e1f1 990 // true == adaptive data rate is on
Mike Fiore 11:d8464345e1f1 991 // set function returns MDOT_OK if success
Mike Fiore 11:d8464345e1f1 992 int32_t setAdr(const bool& on);
Mike Fiore 11:d8464345e1f1 993 bool getAdr();
mfiore 0:c62615f15125 994
mfiore 0:c62615f15125 995 // MTS_RADIO_DEBUG_COMMANDS
Mike Fiore 7:683dba5d576f 996
Mike Fiore 7:683dba5d576f 997 void openRxWindow(uint32_t timeout, uint8_t bandwidth = 0);
Mike Fiore 6:390fc83d588d 998 void sendContinuous();
mfiore 0:c62615f15125 999 int32_t setDeviceId(const std::vector<uint8_t>& id);
mfiore 0:c62615f15125 1000 int32_t setFrequencyBand(const uint8_t& band);
mfiore 0:c62615f15125 1001 bool saveProtectedConfig();
mfiore 0:c62615f15125 1002 void resetRadio();
mfiore 0:c62615f15125 1003 int32_t setRadioMode(const uint8_t& mode);
mfiore 0:c62615f15125 1004 std::map<uint8_t, uint8_t> dumpRegisters();
mfiore 0:c62615f15125 1005 void eraseFlash();
mfiore 0:c62615f15125 1006
Mike Fiore 7:683dba5d576f 1007 // deprecated - use setWakeInterval
Mike Fiore 7:683dba5d576f 1008 int32_t setSerialWakeInterval(const uint32_t& interval);
Mike Fiore 7:683dba5d576f 1009 // deprecated - use getWakeInterval
Mike Fiore 7:683dba5d576f 1010 uint32_t getSerialWakeInterval();
Mike Fiore 6:390fc83d588d 1011
Mike Fiore 7:683dba5d576f 1012 // deprecated - use setWakeDelay
Mike Fiore 7:683dba5d576f 1013 int32_t setSerialWakeDelay(const uint32_t& delay);
Mike Fiore 7:683dba5d576f 1014 // deprecated - use setWakeDelay
Mike Fiore 7:683dba5d576f 1015 uint32_t getSerialWakeDelay();
Mike Fiore 7:683dba5d576f 1016
Mike Fiore 7:683dba5d576f 1017 // deprecated - use setWakeTimeout
Mike Fiore 7:683dba5d576f 1018 int32_t setSerialReceiveTimeout(const uint16_t& timeout);
Mike Fiore 7:683dba5d576f 1019 // deprecated - use getWakeTimeout
Mike Fiore 7:683dba5d576f 1020 uint16_t getSerialReceiveTimeout();
mfiore 0:c62615f15125 1021
Mike Fiore 11:d8464345e1f1 1022 void setWakeupCallback(void (*function)(void));
Mike Fiore 11:d8464345e1f1 1023
Mike Fiore 11:d8464345e1f1 1024 template<typename T>
Mike Fiore 11:d8464345e1f1 1025 void setWakeupCallback(T *object, void (T::*member)(void)) {
Mike Fiore 11:d8464345e1f1 1026 _wakeup_callback.attach(object, member);
Mike Fiore 11:d8464345e1f1 1027 }
Mike Fiore 11:d8464345e1f1 1028
mfiore 0:c62615f15125 1029 private:
mfiore 0:c62615f15125 1030 mdot_stats _stats;
mfiore 0:c62615f15125 1031
Mike Fiore 11:d8464345e1f1 1032 FunctionPointer _wakeup_callback;
Mike Fiore 11:d8464345e1f1 1033
mfiore 0:c62615f15125 1034 };
mfiore 0:c62615f15125 1035
mfiore 0:c62615f15125 1036 #endif