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