mDot
/
libmDot-mbed5
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of
libmDot-mbed5
by 
MultiTech
Embed:
(wiki syntax)
Show/hide line numbers
mDot.h
00001 // TODO: add license header 00002 00003 #ifndef MDOT_H 00004 #define MDOT_H 00005 00006 #include "mbed.h" 00007 //#include "rtos.h" 00008 #include "Mote.h" 00009 #include <vector> 00010 #include <map> 00011 #include <string> 00012 00013 class mDotEvent; 00014 class LoRaConfig; 00015 00016 class mDot { 00017 friend class mDotEvent; 00018 00019 private: 00020 00021 mDot(); 00022 ~mDot(); 00023 00024 void initLora(); 00025 00026 void setLastError(const std::string& str); 00027 00028 static bool validateBaudRate(const uint32_t& baud); 00029 static bool validateFrequencySubBand(const uint8_t& band); 00030 bool validateDataRate(const uint8_t& dr); 00031 00032 int32_t joinBase(const uint32_t& retries); 00033 int32_t sendBase(const std::vector<uint8_t>& data, const bool& confirmed = false, const bool& blocking = true, const bool& highBw = false); 00034 void waitForPacket(); 00035 void waitForLinkCheck(); 00036 00037 void setActivityLedState(const uint8_t& state); 00038 uint8_t getActivityLedState(); 00039 00040 void blinkActivityLed(void) { 00041 if (_activity_led) { 00042 int val = _activity_led->read(); 00043 _activity_led->write(!val); 00044 } 00045 } 00046 00047 mDot(const mDot&); 00048 mDot& operator=(const mDot&); 00049 00050 uint32_t RTC_ReadBackupRegister(uint32_t RTC_BKP_DR); 00051 void RTC_WriteBackupRegister(uint32_t RTC_BKP_DR, uint32_t Data); 00052 00053 void wakeup(); 00054 00055 void enterStopMode(const uint32_t& interval, const uint8_t& wakeup_mode = RTC_ALARM); 00056 void enterStandbyMode(const uint32_t& interval, const uint8_t& wakeup_mode = RTC_ALARM); 00057 00058 static mDot* _instance; 00059 00060 lora::Mote _mote; 00061 LoRaConfig* _config; 00062 lora::Settings _settings; 00063 mDotEvent* _events; 00064 00065 std::string _last_error; 00066 static const uint32_t _baud_rates[]; 00067 uint8_t _activity_led_state; 00068 Ticker _tick; 00069 DigitalOut* _activity_led; 00070 bool _activity_led_enable; 00071 PinName _activity_led_pin; 00072 bool _activity_led_external; 00073 uint8_t _linkFailCount; 00074 uint8_t _class; 00075 InterruptIn* _wakeup; 00076 PinName _wakeup_pin; 00077 00078 typedef enum { 00079 OFF, 00080 ON, 00081 BLINK, 00082 } state; 00083 00084 public: 00085 00086 #if defined(TARGET_MTS_MDOT_F411RE) 00087 typedef enum { 00088 FM_APPEND = (1 << 0), 00089 FM_TRUNC = (1 << 1), 00090 FM_CREAT = (1 << 2), 00091 FM_RDONLY = (1 << 3), 00092 FM_WRONLY = (1 << 4), 00093 FM_RDWR = (FM_RDONLY | FM_WRONLY), 00094 FM_DIRECT = (1 << 5) 00095 } FileMode; 00096 #endif /* TARGET_MTS_MDOT_F411RE */ 00097 00098 typedef enum { 00099 MDOT_OK = 0, 00100 MDOT_INVALID_PARAM = -1, 00101 MDOT_TX_ERROR = -2, 00102 MDOT_RX_ERROR = -3, 00103 MDOT_JOIN_ERROR = -4, 00104 MDOT_TIMEOUT = -5, 00105 MDOT_NOT_JOINED = -6, 00106 MDOT_ENCRYPTION_DISABLED = -7, 00107 MDOT_NO_FREE_CHAN = -8, 00108 MDOT_TEST_MODE = -9, 00109 MDOT_NO_ENABLED_CHAN = -10, 00110 MDOT_AGGREGATED_DUTY_CYCLE = -11, 00111 MDOT_MAX_PAYLOAD_EXCEEDED = -12, 00112 MDOT_ERROR = -1024, 00113 } mdot_ret_code; 00114 00115 enum JoinMode { 00116 MANUAL = 0, 00117 OTA, 00118 AUTO_OTA, 00119 PEER_TO_PEER 00120 }; 00121 00122 enum Mode { 00123 COMMAND_MODE, 00124 SERIAL_MODE 00125 }; 00126 00127 enum RX_Output { 00128 HEXADECIMAL, 00129 BINARY 00130 }; 00131 00132 enum DataRates { 00133 DR0, 00134 DR1, 00135 DR2, 00136 DR3, 00137 DR4, 00138 DR5, 00139 DR6, 00140 DR7, 00141 DR8, 00142 DR9, 00143 DR10, 00144 DR11, 00145 DR12, 00146 DR13, 00147 DR14, 00148 DR15, 00149 SF_12 = 16, 00150 SF_11, 00151 SF_10, 00152 SF_9, 00153 SF_8, 00154 SF_7, 00155 SF_7H, 00156 SF_FSK 00157 }; 00158 00159 enum FrequencyBands { 00160 FB_868 = 0, 00161 FB_915 = 1, 00162 FB_EU868 = 0, // EU868 00163 FB_US915 = 1, // US915 00164 FB_AU915 = 2 00165 }; 00166 00167 enum FrequencySubBands { 00168 FSB_ALL, 00169 FSB_1, 00170 FSB_2, 00171 FSB_3, 00172 FSB_4, 00173 FSB_5, 00174 FSB_6, 00175 FSB_7, 00176 FSB_8 00177 }; 00178 00179 enum JoinByteOrder { 00180 LSB, 00181 MSB 00182 }; 00183 00184 enum wakeup_mode { 00185 RTC_ALARM, 00186 INTERRUPT, 00187 RTC_ALARM_OR_INTERRUPT 00188 }; 00189 00190 enum UserBackupRegs { 00191 UBR0, 00192 UBR1, 00193 UBR2, 00194 UBR3, 00195 UBR4, 00196 UBR5, 00197 UBR6, 00198 UBR7, 00199 UBR8, 00200 UBR9 00201 #if defined (TARGET_XDOT_L151CC) 00202 ,UBR10, 00203 UBR11, 00204 UBR12, 00205 UBR13, 00206 UBR14, 00207 UBR15, 00208 UBR16, 00209 UBR17, 00210 UBR18, 00211 UBR19, 00212 UBR20, 00213 UBR21 00214 #endif /* TARGET_XDOT_L151CC */ 00215 }; 00216 00217 #if defined(TARGET_MTS_MDOT_F411RE) 00218 typedef struct { 00219 int16_t fd; 00220 char name[33]; 00221 uint32_t size; 00222 } mdot_file; 00223 #endif /* TARGET_MTS_MDOT_F411RE */ 00224 00225 typedef struct { 00226 uint32_t Up; 00227 uint32_t Down; 00228 uint32_t Joins; 00229 uint32_t JoinFails; 00230 uint32_t MissedAcks; 00231 uint32_t CRCErrors; 00232 } mdot_stats; 00233 00234 typedef struct { 00235 int16_t last; 00236 int16_t min; 00237 int16_t max; 00238 int16_t avg; 00239 } rssi_stats; 00240 00241 typedef struct { 00242 int16_t last; 00243 int16_t min; 00244 int16_t max; 00245 int16_t avg; 00246 } snr_stats; 00247 00248 typedef struct { 00249 bool status; 00250 int32_t dBm; 00251 uint32_t gateways; 00252 std::vector<uint8_t> payload; 00253 } link_check; 00254 00255 typedef struct { 00256 int32_t status; 00257 int16_t rssi; 00258 int16_t snr; 00259 } ping_response; 00260 00261 static const uint8_t MaxLengths_915[]; 00262 static const uint8_t MaxLengths_868[]; 00263 00264 static std::string JoinModeStr(uint8_t mode); 00265 static std::string ModeStr(uint8_t mode); 00266 static std::string RxOutputStr(uint8_t format); 00267 static std::string DataRateStr(uint8_t rate); 00268 static std::string FrequencyBandStr(uint8_t band); 00269 static std::string FrequencySubBandStr(uint8_t band); 00270 00271 #if defined(TARGET_MTS_MDOT_F411RE) 00272 uint32_t UserRegisters[10]; 00273 #else 00274 uint32_t UserRegisters[22]; 00275 #endif /* TARGET_MTS_MDOT_F411RE */ 00276 00277 /** Get a handle to the singleton object 00278 * @returns pointer to mDot object 00279 */ 00280 static mDot* getInstance(); 00281 00282 void setEvents(mDotEvent* events); 00283 00284 /** Get library version information 00285 * @returns string containing library version information 00286 */ 00287 std::string getId(); 00288 00289 /** Perform a soft reset of the system 00290 */ 00291 void resetCpu(); 00292 00293 /** Reset config to factory default 00294 */ 00295 void resetConfig(); 00296 00297 /** Save config data to non volatile memory 00298 * @returns true if success, false if failure 00299 */ 00300 bool saveConfig(); 00301 00302 /** Set the log level for the library 00303 * options are: 00304 * NONE_LEVEL - logging is off at this level 00305 * FATAL_LEVEL - only critical errors will be reported 00306 * ERROR_LEVEL 00307 * WARNING_LEVEL 00308 * INFO_LEVEL 00309 * DEBUG_LEVEL 00310 * TRACE_LEVEL - every detail will be reported 00311 * @param level the level to log at 00312 * @returns MDOT_OK if success 00313 */ 00314 int32_t setLogLevel(const uint8_t& level); 00315 00316 /** Get the current log level for the library 00317 * @returns current log level 00318 */ 00319 uint8_t getLogLevel(); 00320 00321 /** Seed pseudo RNG in LoRaMac layer, uses random value from radio RSSI reading by default 00322 * @param seed for RNG 00323 */ 00324 void seedRandom(uint32_t seed); 00325 00326 /** Enable or disable the activity LED. 00327 * @param enable true to enable the LED, false to disable 00328 */ 00329 void setActivityLedEnable(const bool& enable); 00330 00331 /** Find out if the activity LED is enabled 00332 * @returns true if activity LED is enabled, false if disabled 00333 */ 00334 bool getActivityLedEnable(); 00335 00336 /** Use a different pin for the activity LED. 00337 * The default is XBEE_RSSI. 00338 * @param pin the new pin to use 00339 */ 00340 void setActivityLedPin(const PinName& pin); 00341 00342 /** Use an external DigitalOut object for the activity LED. 00343 * The pointer must stay valid! 00344 * @param pin the DigitalOut object to use 00345 */ 00346 void setActivityLedPin(DigitalOut* pin); 00347 00348 /** Find out what pin the activity LED is on 00349 * @returns the pin the activity LED is using 00350 */ 00351 PinName getActivityLedPin(); 00352 00353 /** Returns boolean indicative of start-up from standby mode 00354 * @returns true if dot woke from standby 00355 */ 00356 bool getStandbyFlag(); 00357 00358 std::vector<uint16_t> getChannelMask(); 00359 00360 int32_t setChannelMask(uint8_t offset, uint16_t mask); 00361 00362 /** Add a channel frequencies currently in use 00363 * @returns MDOT_OK 00364 */ 00365 int32_t addChannel(uint8_t index, uint32_t frequency, uint8_t datarateRange); 00366 00367 /** Get list of channel frequencies currently in use 00368 * @returns vector of channels currently in use 00369 */ 00370 std::vector<uint32_t> getChannels(); 00371 00372 /** Get list of channel datarate ranges currently in use 00373 * @returns vector of datarate ranges currently in use 00374 */ 00375 std::vector<uint8_t> getChannelRanges(); 00376 00377 /** Get list of channel frequencies in config file to be used as session defaults 00378 * @returns vector of channels in config file 00379 */ 00380 std::vector<uint32_t> getConfigChannels(); 00381 00382 /** Get list of channel datarate ranges in config file to be used as session defaults 00383 * @returns vector of datarate ranges in config file 00384 */ 00385 std::vector<uint8_t> getConfigChannelRanges(); 00386 00387 /** Get frequency band 00388 * @returns FB_915 if configured for United States, FB_868 if configured for Europe 00389 */ 00390 uint8_t getFrequencyBand(); 00391 00392 /** Set frequency sub band 00393 * only applicable if frequency band is set for United States (FB_915) 00394 * sub band 0 will allow the radio to use all 64 channels 00395 * sub band 1 - 8 will allow the radio to use the 8 channels in that sub band 00396 * for use with Conduit gateway and MTAC_LORA, use sub bands 1 - 8, not sub band 0 00397 * @param band the sub band to use (0 - 8) 00398 * @returns MDOT_OK if success 00399 */ 00400 int32_t setFrequencySubBand(const uint8_t& band); 00401 00402 /** Get frequency sub band 00403 * @returns frequency sub band currently in use 00404 */ 00405 uint8_t getFrequencySubBand(); 00406 00407 /** Get the datarate currently in use within the MAC layer 00408 * returns 0-15 00409 */ 00410 uint8_t getSessionDataRate(); 00411 00412 /** Enable/disable public network mode 00413 * JoinDelay will be set to (public: 5s, private: 1s) and 00414 * RxDelay will be set to 1s both can be adjusted afterwards 00415 * @param on should be true to enable public network mode 00416 * @returns MDOT_OK if success 00417 */ 00418 int32_t setPublicNetwork(const bool& on); 00419 00420 /** Get public network mode 00421 * @returns true if public network mode is enabled 00422 */ 00423 bool getPublicNetwork(); 00424 00425 /** Get the device ID 00426 * @returns vector containing the device ID (size 8) 00427 */ 00428 std::vector<uint8_t> getDeviceId(); 00429 00430 /** Get the device port to be used for lora application data (1-223) 00431 * @returns port 00432 */ 00433 uint8_t getAppPort(); 00434 00435 /** Set the device port to be used for lora application data (1-223) 00436 * @returns MDOT_OK if success 00437 */ 00438 int32_t setAppPort(uint8_t port); 00439 00440 /** Set the device class A, B or C 00441 * @returns MDOT_OK if success 00442 */ 00443 int32_t setClass(std::string newClass); 00444 00445 /** Get the device class A, B or C 00446 * @returns MDOT_OK if success 00447 */ 00448 std::string getClass(); 00449 00450 /** Get the max packet length with current settings 00451 * @returns max packet length 00452 */ 00453 uint8_t getMaxPacketLength(); 00454 00455 /** Set network address 00456 * for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes 00457 * @param addr a vector of 4 bytes 00458 * @returns MDOT_OK if success 00459 */ 00460 int32_t setNetworkAddress(const std::vector<uint8_t>& addr); 00461 00462 /** Get network address 00463 * @returns vector containing network address (size 4) 00464 */ 00465 std::vector<uint8_t> getNetworkAddress(); 00466 00467 /** Set network session key 00468 * for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes 00469 * @param key a vector of 16 bytes 00470 * @returns MDOT_OK if success 00471 */ 00472 int32_t setNetworkSessionKey(const std::vector<uint8_t>& key); 00473 00474 /** Get network session key 00475 * @returns vector containing network session key (size 16) 00476 */ 00477 std::vector<uint8_t> getNetworkSessionKey(); 00478 00479 /** Set data session key 00480 * for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes 00481 * @param key a vector of 16 bytes 00482 * @returns MDOT_OK if success 00483 */ 00484 int32_t setDataSessionKey(const std::vector<uint8_t>& key); 00485 00486 /** Get data session key 00487 * @returns vector containing data session key (size 16) 00488 */ 00489 std::vector<uint8_t> getDataSessionKey(); 00490 00491 /** Set network name 00492 * for use with OTA & AUTO_OTA network join modes 00493 * generates network ID (crc64 of name) automatically 00494 * @param name a string of of at least 8 bytes and no more than 128 bytes 00495 * @return MDOT_OK if success 00496 */ 00497 int32_t setNetworkName(const std::string& name); 00498 00499 /** Get network name 00500 * @return string containing network name (size 8 to 128) 00501 */ 00502 std::string getNetworkName(); 00503 00504 /** Set network ID 00505 * for use with OTA & AUTO_OTA network join modes 00506 * setting network ID via this function sets network name to empty 00507 * @param id a vector of 8 bytes 00508 * @returns MDOT_OK if success 00509 */ 00510 int32_t setNetworkId(const std::vector<uint8_t>& id); 00511 00512 /** Get network ID 00513 * @returns vector containing network ID (size 8) 00514 */ 00515 std::vector<uint8_t> getNetworkId(); 00516 00517 /** Set network passphrase 00518 * for use with OTA & AUTO_OTA network join modes 00519 * generates network key (cmac of passphrase) automatically 00520 * @param name a string of of at least 8 bytes and no more than 128 bytes 00521 * @return MDOT_OK if success 00522 */ 00523 int32_t setNetworkPassphrase(const std::string& passphrase); 00524 00525 /** Get network passphrase 00526 * @return string containing network passphrase (size 8 to 128) 00527 */ 00528 std::string getNetworkPassphrase(); 00529 00530 /** Set network key 00531 * for use with OTA & AUTO_OTA network join modes 00532 * setting network key via this function sets network passphrase to empty 00533 * @param id a vector of 16 bytes 00534 * @returns MDOT_OK if success 00535 */ 00536 int32_t setNetworkKey(const std::vector<uint8_t>& id); 00537 00538 /** Get network key 00539 * @returns a vector containing network key (size 16) 00540 */ 00541 std::vector<uint8_t> getNetworkKey(); 00542 00543 /** Set join byte order 00544 * @param order 0:LSB 1:MSB 00545 */ 00546 uint32_t setJoinByteOrder(uint8_t order); 00547 00548 /** Get join byte order 00549 * @returns byte order to use in joins 0:LSB 1:MSB 00550 */ 00551 uint8_t getJoinByteOrder(); 00552 00553 /** Attempt to join network 00554 * each attempt will be made with a random datarate up to the configured datarate 00555 * JoinRequest backoff between tries is enforced to 1% for 1st hour, 0.1% for 1-10 hours and 0.01% after 10 hours 00556 * Check getNextTxMs() for time until next join attempt can be made 00557 * @returns MDOT_OK if success 00558 */ 00559 int32_t joinNetwork(); 00560 00561 /** Attempts to join network once 00562 * @returns MDOT_OK if success 00563 */ 00564 int32_t joinNetworkOnce(); 00565 00566 /** Resets current network session, essentially disconnecting from the network 00567 * has no effect for MANUAL network join mode 00568 */ 00569 void resetNetworkSession(); 00570 00571 /** Restore saved network session from flash 00572 * has no effect for MANUAL network join mode 00573 */ 00574 void restoreNetworkSession(); 00575 00576 /** Save current network session to flash 00577 * has no effect for MANUAL network join mode 00578 */ 00579 void saveNetworkSession(); 00580 00581 /** Set number of times joining will retry each sub-band before changing 00582 * to the next subband in US915 and AU915 00583 * @param retries must be between 0 - 255 00584 * @returns MDOT_OK if success 00585 */ 00586 int32_t setJoinRetries(const uint8_t& retries); 00587 00588 /** Get number of times joining will retry each sub-band 00589 * @returns join retries (0 - 255) 00590 */ 00591 uint8_t getJoinRetries(); 00592 00593 /** Set network join mode 00594 * MANUAL: set network address and session keys manually 00595 * OTA: User sets network name and passphrase, then attempts to join 00596 * AUTO_OTA: same as OTA, but network sessions can be saved and restored 00597 * @param mode MANUAL, OTA, or AUTO_OTA 00598 * @returns MDOT_OK if success 00599 */ 00600 int32_t setJoinMode(const uint8_t& mode); 00601 00602 /** Get network join mode 00603 * @returns MANUAL, OTA, or AUTO_OTA 00604 */ 00605 uint8_t getJoinMode(); 00606 00607 /** Get network join status 00608 * @returns true if currently joined to network 00609 */ 00610 bool getNetworkJoinStatus(); 00611 00612 /** Do a network link check 00613 * application data may be returned in response to a network link check command 00614 * @returns link_check structure containing success, dBm above noise floor, gateways in range, and packet payload 00615 */ 00616 link_check networkLinkCheck(); 00617 00618 /** Set network link check count to perform automatic link checks every count packets 00619 * only applicable if ACKs are disabled 00620 * @param count must be between 0 - 255 00621 * @returns MDOT_OK if success 00622 */ 00623 int32_t setLinkCheckCount(const uint8_t& count); 00624 00625 /** Get network link check count 00626 * @returns count (0 - 255) 00627 */ 00628 uint8_t getLinkCheckCount(); 00629 00630 /** Set network link check threshold, number of link check failures or missed acks to tolerate 00631 * before considering network connection lost 00632 * @pararm count must be between 0 - 255 00633 * @returns MDOT_OK if success 00634 */ 00635 int32_t setLinkCheckThreshold(const uint8_t& count); 00636 00637 /** Get network link check threshold 00638 * @returns threshold (0 - 255) 00639 */ 00640 uint8_t getLinkCheckThreshold(); 00641 00642 /** Get/set number of failed link checks in the current session 00643 * @returns count (0 - 255) 00644 */ 00645 uint8_t getLinkFailCount(); 00646 int32_t setLinkFailCount(uint8_t count); 00647 00648 /** Set UpLinkCounter number of packets sent to the gateway during this network session (sequence number) 00649 * @returns MDOT_OK 00650 */ 00651 int32_t setUpLinkCounter(uint32_t count); 00652 00653 /** Get UpLinkCounter 00654 * @returns number of packets sent to the gateway during this network session (sequence number) 00655 */ 00656 uint32_t getUpLinkCounter(); 00657 00658 /** Set UpLinkCounter number of packets sent by the gateway during this network session (sequence number) 00659 * @returns MDOT_OK 00660 */ 00661 int32_t setDownLinkCounter(uint32_t count); 00662 00663 /** Get DownLinkCounter 00664 * @returns number of packets sent by the gateway during this network session (sequence number) 00665 */ 00666 uint32_t getDownLinkCounter(); 00667 00668 /** Enable/disable AES encryption 00669 * AES encryption must be enabled for use with Conduit gateway and MTAC_LORA card 00670 * @param on true for AES encryption to be enabled 00671 * @returns MDOT_OK if success 00672 */ 00673 int32_t setAesEncryption(const bool& on); 00674 00675 /** Get AES encryption 00676 * @returns true if AES encryption is enabled 00677 */ 00678 bool getAesEncryption(); 00679 00680 /** Get RSSI stats 00681 * @returns rssi_stats struct containing last, min, max, and avg RSSI in dB 00682 */ 00683 rssi_stats getRssiStats(); 00684 00685 /** Get SNR stats 00686 * @returns snr_stats struct containing last, min, max, and avg SNR in cB 00687 */ 00688 snr_stats getSnrStats(); 00689 00690 /** Get ms until next free channel 00691 * only applicable for European models, US models return 0 00692 * @returns time (ms) until a channel is free to use for transmitting 00693 */ 00694 uint32_t getNextTxMs(); 00695 00696 /** Get join delay in seconds 00697 * Public network defaults to 5 seconds 00698 * Private network defaults to 1 second 00699 * @returns number of seconds before join accept message is expected 00700 */ 00701 uint8_t getJoinDelay(); 00702 00703 /** Set join delay in seconds 00704 * Public network defaults to 5 seconds 00705 * Private network defaults to 1 second 00706 * @param delay number of seconds before join accept message is expected 00707 * @return MDOT_OK if success 00708 */ 00709 uint32_t setJoinDelay(uint8_t delay); 00710 00711 /** Get join Rx1 datarate offset 00712 * defaults to 0 00713 * @returns offset 00714 */ 00715 uint8_t getJoinRx1DataRateOffset(); 00716 00717 /** Set join Rx1 datarate offset 00718 * @param offset for datarate 00719 * @return MDOT_OK if success 00720 */ 00721 uint32_t setJoinRx1DataRateOffset(uint8_t offset); 00722 00723 /** Get join Rx2 datarate 00724 * defaults to US:DR8, AU:DR8, EU:DR0 00725 * @returns datarate 00726 */ 00727 uint8_t getJoinRx2DataRate(); 00728 00729 /** Set join Rx2 datarate 00730 * @param datarate 00731 * @return MDOT_OK if success 00732 */ 00733 uint32_t setJoinRx2DataRate(uint8_t datarate); 00734 00735 /** Get join Rx2 frequency 00736 * defaults US:923.3, AU:923.3, EU:869.525 00737 * @returns frequency 00738 */ 00739 uint32_t getJoinRx2Frequency(); 00740 00741 /** Set join Rx2 frequency 00742 * @param frequency 00743 * @return MDOT_OK if success 00744 */ 00745 uint32_t setJoinRx2Frequency(uint32_t frequency); 00746 00747 /** Get rx delay in seconds 00748 * Defaults to 1 second 00749 * @returns number of seconds before response message is expected 00750 */ 00751 uint8_t getRxDelay(); 00752 00753 /** Set rx delay in seconds 00754 * Defaults to 1 second 00755 * @param delay number of seconds before response message is expected 00756 * @return MDOT_OK if success 00757 */ 00758 uint32_t setRxDelay(uint8_t delay); 00759 00760 /** Get preserve session to save network session info through reset or power down in AUTO_OTA mode 00761 * Defaults to off 00762 * @returns true if enabled 00763 */ 00764 bool getPreserveSession(); 00765 00766 /** Set preserve session to save network session info through reset or power down in AUTO_OTA mode 00767 * Defaults to off 00768 * @param enable 00769 * @return MDOT_OK if success 00770 */ 00771 uint32_t setPreserveSession(bool enable); 00772 00773 /** Get data pending 00774 * only valid after sending data to the gateway 00775 * @returns true if server has available packet(s) 00776 */ 00777 bool getDataPending(); 00778 00779 /** Get ack requested 00780 * only valid after sending data to the gateway 00781 * @returns true if server has requested ack 00782 */ 00783 bool getAckRequested(); 00784 00785 /** Get is transmitting indicator 00786 * @returns true if currently transmitting 00787 */ 00788 bool getIsTransmitting(); 00789 00790 /** Get is idle indicator 00791 * @returns true if not currently transmitting, waiting or receiving 00792 */ 00793 bool getIsIdle(); 00794 00795 /** Set TX data rate 00796 * data rates affect maximum payload size 00797 * @param dr SF_7 - SF_12|DR0-DR7 for Europe, SF_7 - SF_10 | DR0-DR4 for United States 00798 * @returns MDOT_OK if success 00799 */ 00800 int32_t setTxDataRate(const uint8_t& dr); 00801 00802 /** Get TX data rate 00803 * @returns current TX data rate (DR0-DR15) 00804 */ 00805 uint8_t getTxDataRate(); 00806 00807 /** Get a random value from the radio based on RSSI 00808 * @returns randome value 00809 */ 00810 uint32_t getRadioRandom(); 00811 00812 /** Get data rate spreading factor and bandwidth 00813 * EU868 Datarates 00814 * --------------- 00815 * DR0 - SF12BW125 00816 * DR1 - SF11BW125 00817 * DR2 - SF10BW125 00818 * DR3 - SF9BW125 00819 * DR4 - SF8BW125 00820 * DR5 - SF7BW125 00821 * DR6 - SF7BW250 00822 * DR7 - FSK 00823 * 00824 * US915 Datarates 00825 * --------------- 00826 * DR0 - SF10BW125 00827 * DR1 - SF9BW125 00828 * DR2 - SF8BW125 00829 * DR3 - SF7BW125 00830 * DR4 - SF8BW500 00831 * 00832 * AU915 Datarates 00833 * --------------- 00834 * DR0 - SF10BW125 00835 * DR1 - SF9BW125 00836 * DR2 - SF8BW125 00837 * DR3 - SF7BW125 00838 * DR4 - SF8BW500 00839 * 00840 * @returns spreading factor and bandwidth 00841 */ 00842 std::string getDateRateDetails(uint8_t rate); 00843 00844 /** Set TX power output of radio before antenna gain, default: 14 dBm 00845 * actual output power may be limited by local regulations for the chosen frequency 00846 * power affects maximum range 00847 * @param power 2 dBm - 20 dBm 00848 * @returns MDOT_OK if success 00849 */ 00850 int32_t setTxPower(const uint32_t& power); 00851 00852 /** Get TX power 00853 * @returns TX power (2 dBm - 20 dBm) 00854 */ 00855 uint32_t getTxPower(); 00856 00857 /** Get configured gain of installed antenna, default: +3 dBi 00858 * @returns gain of antenna in dBi 00859 */ 00860 int8_t getAntennaGain(); 00861 00862 /** Set configured gain of installed antenna, default: +3 dBi 00863 * @param gain -127 dBi - 128 dBi 00864 * @returns MDOT_OK if success 00865 */ 00866 int32_t setAntennaGain(int8_t gain); 00867 00868 /** Enable/disable TX waiting for rx windows 00869 * when enabled, send calls will block until a packet is received or RX timeout 00870 * @param enable set to true if expecting responses to transmitted packets 00871 * @returns MDOT_OK if success 00872 */ 00873 int32_t setTxWait(const bool& enable); 00874 00875 /** Get TX wait 00876 * @returns true if TX wait is enabled 00877 */ 00878 bool getTxWait(); 00879 00880 /** Cancel pending rx windows 00881 */ 00882 void cancelRxWindow(); 00883 00884 /** Get time on air 00885 * @returns the amount of time (in ms) it would take to send bytes bytes based on current configuration 00886 */ 00887 uint32_t getTimeOnAir(uint8_t bytes); 00888 00889 /** Get min frequency 00890 * @returns minimum frequency based on current configuration 00891 */ 00892 uint32_t getMinFrequency(); 00893 00894 /** Get max frequency 00895 * @returns maximum frequency based on current configuration 00896 */ 00897 uint32_t getMaxFrequency(); 00898 00899 // get/set adaptive data rate 00900 // configure data rates and power levels based on signal to noise of packets received at gateway 00901 // true == adaptive data rate is on 00902 // set function returns MDOT_OK if success 00903 int32_t setAdr(const bool& on); 00904 bool getAdr(); 00905 00906 /** Set forward error correction bytes 00907 * @param bytes 1 - 4 bytes 00908 * @returns MDOT_OK if success 00909 */ 00910 int32_t setFec(const uint8_t& bytes); 00911 00912 /** Get forward error correction bytes 00913 * @returns bytes (1 - 4) 00914 */ 00915 uint8_t getFec(); 00916 00917 /** Enable/disable CRC checking of packets 00918 * CRC checking must be enabled for use with Conduit gateway and MTAC_LORA card 00919 * @param on set to true to enable CRC checking 00920 * @returns MDOT_OK if success 00921 */ 00922 int32_t setCrc(const bool& on); 00923 00924 /** Get CRC checking 00925 * @returns true if CRC checking is enabled 00926 */ 00927 bool getCrc(); 00928 00929 /** Set ack 00930 * @param retries 0 to disable acks, otherwise 1 - 8 00931 * @returns MDOT_OK if success 00932 */ 00933 int32_t setAck(const uint8_t& retries); 00934 00935 /** Get ack 00936 * @returns 0 if acks are disabled, otherwise retries (1 - 8) 00937 */ 00938 uint8_t getAck(); 00939 00940 /** Set number of packet repeats for unconfirmed frames 00941 * @param repeat 0 or 1 for no repeats, otherwise 2-15 00942 * @returns MDOT_OK if success 00943 */ 00944 int32_t setRepeat(const uint8_t& repeat); 00945 00946 /** Get number of packet repeats for unconfirmed frames 00947 * @returns 0 or 1 if no repeats, otherwise 2-15 00948 */ 00949 uint8_t getRepeat(); 00950 00951 /** Send data to the gateway 00952 * validates data size (based on spreading factor) 00953 * @param data a vector of up to 242 bytes (may be less based on spreading factor) 00954 * @returns MDOT_OK if packet was sent successfully (ACKs disabled), or if an ACK was received (ACKs enabled) 00955 */ 00956 int32_t send(const std::vector<uint8_t>& data, const bool& blocking = true, const bool& highBw = false); 00957 00958 /** Inject mac command 00959 * @param data a vector containing mac commands 00960 * @returns MDOT_OK 00961 */ 00962 int32_t injectMacCommand(const std::vector<uint8_t>& data); 00963 00964 /** 00965 * Clear MAC command buffer to be sent in next uplink 00966 * @returns MDOT_OK 00967 */ 00968 int32_t clearMacCommands(); 00969 00970 /** 00971 * Get MAC command buffer to be sent in next uplink 00972 * @returns command bytes 00973 */ 00974 std::vector<uint8_t> getMacCommands(); 00975 00976 /** Fetch data received from the gateway 00977 * this function only checks to see if a packet has been received - it does not open a receive window 00978 * send() must be called before recv() 00979 * @param data a vector to put the received data into 00980 * @returns MDOT_OK if packet was successfully received 00981 */ 00982 int32_t recv(std::vector<uint8_t>& data); 00983 00984 /** Ping 00985 * status will be MDOT_OK if ping succeeded 00986 * @returns ping_response struct containing status, RSSI, and SNR 00987 */ 00988 ping_response ping(); 00989 00990 /** Get return code string 00991 * @returns string containing a description of the given error code 00992 */ 00993 static std::string getReturnCodeString(const int32_t& code); 00994 00995 /** Get last error 00996 * @returns string explaining the last error that occured 00997 */ 00998 std::string getLastError(); 00999 01000 /** Go to sleep 01001 * @param interval the number of seconds to sleep before waking up if wakeup_mode == RTC_ALARM or RTC_ALARM_OR_INTERRUPT, else ignored 01002 * @param wakeup_mode RTC_ALARM, INTERRUPT, RTC_ALARM_OR_INTERRUPT 01003 * if RTC_ALARM the real time clock is configured to wake the device up after the specified interval 01004 * if INTERRUPT the device will wake up on the rising edge of the interrupt pin 01005 * if RTC_ALARM_OR_INTERRUPT the device will wake on the first event to occur 01006 * @param deepsleep if true go into deep sleep mode (lowest power, all memory and registers are lost, peripherals turned off) 01007 * else go into sleep mode (low power, memory and registers are maintained, peripherals stay on) 01008 * 01009 * For the MDOT 01010 * in sleep mode, the device can be woken up on an XBEE_DI (2-8) pin or by the RTC alarm 01011 * in deepsleep mode, the device can only be woken up using the WKUP pin (PA0, XBEE_DIO7) or by the RTC alarm 01012 * For the XDOT 01013 * in sleep mode, the device can be woken up on GPIO (0-3), UART1_RX, WAKE or by the RTC alarm 01014 * in deepsleep mode, the device can only be woken up using the WKUP pin (PA0, WAKE) or by the RTC alarm 01015 */ 01016 void sleep(const uint32_t& interval, const uint8_t& wakeup_mode = RTC_ALARM, const bool& deepsleep = true); 01017 01018 /** Set wake pin 01019 * @param pin the pin to use to wake the device from sleep mode 01020 * For MDOT, XBEE_DI (2-8) 01021 * For XDOT, GPIO (0-3), UART1_RX, or WAKE 01022 */ 01023 void setWakePin(const PinName& pin); 01024 01025 /** Get wake pin 01026 * @returns the pin to use to wake the device from sleep mode 01027 * For MDOT, XBEE_DI (2-8) 01028 * For XDOT, GPIO (0-3), UART1_RX, or WAKE 01029 */ 01030 PinName getWakePin(); 01031 01032 /** Write data in a user backup register 01033 * @param register one of UBR0 through UBR9 for MDOT, one of UBR0 through UBR21 for XDOT 01034 * @param data user data to back up 01035 * @returns true if success 01036 */ 01037 bool writeUserBackupRegister(uint32_t reg, uint32_t data); 01038 01039 /** Read data in a user backup register 01040 * @param register one of UBR0 through UBR9 for MDOT, one of UBR0 through UBR21 for XDOT 01041 * @param data gets set to content of register 01042 * @returns true if success 01043 */ 01044 bool readUserBackupRegister(uint32_t reg, uint32_t& data); 01045 01046 #if defined(TARGET_MTS_MDOT_F411RE) 01047 /////////////////////////////////////////////////////////////////// 01048 // Filesystem (Non Volatile Memory) Operation Functions for mDot // 01049 /////////////////////////////////////////////////////////////////// 01050 01051 // Save user file data to flash 01052 // file - name of file max 30 chars 01053 // data - data of file 01054 // size - size of file 01055 // returns true if successful 01056 bool saveUserFile(const char* file, void* data, uint32_t size); 01057 01058 // Append user file data to flash 01059 // file - name of file max 30 chars 01060 // data - data of file 01061 // size - size of file 01062 // returns true if successful 01063 bool appendUserFile(const char* file, void* data, uint32_t size); 01064 01065 // Read user file data from flash 01066 // file - name of file max 30 chars 01067 // data - data of file 01068 // size - size of file 01069 // returns true if successful 01070 bool readUserFile(const char* file, void* data, uint32_t size); 01071 01072 // Move a user file in flash 01073 // file - name of file 01074 // new_name - new name of file 01075 // returns true if successful 01076 bool moveUserFile(const char* file, const char* new_name); 01077 01078 // Delete user file data from flash 01079 // file - name of file max 30 chars 01080 // returns true if successful 01081 bool deleteUserFile(const char* file); 01082 01083 // Open user file in flash, max of 4 files open concurrently 01084 // file - name of file max 30 chars 01085 // mode - combination of FM_APPEND | FM_TRUNC | FM_CREAT | 01086 // FM_RDONLY | FM_WRONLY | FM_RDWR | FM_DIRECT 01087 // returns - mdot_file struct, fd field will be a negative value if file could not be opened 01088 mDot::mdot_file openUserFile(const char* file, int mode); 01089 01090 // Seek an open file 01091 // file - mdot file struct 01092 // offset - offset in bytes 01093 // whence - where offset is based SEEK_SET, SEEK_CUR, SEEK_END 01094 // returns true if successful 01095 bool seekUserFile(mDot::mdot_file& file, size_t offset, int whence); 01096 01097 // Read bytes from open file 01098 // file - mdot file struct 01099 // data - mem location to store data 01100 // length - number of bytes to read 01101 // returns - number of bytes read, negative if error 01102 int readUserFile(mDot::mdot_file& file, void* data, size_t length); 01103 01104 // Write bytes to open file 01105 // file - mdot file struct 01106 // data - data to write 01107 // length - number of bytes to write 01108 // returns - number of bytes written, negative if error 01109 int writeUserFile(mDot::mdot_file& file, void* data, size_t length); 01110 01111 // Close open file 01112 // file - mdot file struct 01113 // returns true if successful 01114 bool closeUserFile(mDot::mdot_file& file); 01115 01116 // List user files stored in flash 01117 std::vector<mDot::mdot_file> listUserFiles(); 01118 01119 // Move file into the firmware upgrade path to be flashed on next boot 01120 // file - name of file 01121 // returns true if successful 01122 bool moveUserFileToFirmwareUpgrade(const char* file); 01123 #else 01124 /////////////////////////////////////////////////////////////// 01125 // EEPROM (Non Volatile Memory) Operation Functions for xDot // 01126 /////////////////////////////////////////////////////////////// 01127 01128 // Write to EEPROM 01129 // addr - address to write to (0 - 0x17FF) 01130 // data - data to write 01131 // size - size of data 01132 // returns true if successful 01133 bool nvmWrite(uint16_t addr, void* data, uint16_t size); 01134 01135 // Read from EEPROM 01136 // addr - address to read from (0 - 0x17FF) 01137 // data - buffer for data 01138 // size - size of buffer 01139 // returns true if successful 01140 bool nvmRead(uint16_t addr, void* data, uint16_t size); 01141 #endif /* TARGET_MTS_MDOT_F411RE */ 01142 01143 // get current statistics 01144 // Join Attempts, Join Fails, Up Packets, Down Packets, Missed Acks 01145 mdot_stats getStats(); 01146 01147 // reset statistics 01148 // Join Attempts, Join Fails, Up Packets, Down Packets, Missed Acks 01149 void resetStats(); 01150 01151 // Convert pin number 2-8 to pin name DIO2-DI8 01152 static PinName pinNum2Name(uint8_t num); 01153 01154 // Convert pin name DIO2-DI8 to pin number 2-8 01155 static uint8_t pinName2Num(PinName name); 01156 01157 // Convert pin name DIO2-DI8 to string 01158 static std::string pinName2Str(PinName name); 01159 01160 uint64_t crc64(uint64_t crc, const unsigned char *s, uint64_t l); 01161 01162 /************************************************************************* 01163 * The following functions are only used by the AT command application and 01164 * should not be used by standard applications consuming the mDot library 01165 ************************************************************************/ 01166 01167 // set/get configured baud rate for command port 01168 // only for use in conjunction with AT interface 01169 // set function returns MDOT_OK if success 01170 int32_t setBaud(const uint32_t& baud); 01171 uint32_t getBaud(); 01172 01173 // set/get baud rate for debug port 01174 // set function returns MDOT_OK if success 01175 int32_t setDebugBaud(const uint32_t& baud); 01176 uint32_t getDebugBaud(); 01177 01178 // set/get command terminal echo 01179 // set function returns MDOT_OK if success 01180 int32_t setEcho(const bool& on); 01181 bool getEcho(); 01182 01183 // set/get command terminal verbose mode 01184 // set function returns MDOT_OK if success 01185 int32_t setVerbose(const bool& on); 01186 bool getVerbose(); 01187 01188 // set/get startup mode 01189 // COMMAND_MODE (default), starts up ready to accept AT commands 01190 // SERIAL_MODE, read serial data and send it as LoRa packets 01191 // set function returns MDOT_OK if success 01192 int32_t setStartUpMode(const uint8_t& mode); 01193 uint8_t getStartUpMode(); 01194 01195 int32_t setRxDataRate(const uint8_t& dr); 01196 uint8_t getRxDataRate(); 01197 01198 // get/set TX/RX frequency 01199 // if frequency band == FB_868 (Europe), must be between 863000000 - 870000000 01200 // if frequency band == FB_915 (United States), must be between 902000000-928000000 01201 // if set to 0, device will hop frequencies 01202 // set function returns MDOT_OK if success 01203 int32_t setTxFrequency(const uint32_t& freq); 01204 uint32_t getTxFrequency(); 01205 int32_t setRxFrequency(const uint32_t& freq); 01206 uint32_t getRxFrequency(); 01207 01208 // get/set TX/RX inverted 01209 // true == signal is inverted 01210 // set function returns MDOT_OK if success 01211 int32_t setTxInverted(const bool& on); 01212 bool getTxInverted(); 01213 int32_t setRxInverted(const bool& on); 01214 bool getRxInverted(); 01215 01216 // get/set RX output mode 01217 // valid options are HEXADECIMAL and BINARY 01218 // set function returns MDOT_OK if success 01219 int32_t setRxOutput(const uint8_t& mode); 01220 uint8_t getRxOutput(); 01221 01222 // get/set serial wake interval 01223 // valid values are 2 s - INT_MAX (2147483647) s 01224 // set function returns MDOT_OK if success 01225 int32_t setWakeInterval(const uint32_t& interval); 01226 uint32_t getWakeInterval(); 01227 01228 // get/set serial wake delay 01229 // valid values are 2 ms - INT_MAX (2147483647) ms 01230 // set function returns MDOT_OK if success 01231 int32_t setWakeDelay(const uint32_t& delay); 01232 uint32_t getWakeDelay(); 01233 01234 // get/set serial receive timeout 01235 // valid values are 0 ms - 65000 ms 01236 // set function returns MDOT_OK if success 01237 int32_t setWakeTimeout(const uint16_t& timeout); 01238 uint16_t getWakeTimeout(); 01239 01240 // get/set serial wake mode 01241 // valid values are INTERRUPT or RTC_ALARM 01242 // set function returns MDOT_OK if success 01243 int32_t setWakeMode(const uint8_t& delay); 01244 uint8_t getWakeMode(); 01245 01246 // get/set serial flow control enabled 01247 // set function returns MDOT_OK if success 01248 int32_t setFlowControl(const bool& on); 01249 bool getFlowControl(); 01250 01251 // get/set serial clear on error 01252 // if enabled the data read from the serial port will be discarded if it cannot be sent or if the send fails 01253 // set function returns MDOT_OK if success 01254 int32_t setSerialClearOnError(const bool& on); 01255 bool getSerialClearOnError(); 01256 01257 // MTS_RADIO_DEBUG_COMMANDS 01258 01259 /** Disable Duty cycle 01260 * enables or disables the duty cycle limitations 01261 * **** ONLY TO BE USED FOR TESTINGS PURPOSES **** 01262 * **** ALL DEPLOYABLE CODE MUST ADHERE TO LOCAL REGULATIONS **** 01263 * **** THIS SETTING WILL NOT BE SAVED TO CONFIGURATION ***** 01264 * @param val true to disable duty-cycle (default:false) 01265 */ 01266 int32_t setDisableDutyCycle(bool val); 01267 01268 /** Disable Duty cycle 01269 * **** ONLY TO BE USED FOR TESTINGS PURPOSES **** 01270 * **** ALL DEPLOYABLE CODE MUST ADHERE TO LOCAL REGULATIONS **** 01271 * **** THIS SETTING WILL NOT BE SAVED TO CONFIGURATION ***** 01272 * @return true if duty-cycle is disabled (default:false) 01273 */ 01274 uint8_t getDisableDutyCycle(); 01275 01276 void openRxWindow(uint32_t timeout, uint8_t bandwidth = 0); 01277 void closeRxWindow(); 01278 void sendContinuous(bool enable=true); 01279 int32_t setDeviceId(const std::vector<uint8_t>& id); 01280 int32_t setFrequencyBand(const uint8_t& band); 01281 bool saveProtectedConfig(); 01282 void resetRadio(); 01283 int32_t setRadioMode(const uint8_t& mode); 01284 std::map<uint8_t, uint8_t> dumpRegisters(); 01285 void eraseFlash(); 01286 01287 // deprecated - use setWakeInterval 01288 int32_t setSerialWakeInterval(const uint32_t& interval); 01289 // deprecated - use getWakeInterval 01290 uint32_t getSerialWakeInterval(); 01291 01292 // deprecated - use setWakeDelay 01293 int32_t setSerialWakeDelay(const uint32_t& delay); 01294 // deprecated - use setWakeDelay 01295 uint32_t getSerialWakeDelay(); 01296 01297 // deprecated - use setWakeTimeout 01298 int32_t setSerialReceiveTimeout(const uint16_t& timeout); 01299 // deprecated - use getWakeTimeout 01300 uint16_t getSerialReceiveTimeout(); 01301 01302 void setWakeupCallback(void (*function)(void)); 01303 01304 template<typename T> 01305 void setWakeupCallback(T *object, void (T::*member)(void)) { 01306 _wakeup_callback.attach(object, member); 01307 } 01308 01309 private: 01310 mdot_stats _stats; 01311 01312 FunctionPointer _wakeup_callback; 01313 01314 bool _standbyFlag; 01315 bool _testMode; 01316 uint8_t _savedPort; 01317 void handleTestModePacket(); 01318 01319 }; 01320 01321 #endif
Generated on Sat Jul 16 2022 05:44:25 by
1.7.2